Skip to main content
/api/v1 keeps working unchanged — its routes, response shapes, headers, and status codes are identical to before. 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; and read a single row or cell.
  • 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.

​
Skills and tooling

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