Skip to main content
Four endpoints and no more. Everything an agent might want that is not one of these is somebody else’s decision, and lives on the control plane behind a different credential. Authenticate with the agent’s key:

​
POST /api/v1/gateway/execute

Run one operation through the pipeline.
​
string
SQL (or Cypher, per engine), with parameters as placeholders. Never interpolate values — a bound parameter cannot become an identifier.
​
object
A command document, for engines without a query language. Use this or statement.
​
array
Positional parameter values.
​
string
The agent’s explanation, shown to whoever reviews it. Untrusted text: displayed, never interpreted.
​
string
Groups operations belonging to one task.
​
integer
Which step of that task.
​
string
Fingerprints the agent’s plan. With task_id and step_index it forms the identity of a logical operation, so a retry deduplicates but a genuinely changed plan does not.
​
string
Deduplicates retries. Policy decides when one is required.
​
string
blocking or async. Empty takes the connection’s default. See approvals.

​
Response

The body has the same shape whether the operation ran or not, so an integration parses one thing.
​
string
required
committed, replayed, proposed, rejected, expired, stale, stopped, or denied.
​
array
Result rows, masked and column-restricted.
​
array
Column names.
​
integer
For a change, how many records it touched.
​
boolean
A row limit capped the result. An agent that believes it saw everything when it saw the first N will reason wrongly about the rest.
​
array
Signals worth reasoning about — most importantly that an empty result looks suspicious rather than genuine.
​
string
The operation’s ID, and the handle for an async proposal.
​
string
read, write, delete, ddl, or admin.
​
integer
Wall time, including any wait for a human.
​
string
The failure code, when it did not run. See errors.
​
string
An agent-safe description. Operator detail stays in the audit log.
​
boolean
The field integrations most often get wrong: an expired approval did not run, so re-proposing is safe, while a rejection will never succeed.
​
object
Present when a human let it run: kind, by, reason, waited_ms. An agent that does not report this will tell its user a reviewed change ran unattended.
​
string
When a proposal expires unanswered. Only on proposed.
​
string
Where to read the outcome. Only on proposed.

​
Statuses

​
GET /api/v1/gateway/operations/

Collect an async proposal’s outcome. ?wait=N long-polls up to N seconds (60 maximum). Returns proposed with HTTP 202 while it waits, and otherwise exactly what a blocking call would have returned. An ID that is not this agent’s own is reported as operation_unknown with HTTP 404 — identical to one that does not exist, so outcomes cannot be used to discover what other agents are doing.

​
GET /api/v1/gateway/schema

The catalog this agent is permitted to see: resources, fields, descriptions, and legal enum values. Filtered by policy rather than dumped, because a schema listing is reconnaissance.

​
GET /api/v1/gateway/whoami

The agent’s own ID, connection, owner, and the scope its access is limited to. The fastest way to confirm a key and a configuration are wired correctly.