> ## 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.