​
Ingestion API

POST /api/ingest validates normalized JSON traces, stores the raw payload, queues an ingest job, and returns immediately. The generated reference page for this flow is Queue trace ingestion.

​
Authentication

POST /api/ingest accepts either:
  • a bearer token from the CLI
  • a signed-in browser session

​
JSON trace upload

POST /api/ingest
Authorization: Bearer <token>
Content-Type: application/json

{
  "traces": [
    {
      "source": "codex_jsonl",
      "sourceId": "session-123",
      "model": "gpt-5",
      "createdAt": "2026-06-04T12:00:00.000Z",
      "messages": [
        {
          "position": 0,
          "role": "user",
          "content": "Build a trace uploader.",
          "tokenCount": 6,
          "createdAt": "2026-06-04T12:00:00.000Z"
        }
      ]
    }
  ]
}
JSON uploads can include up to 1,000 traces per request. Long traces are accepted; the server does not reject a trace because of its token count, message count, or per-message content length. The server recounts message tokens and ignores client-supplied token counts for payout-sensitive accounting.

​
Queued response

{
  "ok": true,
  "jobId": "019e...",
  "status": "queued"
}
The HTTP status is 202.

​
Server processing

The background worker loads the raw JSON upload blob, then calls the ingest pipeline. The pipeline normalizes, scrubs, rejects high-risk PII, scores, deduplicates, inserts trace/message rows, and writes raw plus derived blobs.