/api/v1 keeps working — its routes, response shapes, headers, and
status codes are unchanged, except that a key bound to one project gets 403 FORBIDDEN on v1 and v2 and works only on v3 (a key limited to the Autopilot API, with Autopilot or Budget access but not Full API, also gets 403 FORBIDDEN on v1, as on v2 and v3). There is no time-boxed deprecation
window and no Sunset or Deprecation headers in this release. v1 stays fully
functional; a separate future change will introduce a dated sunset once consumers
have migrated. This guide maps every v1 route to its canonical v2 equivalent so
new integrations can target v2 directly.
Why v2
- One canonical surface organized into clear segments — Projects, Agents, Runs, Tables, Workspace, Campaigns, Sequences, Scheduled agents, and Account — instead of v1’s flat table-and-credits surface. See objects and relationships for the full map.
- Full data addressability: tables, columns, rows (list and upsert), single row, single cell, and enrichment runs with per-row outcomes.
- Self-describing objects (every object names its type) and one list envelope everywhere.
- A standard error envelope
{ error, code, details?, handoff? }, where any 4xx the user can fix in-app carries a forwardablehandofflink. - Campaigns, sequences, scheduled agents, projects, and account state are reachable from the API for the first time.
Route mapping
New in v2
These segments have no v1 equivalent:- Projects — child orgs under your parent
org, selected per request with the
x-origami-projectheader. See authentication. - Agents and runs — create, list, get, and archive agents; send
and poll runs; cancel an active run; and bind existing documents or tables to a
run with
attachments. - Workspace — bootstrap, list, get, and delete workspaces; upload, list, read, rename, and delete documents; read a single row or cell; and bulk soft-delete rows by id (up to 100 per call).
- Campaigns — first-class outreach campaigns: create and edit agentically, read people and stats, and launch, pause, or resume.
- Sequences — read per-recipient sequences with steps inline, stop, and delete.
- Scheduled agents — recurring (cron) agents with full CRUD, enable/disable, manual trigger, and run history.
- Account — an org overview with plan and capability flags.
Behavioral differences to know
- Pagination. v2 list endpoints return the cursor envelope
{ object: "list", items, nextCursor, url }— page by passingnextCursorback ascursor, and stop when it’snull. There is nopage/pageSize. v1’s offset response fields are unchanged on v1. - Self-describing objects. Every v2 object carries an
objectfield naming its type; every list is{ object: "list", items, … }. - Error envelope. v2 returns
{ error, code, details?, handoff? }with validation issues underdetails.issues[]. v1 keeps its legacy{ error, code, path? }body. Map your error handling per version. - Handoffs. A 4xx the user can resolve in the app carries a
handoff({ kind, url, label }) — forwardurlto your user unchanged. - Polymorphic cells. v2 rows return tagged cells (
scalar,valuewith run metadata, orsequence); a sequence cell links into the Sequences API. Use?cells=flatfor the v1-style{ slug: value }shape. - Async agent work. Creating an agent or sending a run returns a
runningrun; pollGET /api/v2/agents/{id}/runs/{runId}and honorRetry-After. See the run object. - Hidden rows and tables. v1 and v2 return only what you can see in the
app. Tables not shown in the app are left out of table lists (and of v1’s
total), and return404when read by id. On a table whose rows must be bought before they show in the app, rows not yet bought are left out. On a campaign’s lead table, only the rows delivered to you come back. On v2, reading a hidden row or one of its cells by id returns404 ROW_NOT_FOUND.