API reference - MedLog

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.

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

​Authentication

​Endpoints

​The event model

​Responses

Authentication

Endpoints

The event model

Responses