Agents

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

GET /v1/agents lists the agents your organization can run; POST /v1/agent-runs starts one on a set of files. Everything after that is one object — the agent run (agr_…) — that you poll or subscribe to.

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
}

Only active agents are listed. Ids are opaque strings — don’t parse them.

Who does each step

Every step has an executor, and that is the whole division of labour:

• agent — it runs by itself. Nothing for you to do.
• human — it waits. Complete it with POST /v1/agent-runs/:id/tasks/:taskId/complete, optionally attaching a note and files.

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 anything waiting on it, exactly like a completed one.

Sign-off gates

An action’s approval says where a human has to agree before the agent may proceed:

Every outstanding sign-off appears in approvals[] on the run, with a kind of before or output, the action’s name, the files it touches, and — for a before gate — the proposed params. Answer it with POST /v1/agent-runs/:id/approvals/:approvalId; approving lets you replace those params or files first, and rejecting requires a note.

Run statuses

completed, failed, cancelled, and expired are terminal.

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

Long-lived by design

An agent run that is blocked on a person waits days, and the API is built for 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, so a human step has to land before then.
• Input files are never purged on a deadline. Files you pass as { "url": … } join your reusable file corpus, so the run still has its inputs however long it waits. There is no ttl on POST /v1/agent-runs.
• output.files[] links are short-lived — each signed URL is good for about an hour. Re-read the run for a fresh one.

Next steps