API and agentsAPI reference
Agents
Drive Dezfil from AI agents: the documented API surface, served as MCP tools, plus the in-product assistant.
13 operations on 8 paths.
/api/assistant/runs
POSTReserve an assistant run
Sign-in Session cookie or Bearer token
Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Obtain a server-issued run identity bound to the authenticated account before sending a new message. Performs no model or product operation. Eight reserved, running or awaiting-confirmation runs share capacity; unused reservations expire after five minutes. Capacity refusal preserves occupied slots and points to GET /api/assistant/pending and DELETE /api/assistant/runs/{id} for recovery or release.
Responses
201
Success.
application/json401403503default
Error with a machine-readable code and human message.
application/json405
method_not_allowed: the method is unsupported for this path.
application/jsonAllowHeaderExactly the documented methods for this path.
stringalways
OPTIONS, POST
Also on this path: OPTIONS under System.
/api/assistant/runs/{id}
GETRead assistant recovery state
Sign-in Session cookie or Bearer token
Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Run receipts and parked confirmations retain their initiating account through completion, failure and deletion of any output. Deactivation interrupts unfinished execution without retaining late provider content; reactivation restores access to the same private receipts. Only the reserving account can read or control this run; another account receives 404 assistant_run_unavailable. Read reserved, running, awaiting_confirmation, completed, interrupted, failed or unavailable state, received text, attempted actions, known outcomes and the original open pending action. No replay or continuation occurs. Unknown, evicted and pre-restart identities answer 404 assistant_run_unavailable. Only the newest 256 terminal receipts are retained, each at most 64 KiB; incomplete marks omitted text or arguments. Raw tool result bodies are never retained. Live recovery is bounded to 1 MiB, with oversized proposed actions refused before execution. provenance carries the model choice the run bound and, separately, the identities its completed provider responses reported, inside those same bounds.
Parameters
idPathrequiredServer-issued run identity
string
Responses
200
Success.
application/json401403503default
Error with a machine-readable code and human message.
application/json405
method_not_allowed: the method is unsupported for this path.
application/jsonAllowHeaderExactly the documented methods for this path.
stringalways
DELETE, GET, HEAD, OPTIONS
DELETERelease an assistant reservation or abandon a pending turn
Sign-in Session cookie or Bearer token
Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Release an unused reservation (state becomes unavailable) or abandon an awaiting-confirmation turn (interrupted, pending action superseded). Neither starts model or tool work. Other states refuse with 409 assistant_run_state. Frees admission capacity; the old identity never starts new work.
Parameters
idPathrequiredServer-issued run identity
string
Responses
200
Success.
application/json401403503default
Error with a machine-readable code and human message.
application/json405
method_not_allowed: the method is unsupported for this path.
application/jsonAllowHeaderExactly the documented methods for this path.
stringalways
DELETE, GET, HEAD, OPTIONS
HEADRead response headers
Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 405, 503, defaultAllow
DELETE, GET, HEAD, OPTIONSAutomatic HEAD uses GET with no response body.
Also on this path: OPTIONS under System.
/api/assistant/runs/{id}/cancel
POSTCancel active assistant execution
Sign-in Session cookie or Bearer token
Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Stops further admission and cancels an active provider or read-only tool request. A dispatched mutation settles to its known API outcome; an unknown outcome stays uncertain and is never re-executed. Accepted asynchronous jobs retain their own lifecycle and identity. Closing the execution stream has the same effect. Completed changes remain and an already parked confirmation stays recoverable. Closing a duplicate observer or recovery read cannot cancel the execution. Read the run again to observe settlement; this request does not wait for it.
Parameters
idPathrequiredServer-issued run identity
string
Responses
200
Success.
application/json401403503default
Error with a machine-readable code and human message.
application/json405
method_not_allowed: the method is unsupported for this path.
application/jsonAllowHeaderExactly the documented methods for this path.
stringalways
OPTIONS, POST
Also on this path: OPTIONS under System.
/api/assistant/pending
GETList open assistant confirmations
Sign-in Session cookie or Bearer token
Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Returns only the caller’s open pending actions (at most eight) with runId, server-issued pending id, original tool, exact arguments and confirmation words. Includes actions whose stream event was lost; read on pane mount. Pending actions have no wall-clock expiry. This read starts no work.
Responses
200
Success.
application/json401403503default
Error with a machine-readable code and human message.
application/json405
method_not_allowed: the method is unsupported for this path.
application/jsonAllowHeaderExactly the documented methods for this path.
stringalways
GET, HEAD, OPTIONS
HEADRead response headers
Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 405, 503, defaultAllow
GET, HEAD, OPTIONSAutomatic HEAD uses GET with no response body.
Also on this path: OPTIONS under System.
/api/assistant
GETAssistant status
Sign-in Session cookie or Bearer token
Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Whether the in-product assistant is enabled. When enabled, reports the resolved provider, model, step budget and whether the map is checked automatically after a turn that changed it, and every model a request may choose on this instance with that model's own effort levels. When not, reports the reason and how to enable it. The model credential is never included. Enablement is a deployment setting (an Anthropic or OpenAI API key); with none, this is a complete non-assistant instance and the surface is absent.
Responses
200
Success.
application/json401403503default
Error with a machine-readable code and human message.
application/json405
method_not_allowed: the method is unsupported for this path.
application/jsonAllowHeaderExactly the documented methods for this path.
stringalways
GET, HEAD, OPTIONS
Examples
Read the assistant's status on an instance with a key
Needs a token. The instance has an Anthropic key and the shipped model list.
curl
curl -s http://localhost:3000/api/assistant \ -H "Authorization: Bearer <YOUR_TOKEN>"JavaScript
const response = await fetch("http://localhost:3000/api/assistant", { headers: { Authorization: "Bearer <YOUR_TOKEN>" },});console.log(JSON.stringify(await response.json(), null, 2));Answers 200 application/json
{ "enabled": true, "provider": "anthropic", "model": "claude-opus-5", "models": [ { "id": "claude-opus-5", "name": "Opus 5", "efforts": [ { "value": "default", "label": "Default" }, { "value": "low", "label": "Low" }, { "value": "medium", "label": "Medium" }, { "value": "high", "label": "High" }, { "value": "xhigh", "label": "XHigh" }, { "value": "max", "label": "Max" } ] }, { "id": "claude-fable-5", "name": "Fable 5", "efforts": [ { "value": "default", "label": "Default" }, { "value": "low", "label": "Low" }, { "value": "medium", "label": "Medium" }, { "value": "high", "label": "High" }, { "value": "xhigh", "label": "XHigh" } ] }, { "id": "claude-sonnet-5", "name": "Sonnet 5", "efforts": [ { "value": "default", "label": "Default" }, { "value": "low", "label": "Low" }, { "value": "medium", "label": "Medium" }, { "value": "high", "label": "High" } ] }, { "id": "claude-haiku-4", "name": "Haiku 4", "efforts": [ { "value": "default", "label": "Default" }, { "value": "low", "label": "Low" }, { "value": "medium", "label": "Medium" }, { "value": "high", "label": "High" } ] } ], "catalogue": { "source": "shipped", "instance": "absent" }, "stepBudget": 20, "autoCheck": true}Read the assistant's status on an instance without a key
Needs a token. The instance has no provider key, so the assistant is off.
curl
curl -s http://localhost:3000/api/assistant \ -H "Authorization: Bearer <YOUR_TOKEN>"JavaScript
const response = await fetch("http://localhost:3000/api/assistant", { headers: { Authorization: "Bearer <YOUR_TOKEN>" },});console.log(JSON.stringify(await response.json(), null, 2));Answers 200 application/json
{ "enabled": false, "reason": "No model credential is configured. Set ANTHROPIC_API_KEY or OPENAI_API_KEY (optionally DEZFIL_AI_PROVIDER and DEZFIL_AI_MODEL) and restart to enable the assistant."}HEADRead response headers
Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 405, 503, defaultAllow
GET, HEAD, OPTIONSAutomatic HEAD uses GET with no response body.
Also on this path: OPTIONS under System.
/api/assistant/policy
GETRead a page's assistant policy and default offer
Sign-in Session cookie or Bearer token
Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. For a page (builder, sql or workflow), the action policy its runs bind with, every operation that policy admits, the operations a run under that page is offered at its start (the page's relevant operations and the grounding reads, inside admission), and whether discovery is offered to reach the admitted operations the offer omits. Reports the same derivation the message route applies. Starts no work. A page outside the three answers 400 invalid_request.
Parameters
pageQueryrequiredThe page the run would carry as its context.
string
One of
builder,sql,workflow
Responses
200
Success.
application/json401403503default
Error with a machine-readable code and human message.
application/json405
method_not_allowed: the method is unsupported for this path.
application/jsonAllowHeaderExactly the documented methods for this path.
stringalways
GET, HEAD, OPTIONS
HEADRead response headers
Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 405, 503, defaultAllow
GET, HEAD, OPTIONSAutomatic HEAD uses GET with no response body.
Also on this path: OPTIONS under System.
/api/assistant/messages
POSTSend a message to the assistant
Sign-in Session cookie or Bearer token
At most 131,072 wire bytes; a larger body is refused with assistant_submission_too_large before JSON parsing. Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Reservations and pending actions are bound to their account. Every continuation reauthenticates that same account and uses its current permissions. A foreign run is unavailable; a foreign pending action is unknown. Grounding, subject reads, execution and automatic checks use the caller’s bearer-equivalent identity on every internal request. No credential is retained with a pending action. Every new message requires a runId from POST /api/assistant/runs. Unreserved requests refuse with 400 assistant_reservation_required before work. Unknown or evicted identities refuse with 404 assistant_run_unavailable. The first accepted submission binds its message, history, context and supersession. Identical concurrent or later submissions return an application/json AssistantRun snapshot without another exchange; changed input refuses with 409 assistant_run_conflict. Plain-English request; the assistant works through the same documented API these docs describe and streams its actions back as newline-delimited JSON events (application/x-ndjson): assistant text, tool calls and their results, confirmation prompts for destructive or publishing actions, and a terminal done/error. A confirm_required event pauses the run and carries a server-issued pending-action id; resolve it by posting a resolution referencing that id. Approval executes exactly the presented action once and the run continues where it paused, a decline skips it and the assistant finishes its turn. A pending action resolves at most once (409 pending_resolved on a repeat); a new message may name a pending action it supersedes (the implicit decline), after which resolution answers 409 pending_superseded. A hidden or unknown pending id cannot be resolved; naming one only to supersede it is a harmless no-op. Pending actions are working state, and bounded: after a container replacement resolution answers 404 pending_unknown and nothing re-runs; only a small number of reserved, running or parked runs share eight admission slots. A full instance refuses new reservations with assistant_capacity; live and pending runs are never silently evicted. Only unused reservations expire after five minutes. Pending turns have no wall-clock expiry and are recoverable through GET /api/assistant/pending. Release a reservation or abandon a pending turn with DELETE /api/assistant/runs/{id}. The resolved trace behind the 409 answers is bounded, so a sufficiently old repeat answers pending_unknown instead. The step budget spans the whole turn, pauses included. Submissions above 128 KiB refuse with assistant_submission_too_large before work. Terminal recovery keeps 256 receipts of at most 64 KiB; live recovery is at most 1 MiB per run and stops with assistant_recovery_limit before protected action data would exceed it. Returns 404 with assistant_disabled when no model credential is configured. The page action policy binds at the first accepted submission from the context's page and holds through the run's confirmation continuations: a builder context, and no context, admit every generated tool with its confirmation gates; a sql context and a workflow context admit only the operations that declare themselves read-only by their effects, the read-only query and the schema reads among them, and no operation that declares a write on any argument, conditional (plan or run) operations included; of the read-only ones they refuse any that reaches outside this server or asks for confirmation, a service's or a part's Test among them. The model is offered only what its run admits. A call outside the set, however it arrives, is refused before any product operation: its tool_result carries the documented error assistant_action_not_admitted and the run's receipt records the action as refused. A message may carry an optional choice of model and effort; GET /api/assistant reports what this instance offers. It binds with the rest of the submission at the first accepted one and holds through every continuation of the run; a choice on a resolution is ignored. A malformed choice, a model this instance does not offer, an effort the selected model does not offer and a named level for a model that has no levels of its own refuse with 400 assistant_choice_invalid, assistant_model_not_offered, assistant_effort_not_offered and assistant_effort_not_supported respectively, each before the run binds and before any provider call or product operation, leaving the reservation unbound and reusable. The run's receipt reports the pair it bound and, separately, the identities its completed provider responses named.
Request body
At most 131,072 bytes (128 KiB); a larger body is refused with assistant_submission_too_large.
application/json
Responses
200
A stream of newline-delimited assistant events (application/x-ndjson).
application/jsonapplication/x-ndjson401403413503default
Error with a machine-readable code and human message.
application/json405
method_not_allowed: the method is unsupported for this path.
application/jsonAllowHeaderExactly the documented methods for this path.
stringalways
OPTIONS, POST
Also on this path: OPTIONS under System.
/api/mcp
POSTMCP endpoint
Sign-in Session cookie or Bearer token
At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Model Context Protocol over the streamable HTTP transport, stateless. Supply an account API token in Authorization: Bearer on every request. Tools use the caller’s current permissions, including admin checks. Cookie callers use a short-lived server delegation tied to their session. Every internal hop rechecks current access; credentials never enter model input or retained confirmation state. Point a token-capable MCP client at this URL to get one tool per documented operation (the operation's x-tool name). External agents bring their own model; no server-side model credential is needed. The whole journey (upload, SQL, layer, style, publish) is completable through these tools.
Request body
At most 16,777,216 bytes (16 MiB); a larger body is refused with request_body_too_large.
application/json
object
A JSON-RPC 2.0 MCP message.
Responses
200
JSON-RPC response, as application/json or text/event-stream.
application/jsonobject
A JSON-RPC 2.0 MCP response.
text/event-streamstring
The JSON-RPC 2.0 MCP response as server-sent events.
401403413503default
Error with a machine-readable code and human message.
application/json405
method_not_allowed: the method is unsupported for this path.
application/jsonAllowHeaderExactly the documented methods for this path.
stringalways
OPTIONS, POST
Example
Call the tool create_map
Needs a token. Send Accept: application/json, text/event-stream; the answer arrives as one server-sent event holding the JSON-RPC response, the tool's result in structuredContent.
curl
curl -s http://localhost:3000/api/mcp \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "create_map", "arguments": {"name": "Field notes"}}}'JavaScript
const response = await fetch("http://localhost:3000/api/mcp", { method: "POST", headers: { Authorization: "Bearer <YOUR_TOKEN>", "Content-Type": "application/json", Accept: "application/json, text/event-stream", }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "create_map", arguments: { name: "Field notes" } }, }),});console.log(await response.text());Answers 200 text/event-stream
event: messagedata: {"result":{"content":[{"type":"text","text":"{\"id\":\"6a3f8d20-4c1e-4b97-a2d5-8e9f0c1b3a74\",\"name\":\"Field notes\",\"viewport\":{\"lng\":0,\"lat\":40,\"zoom\":1.3},\"basemap\":null,\"customBasemap\":null,\"basemapLayers\":null,\"note\":null,\"legendCorner\":null,\"legendOrder\":null,\"timeline\":null,\"widgets\":[],\"widgetsPublished\":true,\"publishToken\":null,\"publishedAt\":null,\"published\":false,\"createdAt\":\"2026-10-20T09:00:02.875Z\",\"updatedAt\":\"2026-10-20T09:00:02.875Z\",\"editRevision\":\"9c41e07a5d2b4f8e8a6c1d3b7e05f2a4\",\"lastChangedAt\":\"2026-10-20T09:00:02.875Z\",\"lastChangedBy\":{\"name\":\"Ana Diaz\",\"sqlName\":\"ana_diaz\"},\"projectId\":null,\"owner\":{\"name\":\"Ana Diaz\",\"sqlName\":\"ana_diaz\"},\"home\":\"ana_diaz\"}"}],"structuredContent":{"result":{"id":"6a3f8d20-4c1e-4b97-a2d5-8e9f0c1b3a74","name":"Field notes","viewport":{"lng":0,"lat":40,"zoom":1.3},"basemap":null,"customBasemap":null,"basemapLayers":null,"note":null,"legendCorner":null,"legendOrder":null,"timeline":null,"widgets":[],"widgetsPublished":true,"publishToken":null,"publishedAt":null,"published":false,"createdAt":"2026-10-20T09:00:02.875Z","updatedAt":"2026-10-20T09:00:02.875Z","editRevision":"9c41e07a5d2b4f8e8a6c1d3b7e05f2a4","lastChangedAt":"2026-10-20T09:00:02.875Z","lastChangedBy":{"name":"Ana Diaz","sqlName":"ana_diaz"},"projectId":null,"owner":{"name":"Ana Diaz","sqlName":"ana_diaz"},"home":"ana_diaz"},"history":null},"isError":false},"jsonrpc":"2.0","id":1}Also on this path: OPTIONS under System.
7439201b