Skip to main content
/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 forwardable handoff link.
  • 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-project header. 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 passing nextCursor back as cursor, and stop when it’s null. There is no page/pageSize. v1’s offset response fields are unchanged on v1.
  • Self-describing objects. Every v2 object carries an object field naming its type; every list is { object: "list", items, … }.
  • Error envelope. v2 returns { error, code, details?, handoff? } with validation issues under details.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 }) — forward url to your user unchanged.
  • Polymorphic cells. v2 rows return tagged cells (scalar, value with run metadata, or sequence); a sequence cell links into the Sequences API. Use ?cells=flat for the v1-style { slug: value } shape.
  • Async agent work. Creating an agent or sending a run returns a running run; poll GET /api/v2/agents/{id}/runs/{runId} and honor Retry-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 return 404 when 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 returns 404 ROW_NOT_FOUND.

Skills and tooling

The Origami skill and the v2 OpenAPI spec teach v2 only. v1 appears solely as deprecated, with these migration pointers.