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

# Quickstart

> Emit your first MedLog record by writing a stream of events to a collector.

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.

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

## Emit a record

<Steps>
  <Step title="Record the start of inference">
    The first message captures everything available at invocation: the [header](/specification/header),
    [model instance](/specification/model-instance),
    [user](/specification/user-identity) and
    [target](/specification/target-identity) identities, and the
    [inputs](/specification/inputs). It mints the `event_id` (and a `run_id` if
    this is part of a multi-step workflow).

    ```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 '{
        "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?" }
      }'
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    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"
        }
      }'
    ```
  </Step>

  <Step title="Record the human-facing output">
    The prediction, generation, or recommendation shown to a clinician or patient.

    ```bash theme={null}
    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)"
        }
      }'
    ```
  </Step>

  <Step title="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`.

    ```bash theme={null}
    # 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." }
      }'
    ```
  </Step>
</Steps>

## Minimal implementations

MedLog scales down. In low-resource or offline settings you can log only a small set of fields —
[Header](/specification/header), [Model instance](/specification/model-instance), and
[Outputs](/specification/outputs) — and add more fields as local capacity grows.

<Tip>
  When connectivity is intermittent, buffer events on-device with write-behind caching and synchronize
  once the network returns. See [low-resource settings](/implementation/low-resource).
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="The record schema" icon="table-list" href="/specification/overview">
    Understand the nine fields in depth.
  </Card>

  <Card title="Example record" icon="file-code" href="/specification/example-record">
    An annotated, real MedLog record showing every field.
  </Card>

  <Card title="Integration patterns" icon="plug" href="/implementation/integration">
    Wrap model calls at API gateways, LLM proxies, and agent frameworks.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/overview">
    The five write-once event endpoints.
  </Card>
</CardGroup>