Agents

The capability verbs do one thing per call. An agent does a sequence of things. Example: read the intake pack, extract the fields, fill the form, wait for a human to countersign, file the result. An agent is a saved, reviewed automation. It holds a list of steps, the saved configs it may use, and the points where a person must sign off.

GET /v1/agents lists the agents your organization can run. POST /v1/agent-runs starts one on a set of files. After that, you work with one object: the agent run (agr_…). Poll it or subscribe to it.

An agent

1
{
2
  "object": "agent",
3
  "id": "01JQ8ZKMRT4V6WXYZ0ABCDEFGH",
4
  "name": "Client intake",
5
  "description": "Reads an intake pack, files the data, and collects a signature.",
6
  "version": 7,
7
  "tasks": [
8
    { "id": "task-1", "title": "Extract the intake fields", "executor": "agent", "dependsOn": [] },
9
    { "id": "task-2", "title": "Countersign the engagement letter", "executor": "human", "dependsOn": ["task-1"] }
10
  ],
11
  "actions": [
12
    { "name": "Extract structured data", "approval": "output" },
13
    { "name": "Sign document", "approval": "before" }
14
  ],
15
  "updatedAt": "2026-07-28T14:02:11.884Z"
16
}

The API lists only active agents. Ids are opaque strings. Do not parse them.

Who does each step

Every step has an executor. That field sets the full division of labour:

• agent — the step runs by itself. You do nothing.
• human — the step waits. Complete it with POST /v1/agent-runs/:id/tasks/:taskId/complete. Attach a note and files if you need to.

On a run, each step also carries a status: pending (blocked on its dependsOn), ready (open), in_progress, completed, or skipped. A skipped step satisfies dependencies the same way a completed step does.

Sign-off gates

An action’s approval says where a human must agree before the agent proceeds:

Every outstanding sign-off appears in approvals[] on the run. Each entry carries a kind of before or output, the action’s name, and the files it touches. A before gate also carries the proposed params. Answer it with POST /v1/agent-runs/:id/approvals/:approvalId. When you approve, you can replace those params or files first. When you reject, you must include a note.

Run statuses

completed, failed, cancelled, and expired are terminal.

A completed run that had outstanding work also carries incomplete: true. The run closed with unfinished steps, and tasks[] shows which. Treat this as done with gaps, not as a failure.

Long-lived by design

An agent run that is blocked on a person can wait days. The API supports that:

• expiresAt is about seven days out. That is the run’s deadline, not a cleanup timer. An unfinished run parks itself for good when it passes the deadline. A human step must land before then.
• The API never purges input files on a deadline. Files you pass as { "url": … } join your reusable file corpus. The run keeps its inputs however long it waits. POST /v1/agent-runs has no ttl.
• output.files[] links are short-lived. Each signed URL is valid for about an hour. Re-read the run to get a fresh one.

Next steps