Skip to main content
v2 is a ground-up redesign of the Deck platform. If you have an existing v1 integration, this guide covers what changed, what maps to what, and how to get started on v2.

​
Getting started on v2

You can use your existing Deck account. From the Dashboard, create a new v2 organization. Data is not shared between v1 and v2. Agents, sources, connections, and task history from your v1 organization do not carry over. You’re starting fresh. Your v1 organization continues to work as-is. You can run both versions in parallel while you migrate.

​
Authentication changes

v1v2
Auth methodx-deck-client-id + x-deck-secret headersAuthorization: Bearer sk_live_... header
Key formatClient ID + secret pairSingle API key with sk_live_ prefix
Base URLhttps://live.deck.co/api/v1https://api.deck.co/v2
v2 uses a single Bearer token instead of a client ID and secret pair. Generate your API key from the v2 organization in the Dashboard.

​
Concept mapping

The core ideas are the same, but the naming and structure have changed.
v1 Conceptv2 ConceptWhat changed
DeckAgentA “deck” is now an “agent.” Agents scope tasks for a use case.
Source (GUID)Source (ID)In v1, sources were selected from a shared catalog managed by Deck. In v2, you create your own sources by providing a URL. Sources use prefixed IDs (src_) instead of GUIDs.
EnsureConnection jobPOST /v2/connectionsOpening a connection is a dedicated endpoint, not a job submission.
CloseConnection jobPOST /v2/connections/{connection_id}/disconnectDisconnecting a connection is a dedicated endpoint.
Access tokenConnection IDv1 returned an access_token to reference a connection. v2 returns a connection_id directly on the connection object.
JobTaskA “job” is now a “task.” Tasks have explicit input and output schemas.
Job submissionPOST /v2/tasks/{task_id}/runRunning a task is a dedicated endpoint with typed input, not a generic jobs/submit.
Job codeTask IDv1 identified jobs by a string code (FetchDocuments). v2 uses a typed task ID (task_abc123).
Webhook eventsEvent systemv1 delivered results via webhooks only. v2 has a full event system with destinations, deliveries, filtering, and replay.
MFA via jobs/mfa/answerInteraction endpointv1 had a single MFA answer endpoint. v2 has a general-purpose interaction system that handles MFA, security questions, account selection, and more.
DocumentsStorage itemsv1 had documents attached to jobs. v2 has storage items with download URLs, metadata, and optional data extraction.

​
Source changes

In v1, sources came from a shared catalog maintained by Deck. You browsed a list of pre-configured sources (Hilton, Hubspot, Coinbase, etc.), picked one by its GUID, and used it. You could not add your own. In v2, sources are yours. You create them by providing a name, type, and URL: 
POST /v2/sources

{
  "name": "Hilton",
  "type": "website",
  "website": {
    "url": "https://hilton.com"
  }
}
This means you can connect to any source, rather than being limited to ones predefined by Deck. Sources belong to your organization and can be shared across agents. If you were using a source from the v1 catalog, recreate it in v2 with the same URL.

​
API structure changes

v1 had a small number of generic endpoints. v2 has resource-specific endpoints for each object type.

​
v1 pattern

# Open a connection
POST /api/v1/jobs/submit
{ "job_code": "EnsureConnection", "input": { "source_guid": "...", "username": "...", "password": "..." } }

# Run a job
POST /api/v1/jobs/submit
{ "job_code": "FetchDocuments", "access_token": "..." }

# Answer MFA
POST /api/v1/jobs/mfa/answer
{ "job_guid": "...", "answer": "123456" }

​
v2 pattern

# Open a connection
POST /v2/connections
{ "source_id": "src_...", "auth_method": "username_password", "auth_credentials": { "username": "...", "password": "..." } }

# Run a task
POST /v2/tasks/{task_id}/run
{ "connection_id": "conn_...", "input": { ... } }

# Answer an interaction
POST /v2/connections/{connection_id}/interaction
{ "inputs": { "code": "123456" } }
Every resource in v2 (agents, sources, connections, tasks, task runs, storage items, events, event destinations, workflows) has its own set of CRUD endpoints. IDs are prefixed by type (agt_, src_, conn_, task_, trun_, stor_, evt_, evtd_, wflo_).

​
Webhook and event changes

v1 used a single webhook URL configured in the Dashboard. All events were delivered to that one endpoint. v2 introduces a full event system:
  • Create multiple event destinations (webhooks, AWS SQS, GCP Pub/Sub, and more)
  • Subscribe each destination to specific event types
  • Track individual delivery attempts with statuses and retries
  • Replay failed deliveries
  • Verify webhook signatures using the Standard Webhooks specification
v2 events use a consistent format with a type field (like connection.connected or task_run.completed) instead of v1’s webhook_type + webhook_code combination.

​
What v2 gives you

Features available in v2 that do not exist in v1:
  • Workflows. Chain multiple tasks into a single execution with branching, loops, and sleep steps. No more orchestrating multi-step flows from your server.
  • Typed input and output schemas. Every task defines exactly what input it expects and what output it returns. Deck validates both ends.
  • Interaction system. A general-purpose system for handling MFA, security questions, account selection, and other mid-flow prompts.
  • Multiple event destinations. Subscribe different endpoints to different events. Deliver to webhooks, cloud queues, or message brokers.
  • Event replay. Replay individual events or deliveries when your endpoint was down.
  • Custom extraction schemas. Define your own JSON schemas for document extraction instead of using fixed output formats. (Enterprise)
  • Idempotency keys on all create endpoints. v1 only supported idempotency on job submissions.
  • Prefixed resource IDs. Every ID tells you what type of resource it is (agt_, conn_, trun_), making debugging and logging easier.

​
Migration checklist

1

Create a v2 organization

Log in to the Dashboard and create a new v2 organization.
2

Generate a v2 API key

Get your sk_live_ API key from the v2 organization settings.
3

Recreate your agents and sources

Create agents (previously decks) and sources using the v2 API or Dashboard.
4

Define tasks with schemas

Create tasks with explicit input and output schemas. These replace your v1 job codes.
5

Update your auth flow

Replace EnsureConnection job submissions with POST /v2/connections. Update your frontend to handle the new interaction system.
6

Update task execution

Replace jobs/submit calls with POST /v2/tasks/{task_id}/run. Parse the new response format with typed task run objects.
7

Set up event destinations

Create event destinations to replace your v1 webhook configuration. Subscribe to the event types you need.
8

Update error handling

v2 errors use a consistent errors array with type, code, and message fields. Update your error parsing logic.