> ## Documentation Index
> Fetch the complete documentation index at: https://medlogprotocol.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> The five write-once event endpoints that assemble a MedLog record.

The MedLog API is a set of **write-once event endpoints**. A collector accepts events but never returns
record contents — each call appends one schema-compliant message that is later assembled into a complete
[record](/specification/overview). The interactive endpoint pages in this section are generated
directly from the [OpenAPI specification](https://github.com/mims-harvard/medlog).

## Authentication

All endpoints require an API key passed in the **`X-API-Key`** header.

```bash theme={null}
curl -X POST https://your-collector.example.org/event/inference-start \
  -H "X-API-Key: $MEDLOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

## Endpoints

Each endpoint records one part of a MedLog record:

| Method | Path                       | Records                                                                  |
| ------ | -------------------------- | ------------------------------------------------------------------------ |
| `POST` | `/event/inference-start`   | The beginning of an inference run — creates the `event_id` and `run_id`. |
| `POST` | `/event/internal-artifact` | An intermediate artifact (reasoning trace, retrieved context, …).        |
| `POST` | `/event/human-output`      | Content shown to a human user.                                           |
| `POST` | `/event/outcome`           | A downstream patient or system outcome attributed to a prior inference.  |
| `POST` | `/event/user-feedback`     | Explicit user feedback.                                                  |

<Tip>
  Select an endpoint in the sidebar to see its full schema and try it against a server using the built-in
  API playground.
</Tip>

## The event model

Every event extends a shared **`BaseEvent`** and adds an event-specific payload. The base fields carry
identity and linkage:

| Field             | Type      | Notes                                                          |
| ----------------- | --------- | -------------------------------------------------------------- |
| `event_id`        | uuid      | Unique ID for this event. **Required.**                        |
| `run_id`          | uuid      | Constant across all events in the same run.                    |
| `parent_event_id` | uuid      | The event this one expands on.                                 |
| `timestamp`       | date-time | When the event occurred. **Required.**                         |
| `medlog_version`  | string    | Protocol version. **Required.**                                |
| `system_metadata` | object    | `hostname`, `app_name`, `proc_id`, `latency_ms`. **Required.** |

The first event (`inference-start`) additionally carries the model instance, user and target identities,
and inputs. Later events carry a single typed payload — an `artifact`, `output`, `outcome`, or
`feedback` object. See [the record fields](/specification/overview) for the conceptual model
behind these payloads.

## Responses

| Status | Meaning                                          |
| ------ | ------------------------------------------------ |
| `201`  | Event accepted.                                  |
| `400`  | Bad request — invalid payload or missing fields. |
| `401`  | Unauthorized — missing or invalid credentials.   |
| `403`  | Forbidden — insufficient permissions.            |

Error responses return an `Error` object with a `message`, and optionally a `code` and `details`.