Agents and durable runs
Define governed agents, attach knowledge and tools, and execute bounded workflows.
Agents package a persona, model policy, optional knowledge, and tool grants. Use one-shot invocation for a single governed completion or create a durable run for multi-turn tool execution, approval, retry, and checkpointing.
Available external Blinqs with an accepted current version appear in the shared
template catalog. Their summaries carry executor_mode: "external" and a
setup_required boolean. A release that declares tools for a connected account
sets it to true. Use the status of the installed Blinq to decide whether its
owner still needs to complete setup.
An external manifest can include a bounded presentation object with name,
description, color and avatar. It is frozen into that version's digest.
Omitting it preserves earlier digests and uses the registered name with generic
presentation. Promotion appends an immutable template edition; pinning an older
version selects its saved edition. Template edition numbers are separate from
Blinq version numbers. Applications cannot publish or rewrite these definitions.
Create an agent
curl -H "Authorization: Bearer $DEEPLINQ_TOKEN" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v1/agents" -d '{
"owner_type":"user",
"owner_id":"user-42",
"name":"Mailbox triage",
"description":"Find and summarize billing email.",
"persona":"Be concise. Never send email without explicit approval.",
"default_model":"gpt-5-mini",
"allowed_models":["gpt-5-mini"],
"temperature":0.2,
"tools":[
{"tool_name":"email.search","policy":"auto"},
{"tool_name":"email.send","policy":"requires_approval"}
]
}'Agents can belong to a user, team, or org. Creation and management
authority follows that owner.
Hire and configure a Blinq
Blinq is the SaaS name for a personally hired agent based on an Engine-owned agent template and an immutable edition. The Engine provides the same eight built-in templates and 24 jobs across its applications. The existing tenant model is unchanged: each tenant belongs to an Engine application. An integrator does not need SaaS, a template publication step or a copy of the definitions to use them.
The shared template defines expertise, setup questions, allowed preferences, named jobs and ordered workflows. The Engine also supplies its name, description, color, avatar and hiring availability. It reuses the existing agent, conversation, tool-grant, knowledge, run, approval and checkpoint services.
Only template content and presentation are shared. Each person's hire, answers, preferences, connections, grants, attached knowledge, conversations and runs stay within their existing owner and tenant access boundaries. A common template does not share a person's data with another hire or application.
Ordinary agents keep the create/invoke/run behavior described elsewhere on this
page. Governed hires enter through trusted hiring and job routing; supplying a
persona or legacy blueprint in an ordinary create request cannot publish a
template or replace its protected workflow.
Before enabling hiring, follow the Blinq rollout constraint. Every replica and worker must support governed workflows before accepting hires.
Discover built-in templates
Use the tenant's normal authentication to read the catalog:
GET /v1/agent-templatesThe response is { "items": [...] }. Each item carries role_id, edition,
name, description, color, avatar and availability; it does not contain
expertise or workflow instructions. color is a six-digit hex color and avatar
is the neutral "agent" token; a consuming product may render its own matching
agent artwork, as SaaS does with the Blinq mascot. Render those values from the
Engine instead of maintaining an application-owned list of known roles. The built-in templates
are Executive assistant, Sales assistant, Customer support, Finance assistant,
Marketing assistant, Operations coordinator, People assistant and Business
analyst, with three jobs each.
availability: "available" permits a new hire. "coming_soon" is a display-only
entry with edition: 0; show it as planned and do not offer hiring. Available
entries have a positive edition. All eight current built-ins are available. Availability does not replace the per-job readiness checks for
the owner's answers, tools and knowledge.
Read GET /v1/agent-templates/{role}/editions/{edition} for a full available
definition and its presentation. After hiring, use GET /v1/agents/{id}/template
to read that hire's exact pinned definition. The Engine owns immutable editions;
applications cannot publish or replace their content. Reading the latest
catalog is not a substitute for reading a saved hire's pinned template. The
setup response's nested role remains the executable definition without
presentation fields. Fields such as role_id, role_edition and nested setup
role keep their wire names.
The migration preserves existing hires, answers, preferences, history and work by binding an old application-owned definition to its identical Engine edition. If a referenced definition does not exactly match, migration fails instead of changing the hire's workflow, exposing private content or discarding its state. There is no application-owned template catalog at runtime.
Hire with the owner's identity
POST /v1/agent-templates/sales-assistant/instantiate
{"edition":1,"model":"gpt-5-mini"}The response is the agent view, including id, role_id, role_edition and status.
Omit edition, or send zero, to choose the latest when first hiring. Repeating
a hire returns the same personal identity, even if a newer edition now exists.
Names do not determine identity, and other owners can hire the same role.
Instantiating a planned entry is refused (404); it cannot begin setup or work.
A matching personal legacy deeplinq/<role>/vN blueprint can be adopted by this
explicit hire request. Adoption preserves the name, model settings and grants
while replacing protected expertise with the trusted definition. Multiple
matching legacy hires return a conflict rather than guessing. Retained legacy
custom_instructions do not become workflow authority. Legacy blueprints that
have not been adopted keep their existing ordinary-agent behavior.
Install an external Blinq
Call the same install route with the device's IANA time_zone, such as
Africa/Dakar. Include a permitted model supported by the release. Pass the
current edition or omit it to select the current edition. The Engine refuses a
missing, blank, Local or unknown timezone before saving an install.
For the install-first flow, omit name and tool_connections. Read the
returned agent's status on install and whenever its owner reopens it.
setup_requiredmeans the Blinq is saved. It has no schedule or activation run. Open a dedicated setup page and offer two actions, finish setup or uninstall.activemeans the Blinq can start work. A release without required setup reaches this state at installation. A client that already has a valid name and account selections for a connected-tool release can supply both in the install request to activate it in one step.disabledmeans a previously configured Blinq is paused. Reopening it preserves that choice.
Read GET /v1/agents/{id}/tool-connections for the installed edition's tools
and saved selections. To finish setup, send the owner's chosen name and at
least one active personal account offering a declared tool. For example, an
edition with email access accepts the following request.
PATCH /v1/agents/{id}
{"name":"My assistant","tool_connections":{"email":"36ff76e1-959f-4806-bb92-489ed43c6729"}}The keys email, calendar and files grant each service separately, even
when two services use the same account. Email and Calendar support Google and
Microsoft accounts. Files supports Google Drive.
A successful response reports status: "active". The Engine saves the name
and selections, activates the Blinq, creates its private schedule and first
run/task, and records the audit events in one transaction. The first run uses
the activation time and the install's saved timezone. A failed submission
leaves the pending install in place so the owner can correct it and retry.
The owner can instead uninstall it with DELETE /v1/agents/{id}.
Installation and activation make no model call and spend no credits.
After activation the owner can use the same patch to rename the Blinq or
replace its selections. Omitting tool_connections preserves the saved
selections. An empty object removes all tool access from a configured
Blinq. Revocation takes effect at the next account read.
For example, Execute delivers meeting briefs, commitment reminders and requests for missing access to the owner's Inbox. Reply in that thread to request a brief, choose a suggested commitment to track, list open items or mark one done.
Repeating or concurrently sending the initial request returns the same hire. Each external retry still names a valid timezone, but the original saved zone does not change. Retrying a complete disabled hire leaves her off and creates no new welcome job. The first run retains its original instant, local date, timezone, version and state snapshot. External hires have no setup conversation; the chat operation below is for internal governed templates.
If an active hire is missing her schedule or first job, the retry restores it before returning the hire. It uses the original saved timezone and start rules. A newly admitted run still uses the current approved version. A finished first job counts as history and never permits another welcome. Repair is atomic: failure leaves the original partial state. An incomplete off hire refuses repair and starts no work. Missing original metadata or jobs removed by an incompatible release is refused explicitly; no device-zone fallback is used. A busy hire returns a retryable conflict.
Begin the real first chat
For a built-in Blinq, read GET /v1/agents/{id}/setup after installing it.
When shared_ready is false, the owner finishes the shared requirements on
the setup page or uninstalls the Blinq. Once those requirements are ready,
open the Blinq's conversation. Each job still checks its own requirements.
POST /v1/agents/{id}/setup/chat
{"request_id":"31557aaf-3307-4b9b-9471-d1c31bb5b88e"}This begins or resumes one saved conversation for the hire. Opening it creates no model completion. The response includes:
setup: saved answers/preferences,revision, the pinnedrole, liverequirementsand per-jobjobsreadiness;conversation_idand persistedmessages, each withid,role,contentandcreated_at;- optional
question: {key, prompt}for the next missing answer; - optional
pending_job: {job_id, request_id, run_id?, ready, missing}for the router's saved job request.
Reply naturally using the latest setup revision:
POST /v1/agents/{id}/setup/chat
{"request_id":"8f057586-afdc-45e6-a89a-36ed7471557d","expected_revision":0,"message":"We run a bakery in Lisbon and supply nearby offices."}The existing governed chat service distinguishes an answer from a clarification
question such as “Why is this needed?” It has no business tools. Only the owner's
screened text becomes an answer; the model cannot invent the saved value.
answer_key is optional for a deliberate answer control, and must name the
current question. Ordinary chat clients should omit it.
Reuse the same request_id and body when delivery is uncertain. A completed
retry returns current setup and history, even after newer changes. A claimed
reply whose result cannot be confirmed returns a conflict instead of silently
calling the model again. Answers and their transcript reply commit together;
failed output screening does not partially save an answer. Configured agent
text blocks/redactions apply to input, context and output. This is not a claim
that every possible secret can be detected; connection credentials belong in
the existing connection flow.
Standard conversation reads expose agent_id for this bound history (empty for
ordinary chats). Reopen it through the Blinq flow. Generic chat, ordinary-agent
invoke and unrouted or wrong-agent runs cannot use that binding to bypass the
workflow. The transcript can also contain tool turns after work has run; clients
must handle those roles when reopening it.
Check readiness and correct saved setup
GET /v1/agents/{id}/setup recalculates readiness rather than trusting a saved
“ready” flag. Each requirement is ready, missing or unavailable, with a
human-readable reason when action is needed. Shared requirements affect every
job; each job's own requirement keys affect only that job. Requirements unused
by a job are optional for that job.
An answer must exist. A tool needs its exact agent grant, current policy and
caller availability; connection-free engine tools such as browser.fetch do
not need an OAuth connection. Knowledge requires attached datasets and current
access under the run's execution identity. Access failures never count as ready.
One job's unavailable mailbox does not block another job that does not use it.
Use revision-checked edits to correct answers or allowed preferences:
PATCH /v1/agents/{id}/setup
{"request_id":"96f5f7ed-345b-49ec-a1c1-87ae7ceebf06","expected_revision":1,"answers":{"sales_context":"We supply offices in Lisbon and Porto."},"preferences":{"tone":"Warm and conversational"}}Null clears one value. Answers accept only declared answer keys, and are
bounded to 4,000 UTF-8 bytes each. Preferences accept only declared keys, exact
choice options or bounded text values. The saved maps together are limited
to 32 KiB. Free-text edits use the configured agent screening layer. Unknown
controls, stale revisions, or reusing a request ID for different input are
refused. An exact retry returns the latest state rather than erasing a newer
edit.
The built-in hire's name, active/disabled status, tool grants and attached knowledge still
use the existing agent controls. Catalog availability belongs to the Engine.
The generic agent patch cannot change a governed hire's expertise, model
controls or custom_instructions; use declared preferences.
Saved context is data, not permission to remove a step, grant a tool or skip an
approval. Later jobs use corrected preferences; work already in progress keeps
its saved input snapshot and continues to obey current access checks.
Request a declared job
POST /v1/agents/{id}/jobs
{"conversation_id":"<setup-conversation-id>","request_id":"484c0af2-d16b-4d8d-956a-8eb3d1838934","message":"Draft a proposal for a weekly breakfast delivery to Acme."}The router chooses only among the role's declared jobs. It persists the original
request and selected job before work starts. The response has kind:
| Kind | Result |
|---|---|
started (202) | run_id identifies the existing durable run. |
setup (200) | The selected job needs answers or access. Resume the setup chat; it asks this job's missing questions. |
clarification (200) | message asks for the detail needed to choose a job. |
unsupported (200) | The role has no matching job; it does not fall through to unrestricted execution. |
After completing missing setup, resume the saved original request:
POST /v1/agents/{id}/jobs
{"conversation_id":"<setup-conversation-id>","request_id":"<pending-job-request-id>","resume":true}Do not send message or replace_pending with resume:true. A new message does
not silently overwrite unfinished work; use replace_pending:true only when
the owner deliberately replaces that pending selection. Request receipts and
the run link prevent a delivered-again request from creating a second run.
Uncertain routing/model outcomes are surfaced instead of automatically retried.
Poll the existing run and approval surfaces below. The run's optional
workflow object reports the pinned role_id, role_edition, job_id,
step_count, zero-based step_index, current attempts, saved inputs and
completed-step evidence. Input keys separate answer:<key> from
preference:<key>. This state is engine-owned and never accepted from a public
run-create body.
What the workflow enforces
Every job covers the declared core stages in order. Consecutive steps may share
a stage; there are no jumps or general-purpose loops. finish is the last step.
max_attempts is bounded to one through three; it does not authorize blind
retries of external actions.
| Step kind | Required behavior |
|---|---|
reason | Produce a bounded nonempty result for the current step. |
knowledge | Retrieve from currently permitted attached knowledge and provide source evidence; missing access or sources cannot pass. |
tool | Use only the step's exact allowed tools with current grants/policy; tool_success needs a confirmed successful result. |
finish | Complete only after earlier required steps have passed. |
Every step includes nonempty. Knowledge steps require sources. Tool steps
require tool_success; a step with approval_required:true also requires the
approval check. Tool definitions must refer to declared tool requirements.
Neither a model claim nor a failed result is proof that an action happened.
Approval stays bound to the parked action. Denial, revocation, known failure and an uncertain action result cannot be reported as successful completion. Failed actions are not blindly retried; uncertain actions retain an explicit uncertain failure reason for investigation. Progress and evidence share the existing atomic run checkpoint, and committed action results are reused after restart.
These controls make the sequence, authority and completion checks predictable. They do not make model prose deterministic or prove every statement correct. Blinqs can hold both tool grants and knowledge for their separate checked steps; ordinary agents retain the restrictions below. Generic invoke/run creation and schedules are not alternate entry points for governed Blinq jobs.
Tool policy is either:
auto: the durable run may execute it;requires_approval: the run parks before execution.
policy is optional. Omit it and the default follows the tool's origin:
first-party tools default to auto, while tools from a registered MCP server
(mcp/<slug>/<tool>) default to requires_approval — that server is operated
by a third party and can change what a granted tool name does. Running one
unattended is possible, but you have to say "policy":"auto".
Agents never store provider or connection credentials. Tools resolve from the invoking owner's current connections.
Attach knowledge or tools
Replace the attached dataset set:
PUT /v1/agents/{id}/datasets
{"dataset_ids":["<dataset-id>"]}Attached datasets are caller-filtered at invocation time. The response reports attachments the caller cannot access rather than using agent ownership as a confused deputy.
For ordinary agents, tool grants and datasets are mutually exclusive in the current one-shot retrieval design. A governed Blinq uses the checked job path above for knowledge and tool steps.
An ordinary agent with attached datasets cannot start a generic durable run.
That path does not retrieve its attached knowledge. Governed Blinq jobs use
checked knowledge steps instead. POST /v1/agents/{id}/runs now answers
409 agent knowledge is not supported by durable runs; use invoke before any
side effect. No backing conversation, no run row, no job, no audit write, no
input screening, and no model spend happens. Use one-shot invocation, which keeps its
retrieval path unchanged, or replace the attached set with an empty one to make
the agent runnable again.
One-shot invocation
curl -H "Authorization: Bearer $DEEPLINQ_TOKEN" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v1/agents/$AGENT_ID/invoke" -d '{
"message":"Find invoices received this week.",
"model":"gpt-5-mini"
}'One-shot invocation can return tool calls but does not execute
requires_approval tools server-side. Use a durable run for managed execution.
Start a durable run
curl -H "Authorization: Bearer $DEEPLINQ_TOKEN" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v1/agents/$AGENT_ID/runs" -d '{
"message":"Find the latest invoice and draft a reply asking for line-item detail.",
"max_turns":8,
"credit_budget":500000
}'The response identifies an asynchronous run. Poll:
GET /v1/runs/{run_id}
GET /v1/runs?agent_id={agent_id}&status=running
GET /v1/runs?schedule_id={schedule_id}
GET /v1/runs?conversation_id={conversation_id}schedule_id filters to the fire history of one
scheduled agent task;
conversation_id filters to one thread of runs. Run
listing and run detail stay owner-only for every role, so an org-admin who may
administer a schedule still does not see its run content, and another person's
thread lists as an empty page rather than a refusal.
Each turn holds a database-time lease, performs model or tool work, and commits a durable checkpoint. Restarts and replica changes do not discard committed progress.
Choose which mailbox a run uses
The email.* tools are declared by both mail providers. When the caller has
Gmail and Outlook connected, the engine's default serves a call through the
longest-standing connection with providers in catalog order — Gmail. To have a
run read another mailbox, name the connection on either create route:
{
"message": "Read my flight itinerary and add the flight to my calendar.",
"model": "gpt-5-mini",
"connection_ids": ["<outlook-connection-id>"]
}Each id must be one of the caller's own active connections (GET /v1/connections); any other is 404. The run view echoes the list as
connection_ids, and a preferred connection that is no longer active falls back
to the default rather than failing the call. An empty list changes nothing.
Name the dataset or the project a run reads
dataset_id names the dataset the task reads through. It is optional on both
create routes, and the run view echoes it as dataset_id, null when the run
has none:
{
"message": "How many orders shipped late last quarter?",
"model": "gpt-5-mini",
"dataset_id": "<dataset-id>"
}The engine checks the id at create with the identity the RUN will execute
under, and that identity carries no roles. Read access that survives losing
the roles is: owning the dataset, a direct user grant on it, a team grant on
it, owning the project the dataset belongs to, or a user or team grant on that
project. A dataset shared only through a role — the ownerless organization
dataset with a role:org-member read grant — is therefore not usable as a
run's dataset, and is refused exactly like a dataset that does not exist.
Unknown, unreadable and malformed ids all answer 404, with no way to tell
them apart. The id is stored in canonical form, so any accepted spelling comes
back as the canonical 36-character lowercase uuid.
project_id names a project instead, and a task started in one reads the
whole of it — the project's own files plus the datasets attached to it:
{
"message": "How many orders shipped late last quarter?",
"model": "gpt-5-mini",
"project_id": "<project-id>"
}The two fields are mutually exclusive: sending both is 400 project_id and dataset_id are mutually exclusive. A project is a set of datasets, so naming
one of each says two different things about what the run reads.
POST /v1/schedules
is the one door that takes the pair, and it says which one wins.
The project is checked exactly as the dataset is — at create, with the
roleless identity the run executes under — so a project shared only through a
role:org-member grant is not usable by the run. Unknown, unreadable and
malformed all answer 404 project not found, with no way to tell them apart.
The role-only project is the one exception, and it answers 400 instead:
{ "error": { "type": "invalid_request", "field": "project_id",
"message": "project_id: a task runs without your organization roles, and this project is shared with you only through one" } }You can open that project yourself and your task cannot, so 404 would be a
lie. The engine only reaches this answer by asking a second time with your own
roles after the roleless ask refuses, and only when that second ask succeeds —
a project you cannot see is refused by both and keeps the flat 404, so the
door never confirms which project ids exist. Both create routes answer this
way, and so does POST /v1/schedules with an agent_run task. The remedy is
a grant that survives losing the roles: the project given to you directly, as
a user or a team.
Unlike dataset_id, the project belongs to the run's thread rather than
to the run row. It is written on the conversation the run opens, so:
- the run view echoes it as
project_id,nullwhen the thread is in no project; - a follow-up run (
conversation_id) inherits the thread's project and need not send anything. Naming a different one is400 a follow-up keeps its thread's project, and sendingdataset_idon a follow-up whose thread is in a project is400 a follow-up cannot name a dataset: its thread is in a project; - a schedule's
project_idis written on every fired run's conversation, so every run of a scheduled task reads the same project.
Placing a task in a project also files its thread there: the conversation appears wherever that project's conversations do.
Query a dataset's tables
dataset.query is an engine tool: the engine executes it, not a connection
and not the runner. It answers a question about the tabular files in one
dataset — CSV files and Excel sheets, one table per file or sheet — from a
question in plain words, which the engine turns into a read-only DuckDB
SELECT, or from a statement you write yourself. One query reads one table;
a run started with project_id may reach any table in the project — across
at most ten of its datasets, the same ceiling a project's scope carries
everywhere else — and the engine records which dataset the table was found
in.
A run is granted the engine's tools automatically in exactly one shape: a
create body that omits tools — POST /v1/runs, and the message + model
schedule shape. That runner is granted what its person can reach, and the
engine asks the same roleless identity the run executes under whether the
caller can read at least one dataset, or failing that at least one project. A
caller who can read neither is not offered dataset.query — or
ui.surface, which needs a query and therefore a
dataset just as much — rather than being offered tools whose every call they
would have to refuse. Both engine tools only read, so the reach grants them at
auto. POST /v1/runs re-takes that reach on every request; a schedule takes
it once, when the schedule is created.
Both other shapes bypass the reach gate, and in both you must ask for each tool by name:
toolspresent. The runner is granted exactly the names you sent, at the catalog's default policy, and is never re-synced. Includedataset.queryamong them — andui.surfacetoo if the task should answer with an interface — or the run cannot call it; an explicit[]is a runner with no tools at all.POST /v1/agents/{id}/runs. The named agent's own grants decide, so each engine tool you want has to be one of them (PUT /v1/agents/{id}/tools).
| Argument | What it is |
|---|---|
dataset | Optional. The dataset to read, by id or by its exact name, matched case-insensitively among the datasets the caller can read — a project's files are named by the project. Omitted, the run's own dataset_id is used; with neither, the run thread's project, if it has one; with none of the three the call is refused. |
table | The table to read. Optional with question — the engine picks the table the question fits — and required with sql. Without dataset, a project-scoped run resolves the name across every dataset of the project. |
question | What to compute, in plain words. |
sql | An explicit read-only SELECT over one table. |
calculation | A typed row count or numeric sum, with optional population predicates, grouping, ranking and target selection. Requires table. |
max_rows | Optional. Omitted means 2000, which is also the cap; a larger value is cut to 2000. A value below 1 is refused by argument validation — the schema declares a minimum of 1 — rather than raised to anything. |
Exactly one of question, sql and calculation. A question is turned into a
SELECT by the engine, validated, and repaired once if the statement is
rejected; an explicit sql is validated and run as given, never repaired, and
must name its table. Writing the statement is a model call like any other: it
is billed to the organization and counted in the run's credits.
Extract one row per document
dataset.extract is the engine's third tool, and it is the other half of
dataset.query: where a query reads a table that already exists,
dataset.extract makes one out of documents that are not tables at all.
It reads every PDF, Word, PowerPoint, text, Markdown or HTML document the
selector covers, once each, with the fields you name — and writes one typed,
source-linked row per document into a new table in the dataset, which the next
call can query and a surface can bind exactly like any uploaded spreadsheet.
It is granted on the same reach gate as dataset.query and ui.surface: a
run whose create body omits tools is offered it when the caller can read at
least one dataset or project, and the other two shapes must ask for
dataset.extract by name.
It writes, so it stops for approval. A run that calls it parks at
awaiting_approval with a pending dataset.extract, and
POST /v1/runs/{id}/approve resumes it — the same gate email.send gets, and
for the same reason. See Handle approval.
It names one destination. A new table has no existing table to be found
by, so the tool never searches: the run's own dataset_id is where it writes,
or the attachment store of the run thread's project, and the caller must hold
write on it. With neither, the call is refused dataset.extract writes a new table, so the task has to run in a project or name a dataset with dataset_id.
| Argument | What it is |
|---|---|
table | Required. The name of the table this extraction produces: lower-case letters, digits and underscores, starting with a letter or underscore, at most 63 characters. |
fields | Required. 1 to 16 entries, each {name, type, description}. name follows the same SQL-safe rule and is unique within the schema; description is 1 to 200 characters and is what the model reading each document is shown. |
where | Optional. Which of the dataset's documents this definition covers: filename (a glob over the base filename, e.g. *.pdf) and types (extensions, e.g. ["pdf","docx"]). Omitted means every non-tabular document. |
A field's type is one of text, number, boolean, date and text[],
and the type is enforced at the boundary rather than trusted:
numberis a plain JSON number, and lands asDOUBLE.booleanistrueorfalse, and lands asBOOLEAN.dateisYYYY-MM-DDexactly, and lands asDATE.text[]is a JSON array of strings, stored", "-joined in oneVARCHARcolumn.textis a string, and lands asVARCHAR.
A value the document does not state is null, never guessed. A value that is
stated but fails its declared type also becomes null, the failure is
recorded on the row's error, and the row still counts as read — one bad
field does not throw away the other fifteen.
Three column names are the table's own and cannot be used as field names:
source_document (the document id the row came from), source_file (its
filename) and source_status (whose values the row carries: current, or
previous_file — see below). values and evidence are reserved as well —
they are the envelope's own keys. The projected table's columns are
source_document, source_file, source_status, then your fields in declared
order.
An extraction of a folder of CVs looks like this:
{
"table": "candidates",
"fields": [
{"name": "full_name", "type": "text", "description": "the candidate's full name as written"},
{"name": "years_experience", "type": "number", "description": "total professional experience in years"},
{"name": "worked_in_finance", "type": "boolean", "description": "held a role at a bank, insurer or fund"},
{"name": "languages", "type": "text[]", "description": "languages spoken"}
],
"where": {"filename": "cv-*.pdf"}
}The answer says only what is true when it is said — the definition exists and the documents are staked; the rows land as they are read:
{
"table": "candidates",
"fields": ["full_name", "years_experience", "worked_in_finance", "languages"],
"documents": 5,
"rows_ready": 0,
"message": "Reading 5 documents into candidates. Rows land as documents are read; a follow-up on this thread can query and bind the table."
}fields in the answer is the column NAMES, which is what a follow-up
dataset.query needs. A tabular file is never a candidate whatever the
selector says — a CSV or a spreadsheet is already a table.
The definition STANDS. It is not one batch: a document uploaded into the
dataset afterwards joins it automatically, under the same schema, with no
second call and no run. Calling the tool again with the same table, the same
fields and the same where reports progress and stakes nothing new. Change
any of them and the next generation opens: every matching document is
re-read under the new schema, and the previous generation's table stays
queryable until the new one publishes. At most 200 documents may be covered by
one definition; more is refused, naming the count so you can narrow where.
A document whose content changes after its row was read is read again,
with a new model call — a
replaced file, for instance.
Until the re-read lands, its row stays in the table with the previous file's
values and source_status previous_file; every other row reads current.
A re-read that succeeds makes the row current with the new values; one that
fails takes the row out of the table, and the rows read shows it failed.
Each extraction owns a resource in the dataset, so it appears in the resource
listing and DELETE /v1/datasets/{id}/resources/{rid} removes the definition,
its rows and its table together.
Arguments are refused the way a surface is — an error word and every problem located by JSON Pointer, so a model repairs the argument it got wrong:
{
"error": "extraction refused",
"problems": [
{"path": "/args/fields/2/type", "message": "unknown type \"money\"; one of text, number, boolean, date, text[]"}
]
}Read what an extraction has done
Three routes read a dataset's extractions. Each is mirrored under
/v1/projects/{id}/... through the project's attachment store — read access
for the two GETs, write access for the retry.
GET /v1/datasets/{id}/extractions lists the dataset's standing definitions
with their progress:
{
"extractions": [
{
"table": "candidates",
"fields": [{"name": "full_name", "type": "text", "description": "the candidate's full name as written"}],
"where": {"filename": "cv-*.pdf"},
"generation": 1,
"published": true,
"rereading": 0,
"coverage": {"documents": 5, "current": 4, "previous_file": 0, "missing": 1, "reading": 0, "complete": false, "published_revision": 7},
"model": "gpt-4.1",
"run_id": "run_01J…",
"credits_spent": 1840,
"counts": {"queued": 0, "extracting": 0, "done": 4, "failed": 1, "skipped": 0},
"created_at": "2026-09-19T09:12:04Z",
"updated_at": "2026-09-19T09:13:41Z"
}
]
}published is true only when the queryable table IS this generation at this
revision — a table left over from the previous schema, or one missing rows
that have already finished, reads false. where carries only the keys the
selector actually set, so an unrestricted definition's is {}.
coverage describes the published table, counted from the same snapshot its
rows were built from, and is null until the first publish. Of the
documents in scope, each is current, previous_file (values kept from a
replaced file while it is read again), missing (its row failed or was
skipped, or its document's ingest failed) or reading (not read yet, or its
document is being ingested again).
complete is true only when previous_file, missing and reading are all
0; otherwise a total over the table is partial. published_revision names
the snapshot the counts describe. rereading is live rather than the table's:
how many rows hold the previous file's values and are queued or
extracting right now.
GET /v1/datasets/{id}/extractions/{table}/rows?cursor= is one keyset page of
50 rows of the current generation, oldest first, with next_cursor empty on
the last page:
{
"rows": [
{
"id": "exr_01J…",
"document_id": "doc_01J…",
"source_file": "cv-amina.pdf",
"state": "done",
"values": {"full_name": "Amina Haddad", "years_experience": 8, "worked_in_finance": true, "languages": "French, Arabic, English"},
"evidence": {"full_name": "Name: Amina Haddad", "years_experience": "Experience: 8 years", "worked_in_finance": "Finance: yes", "languages": "Languages: French, Arabic, English"},
"flags": {},
"from_previous_file": false,
"error": "",
"attempts": 1,
"updated_at": "2026-09-19T09:13:40Z"
}
],
"next_cursor": ""
}state is one of queued, extracting, done, failed and skipped
(skipped with error: "over_cap" is a document past the 200-document
ceiling). evidence is a verbatim quote of at most 200 characters per stated
value, copied from the document — and it is checked: flags carries
evidence_unverified when any quote does not appear in the document it came
from, and truncated_input when the document was longer than the model was
shown. Neither flag fails the row; both are there so you can see which values
to trust. values, evidence and flags are always objects, never null.
from_previous_file is the rows read's twin of the table's source_status:
true when the values were read from a file the document no longer holds. A
queued or extracting row being read again carries them, marked so.
POST /v1/datasets/{id}/extractions/{table}/retry puts back everything
waiting can fix — the failed rows, and the rows that stalled on credit — and
answers 202 with the number it re-queued:
{"restaked": 1}While a worker still holds one of the table's rows it answers 409
extraction_in_progress with an extraction is in progress; retry when it has finished.
The two GETs answer 404 for a {table} that is not one of the dataset's
extractions and for a dataset this caller cannot read — the same refusal
an unknown id gets, so a listing never tells you that somebody else's dataset
exists. The retry is a write, and answers by tier instead: 403
dataset_write_required for a caller who can read the dataset but not write
into it, and 403 forbidden for one with no access to it at all.
Billing. The tool itself reads no document and calls no provider; it
checks that the batch is affordable and refuses insufficient_credits or
user_limit when it is not, creating nothing. The real cost is one model call
per document, billed as it happens and reported on the definition's
credits_spent. Work already accepted can still pause for credit — such rows
stay queued with error: "insufficient_credits" and are picked up again
within five minutes, or immediately by retry.
Count or rank with a typed calculation
Use calculation when the task needs an explicit count, total or rank whose
scope must travel with the result. A count of completed transactions is:
{
"table": "transactions",
"calculation": {
"metric": {"op": "count"},
"population": [
{"column": "status", "op": "eq", "value": "completed"}
]
}
}count counts matching rows and takes no column. sum requires one numeric
column. Population predicates are applied before aggregation; the supported
operators are eq, ne, in, gte and lt. A calculation accepts at most
16 predicates, and an in predicate accepts 1 to 100 values. Values are
typed JSON literals, not SQL expressions.
This ranks six observed calendar months by net amount, smallest first, then returns August's row:
{
"table": "transactions",
"calculation": {
"metric": {"op": "sum", "column": "net_amount_usd"},
"population": [
{"column": "transaction_date", "op": "gte", "value": "2026-03-01"},
{"column": "transaction_date", "op": "lt", "value": "2026-09-01"}
],
"group_by": {"column": "transaction_date", "transform": "month"},
"rank": {"direction": "asc"},
"target": "2026-08-01"
}
}The population fixes the rows being compared. target is applied only after
those rows are grouped and, when requested, ranked, so it selects August
without shrinking the six-month comparison to August. rank and target each
require group_by, but either can be used without the other.
The month transform accepts a DATE column only; timestamps are refused
because they need an explicit timezone policy. Only months observed in the
source are returned—missing months are not inserted.
Ascending or descending ranking uses SQL RANK: equal numeric values share a
rank and leave a gap after the tie. Null group keys are excluded from a ranked
population and counted in excluded_null_group_rows. A group whose sum is
null remains visible when no target removes it, but its rank is null and it is
not included in the ranked population_size. A sum with no finite value stays
null rather than becoming zero.
The result uses stable columns: group_value when grouped, metric_value,
and, when ranked, rank and population_size. The tool result also gains an
optional server-owned calculation object:
{
"query_id": "q_9f2c1ab40e57",
"table": "transactions",
"columns": ["group_value", "metric_value", "rank", "population_size"],
"preview_rows": [["2026-08-01", 76856, 4, 6]],
"preview_truncated": false,
"capture_rows": 1,
"total_rows": 1,
"truncated": false,
"calculation": {
"definition": {
"version": 1,
"source": {
"dataset_id": "8a73e7d1-5c91-4f38-9c16-55b16a4ad037",
"table_id": "cb874f32-96c8-49fa-92b0-f46edc64fc2f",
"table": "transactions"
},
"metric": {"op": "sum", "column": "net_amount_usd"},
"population": [
{"column": "transaction_date", "op": "gte", "value": "2026-03-01"},
{"column": "transaction_date", "op": "lt", "value": "2026-09-01"}
],
"group_by": {"column": "transaction_date", "transform": "month"},
"rank": {"direction": "asc"},
"target": "2026-08-01",
"output_columns": [
{"name": "group_value", "meaning": "group key"},
{"name": "metric_value", "meaning": "row count or sum; null means no finite sum"},
{"name": "rank", "meaning": "RANK among non-null groups with finite metrics; ties leave gaps"},
{"name": "population_size", "meaning": "number of groups eligible for ranking before target selection"}
],
"literal_text": {}
},
"execution": {
"executed_at": "2026-09-14T12:00:00Z",
"population_size": 6,
"excluded_null_group_rows": 2,
"target_outcome": "present"
}
},
"usage": {"input_tokens": 0, "output_tokens": 0}
}execution.population_size means matching source rows without grouping,
observed groups with grouping alone, and groups eligible for ranking when
rank is present. An empty ungrouped population is therefore 0.
target_outcome is not_requested, present or absent; an absent target is
reported there instead of as a fabricated row.
JSON parsers can round wide integers and long decimals. For every numeric
predicate or target, definition.literal_text supplies canonical exact text
at a JSON Pointer such as /population/0/value,
/population/1/values/0 or /target. Use that text in a calculation
disclosure. String, date and boolean literals use their ordinary values. The
map is output-only: a tool call that supplies literal_text is refused.
For example, an input predicate whose JSON number is 9007199254740993
produces {"/population/0/value":"9007199254740993"} even though a
JavaScript parser rounds the numeric field itself.
The definition records what the engine executed. It does not certify the model's interpretation of the request, its prose, or a separate SQL query.
The model is shown a preview, not the whole capture:
{
"query_id": "q_9f2c1ab40e57",
"table": "orders",
"columns": ["region", "shipped_late"],
"preview_rows": [["EMEA", 412], ["AMER", 233]],
"preview_truncated": false,
"capture_rows": 2,
"total_rows": 2,
"truncated": false,
"usage": {"input_tokens": 1180, "output_tokens": 64}
}preview_rows holds at most 100 rows and is bounded by bytes as well, so a
wide table is cut here — preview_truncated says so — rather than losing its
query_id to the run's tool-result cap. capture_rows is how many rows the
stored capture holds, truncated whether that capture holds fewer than the
statement produced, and total_rows is null when the engine could not count
them. Over a table an extraction published,
the result also carries that table's coverage as of the snapshot the query
read — the shape the definition read reports — so an answer can say when a
total is partial; over any other table the key is absent.
The whole capture is stored on the engine's side — up to 2000 rows and 2 MiB
of JSON per query — and query_id is the handle a surface binds to. A task
that also holds ui.surface can answer with an
interface over these very rows, and GET /v1/surfaces/{revision_id} is where
they are read back. No route returns a capture on its own: rows reach a client
as part of the surface that binds them, never as a query you can address
directly.
A refusal comes back as a tool result rather than an error, so the model can act on it and ask again:
{"error": "no dataset \"files\" you can read; datasets you can read: Sales"}Both dataset refusals name what the caller could ask for instead: with
nothing to read at all it is this task has no project and no dataset; start it in a project, or name a dataset you can read: Sales, Support tickets, and
with a name it cannot read, the message above. When there is nothing to list,
the first becomes this task has no project and no dataset, and you have no dataset you can name: start it in a project, add a CSV or Excel file to a project's files or datasets, or rename any that share a name, and the second
ends with the same you have no dataset you can name — … clause.
A run started with project_id is told about tables instead, since its
caller named no dataset and may not know one exists. The tables are listed
grouped by the dataset each is in, with the project's own files written
(files):
no table "invoices" in project "Quarterly review"; tables you can read: sales, orders ("Quarterly review"), regions ("Geo")— bounded to ten, with a trailing…when there are more. A project's own files are named by the project, which is what its hidden store is called;table "sales" is in more than one of the project's datasets: "Quarterly review" (files), "Geo"; name the dataset too— senddatasetas well astable. Every dataset either sentence names is one thedatasetargument resolves to that very dataset; one whose name would reach a different dataset you can read is left unnamed rather than offered;project "Quarterly review" has no table you can read; datasets you can read: Sales— the project holds no CSV or spreadsheet this run can read.
A reference in a project that the caller cannot read in their own right is simply not in the scope: it is never read and never named. A project-scoped run therefore reaches no more than a chat in that project does.
The tool also refuses when sql arrives without table, when the statement
is not a single SELECT, when a generated statement could not be repaired,
when the query exceeded the sidecar's thirty-second budget — ask a narrower
one — when the dataset holds no tables at all (dataset: has no tables),
when the named table is not one of that dataset's tables, and when that name
matches two of its documents, which a re-ingested dataset can hold when two
generations carry one sheet name and neither is authoritative.
One refusal is worth reading for its remedy rather than its cause: when two
datasets the caller can read share the name given, the tool answers more than one dataset is called Orders; name it by id. Send the dataset's id in
dataset — or start the task with dataset_id — instead of the name.
Repeating the same call in the same place of the same run answers from what was stored rather than querying again. Change the arguments and it is a fresh query.
Answer with a surface
ui.surface is the engine's second tool. Where dataset.query reads a table,
ui.surface answers the task with an interface over the rows it has
already read — filters, a table, charts, headline numbers — instead of a
paragraph describing them.
It takes one argument, spec: the whole surface as
{
"spec": {
"root": "page",
"elements": {
"page": {
"type": "Section",
"props": {"title": "Late shipments"},
"children": ["by-region"],
"visible": true
},
"by-region": {
"type": "Chart",
"props": {
"chartType": "bar",
"data": {"$query": "q_9f2c1ab40e57"},
"xKey": "region",
"yKey": "shipped_late"
},
"children": [],
"visible": true
}
}
}
}Every element carries all four of type, props, children and visible,
and no key outside them. visible is true or a condition on interaction
state — {"$state": "/ui/expanded"}, optionally with not, eq or neq.
The vocabulary is fixed: Section, Row, Column, Expanded, Divider,
DataList, FilterBar, Chart, StatTile, Badge, Tabs and Dialog. A
spec is data — no expression language, no URLs, no HTML — and it carries no
rows of its own. Every DataList, Chart and StatTile binds a query the
same thread already made, as {"$query": "<query_id>"}, and may name only
columns that query returned.
Interaction state lives under /ui/: a FilterBar control writes a /ui/
path, and a DataList, Chart or StatTile filter reads it back as its
value with {"$state": "/ui/country"} — one control drives all three at once.
A filter selects among the captured rows a client already holds, and the
capture is sized so that a filter over a small table is complete, so no
further query is made. There are no actions, buttons or forms in this
vocabulary; what a person should do next belongs in the task's own answer.
The surface is bounded, and the engine refuses one that is not: at most 60
elements, 8 levels deep and 12 bound queries, with a root that is a Section
and is itself one of the elements, exactly one parent per element, and
nothing left unreachable from the root. A StatTile or a Chart has to stand
on a query that was not truncated, so a whole-table number is a
dataset.query with GROUP BY, SUM or COUNT rather than arithmetic over
2000 captured rows. What the catalog's rules advise rather than enforce is
the shape: keep the surface small — a KPI row, one or two charts and a list.
Since catalog 1.2.0 (2026-09-18) the engine also refuses numbers in
surface text. Every text prop — a Section title, subtitle or body, a
StatTile, Badge, column, series, control or tab label, a Dialog title —
may not carry a numeral, except a year (2026), an ISO date (2026-08,
2026-08-31) or a quarter (Q1–Q4, T1–T4), nor a cardinal or ordinal
number word in English or French ("five", "fourth", "cinq", "première"). A
written StatTile.delta is refused too. Numbers reach the reader only through
bound components: a StatTile value, a Chart series, a DataList cell.
FilterBar options and placeholder are filter values and are not read.
The refusal names the prop and quotes the first offender:
{"path": "/spec/elements/banner/props/label",
"message": "label contains a number (\"five\"); surface text carries no numbers — put the value on a StatTile bound to a query"}The rule's data — the regex sources and both word lists — ships in the
bundle as text-rule.json, and the bundle digest now covers the schema, the
rules and that file, in that order. It runs at acceptance only; a refresh
never re-checks text, so a revision stored under 1.1.0 keeps refreshing.
What the model is told
The engine accepts a surface; it does not render one. A successful call answers:
{
"revision_id": "9f1c7a6e-3b90-4d1a-8f22-6a5b0c4e7d11",
"revision": 2,
"accepted": true,
"message": "Revision 2 of this thread's surface is accepted and stored. A follow-up on this thread refines it."
}Revisions are numbered per conversation, so a follow-up run that answers with
a surface again is revision 3. A refinement is a whole new surface, never
a patch — hand in the complete spec each time. Acceptance runs no query and
makes no model call: it copies the statements and the captures the thread's
dataset.query calls already produced.
A refusal is a tool result the model can act on, with every problem located by
JSON path under /spec and all of them reported in one pass:
{
"error": "surface refused",
"problems": [
{"path": "/spec/elements/by-region/props/yKey", "message": "column \"late\" is not in q_9f2c1ab40e57; columns: region, shipped_late"},
{"path": "/spec/elements/late-tile/props/value/data", "message": "q_4c81ea92f003 is truncated; aggregate it in SQL and bind the tile to that query"}
]
}A problem with the argument as a whole carries the path /spec exactly. The
argument is capped at 256 KiB and that cap is checked before the JSON is
parsed. Two refusals are worth knowing about as an integrator, because they
are about the thread rather than about the spec: binding a query_id that two
finished queries of the thread both carry is refused (run dataset.query again and bind the new id), and a surface whose bound captures exceed 2048 KiB in
total is refused naming the three largest queries to narrow.
Read the surface a task answered with
Every run view carries the surface that run accepted:
{
"has_surface": true,
"surface": {
"revision_id": "9f1c7a6e-3b90-4d1a-8f22-6a5b0c4e7d11",
"revision": 2,
"catalog_version": "1.1.0",
"created_at": "2026-09-11T09:14:02Z",
"refreshed_at": null
}
}Both fields are on every run view — GET /v1/runs/{id}, the listing, and
the approve and deny responses — so a run that answered with no surface is
"surface": null beside "has_surface": false rather than a missing key you
have to guess at. refreshed_at is null until a refresh of that revision
has succeeded. POST /v1/runs/{run_id}/cancel deliberately carries neither:
it answers the narrower run-metadata shape.
Three routes read the surface itself, and all three are the revision owner's
for every role — a revision that is not yours is 404 rather than 403, a
malformed id answers exactly as a well-formed stranger's id does, and a thread
that is not yours lists nothing rather than refusing:
GET /v1/surfaces/{revision_id}
POST /v1/surfaces/{revision_id}/refresh
GET /v1/conversations/{conversation_id}/surfacesGET /v1/surfaces/{revision_id} is the whole thing — spec is the very
document the task handed in, stored as it was accepted:
{
"id": "9f1c7a6e-3b90-4d1a-8f22-6a5b0c4e7d11",
"run_id": "…",
"conversation_id": "…",
"revision": 2,
"catalog_version": "1.1.0",
"catalog_digest": "aff0601351e626ab…",
"spec": {
"root": "page",
"elements": {
"page": {
"type": "Section",
"props": {"title": "Late shipments"},
"children": ["by-region"],
"visible": true
},
"by-region": {
"type": "Chart",
"props": {
"chartType": "bar",
"data": {"$query": "q_9f2c1ab40e57"},
"xKey": "region",
"yKey": "shipped_late"
},
"children": [],
"visible": true
}
}
},
"queries": [
{"query_id": "q_9f2c1ab40e57", "table": "orders", "columns": ["region", "shipped_late"]}
],
"capture": {
"q_9f2c1ab40e57": {
"rows": [["EMEA", 412], ["AMER", 233]],
"row_count": 2,
"total_rows": 2,
"truncated": false,
"coverage": null
}
},
"refresh": null,
"created_at": "2026-09-11T09:14:02Z"
}Four things about that body are worth stating exactly.
Calculation metadata follows the selected capture. A calculation query
adds the same calculation object to its queries[] entry and its keyed
capture entry. A successful refresh recompiles the saved versioned definition
against the current table schema and replaces the rows, columns, source
provenance and execution facts together. A failed refresh keeps the entire
last good capture and its metadata. Never combine refreshed rows with an older
executed_at, population size or target outcome.
The field is additive and optional. Queries made with question or sql, and
rows stored before calculation metadata existed, have no calculation; render
their rows as before. If an older stored definition has no literal_text or
has it as null, exact numeric spelling is unavailable—do not reconstruct it
from a parsed JSON number.
The statement is not a field. A query is projected to query_id, table
and columns. The SQL a run wrote is visible to that run's owner in the
thread's own turns, like any other tool argument, and this route does not
repeat it. That is a rule about the response shape, not a promise that no
SQL text appears anywhere in the body — a failed refresh's problem messages
are the sidecar's own refusals and routinely quote the fragment they could not
parse. They are rendered verbatim, deliberately: every route here is
owner-scoped, the same person reads the whole statement in the run's turns,
and classing that message would cost the one detail that explains the failure.
Technical failures are the opposite case and carry no cause at all — see
below.
table is a name, never a table id. Re-ingesting a file keeps the name and
replaces the id, and that is precisely the case a refresh exists for.
Read columns from queries[], not from the capture. queries[].columns
is the column list the rows you are given are actually in: the shown capture's
own list when it carries one, and the revision's recorded list when it does
not. A re-uploaded sheet can return the same columns reordered or with one
inserted; rendering a refresh's rows under the revision's original header
would mislabel every value and look plausible doing it.
Absences are narrow. capture is always an object ({} for a surface
that binds no query), queries[].columns is always a list, and inside a
refresh problems and notices are always lists — [] on a refresh that
succeeded and on one that found no new tables. The real nulls are refresh
(never refreshed), finished_at (queued or running) and a capture's
coverage over a table no extraction published; over one that an extraction
did, coverage is that table's as of the snapshot the capture read, and it
changes with the rows, on a refresh that succeeds. Inside a capture,
total_rows is a number and is -1 when the engine did not count the rows;
the null you may have seen is on the dataset.query tool result the model
reads, not here.
GET /v1/conversations/{conversation_id}/surfaces is the thread's revisions,
newest first, metadata only — no spec and no capture, because neither is
read for the listing:
{"items": [{"id": "…", "run_id": "…", "conversation_id": "…", "revision": 2, "catalog_version": "1.1.0", "created_at": "…", "refresh": null}]}It answers the newest 200 and carries no cursor: a longer thread does not list its oldest revisions, and the shape has no marker saying so.
Refresh a surface's rows
A revision is immutable, but its data does not have to be. POST /v1/surfaces/{revision_id}/refresh re-runs the revision's stored statements
against the current tables:
{"refresh_id": "3a18e4c2-…", "state": "queued"}That is a 202, not a 200: a refresh can run twelve statements of up to
thirty seconds each, so the row is accepted and the work happens off-request.
Poll GET /v1/surfaces/{revision_id} and read its refresh field, exactly as
you poll a run. One refresh at a time per revision — a second while one is in
flight is 409, and the id of the refresh already running is inside the typed
envelope's message (a refresh is already in progress: <refresh-id>),
because the envelope has no other slot for it. A refresh whose worker died is
reaped by the next GET or POST on the revision, roughly sixteen minutes
after it started, so that 409 is never permanent.
A refresh makes no model call and takes no billing hold, so it spends no credits. No SQL is written again: the statements are the ones the revision recorded, resolved against the tables by name, as the revision's owner without roles. Each query is re-run against the dataset its own row names, so a revision made by a project-scoped task can span several of that project's datasets and each one is re-read where it lives.
A finished refresh reads back like this:
{
"refresh": {
"id": "3a18e4c2-…",
"state": "failed",
"started_at": "2026-09-11T10:02:11Z",
"finished_at": "2026-09-11T10:02:13Z",
"problems": [
{"query_id": "q_9f2c1ab40e57", "message": "the dataset is no longer readable by you; ask its owner to share it again"}
],
"notices": []
}
}- A failed refresh keeps the last good data.
capturestill holds the rows of the newest refresh that succeeded — or the revision's own, if none has — andqueries[].columnsstill describes those very rows. The failure is reported beside them rather than instead of them, so a page can draw the surface it has and say that the newest attempt did not land. No partial capture is ever substituted: half a surface's queries is not a result. - Problems are collected in one pass, one per reason, attributed to a query when the reason belongs to one. A dataset that has been unshared fails every query of it with one sentence and runs no statement at all. A renamed column, or a query that has become truncated under a tile or a chart, fails the refresh in the same words acceptance would have used.
- A technical failure says only a class.
the refresh did not finish: technical failureor… unavailable, never the underlying message — that prose can carry a column name or a fragment of a statement. It is appended to the reasons the refresh had already learned rather than replacing them, so an unshared dataset is still named when a later query hits an outage. The refresh's own five-minute clock reportsthe refresh timed out after 5m0s. noticesname unbound tables in the revision's datasets (new tables: orders_2026-09), so a follow-up can use them, and they ride a failed refresh too — a renamed sheet is exactly where the new name is the fact that explains the failure. They are computed only over datasets that the refresh could actually list, which is why the example above carries none: its one dataset is the one that became unreadable, and a dataset that cannot be listed names no table. A revision spanning several of a project's datasets can therefore fail on one of them and still carry notices from the others. One further limit: the datasets are the revision's own queries' datasets, so a dataset attached to the thread's project after the revision was made is not announced.
The catalog version and digest
Every revision records the catalog_version and catalog_digest it was
validated against — this release vendors version 1.2.0; revisions stored
before 2026-09-18 carry 1.1.0 — and is never
rewritten. Nothing migrates a stored spec to a later bundle. A client that
draws surfaces should compare these against the bundle it holds and refuse a
version it cannot draw, naming it, rather than guessing at an element type it
does not know. Additive catalog changes keep older revisions drawable: a
client should hold a small table of the versions it can draw, each with its
digest, rather than one pinned version — Deeplinq's own console draws 1.1.0
and 1.2.0 and applies the text rule only from 1.2.0.
These routes are the wire contract, and they are complete: a client can read a revision, its rows and its refresh state today. Rendering the spec in Deeplinq's own console is a following stage — until it ships, a person reads the task's text answer and an integrator reads the surface through the routes above.
Continue a thread
Every run answers with a conversation_id. Send it back when you create the
next run and that run joins the same conversation instead of opening one of
its own: the earlier runs' messages, tool calls and tool results are the new
run's history, so a follow-up can act on what an earlier run read without
reading it again.
curl -H "Authorization: Bearer $DEEPLINQ_TOKEN" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v1/runs" -d '{
"message":"Now add that flight to my calendar.",
"model":"gpt-5-mini",
"conversation_id":"'"$CONVERSATION_ID"'"
}'Both create routes take the field. The conversation must be one of your own
that a run opened: another person's, another organization's or a deleted one
is 404, a plain chat conversation is 400, and a follow-up while a run on
the thread is still queued, running or awaiting_approval is 409 — one
run at a time on a thread.
GET /v1/runs?conversation_id={conversation_id} lists the thread's runs,
newest first, paged like the rest of the listing; reverse the page to read the
thread in order.
Read the thread in one request
GET /v1/runs/{id}/thread returns { "items": [...] }. Each item has the
same run, turns and pending_approval fields as GET /v1/runs/{id},
including workflow and surface metadata and the lossless tool_args_json
approval text. Items are ordered oldest first.
The response contains at most the latest 50 runs from the named run's conversation. If that page no longer contains the named run, the response contains that run alone. This is a bounded view, not a complete-history export. The named run must belong to the caller in the current organization; an administrator cannot use this read to inspect another person's content.
Read the conversation transcript separately for the user and assistant messages. Polling needs these two reads regardless of the number of runs. The lifecycle and transcript are eventual snapshots; a later poll can bring them up to date. The endpoint accepts no query parameters and does not start or resume work.
Handle approval
When status is awaiting_approval, inspect the pending action in the owner-only
run view, then:
curl -H "Authorization: Bearer $DEEPLINQ_TOKEN" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v1/runs/$RUN_ID/approve" \
-d '{"note":"The draft is safe to send."}'Or deny:
POST /v1/runs/{run_id}/deny
{"note":"Do not contact this recipient."}Approval, state transition, and continuation-job creation commit atomically. Denial becomes a tool result so the model can adapt.
Bounds and cancellation
Every run is bounded by:
- maximum turns;
- an optional micro-USD credit budget;
- a wall-clock deadline;
- an approval timeout;
- a maximum tool-result size.
Cancel with:
POST /v1/runs/{run_id}/cancelCancellation stops after in-flight work completes. Explicit terminal reasons include budget, turn, timeout, guardrail, tool, and cancellation outcomes.
Events
Runs emit content-free events including run.started,
run.approval_required, run.tool_unavailable, run.succeeded, and
run.failed. The shared webhook delivery state machine can deliver them without
placing prompts, tool arguments, or results in the event payload.
Turn an external hire off or on
Once setup is complete, the personal owner uses POST /v1/agents/{id}/disable or
POST /v1/agents/{id}/enable, with no request body. Both return the current
agent. A pending install returns 409 on either operation. Disable atomically pauses her managed schedule, cancels unfinished runs
and ends their authority. Enable resumes future mornings without another
welcome or reviving canceled work. Repeated calls converge. Current membership
is required to enable; model credits are not required. Internal agents answer
409 on these operations and retain their existing controls. Another person,
including an organization administrator, receives 404 for a personal hire.
For a configured external hire, ordinary PATCH /v1/agents/{id} writes only the editable
fields sent and ignores status, including a status-only patch. Use the
dedicated operations above for availability. A rename that arrives after
disable leaves her off, even if an old form sends status: "active"; fields
not named in the edit retain their current values. Internal agents keep their
existing status-edit behavior.
The external Blinq server boundary uses contract version 1. Pairing uses a service secret; announcement and claiming use the paired server credential; context, model calls, connected tool reads and transitions require that credential plus live per-claim authority. None uses tenant authentication. The generated operation metadata records this version; v1 changes are additive and preserve existing fields, types and authority requirements.