> ## Documentation Index
> Fetch the complete documentation index at: https://docs.origami.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating from v1 to v2

> Map every v1 Data API route to its canonical v2 equivalent.

`/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](/agents/objects) 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

| v1 route                                      | v2 equivalent                                                                 | Notes                                                                                                                                                                                                                                                                                            |
| --------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GET /api/v1/tables`                          | [`GET /api/v2/tables`](/agents/reference/list-tables)                         | Cursor-paginated list envelope of full table objects.                                                                                                                                                                                                                                            |
| `GET /api/v1/tables/{tableId}/rows`           | [`GET /api/v2/tables/{tableId}/rows`](/agents/reference/list-rows)            | Typed polymorphic cells by default; `?cells=flat` and `?format=csv` reproduce the v1 flat shape.                                                                                                                                                                                                 |
| `POST /api/v1/tables/{tableId}/rows` (insert) | [`POST /api/v2/tables/{tableId}/rows/upsert`](/agents/reference/upsert-rows)  | v2 has **no bare insert** — use upsert with `matchColumns` (an insert-only call is an upsert whose rows match nothing). Same caps and idempotent `batchId`; adds per-row inserted/updated/skipped outcomes. A CSV variant lives at [`.../rows/upsert-file`](/agents/reference/upsert-rows-file). |
| `GET /api/v1/batches/{batchId}`               | [`GET /api/v2/enrichment-runs/{runId}`](/agents/reference/get-enrichment-run) | A batch is now an **enrichment run**; adds the per-row upsert outcome ledger. `GET /api/v2/batches/{batchId}` remains a deprecated alias.                                                                                                                                                        |
| *(none)*                                      | [`GET /api/v2/enrichment-runs`](/agents/reference/list-enrichment-runs)       | List enrichment runs org-wide or per table. `GET /api/v2/batches` is the deprecated alias.                                                                                                                                                                                                       |
| `GET /api/v1/credits`                         | [`GET /api/v2/account/credits`](/agents/reference/get-credits)                | Same balance source; [`GET /api/v2/account`](/agents/reference/get-account) adds plan and capability flags.                                                                                                                                                                                      |

## New in v2

These segments have no v1 equivalent:

* **[Projects](/agents/reference/list-projects)** — child orgs under your parent
  org, selected per request with the `x-origami-project` header. See
  [authentication](/authentication#projects-and-the-x-origami-project-header).
* **[Agents and runs](/agents)** — 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](/agents/reference/rename-document), and delete
  [documents](/agents/reference/list-documents); and read a single row or cell.
* **[Campaigns](/agents/reference/list-workspace-campaigns)** — first-class
  outreach campaigns: create and edit agentically, read people and stats, and
  launch, pause, or resume.
* **[Sequences](/agents/reference/list-sequences)** — read per-recipient
  sequences with steps inline, stop, and delete.
* **[Scheduled agents](/agents/reference/list-scheduled-agents)** — recurring
  (cron) agents with full CRUD, enable/disable, manual trigger, and run history.
* **[Account](/agents/reference/get-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}`](/agents/reference/get-run)
  and honor `Retry-After`. See the [run object](/agents/run-object).

## Skills and tooling

The [Origami skill](/agents/skill) and the v2 OpenAPI spec teach v2 only. v1
appears solely as deprecated, with these migration pointers.