API | 1321

Getting Started

A local HTTP API for evidence-backed media understanding. Register a source, run a bounded study, and read receipts your pipeline can verify. Studio and agentic editors are clients of the same local runtime host.

Core Flow

Sources And Ingest: Register or list a local source before any study can start.
Runtime Lifecycle: Plan or start one bounded study, then poll its journal to terminal.
Evidence Audits: Optional: reopen and re-verify stored assessments and decision receipts.
Publish Review: Attested approve or reject. Required before private caption production.
Captions And QC: Private caption candidates and structural QC. The default host fails closed with 409; 201 examples require an opt-in test executor.
Private Playback: Mint an origin-bound grant, then stream exact private source bytes.
Language Explanations: Typed facets over one verified caption span. The default host returns an empty list; 201 examples require an opt-in OpenAI executor.

An empty list is a valid response, not an error. When the host cannot verify a fact, reads return unavailable or withheld instead of a guess. Improve documents the evaluation loop behind the API; it is not a /v1 route.

First Request

With a running host and bearer token, GET /v1/source-sessions verifies authorization and lists registered sources. From there, Runtime Lifecycle runs the study itself.

The host serves loopback only and requires a bearer token; see Authentication. Example responses in this reference were captured from a running host; hand-written examples are marked illustrative.

Request

# printed on stdout when the host starts
TOKEN=<authorizationToken>

curl -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:4312/v1/source-sessions

Quickstart

The smallest sequence that proves the default npm run runtime:host end to end: list sources, plan, start, poll events to terminal. No model spend and no hosted upload.

Caption production comes later, and only after Publish Review. Responses labeled test executor or OpenAI executor require opt-in host flags and are not default behavior.

Quickstart

# Quickstart: local host only (no SaaS, no model spend)
# 1. npm run runtime:host
# 2. Copy authorizationToken from the host stdout JSON
TOKEN=<authorizationToken>

# 3. Verify authorization and list registered sources (one sample source ships pre-registered)
curl -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:4312/v1/source-sessions

# 4. Plan the study and read its forecast; nothing durable is written
curl -X POST http://127.0.0.1:4312/v1/runtime-plans \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "sourceSessionId": "source-session:50e48113837e62499233f29f53ab91f5ed591d39bda98879effb02364e2a03a2",
  "sourceRevisionId": "source-revision:6800f536f61f5d73dc474443cf0469c823ae94a984a209192940fc28b94afa09",
  "range": {
    "startMs": 0,
    "endMs": 47200
  },
  "requestedSourceLanguage": {
    "mode": "declared",
    "languages": [
      "ko"
    ],
    "reason": null
  },
  "targetLanguage": "en",
  "selectedLanguagePackId": "ko-v3",
  "outputDepth": "evidence"
}'

# 5. Start one bounded study; read runtimeId from the 202 ack
curl -X POST http://127.0.0.1:4312/v1/runtime-starts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "sourceSessionId": "source-session:50e48113837e62499233f29f53ab91f5ed591d39bda98879effb02364e2a03a2",
  "sourceRevisionId": "source-revision:6800f536f61f5d73dc474443cf0469c823ae94a984a209192940fc28b94afa09",
  "range": {
    "startMs": 0,
    "endMs": 47200
  },
  "requestedSourceLanguage": {
    "mode": "declared",
    "languages": [
      "ko"
    ],
    "reason": null
  },
  "targetLanguage": "en",
  "selectedLanguagePackId": "ko-v3",
  "outputDepth": "evidence"
}'

# 6. Poll events until lifecycle is terminal (or reachedHead)
curl -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:4312/v1/runtimes/$RUNTIME_ID/events?after=0&limit=100"

# Caption production requires an approved Publish Review decision. The default
# host fails closed with 409 for caption production; the deterministic test
# executor is an opt-in host configuration:
#   --caption-executor deterministic-test --allow-deterministic-caption-test-seam
# Language explanations additionally require an opt-in OpenAI executor:
#   --language-explanation-executor openai --allow-real-language-explanation
#   --language-explanation-model gpt-4o-mini
# The default host returns an empty language list.