Authentication | 1321 API

Getting Started

Start the host with npm run runtime:host; it binds 127.0.0.1:4312, prints one token per process on stdout as authorizationToken, and serves only that loopback address. Browser clients must also match an explicit origin allowlist; wildcard origins are rejected.

Base URLhttp://127.0.0.1:4312self-hosted

Authorizationstringheaderrequired

Bearer <token>, compared exactly against the token the host issued. Missing or wrong tokens return 401. The private media route is the one exception; it authorizes by grant secret instead, so media elements can stream.

Quickstart

Same sequence as the Overview: list sources, plan, start, poll events to terminal. It verifies the token against every core endpoint on the local host.

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.