The Grounded front end is a client of this API. There is no second, smaller API for integrations: what the browser calls, a script can call, with the same organisation scope and the same cited, checked answers. The interactive reference is on every instance at /docs. It is generated from the code, so it always describes the build that is running.
If you want an agent, not a script, the MCP server is the shorter road: three tools, one key, and the citations arrive as data. This page covers what MCP does not: loading documents, managing folders and sharing, reading audit packages, running golden questions, and driving the chat stream yourself.
Auth
Bearer token in the Authorization header. The token is the instance’s auth provider JWT, the same one the browser holds after sign-in. It carries the user, their organisation and whether they are an administrator, and every route checks it. Public sign-up is off, so tokens come from accounts an administrator created.
The resources
Documents (/documents) Upload, list, search, get, retry a failed ingestion, delete, move, bulk move and bulk delete, download the original, fetch the rendered view (the grid for a spreadsheet, the page for a PDF) and the chunks behind a citation. Upload is a multipart POST; ingestion runs in the background and the document’s status moves from pending to processing to completed.
Folders (/folders) Create, list, rename, move, delete, ancestors, and share or unshare with the organisation. Sharing changes visibility, not location.
Threads and messages (/threads, /threads/{id}/messages) Create a thread, post a message, read the messages back, re-check a message’s citations, leave feedback, compact a long thread, delete one or all. Posting a message returns a server-sent event stream (below).
Audit (/audit) List audit packages, read one, download it, download every package for a thread. Packages survive thread deletion by design; there is no foreign key to the thread.
Evals (/evals) Your golden questions: create, edit, delete, seed the defaults, start a run, read a run’s results. This is the API the in-app evals page and the CLI suite share.
Notes (/notes) Notebook notes with their trust tier, which retrieval treats as a source beside the documents.
Skills (/skills) List, create, import from a file or a URL, export, share with the organisation, and manage a skill’s files. The six close skills and reconciliation are skills in this sense.
Harness (/threads/{id}/harness) Start an advisory or other multi-phase run on a thread, read its state, cancel it.
Also: /home/summary for the dashboard numbers, /settings/models for the model allow-list, /connections for the instance’s MCP connections (read-only), and /auth/me for who the token is.
The chat stream
POST /threads/{thread_id}/messages with
{"content": "Does the cash in the May pack tie to the bank?", "deep_mode": false}returns text/event-stream. Each event is one JSON object on a data: line. The ones a client needs:
- text_delta: a fragment of the answer, in order
- citation_metadata: the citations list once the answer is grounded, each with the source, page or sheet and cell range, the quote and its verification status
- citation_alias: the [S#] marker to citation mapping
- agent_status, tool_call_start, tool_call_complete, skill_activated: what the agent is doing, for a progress line
- redaction_status: the PII pass ran
- error: the run failed, with a message Concatenate the text deltas, keep the citation metadata, and you have what the browser shows. The MCP server’s ask_grounded is exactly this client. It is forty lines long.
One example, end to end
- POST /threads {“title”: “May close check”} → thread id
- POST /threads/{id}/messages {“content”: ”…”} → stream, collect deltas and citation_metadata
- GET /documents/{document_id}/render?sheet=Summary → the grid the citation points at, to show the cell
- GET /audit/packages?thread_id={id} → the audit package for the answer That is four calls for one cited, checked answer and the audit record behind it.
Reference
/docs on your instance: the full OpenAPI reference with request and response models, generated from the code. /openapi.json for the schema itself.
What is not here
There are no webhooks yet. The REST layer has no API keys beyond the auth provider’s JWT, so a service account is created the same way as a person. Rate limits are whatever the host applies. All three are on my backlog, listed on the engineering record.
Related
Technical: MCP · Security and data · Engineering record. Use case: Ask it from Slack or Claude. Post: What is an API, actually?.
