Build with AI

# Deck v2 API Context

Deck is a platform that connects to external websites on behalf of your users. You make REST API calls, Deck handles authentication, navigation, and data extraction, and returns structured JSON results. You never interact with websites directly.

## API Basics

- Base URL: `https://api.deck.co/v2`
- Auth: `Authorization: Bearer sk_live_...`
- Content type: `application/json`
- All work is asynchronous. API calls return immediately. Results arrive via events.
- There is no sandbox or test environment. All calls are live.

## Core Integration Flow

1. Create a **Source** (an external website, defined by type and URL)
2. Open a **Connection** (authenticates a user to a source using their credentials)
3. Create a **Task** (defines what to do on the source)
4. Run the **Task** against the connection (returns structured output)
5. Receive results via **Events** pushed to your webhook or queue

## Resource ID Prefixes

Every resource ID is prefixed by type:

| Prefix | Resource |
| --- | --- |
| `agt_` | Agent |
| `src_` | Source |
| `conn_` | Connection |
| `task_` | Task |
| `trun_` | Task Run |
| `stor_` | Storage Item |
| `wflo_` | Workflow |
| `wrun_` | Workflow Run |
| `evt_` | Event |
| `evtd_` | Event Destination |
| `edlv_` | Event Delivery |
| `req_` | Request ID |

## Key Endpoints

| Action | Method | Path |
| --- | --- | --- |
| Create source | POST | `/v2/sources` |
| Open connection | POST | `/v2/connections` |
| Submit interaction | POST | `/v2/connections/{connection_id}/interaction` |
| Create task | POST | `/v2/tasks` |
| Run task | POST | `/v2/tasks/{task_id}/run` |
| Submit task interaction | POST | `/v2/task-runs/{task_run_id}/interaction` |
| List task runs | GET | `/v2/task-runs` |
| Get task run | GET | `/v2/task-runs/{task_run_id}` |
| Create event destination | POST | `/v2/event-destinations` |
| Create workflow | POST | `/v2/workflows` |
| Run workflow | POST | `/v2/workflows/{workflow_id}/run` |

## Connection Authentication

Connections support three auth methods:

```json
{
  "source_id": "src_...",
  "auth_method": "username_password",
  "auth_credentials": { "username": "...", "password": "..." }
}
```

Valid `auth_method` values: `username_password`, `google_sso`, `none`.

## Connection States

`connecting` → `connected` → (optionally `interaction_required`) → `connected` → `disconnected` | `terminated`

- `interaction_required` means the source needs user input (MFA, security question)
- `disconnected` means the session was closed but can be reopened
- `terminated` means the connection was permanently closed and credentials deleted

## Interactions

When a connection or task run needs user input, status becomes `interaction_required`. The response includes an `interaction` object with `type`, `message`, and `fields`. Submit the response to:

- Connections: `POST /v2/connections/{connection_id}/interaction`
- Task runs: `POST /v2/task-runs/{task_run_id}/interaction`

Body: `{ "inputs": { "<field_name>": "<value>" } }`

## Events and Webhooks

Deck pushes events to destinations you configure (webhooks, AWS SQS, Kinesis, S3, GCP Pub/Sub, Azure Service Bus, RabbitMQ, Hookdeck).

Event format:
```json
{
  "id": "evt_...",
  "type": "task_run.completed",
  "data": { ... },
  "created_at": "2025-01-15T09:30:00Z"
}
```

Key event types:
- `connection.connected`, `connection.invalid`, `connection.disconnected`, `connection.terminated`
- `connection.interaction_required`
- `task_run.pending`, `task_run.completed`, `task_run.failed`
- `task_run.interaction_required`

Webhook signatures follow the Standard Webhooks specification. Use the `standardwebhooks` SDK to verify with your `whsec_` signing secret.

## Pagination

All list endpoints use cursor-based pagination:
- Query params: `limit` (default 20, max 100), `cursor`
- Response: `{ "data": [...], "has_more": true, "next_cursor": "eyJ..." }`
- Loop until `has_more` is `false`

## Idempotency

All POST create endpoints accept an `Idempotency-Key` header (max 256 chars, expires after 24h). Same key + same params returns the original response. Same key + different params returns HTTP 409.

## Error Format

```json
{
  "errors": [{ "type": "request", "code": "input_missing", "field": "name", "message": "..." }],
  "request_id": "req_..."
}
```

Always branch on `type` and `code`, never on `message`. Always log `request_id` for debugging.

Common error codes:
- `rate_limit_exceeded` (429) — back off with exponential delay
- `connection_in_use` (429) — connection is busy, wait and retry
- `connection_not_ready` (429) — connection still authenticating
- `auth_invalid` (401) — credentials are wrong
- `mfa_timeout` (408) — MFA expired, start a new connection
- `input_missing` (400) — check the `field` property
- `source_not_available` (503) — external website is down, retry later
- `idempotency_error` (409) — same key with different params

## CRITICAL RULES FOR AI MODELS

### Always do

1. Use event destinations (webhooks, queues) to receive results. Never poll.
2. Use `Idempotency-Key` on all create requests.
3. Handle `interaction_required` status on both connections and task runs.
4. Paginate with `cursor` and `has_more`, never offsets.
5. Verify webhook signatures using the Standard Webhooks SDK.
6. Handle errors by `type` and `code`, never by `message`.

### Never do

1. Do not poll `/v2/task-runs/{id}` in a loop. Use events.
2. Do not hardcode source IDs. Create sources via the API or look them up.
3. Do not ignore `interaction_required`. Users may need to complete MFA.
4. Do not assume task runs complete synchronously. They are always async.
5. Do not send credentials from the client. Always proxy through your server.
6. Do not branch on error `message` strings. They can change without notice.

# Deck v2 Integration Rules

## API
- Base URL: `https://api.deck.co/v2`
- Auth: Bearer token with `sk_live_` prefix
- All requests and responses are JSON
- All work is asynchronous. Never poll. Use event destinations.
- No sandbox or test environment. All calls are live.

## Resource IDs
All IDs are prefixed: agt_, src_, conn_, task_, trun_, stor_, wflo_, wrun_, evt_, evtd_, edlv_, req_

## Auth Methods
`username_password`, `google_sso`, `none`

## Patterns
- Create source → open connection → handle interactions → run tasks → receive events
- Use `Idempotency-Key` header on all create requests
- Verify webhook signatures using the Standard Webhooks SDK with your `whsec_` secret
- Paginate with `cursor` and `has_more`, not offsets
- Handle errors by `type` and `code`, never by `message`
- Proxy all credential handling through your server, never from the client

## Common Mistakes
- Do not poll `/v2/task-runs/{id}`. Use events.
- Do not hardcode source IDs. Look them up or create via API.
- Do not ignore `interaction_required`. Users may need to complete MFA.
- Do not assume task runs complete synchronously.
- Do not branch on error `message` strings.