Quickstart

A MedLog record is assembled from a stream of write-once messages sent to a collector. You do not write a record all at once. Instead, you emit one message at inference start and append more messages as artifacts, outputs, outcomes, and feedback become available. Every message after the first references the original event_id (and, for multi-step workflows, a shared run_id). This design means a record exists even when inference fails, and lets outcomes or feedback be added later — sometimes hours or days after the model ran.

All examples below authenticate with an API key passed in the X-API-Key header. Every endpoint is write-only: collectors accept events but never return record contents.

Emit a record

Record the start of inference

The first message captures everything available at invocation: the header, model instance, user and target identities, and the inputs. It mints the event_id (and a run_id if this is part of a multi-step workflow).

curl -X POST https://your-collector.example.org/event/inference-start \
  -H "X-API-Key: $MEDLOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "551b1676-1837-4278-988d-59ba3166b83e",
    "run_id": "492dac48-dd7d-485e-8991-1325e814e73e",
    "timestamp": "2026-01-10T05:31:19.805Z",
    "medlog_version": "0.0.1",
    "system_metadata": { "app_name": "SEP-1 Abstraction AI", "proc_id": "3023" },
    "model_instance": { "model_id": "Llama-3.1-8B-Instruct", "model_version": "2024-07-18" },
    "user_identity": { "caller_type": "service", "caller_id": "sep1-pipeline" },
    "target_identity": { "target_type": "patient", "target_id": "MRN-XXXXXXXX" },
    "inputs": { "prompt": "Does the note contain an explicit mention that the patient has been discharged?" }
  }'

Append internal artifacts (optional)

Reasoning traces, retrieved context, uncertainty estimates, and other intermediate artifacts are referenced back to the same event_id. This field is optional.

curl -X POST https://your-collector.example.org/event/internal-artifact \
  -H "X-API-Key: $MEDLOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "9b1c...",
    "parent_event_id": "551b1676-1837-4278-988d-59ba3166b83e",
    "timestamp": "2026-01-10T05:31:20.110Z",
    "medlog_version": "0.0.1",
    "system_metadata": { "app_name": "SEP-1 Abstraction AI" },
    "artifact": {
      "artifact_type": "reasoning_trace",
      "artifact_uri": "s3://medlog-artifacts/551b1676/cot.txt",
      "mime_type": "text/plain",
      "description": "Chain-of-thought for the discharge-disposition question"
    }
  }'

Record the human-facing output

The prediction, generation, or recommendation shown to a clinician or patient.

curl -X POST https://your-collector.example.org/event/human-output \
  -H "X-API-Key: $MEDLOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "a72f...",
    "parent_event_id": "551b1676-1837-4278-988d-59ba3166b83e",
    "timestamp": "2026-01-10T05:31:20.480Z",
    "medlog_version": "0.0.1",
    "system_metadata": { "app_name": "SEP-1 Abstraction AI" },
    "output": {
      "output_type": "text",
      "output_uri": "s3://medlog-outputs/551b1676/answer.json",
      "summary": "Answer: N (no explicit discharge mention)"
    }
  }'

Attribute an outcome and capture feedback (when available)

Outcomes and feedback often arrive later. Post them whenever they become observable, referencing the original event_id.

# A reviewer confirms the abstraction
curl -X POST https://your-collector.example.org/event/outcome \
  -H "X-API-Key: $MEDLOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "c0d3...",
    "parent_event_id": "551b1676-1837-4278-988d-59ba3166b83e",
    "timestamp": "2026-01-11T14:02:00Z",
    "medlog_version": "0.0.1",
    "system_metadata": { "app_name": "SEP-1 Abstraction AI" },
    "outcome": { "outcome_type": "validated", "description": "QPS analyst: agree, case passes." }
  }'

Minimal implementations

MedLog scales down. In low-resource or offline settings you can log only a small set of fields — Header, Model instance, and Outputs — and add more fields as local capacity grows.

When connectivity is intermittent, buffer events on-device with write-behind caching and synchronize once the network returns. See low-resource settings.

Next steps

The record schema

Understand the nine fields in depth.

Example record

An annotated, real MedLog record showing every field.

Integration patterns

Wrap model calls at API gateways, LLM proxies, and agent frameworks.

API reference

The five write-once event endpoints.

Get started

Deployments

Implementation

Emit a record

Minimal implementations

Next steps

The record schema

Example record

Integration patterns

API reference

​Emit a record

​Minimal implementations

​Next steps

The record schema

Example record

Integration patterns

API reference

Emit a record

Minimal implementations

Next steps