> ## Documentation Index
> Fetch the complete documentation index at: https://warden.buildlab.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Data plane

> What an agent talks to: run an operation, read the schema, confirm identity, collect an async outcome.

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](https://warden.buildlab.in/api/control-plane.md) behind a different credential.

Authenticate with the agent's key:

```
Authorization: Bearer wk_live_…
```

## POST /api/v1/gateway/execute

Run one operation through the pipeline.

**statement** `string`

SQL (or Cypher, per engine), with parameters as placeholders. Never interpolate values — a bound parameter cannot become an identifier.

**command** `object`

A command document, for engines without a query language. Use this *or* `statement`.

**params** `array`

Positional parameter values.

**reason** `string`

The agent's explanation, shown to whoever reviews it. Untrusted text: displayed, never interpreted.

**task\_id** `string`

Groups operations belonging to one task.

**step\_index** `integer`

Which step of that task.

**plan\_hash** `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.

**idempotency\_key** `string`

Deduplicates retries. Policy decides when one is required.

**mode** `string`

`blocking` or `async`. Empty takes the connection's default. See [approvals](https://warden.buildlab.in/configure/approvals.md).

### Response

The body has the same shape whether the operation ran or not, so an integration parses one thing.

**status** `string` *required*

`committed`, `replayed`, `proposed`, `rejected`, `expired`, `stale`, `stopped`, or `denied`.

**rows** `array`

Result rows, masked and column-restricted.

**fields** `array`

Column names.

**records\_affected** `integer`

For a change, how many records it touched.

**truncated** `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.

**warnings** `array`

Signals worth reasoning about — most importantly that an empty result looks suspicious rather than genuine.

**operation\_id** `string`

The operation's ID, and the handle for an async proposal.

**class** `string`

`read`, `write`, `delete`, `ddl`, or `admin`.

**duration\_ms** `integer`

Wall time, including any wait for a human.

**code** `string`

The failure code, when it did not run. See [errors](https://warden.buildlab.in/api/errors.md).

**message** `string`

An agent-safe description. Operator detail stays in the audit log.

**retryable** `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.

**approval** `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.

**deadline** `string`

When a proposal expires unanswered. Only on `proposed`.

**poll** `string`

Where to read the outcome. Only on `proposed`.

### Statuses

| Status | HTTP | Did it run? | What to do |
| - | - | - | - |
| `committed` | 200 | Yes | Continue. Report the approver if one is named |
| `replayed` | 200 | Earlier | The stored result was returned; do not run it again |
| `proposed` | 202 | **No** | A human has it. Poll, or re-send the same key |
| `rejected` | 409 | **No** | A person said no. Escalate; do not retry |
| `expired` | 409 | **No** | Nobody answered in time. Safe to re-propose |
| `stale` | 409 | **No** | The data moved after review. Re-read, then propose again |
| `stopped` | 409 | **No** | A debug session ended while it waited |
| `denied` | 400/403 | **No** | Policy forbids it, or the request was malformed |

## GET /api/v1/gateway/operations/{id}

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.

```json theme={null}
{ "agent_id": "agent:support", "connection": "shop",
  "owner": "platform-team", "scope": { "tenant_id": "acme" } }
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.