Migrating from v1 - Deck Docs

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 Console, create a new v2 organization. Data is not shared between v1 and v2. Agents, sources, credentials, 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

	v1	v2
Auth method	`x-deck-client-id` + `x-deck-secret` headers	`Authorization: Bearer sk_live_...` header
Key format	Client ID + secret pair	Single API key with `sk_live_` prefix
Base URL	`https://live.deck.co/api/v1`	`https://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 Console.

Concept mapping

The core ideas are the same, but the naming and structure have changed.

v1 Concept	v2 Concept	What changed
Deck	Agent	A “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.
EnsureCredential job	`POST /v2/credentials`	Storing a credential is a dedicated endpoint, not a job submission. Credentials are stored in the Credential Vault and verified on first use.
CloseCredential job	`DELETE /v2/credentials/{credential_id}`	Deleting a credential is a dedicated endpoint.
Access token	Credential ID	v1 returned an `access_token` to reference a credential. v2 returns a `credential_id` directly on the credential object.
Job	Task	A “job” is now a “task.” Tasks have explicit input and output schemas.
Job submission	`POST /v2/tasks/{task_id}/run`	Running a task is a dedicated endpoint with typed input, not a generic `jobs/submit`.
Job code	Task ID	v1 identified jobs by a string code (`FetchDocuments`). v2 uses a typed task ID (`task_abc123`).
Webhook events	Event system	v1 delivered results via webhooks only. v2 has a full event system with destinations, deliveries, and filtering.
MFA via `jobs/mfa/answer`	Interaction endpoint	v1 had a single MFA answer endpoint. v2 has a general-purpose interaction system that handles MFA, security questions, account selection, and more.
Documents	Storage items	v1 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 credential
POST /api/v1/jobs/submit
{ "job_code": "EnsureCredential", "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

# Store a credential
POST /v2/credentials
{ "source_id": "src_...", "auth_method": "username_password", "auth_credentials": { "username": "...", "password": "..." } }

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

# Answer an interaction on a task run
POST /v2/task-runs/{task_run_id}/interaction
{ "input": { "code": "123456" } }

Every resource in v2 (agents, sources, credentials, sessions, tasks, task runs, storage items, events, event destinations) has its own set of CRUD endpoints. IDs are prefixed by type (agt_, src_, cred_, sess_, task_, trun_, stor_, evt_, evtd_).

Webhook and event changes

v1 used a single webhook URL configured in the Console. 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
Verify webhook signatures using the Standard Webhooks specification

v2 events use a consistent format with a type field (like credential.verified 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:

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.
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_, cred_, trun_), making debugging and logging easier.

Migration checklist

Create a v2 organization

Generate a v2 API key

Get your sk_live_ API key from the v2 organization settings.

Recreate your agents and sources

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

Define tasks with schemas

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

Update your auth flow

Replace EnsureCredential job submissions with POST /v2/credentials to store credentials. Credentials are verified automatically on first task run.

Update task execution

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

Set up event destinations

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

Update error handling

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

​Getting started on v2

​Authentication changes

​Concept mapping

​Source changes

​API structure changes

​v1 pattern

​v2 pattern

​Webhook and event changes

​What v2 gives you

​Migration checklist