Reference

HTTP API

The current Agent, Turn, Conversation, MemorySpace, usage, credit, and browser runtime surface.

The hosted API uses an App-scoped bearer credential and explicit tenant/user assertions where required:

Authorization: Bearer nvk_…
X-Nvoken-Tenant-Key: acme
X-Nvoken-User-Key: alice

Paths take opaque IDs. nvoken mints them as UUIDv7 and returns them as canonical lowercase text, but nothing in the API constrains their shape: an ID you supply is stored and returned as you sent it. Caller-owned keys are resolved only inside an explicit owner namespace.

Turns

Method	Path	Purpose
`POST`	`/v1/turns`	Durably admit one Turn
`GET`	`/v1/turns`	List Turns with tenant, actor, behavior, continuity, memory, status, and lineage filters
`GET`	`/v1/turns/{turn_id}`	Read current state
`DELETE`	`/v1/turns/{turn_id}`	Erase retained Turn content when eligible
`GET`	`/v1/turns/{turn_id}/stream`	Follow one Turn over SSE
`GET`	`/v1/turns/{turn_id}/result`	Read the composed result
`POST`	`/v1/turns/{turn_id}/cancel`	Discard unfinished work
`POST`	`/v1/turns/{turn_id}/interrupt`	End at a safe boundary
`POST`	`/v1/turns/{turn_id}/resume`	Raise eligible held limits
`POST`	`/v1/turns/{turn_id}/tool-results`	Submit host-tool results

Timeline, traces, logs, tool calls, nudges, and nudge cancellation are also scoped below /v1/turns/{turn_id}.

Agents

Method	Path	Purpose
`POST`	`/v1/agents`	Create an Agent and revision 1
`GET`	`/v1/agents`	List or resolve Agents in an exact owner namespace
`GET`	`/v1/agents/{agent_id}`	Read one Agent
`DELETE`	`/v1/agents/{agent_id}`	Archive an Agent
`POST`	`/v1/agents/{agent_id}/restore`	Restore an Agent
`GET` / `POST`	`/v1/agents/{agent_id}/revisions`	List or publish immutable revisions
`GET`	`/v1/agents/{agent_id}/revisions/{revision}`	Read one exact revision

Conversations

Method	Path	Purpose
`POST` / `GET`	`/v1/conversations`	Create or list Conversations
`GET` / `PATCH` / `DELETE`	`/v1/conversations/{conversation_id}`	Read, update metadata, or erase retained content
`POST`	`/v1/conversations/{conversation_id}/fork`	Fork an inclusive transcript prefix
`GET`	`/v1/conversations/{conversation_id}/messages`	Page canonical messages
`GET`	`/v1/conversations/{conversation_id}/compactions`	List compaction records
`GET`	`/v1/conversations/{conversation_id}/transcript`	Drain a fixed-cut transcript
`GET`	`/v1/conversations/{conversation_id}/stream`	Follow current and future Turns over SSE

MemorySpaces

Method	Path	Purpose
`POST` / `GET`	`/v1/memory-spaces`	Resolve or list exact scoped namespaces
`GET` / `DELETE`	`/v1/memory-spaces/{memory_space_id}`	Read or erase one MemorySpace

Other runtime groups

The public contract also includes identity, models, MCP discovery, usage, credits, tenants, admissions, and anonymous browser access. The generated API reference is authoritative for request schemas, responses, errors, and every operation.

POST /v1/turns returns 202 only after durable admission. Disconnecting from the request or stream does not cancel work.