HTTP API

The route table below is the router’s own contents. Anything absent from it does not exist yet, and scripts/verify-live.ts fails if the router declares a route the verification script never called.

Authentication

Three routes accept no bearer credential: GET /healthz, GET /readyz, and the username/password exchange at POST /v1/dashboard-sessions. Every other route authenticates first; routes without a named scope still require a valid credential.

Scope failures are distinguishable from identity failures, but resource ownership is not: see Errors for why a foreign id returns 404 and never 403. The full scope list and trust ceilings are on Keys & scopes.

Envelopes

Success is data plus meta. Failure is error plus meta. Both always carry meta.request_id, repeated in an x-request-id response header. Envelope responses are content-type: application/json; charset=utf-8, and every response is cache-control: no-store.

{ "data": { "…": "…" },
  "meta": { "request_id": "req_930dd110186f42ad959858d8745fc0b6" } }

{ "error": { "code": "VALIDATION_ERROR", "message": "Field \"kind\" must be one of: …" },
  "meta": { "request_id": "req_71b6d2e2eba54b0298b41de8544dedc6" } }

Request ids are req_ + 32 lowercase hex. Record ids follow the same shape with their own prefix: org_, key_, obs_, claim_, ctx_, fb_.

Three responses sit outside the JSON envelope. GET /v1/export and GET /v1/audit/export stream application/x-ndjson; POST /mcp returns a bare JSON-RPC body, the shape an MCP client expects.

Request limits

Idempotency and meta.replayed

POST /v1/observations, POST /v1/consolidations and POST /v1/context/:id/feedback accept an Idempotency-Key header. The replay record is inserted inside the same atomic batch as the canonical rows, so a duplicate key makes the whole write fail and roll back.

POST /v1/context/:id/feedback additionally accepts a client_mutation_id field in the body, deduplicated per organization by a unique index.

Health

The memory loop

Memories list

GET /v1/memories is the dashboard’s canonical inventory. It defaults to current active and disputed claims and accepts q, subject_id, project_id, status, visibility, kind, limit (1–100, default 25), and an opaque after cursor. Authorization, retention, and validity are applied in SQL before lexical search and pagination. The response exposes has_more and next_cursor instead of a global count, so large tenants can use keyset pagination without an expensive count query. A selected memory can be opened in the dashboard’s Atlas graph for relationship inspection.

A walkthrough with real payloads is in the Quickstart; the ranking is explained on Compile context.

Claim lifecycle

All three stop the claim appearing in compiled context and none of them delete an observation. Details on Claim lifecycle.

Checkpoints

kind is one of task_state, conversation, workflow, cursor. ttl_seconds is between 60 and 2,592,000, and the serialized state is capped at 64,000 characters.

Keys

Directories and scoped access

Organization authority still comes from authentication. Grants are additive, append-and-revoke records over organization, project (including explicit project:null), or subject targets. A caller must hold every permission it delegates, and a foreign or inaccessible target is indistinguishable from a missing one.

Model diagnostics

Diagnostics never mutate runtime configuration, reveal a credential, prompt, raw provider response, or embedding, or write canonical memory. Disabled and partially configured model tuples are reported explicitly.

Dashboard accounts

Human dashboard accounts are separate from API keys used by agents and services. Bootstrap creates username owner with a random temporary password shown once. Temporary-password login can only replace that password; a fresh login is required before the private dashboard becomes available. Established accounts with a passkey must complete a second factor after password verification.

Password login uses persistent progressive delays before password verification. Unknown accounts and wrong passwords return the same response. A passkey challenge binds to the account, session, purpose, and expiry. Staged sessions cannot call product routes. Recovery and passkey revocation remain available if relying-party configuration is later disabled.

Portability

Order matters across requests: an observation references a project, and a claim source references an observation. Follow import_order from the export header: projects, then observations, then claims. A reference to a record that does not exist yet is 400 UNRESOLVED_REFERENCE, not a conflict; a conflict means the id already belongs to another organization. See Backup & export.

Collaboration

Lease ttl_seconds is between 10 and 86,400. More on Leases & handoffs.

MCP

Protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05 are supported. A notification returns 202 with an empty body; a batch returns an array. Key management, membership, retention, webhook, federation, release and Atlas operations are deliberately absent from the agent tool profile; publisher, approver, operator and gateway principals use REST for those. See MCP server.

Events

Event rows are written in the same atomic batch as the canonical change they describe, so an event can never exist for a write that rolled back or be missing for one that committed.

Memory Atlas

Read-only despite the POST; the request needs a bounded body. evidence_trace requires focus_id, neighborhood requires subject_id. Policy runs before traversal: both endpoints of every edge must be authorized, and hidden candidates contribute no edges, labels or counts. An unauthorized focus is a non-disclosing 404. The evidence trace centers that claim and can include readable source observations, complete readable context packs, and current active releases. It labels supports, contradicts, qualifies, selected-in, and released-as relationships; partial contexts and stale releases are omitted rather than partially disclosed.

workspace_graph accepts an optional workspace_id and max_nodes from 25 to 300. It returns only authorized claim and subject nodes with canonical about, related, contradicts, and supersedes edges. Truncation and withheld-edge counts are bounded aggregate state; they never disclose hidden identifiers.

Governance, retention and released knowledge

verified trust describes evidence authority; it does not by itself permit disclosure. A public-facing service uses its bound channel gateway and reads released snapshots, never canonical memory. Reasoning in ADR-0002 and on Channel releases.

Audit

Federation

Passing include_memory: true on a pull opts into signed canonical claim and evidence bundles. The destination enforces explicit claim filters, source-organization binding, trust ceilings, replay identity and complete-graph validation before an atomic import.

Webhooks and delivery

The destination must be https://, or http://localhost / http://127.0.0.1 for development; private and link-local ranges are rejected. Deliveries are signed X-Titen-Signature: sha256=HEX, an HMAC-SHA256 of the raw body, alongside X-Titen-Event and X-Titen-Delivery. Backoff is 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours, capped at 5 attempts, and a webhook is disabled after 10 consecutive failures. A unique index on (webhook, event) makes delivery exactly once per event per webhook even if a drain is replayed. More on Webhooks & events.

Indexing

Observation and claim writes queue an outbox row, and until something consumes them the vector index stays empty. This route is that consumer, pull-driven because an embedding call crosses the network and a canonical write must not wait on one. With no vector capability configured it returns 400; if the model or index is unreachable it returns 503 UNAVAILABLE with meta.pending and meta.retryable and leaves the queue untouched. GET /readyz reports background_repair so an operator can tell whether anything is calling it. See Semantic vectors.

/v1/index/verify never reads embedding values. It compares organization-scoped canonical ids with provider membership and returns checked, present, missing, repairs_queued, and next_after; the normal drain performs any queued rebuild.

Not implemented

Named here because earlier drafts documented them as if they existed: batch observation append, the old /v1/channel-releases and /v1/channel-context paths, /v1/webhook-subscriptions, /v1/webhook-deliveries as a top-level collection, and /v1/audit/events.

Compatibility

Next