Sign in

v1

latestOpenAPI 3.1.02026-07-267154122.0 KB
Agents

Create an agent and admit its first run

Creates a new agent (and, if workspaceId is null and no focusTableIds are passed, an auto-created workspace), inserts a synthetic user message carrying the prompt, claims the per-org concurrent slot, and spawns the agent work in the background. Responds 202 Accepted with the initial run object (status: "running"). Poll GET /agents/{id}/runs/{runId} until status !== "running".

post/agents

Headers

Idempotency-Keystring

Transport-level replay protection — any v2 POST may send it (1–255 printable ASCII characters; UUIDs recommended). The first response for a key is recorded and replayed verbatim for retries with the same key + method/path/body for 24 hours; replayed responses carry the Idempotency-Replay: true response header. Reusing a key with a different request — or retrying while the original is still in flight — returns 409 IDEMPOTENCY_ERROR. 5xx responses are never recorded (the retry re-executes).

Request body

namestring

Optional human-readable label. Auto-generated from prompt if absent.

promptstring required
workspaceIdstring uuid nullable
focusTableIdsstring[]

Table ids to focus the agent on. When the caller also supplies workspaceId, every id must belong to that workspace. When workspaceId is omitted, the workspace is inferred from the first id.

model'origami-lite' | 'origami-max'

Public model id. Plan-aware default — highest model unlocked on the caller's plan (origami-lite for starter, origami-max for pro+). Resolved server-side to an internal chat-agent model; the response's request.model echoes the public id (origami-lite or origami-max), never an internal name. Legacy aliases origami-fast and origami-mid are still accepted and normalized to origami-lite.

Response

Run admitted; agent work is in the background.

Example response

{
  "run": {
    "todo": {
      "pendingQuestions": [
        {
          "freeformOption": "Or something else"
        }
      ]
    }
  }
}