> ## Documentation Index > Fetch the complete documentation index at: https://docs.deck.co/llms.txt > Use this file to discover all available pages before exploring further. # Migrating from v1 > What changes between v1 and v2, and how to move your integration over. 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: ```json theme={null} 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 ```bash theme={null} # 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 ```bash theme={null} # 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](https://www.standardwebhooks.com/) 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 Log in to the Console and create a new v2 organization. Get your `sk_live_` API key from the v2 organization settings. Create agents (previously decks) and sources using the v2 API or Console. Create tasks with explicit input and output schemas. These replace your v1 job codes. Replace `EnsureCredential` job submissions with `POST /v2/credentials` to store credentials. Credentials are verified automatically on first task run. Replace `jobs/submit` calls with `POST /v2/tasks/{task_id}/run`. Parse the new response format with typed task run objects. Create event destinations to replace your v1 webhook configuration. Subscribe to the event types you need. v2 errors use a consistent `errors` array with `type`, `code`, and `message` fields. Update your error parsing logic.