Skip to main content
v3 (/api/v3) replaces “one prompt endpoint + a fat run object” with named, typed operations in three sections (Account, Leads, Send) and one shared Job for all async work. v1 and v2 keep working with the same keys — nothing you run today breaks — but new integrations should target v3 only.

​
The shape change

In v2 you POST /agents with a prompt, poll a run object with eight statuses, then separately wait out the cell pipeline. In v3 you call the operation you mean (leads.searches.create, send.campaigns.launch, …). Async operations return a Job that stays running (with phase: "enriching") until the work including enrichment is done, so succeeded means the result counts are final. AGENT-tagged operations still run the Origami agent under the hood — the brief is still the steer — but as a tag on specific operations, not the whole API.

​
Flow map

​
Renames and status folding

  • AGENT_BUSY → CHAT_BUSY (same 409, same per-session mutex; now carries the blocking details.job_id).
  • NO_SENDING_ACCOUNT → ACCOUNT_CONNECTION_REQUIRED (and ACCOUNT_RECONNECT_REQUIRED when senders exist but all need reauth).
  • ROW_LIMIT_EXCEEDED — unchanged.
v2’s eight run statuses fold into six Job statuses. The recoverable ones survive as failed + error.code:

​
Wire differences

  • snake_case everywhere (v2 is camelCase; the list envelope key is next_cursor, not nextCursor).
  • Strict inputs: unknown fields are 400 VALIDATION_ERROR — a camelCase body fails loudly instead of being silently stripped.
  • Errors are a closed envelope { error, code, details?, handoff? } — v2’s extra 402 top-level keys (creditsRequired, topUpUrl, …) moved into details / handoff.
  • Invalid cursors and out-of-range limits are 400s (v2 silently restarted / clamped).
  • Idempotency conflicts split: IDEMPOTENCY_MISMATCH (caller bug) vs IDEMPOTENCY_PENDING (transient, retry after Retry-After).
  • Rate-limit headers: v3’s org bucket suffix is Org (X-RateLimit-Limit-Org); v1/v2 keep Global. Same underlying buckets — traffic on both versions shares one allowance.
  • Keys now carry a role (existing keys were backfilled to admin; new keys default to member). Admin-gated Account ops return 403 for member keys.

​
New in v3

Job webhooks (job.*) and client metadata correlation · result.row_ids + rows ids filter (the CRM-sync loop) · cross-list dedup (exclude_list_ids) · pool depth (remaining_count, has_more) · relevance_weight read/patch · row status fields + format=csv · list funnel stats · bulk exclusion sync · sender/domain/mailbox management · project-bound keys · approvals ops · joinable reply webhooks (campaign_id, row refs).