REST API¶

The `/v1` HTTP surface

The REST surface is an Axum server exposing records, the query DSL, generation, and administration under /v1, plus two unauthenticated probes. Every endpoint returns the uniform error envelope and stamps x-request-id.

Conventions¶

Handlers never read tenant identity from the request body or path, the Scoped extractor is the only source, and it is populated exclusively by the auth middleware from the presented credential.

Endpoint summary¶

Auth by route group¶

The router wires four distinct middleware groups (core-engine/src/api/mod.rs):

flowchart LR
    A[whoami / query / snapshot / compare / schema / generate / trace] -->|apiKey only| M1[require_api_key]
    B[records / ingest / relationships] -->|apiKey OR connector bearer| M2[require_api_key_or_connector_token]
    C[clarifications / person-aliases] -->|apiKey OR clarify bearer| M3[require_api_key_or_clarify_token]
    D["/admin/*"] -->|admin bearer only| M4[admin interceptor]

• apiKey: the x-api-key header, resolved by SHA-256 lookup against {data_dir}/api_keys.json. Full tenant-admin authority.
• connectorToken: Authorization: Bearer <token>, a "connector"-audience signed token (tenant-scoped, connector-named). Deletes are namespace-checked in the handler: a connector may only tombstone records whose source_connector property matches its own name (403 CONNECTOR_NAMESPACE_MISMATCH otherwise).
• clarifyToken: Authorization: Bearer <token>, a "clarify"-audience signed token (the clarify-bot's answer path). /v1/person-aliases/verified-match accepts only this audience.
• adminToken: a "admin"-audience signed token for the operator retention surface (/admin/*, documented in the Operators section, not here).

All three bearer schemes are signed with the same HMAC scheme described in gRPC API › Auth, keyed off grpc.token_key.

Probes¶

GET /healthz¶

Liveness only; does not touch storage.

curl -fsS http://127.0.0.1:7625/healthz
# ok

GET /readyz¶

Checks the engine handle can open a snapshot.

curl -fsS http://127.0.0.1:7625/readyz
# ok

GET /v1/whoami¶

Echoes the authenticated scope. Unauthenticated calls get 401 UNAUTHORIZED.

curl -fsS http://127.0.0.1:7625/v1/whoami -H "x-api-key: $KEY"

{ "tenant_id": "1111...", "organization_id": "2222...", "request_id": "..." }

Query, snapshot, compare, schema¶

POST /v1/query¶

Executes a query-DSL document. The request body is parsed raw (not through a typed DTO) so validation errors carry a JSON pointer.

{ "find": "RISK", "where": { "severity": { "$gte": 7 } }, "limit": 50 }

{
  "records": [
    {
      "id": "...", "labels": ["RISK"],
      "properties": { "severity": 7, "status": "open" },
      "validTime": { "start": 1750000000000000 },
      "txTime": { "start": 1750000000000000 },
      "tombstone": false,
      "score": 0.87
    }
  ],
  "related": [
    {
      "expandIndex": 0,
      "partial": false,
      "nodes": [
        { "id": "...", "labels": ["PERSON"], "properties": {}, "validTime": {}, "txTime": {}, "tombstone": false,
          "depth": 1, "viaEdge": "...", "decayScore": 0.9 }
      ]
    }
  ],
  "nextCursor": null,
  "traceId": null,
  "stats": {
    "path": "...", "bitmapCandidates": 0, "rowsScanned": 12,
    "rowsFilteredOut": 2, "typeMismatches": 0, "rowsReturned": 10, "durationUs": 340
  }
}

score on a record or related node appears only when the query carried a vector clause. Records whose winning version is linked to an unanswered clarification also carry a pendingClarification object (id, state, kind, severity, candidates, confidences) so a guessed value is never presented as confirmed fact.

POST /v1/snapshot¶

Query sugar: pins atValidTime (required) and optionally atTxTime, find, where, limit, cursor, and re-dispatches through the same executor as /v1/query (identical response shape).

{ "find": "RISK", "atValidTime": "2026-07-01T00:00:00Z" }

curl -fsS -X POST http://127.0.0.1:7625/v1/snapshot \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" \
  -d '{"find": "RISK", "atValidTime": "2026-07-01T00:00:00Z"}'

POST /v1/compare¶

Computes what changed between two bitemporal coordinates: added, removed (tagged tombstone or validityLapse), and modified (per-property old → new). Body is parsed raw, same pointered-error posture as /v1/query.

{
  "baseline": { "validTime": "2026-01-01T00:00:00Z" },
  "comparison": { "validTime": "2026-04-01T00:00:00Z" },
  "find": "RISK",
  "where": { "severity": { "$gte": 7 } },
  "limit": 100
}

{
  "added": [{ "kind": "node", "id": "...", "labels": ["RISK"], "properties": { "severity": 8 } }],
  "removed": [{ "kind": "node", "id": "...", "labels": ["RISK"], "reason": "tombstone" }],
  "modified": [
    {
      "kind": "node", "id": "...", "labels": ["RISK"],
      "versions": {
        "baseline": { "validTimeStart": 1, "txTimeStart": 1 },
        "comparison": { "validTimeStart": 2, "txTimeStart": 2 }
      },
      "props": { "added": {}, "removed": {}, "changed": [{ "key": "severity", "old": 5, "new": 8 }] },
      "labelsAdded": [], "labelsRemoved": [], "touch": false
    }
  ],
  "stats": { "added": 1, "removed": 1, "modified": 1, "unchanged": 4 },
  "nextCursor": null
}

Request fields:

removed[].reason is "tombstone" (winning version at C is a tombstone) or "validityLapse" (no version contains C on the valid-time axis). modified[].touch marks a re-versioned entity with identical content (spec OQ-1: visible but distinguishable).

GET /v1/schema¶

Inferred schema per label: property names, observed types, counts.

curl -fsS "http://127.0.0.1:7625/v1/schema?label=RISK" -H "x-api-key: $KEY"

{ "schemas": [ { "label": "RISK", "properties": { "severity": { "type": "Int", "count": 42 } } } ] }

Records¶

POST /v1/records¶

Creates (or, with id + upsert, idempotently upserts) a batch of records, optionally with inline relationships.

{
  "records": [
    {
      "labels": ["RISK"],
      "properties": { "title": "Supplier delay", "severity": 7 },
      "relationships": [{ "type": "OWNED_BY", "node": "3333...-...", "direction": "out" }]
    }
  ]
}

{
  "records": [
    {
      "id": "...", "labels": ["RISK"],
      "properties": { "title": "Supplier delay", "severity": 7 },
      "validTime": { "start": 1750000000000000 },
      "txTime": { "start": 1750000000000000 },
      "tombstone": false,
      "relationships": ["<edge-id>"]
    }
  ]
}

Per-record fields:

GET /v1/records?externalId=&connector=¶

Resolves a connector-synced item to its projection root record (a point lookup via deterministic source identity).

curl -fsS "http://127.0.0.1:7625/v1/records?externalId=site,item-42&connector=sharepoint" \
  -H "x-api-key: $KEY"

{
  "externalId": "site,item-42", "connector": "sharepoint",
  "sourceId": "...", "sourceVersionTx": 1750000000000000,
  "rootNodeId": "...", "aclJson": { "...": "..." },
  "record": { "id": "...", "labels": ["..."], "properties": {}, "validTime": {}, "txTime": {}, "tombstone": false }
}

connector is inferred from a connector-token caller; API-key callers must supply it explicitly (400 VALIDATION otherwise). A connector token asking for a different namespace gets 403 CONNECTOR_NAMESPACE_MISMATCH. 404 NOT_FOUND for no such source, or when the projection root has not been parsed yet.

GET /v1/records/{id}¶

curl -fsS http://127.0.0.1:7625/v1/records/<id> -H "x-api-key: $KEY"

{ "id": "...", "labels": ["RISK"], "properties": { "severity": 7 },
  "validTime": { "start": 1750000000000000 }, "txTime": { "start": 1750000000000000 }, "tombstone": false }

401 UNAUTHORIZED; 404 NOT_FOUND if no such record.

PUT /v1/records/{id}¶

Writes a new full-snapshot version of an existing record (appends; history is preserved).

{ "labels": ["RISK"], "properties": { "title": "Supplier delay", "severity": 8 } }

{ "id": "...", "labels": ["RISK"], "properties": { "title": "Supplier delay", "severity": 8 },
  "validTime": {}, "txTime": {}, "tombstone": false }

DELETE /v1/records/{id}?validEnd=¶

Tombstones a record and cascades to its live edges.

curl -fsS -X DELETE http://127.0.0.1:7625/v1/records/<id> -H "x-api-key: $KEY"

{ "id": "...", "edgesTombstoned": 3, "txTime": 1750000000000000 }

validEnd (query param, µs) sets the tombstone's valid-time end; default now. A connector-token caller may only delete records whose source_connector property matches its own name (403 CONNECTOR_NAMESPACE_MISMATCH otherwise); API keys are unrestricted tenant-admin credentials. 409 TOMBSTONED if already tombstoned.

GET /v1/records/{id}/history?limit=&cursor=¶

Paginated version history, including tombstones.

curl -fsS "http://127.0.0.1:7625/v1/records/<id>/history?limit=50" -H "x-api-key: $KEY"

{ "versions": [ { "id": "...", "labels": [], "properties": {}, "validTime": {}, "txTime": {}, "tombstone": false } ],
  "nextCursor": null }

limit defaults to 50. 400 BAD_CURSOR for an invalid cursor.

Relationships¶

POST /v1/relationships¶

{ "from": "1111...", "to": "2222...", "type": "OWNED_BY" }

{ "id": "...", "from": "1111...", "to": "2222...", "type": "OWNED_BY", "validTime": {}, "txTime": {} }

DELETE /v1/relationships/{id}?validEnd=¶

{ "id": "...", "txTime": 1750000000000000 }

401 UNAUTHORIZED; 404 NOT_FOUND; 409 TOMBSTONED if already tombstoned.

Ingest¶

POST /v1/ingest¶

Ingests a source document. format=json applies synchronously; other formats (docling, tabular, email, web, ...) enqueue an async parse job for the Python format workers. An identical re-submission (content-hash dedup) returns 200.

curl -fsS -X POST http://127.0.0.1:7625/v1/ingest \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" \
  -d '{"format": "json", "name": "risks.json",
       "content": "[{\"label\": \"RISK\", \"severity\": 7}]"}'

{ "deduplicated": false, "sourceId": "...", "sourceVersionTx": 1750000000000000,
  "nodeIds": ["..."], "edgeIds": [] }

{ "deduplicated": false, "jobId": "...", "sourceId": "...", "statusUrl": "/v1/ingest/<jobId>" }

{ "deduplicated": true, "sourceId": "..." }

Request fields:

GET /v1/ingest/{job_id}¶

curl -fsS http://127.0.0.1:7625/v1/ingest/<jobId> -H "x-api-key: $KEY"

{ "jobId": "...", "kind": "ingest:docling", "state": "pending",
  "attempts": 0, "events": [{ "at": 1750000000000000, "transition": "enqueued", "detail": null }] }

state is one of pending, leased, completed, dead. 404 NOT_FOUND for no such job.

Generation¶

POST /v1/generate¶

Plans evidence, generates a draft with citations, verifies every claim against its planned source spans, and persists an auditable trace. See Generation & traces for the full SSE contract and verification model; this section covers the REST contract shape.

{
  "question": "Which open risks have severity 5 or higher?",
  "query": { "find": "RISK", "where": { "status": { "$eq": "open" } } },
  "semanticModel": "text-embedding-3-small",
  "expandDepth": 1,
  "stream": false
}

{
  "draft": "...", "model": "claude-sonnet-4-5", "traceId": "0197...",
  "planHash": "...", "promptHash": "...",
  "citations": [ ],
  "plan": { "budget": 6000, "used": 3200, "spans": 4, "stats": {} },
  "usage": { "inputTokens": 900, "outputTokens": 210 },
  "verification": { "status": "verified", "claims": [ ] }
}

Request fields:

With "stream": true the response is text/event-stream instead of JSON: chunk ({delta}) events as tokens arrive, one verification event (necessarily trailing the stream), one done event ({traceId, usage, planHash, promptHash, citations}), or an error event ({message}) on a mid-stream provider failure that ends the stream without re-splicing.

GET /v1/trace/{query_id}¶

curl -fsS http://127.0.0.1:7625/v1/trace/<traceId> -H "x-api-key: $KEY"

Returns the full persisted assembly record (request summary, evidence plan, prompt hash, per-claim verdicts, span links). 401 UNAUTHORIZED; 404 NOT_FOUND if no such trace for this tenant.

Clarifications¶

These endpoints back the temporal-clarification workflow (ambiguity detection escalating to a human answer). Full field semantics live alongside the clarify-bot documentation; the shapes below are the REST contract.

GET /v1/clarifications?state=&severity=&limit=&cursor=¶

Tenant-scoped list, backed by the same query executor as /v1/query.

{ "clarifications": [ { "id": "...", "target": "...", "kind": "...", "severity": "...", "state": "..." } ],
  "nextCursor": null }

400 VALIDATION for an unrecognized state/severity; 400 QUERY_INVALID if the derived query fails validation; 401 UNAUTHORIZED.

GET /v1/clarifications/{id}¶

Returns the clarification plus, when resolvable, spanExcerpt (capped at 500 bytes), aclJson, sourceId, sourceName, and askedAliases (delivery identities for the ranked candidates).

401 UNAUTHORIZED; 404 NOT_FOUND.

POST /v1/clarifications/{id}/answer¶

Answers a clarification. Body fields: answerIndex, answerCustom, responder/rights (clarify-audience callers only), channel, messageRef, stewardOverride.

POST /v1/person-aliases/verified-match¶

Clarify-audience only (403 ALIAS_ATTACH_FORBIDDEN for any other caller). Attaches a verified chat alias (slack_user_id in v1) to a PERSON record after re-verifying the evidence server-side.

OpenAPI document¶

GET /v1/openapi.json¶

Unauthenticated. Serves the same utoipa-derived document snapshotted at core-engine/openapi/openapi.json (title "Telha Core API", version 0.1.0), including the four security schemes (apiKey, connectorToken, clarifyToken, adminToken) and every path documented above.

curl -fsS http://127.0.0.1:7625/v1/openapi.json | jq '.paths | keys'

Related¶

• Query language - the JSON DSL behind /v1/query, /v1/snapshot, where in /v1/compare
• gRPC API - the same operations over the internal gRPC surface
• MCP tools - agent-facing tools wrapping this surface
• Generation & traces - /v1/generate SSE contract and verification detail
• Error reference - every error code, HTTP status, and gRPC mapping
• TypeScript SDK / Python SDK - typed clients over this surface