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. The interactive endpoint pages in this section are generated
directly from the OpenAPI specification.
Authentication
All endpoints require an API key passed in the X-API-Key header.
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. |
Select an endpoint in the sidebar to see its full schema and try it against a server using the built-in
API playground.
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. |
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 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 object with a message, and optionally a code and details.