API preview

Preview: the API is part of Business and becomes available when the workspace app launches. The shapes on this page are the design; field names may change before then.

The API lets your own systems hand work to your staff and watch it come back. It covers the same objects the app does, under the same roles and the same floor. Anything an agent cannot do in the app, it cannot do through the API either.

Authentication

Create a key under Settings, then API. Keys start with dlg_live_ followed by a short prefix and a random part; the full key is shown once and only a hash is stored. Each key carries scopes, such as delegations:write, and acts as the workspace's service actor, so its actions appear in the activity log under the key's name. Send it as a bearer token.

Authorization: Bearer dlg_live_k7f2_...

Create a delegation

Two calls: create the draft, then delegate it. Creating returns the draft with its estimate; delegating pins the agent version, reserves the budget and queues the first run.

POST /api/v1/workspaces/{ws}/delegations
{
  "title": "Rank 25 target companies",
  "brief": "Research 25 companies matching the attached profile. Rank them by fit and draft a two-line intro for each. Ask me before anything is sent.",
  "agentId": "agt_01J...",
  "dueAt": "2026-09-19T09:00:00Z",
  "budgetCapCents": 400,
  "checkpoints": { "askBeforeExternal": true, "askBeforeSpendCents": 100 }
}

POST /api/v1/delegations/{id}/actions/delegate

Read status

GET /api/v1/delegations/{id}

{
  "id": "dlg_01J...",
  "status": "WAITING_ON_YOU",
  "agent": { "id": "agt_01J...", "name": "Research analyst", "version": 3 },
  "costUsdMicros": "412000",
  "budgetCapCents": 400,
  "currentRunId": "run_01J...",
  "openApprovals": 1,
  "deliverables": [],
  "updatedAt": "2026-09-17T10:02:11Z"
}

Status is one of DRAFT, DELEGATED, RUNNING, WAITING_ON_YOU, IN_REVIEW, DONE, PAUSED, CANCELLED or FAILED. Costs are integers in micro-dollars, sent as strings; caps are in cents. The steps of the current run are at GET /api/v1/runs/{runId}/steps.

Stream events

GET /api/v1/delegations/{id}/events is a server-sent events stream, one per delegation. Persisted events carry an id, the channel's sequence number; send it back as Last-Event-ID on reconnect and the stream resumes where you left off. Token deltas carry no id and are not replayed. A comment line is sent every 15 seconds to keep the connection open.

run.status, run.step.created, run.step.updated

The Progress timeline as it happens.

run.delta

Text as the agent writes it. Not persisted.

approval.requested, approval.decided

A checkpoint was raised or answered.

deliverable.created, thread.message

Something arrived on the delegation.

Errors and limits

An action the lifecycle does not allow returns 409. A workspace at its hard credit limit returns 402 on new delegations. Rate limits are per key; a 429 carries Retry-After. Approval answers belong to people: nothing an agent outputs can approve its own request, and an answer posted through the API is recorded against the key that made it, with the hash of the preview it was shown.