Skip to main content

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.

Create an agent, store user credentials, 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 Console or through the API. Scope it to a single use case, like hotel reservations.
Request
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"
  }'
Response
{
  "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",
  "request_id": "req_a1b2c3d4..."
}
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 Console with prompting or from a template. They can also be created through the API.
Request
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",
    "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" }
            }
          }
        }
      }
    }
  }'
Response
{
  "id": "task_x9y8z7...",
  "object": "task",
  "name": "Fetch Reservations",
  "prompt": null,
  "status": "learning",
  "agent_id": "agt_a1b2c3d4...",
  "input_schema": {...},
  "output_schema": {...},
  "storage": null,
  "extraction": false,
  "created_at": "2026-03-10T14:01:00Z",
  "updated_at": "2026-03-10T14:01:00Z",
  "request_id": "req_a1b2c3d4..."
}
Tasks start in learning status. You can run tasks in any status, but success rates improve as the task progresses to test and then live. See Tasks for details on task statuses.
3

Add a source

A source is a website your agents connect to. The URL goes inside a website object.
Request
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"
    }
  }'
Response
{
  "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",
  "request_id": "req_a1b2c3d4..."
}

​
Store credentials (optional)

Not all tasks require authentication. If the source requires a user to be logged in, you can store credentials ahead of time and pass them when running tasks. Deck encrypts and stores them in the Credential Vault so they can be reused across multiple task runs.
MethodDescription
username_passwordUsername and password
noneNo credentials needed
Request
curl -X POST https://api.deck.co/v2/credentials \
  -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..."
  }'
The credential is created with unverified status. It becomes verified the first time a task run successfully authenticates with it.
Response
{
  "id": "cred_a1b2c3d4...",
  "object": "credential",
  "status": "unverified",
  "external_id": "user_123...",
  "source_id": "src_a1b2c3d4...",
  "auth_method": "username_password",
  "auth_credentials": {
    "username": "user@example.com"
  },
  "created_at": "2026-03-10T14:03:00Z",
  "updated_at": "2026-03-10T14:03:00Z",
  "request_id": "req_a1b2c3d4..."
}

​
Run a task

Run a task by providing the input. If the source requires authentication, pass a credential_id. Deck creates a session and executes the task. The input must match the task’s input schema.
Request
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 '{
    "credential_id": "cred_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 credential_id and input. The response comes back immediately with status: "queued". Deck creates a session and transitions the run to running once execution begins. The response includes a session_id you can reuse to run additional tasks without re-authenticating.If the source requires verification during execution (MFA, security question), the task run pauses with interaction_required status. See Handling interactions for details.
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 is no longer queued or running. Task runs typically take seconds to minutes depending on complexity. We recommend polling every 5 seconds. The output contains structured data matching the task’s output schema.
Response
{
  "id": "trun_a1b2c3d4...",
  "object": "task_run",
  "status": "completed",
  "result": "success",
  "task_id": "task_x9y8z7...",
  "credential_id": "cred_a1b2c3d4...",
  "session_id": "sess_x9y8z7...",
  "agent_id": "agt_a1b2c3d4...",
  "source_id": "src_a1b2c3d4...",
  "workflow_id": null,
  "runtime_ms": 4523,
  "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
      }
    ]
  },
  "errors": null,
  "interaction": null,
  "canceled_at": null,
  "created_at": "2026-03-10T14:05:00Z",
  "updated_at": "2026-03-10T14:06:12Z",
  "request_id": "req_a1b2c3d4..."
}
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.

Handling interactions

Respond to MFA and verification prompts during execution.

Events

Subscribe to real-time notifications.