Reference

HTTP API

A human-readable map of the hosted Runtime API, including authentication, errors, cursors, retries, and durable resources.

Copy the API base URL from your App's API keys page. All nvoken operations use JSON over HTTPS and bearer authentication. Server-Sent Events carry JSON payloads over a streaming response.

App creation, API-key management, and stored provider-key management happen in the nvoken dashboard. The API below is the runtime surface your backend calls after that setup.

Use this page for the shared rules and a quick map of the API. For exact fields, response shapes, and copyable cURL examples, open the interactive API reference. You can also download the public OpenAPI file.

Shared rules

Send the App's Runtime or Viewer key as:

Authorization: Bearer nvk_…

Unknown JSON fields, duplicate members, trailing values, malformed IDs, and out-of-scope filters are rejected rather than ignored.

Errors use one shape:

{
  "code": "invalid_request",
  "message": "A safe explanation for the caller.",
  "request_id": "req_…",
  "details": { "path": "/spec/model/provider" }
}

Keep request_id in logs and support reports. A 429 response includes Retry-After. The TypeScript SDK exposes the same code, status, request ID, retry information, and safe details through typed errors.

List cursors and transcript page tokens are opaque. Reuse them with the exact same filters and scope. They carry no authority on their own.

Identity

Method	Path	Purpose
`GET`	`/v1/identity`	Explain the current API key's App, profile, and constraints

Agent identities

Agents are identity anchors, not stored configurations.

Method	Path	Purpose
`GET`	`/v1/agents`	List or resolve Agent anchors
`GET`	`/v1/agents/{agent_id}`	Read one Agent anchor

Invocations

Method	Path	Purpose
`GET`	`/v1/invocations`	List authoritative Invocations
`POST`	`/v1/invocations`	Admit one durable turn
`GET`	`/v1/invocations/{invocation_id}`	Read current state
`GET`	`/v1/invocations/{invocation_id}/result`	Read the composed terminal result
`GET`	`/v1/invocations/{invocation_id}/stream`	Replay and follow one Invocation over SSE
`POST`	`/v1/invocations/{invocation_id}/cancel`	Cancel and discard unfinished work from later context
`POST`	`/v1/invocations/{invocation_id}/interrupt`	Stop at a safe boundary and keep the work
`POST`	`/v1/invocations/{invocation_id}/nudge`	Stage new direction for a running turn
`GET`	`/v1/invocations/{invocation_id}/pending-inputs`	List staged nudges and their state
`POST`	`/v1/invocations/{invocation_id}/pending-inputs/{pending_input_id}/cancel`	Withdraw a nudge not yet consumed
`POST`	`/v1/invocations/{invocation_id}/tool-results`	Submit host ToolCall results

Admission idempotency is in the request body because the key is part of the durable turn identity. Retry an uncertain response with the exact body and key.

Sessions

Method	Path	Purpose
`POST`	`/v1/sessions`	Create or resolve a Session without admitting a turn
`GET`	`/v1/sessions`	List Sessions
`GET`	`/v1/sessions/{session_id}`	Read identity, policy, usage, and active state
`PATCH`	`/v1/sessions/{session_id}`	Merge host metadata
`DELETE`	`/v1/sessions/{session_id}`	Erase the Session and its complete subtree
`GET`	`/v1/sessions/{session_id}/messages`	Page canonical messages
`GET`	`/v1/sessions/{session_id}/transcript`	Drain a fixed-cut incremental transcript
`GET`	`/v1/sessions/{session_id}/transcript/stream`	Replay and follow the transcript over SSE

Models and usage

Method	Path	Purpose
`GET`	`/v1/models`	List the curated model catalog
`GET`	`/v1/models/{provider}/{model_id}`	Inspect one exact model and its qualified controls
`GET`	`/v1/usage/daily`	Read daily usage grouped by provider and model

Model IDs may contain reserved characters. Encode the complete ID as one path segment or let the TypeScript SDK do it.

Remote MCP discovery

Method	Path	Purpose
`POST`	`/v1/mcp/list-tools`	Connect to one remote MCP server and preview its projected tools

Discovery is stateless. The server descriptor and any encrypted headers belong to the Invocation that later uses them.

Common conflict codes

Code	What the caller should do
`idempotency_conflict`	Do not retry with changed data; choose a new key for a new logical request
`session_invocation_active`	Wait, or deliberately use interrupt or supersede semantics
`invocation_not_waiting`	Refresh the Invocation before submitting more tool results
`tool_result_conflict`	Keep the first accepted result; do not overwrite it
`tool_result_expired`	The ToolCall deadline or Invocation already won the race

unavailable and transport failures can leave admission ambiguous. Retry the same idempotent request. Do not invent a second turn because the first response was lost.