Skip to main content
Create an agent, connect a user to a website, and get structured data back.

​
Prerequisites

  • A Deck account (console.deck.co)
  • A Deck API key
  • Base URL: https://api.deck.co/v2
All requests require your API key in the Authorization header: 
curl https://api.deck.co/v2/test \
  -H "Authorization: Bearer sk_live_your_key_here"
For details, see Using the API.

​
Set up your agent and tasks

1

Create an agent

Create an agent in the Dashboard or through the API. Scope it to a single use case, like hotel reservations.
curl -X POST https://api.deck.co/v2/agents \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hilton Reservations",
    "description": "Fetch reservations from Hilton"
  }'

{
  "id": "agt_a1b2c3d4...",
  "object": "agent",
  "name": "Hilton Reservations",
  "description": "Fetch reservations from Hilton",
  "tasks": [],
  "created_at": "2026-03-10T14:00:00Z",
  "updated_at": "2026-03-10T14:00:00Z"
}
2

Create a task

Tasks define what the agent does, what task input it needs, and what output it returns. Tasks can be created in the Dashboard with prompting or from a template. They can also be created through the API.
curl -X POST https://api.deck.co/v2/tasks \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fetch Reservations",
    "description": "Fetch hotel reservations within a date range",
    "agent_id": "agt_a1b2c3d4...",
    "input_schema": {
      "type": "object",
      "properties": {
        "check_in_date": { "type": "string" },
        "check_out_date": { "type": "string" }
      }
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "reservations": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "confirmation_number": { "type": "string" },
              "hotel_name": { "type": "string" },
              "check_in": { "type": "string" },
              "check_out": { "type": "string" },
              "total_cost": { "type": "number" }
            }
          }
        }
      }
    }
  }'

{
  "id": "task_x9y8z7...",
  "object": "task",
  "name": "Fetch Reservations",
  "description": "Fetch hotel reservations within a date range",
  "status": "learning",
  "agent_id": "agt_a1b2c3d4...",
  "input_schema": {...},
  "output_schema": {...},
  "storage": {
    "enabled": false,
    "deduplication": false
  },
  "extraction": false,
  "created_at": "2026-03-10T14:01:00Z",
  "updated_at": "2026-03-10T14:01:00Z"
}
Tasks start in learning status. You can run tasks in any status, but success rates improve as the task progresses to testing and then live. See Tasks for details on task statuses.
3

Add a source

A source is a website your agents connect to. Create one by providing a URL.
curl -X POST https://api.deck.co/v2/sources \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hilton",
    "type": "website",
    "website": {
      "url": "https://hilton.com"
    }
  }'

{
  "id": "src_a1b2c3d4...",
  "object": "source",
  "name": "Hilton",
  "type": "website",
  "website": {
    "url": "https://hilton.com"
  },
  "created_at": "2026-03-10T14:02:00Z",
  "updated_at": "2026-03-10T14:02:00Z"
}

​
Open a connection

A connection authenticates one user to one source. Connections time out after a period of inactivity.
MethodDescription
username_passwordUsername and password
google_ssoGoogle single sign-on
noneNo credentials needed
curl -X POST https://api.deck.co/v2/connections \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_method": "username_password",
    "auth_credentials": {
      "username": "user@example.com",
      "password": "secret123"
    },
    "source_id": "src_a1b2c3d4...",
    "external_id": "user_123..."
  }'
Deck authenticates the user in the background. The response returns immediately with connecting status. 
{
  "id": "conn_a1b2c3d4...",
  "object": "connection",
  "status": "connecting",
  "external_id": "user_123...",
  "source_id": "src_a1b2c3d4...",
  "auth_method": "username_password",
  "interaction": null,
  "created_at": "2026-03-10T14:03:00Z",
  "updated_at": "2026-03-10T14:03:00Z"
}

​
Wait for the connection

Connection authentication is asynchronous. After creating a connection, Deck works through the login flow and the status transitions automatically: connecting → connected (or interaction_required if the source needs verification, or invalid if the credentials were rejected) You have two options to track the transition:
  • Events (recommended). Listen for connection.connected or connection.interaction_required events on your event destination. This is the most reliable approach.
  • Polling. Call GET /v2/connections/{connection_id} until status changes from connecting.
Do not run tasks until the connection status is connected.

​
Handle MFA

If the source requires additional verification during login, the connection status becomes interaction_required instead of connected.
1

Your app receives the event

Deck sends an interaction_required event to your webhook. The payload includes the prompt type, message, and fields to collect.
{
  "id": "conn_a1b2c3d4...",
  "status": "interaction_required",
  "interaction": {
    "type": "mfa",
    "message": "Enter the 6-digit code sent to your phone",
    "fields": [
      {
        "name": "code",
        "type": "string",
        "label": "Verification code"
      }
    ]
  }
}
2

Collect input and submit

Display the prompt to your user based on the interaction.fields array. Submit their response:
curl -X POST https://api.deck.co/v2/connections/conn_a1b2c3d4.../interaction \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": { "code": "123456" }
  }'
The agent resumes where it left off.

​
Run a task

Once the connection status is connected, you can run tasks against it. The input must match the task’s input schema. 
curl -X POST https://api.deck.co/v2/tasks/task_x9y8z7.../run \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn_a1b2c3d4...",
    "input": {
      "check_in_date": "2026-04-01",
      "check_out_date": "2026-04-05"
    }
  }'
1

Run the task

Send a task run request with a connection_id and input. Deck returns a task run object and begins execution. If the source requires interaction during execution, the task run pauses with interaction_required status. Handle it the same way as connection interactions.
2

Receive results

When the task completes, Deck sends a task_run.completed or task_run.failed event to your event destination. You can also poll GET /v2/task-runs/{task_run_id} until status changes from running. The output contains structured data matching the task’s output schema.
{
  "id": "trun_a1b2c3d4...",
  "object": "task_run",
  "status": "completed",
  "result": "success",
  "task_id": "task_x9y8z7...",
  "connection_id": "conn_a1b2c3d4...",
  "agent_id": "agt_a1b2c3d4...",
  "source_id": "src_a1b2c3d4...",
  "runtime_ms": 4523,
  "input": {
    "check_in_date": "2026-04-01",
    "check_out_date": "2026-04-05"
  },
  "output": {
    "reservations": [
      {
        "confirmation_number": "HLT-849271",
        "hotel_name": "Hilton Garden Inn Chicago",
        "check_in": "2026-04-01",
        "check_out": "2026-04-05",
        "total_cost": 847.50
      }
    ]
  },
  "storage": null,
  "interaction": null,
  "created_at": "2026-03-10T14:05:00Z",
  "updated_at": "2026-03-10T14:06:12Z"
}
If a task run fails, status is failed and the errors array contains details.

​
What’s next

Building your auth flow

Build a frontend for collecting credentials and handling MFA.

Handling interactions

Respond to MFA and verification prompts during execution.

Workflows

Chain tasks into multi-step automations.

Events

Subscribe to real-time notifications.