> ## 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.

# Quickstart

> Go from zero to structured output in minutes.

Create an agent, store user credentials, and get structured data back.

## Prerequisites

* A Deck account ([console.deck.co](https://console.deck.co))
* A Deck API key
* Base URL: `https://api.deck.co/v2`

All requests require your API key in the `Authorization` header:

```bash theme={null}
curl https://api.deck.co/v2/test \
  -H "Authorization: Bearer sk_live_your_key_here"
```

For details, see [Using the API](https://docs.deck.co/api/using-the-api.md).

## 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. Name it for the use case, not a source: the same agent runs against every hotel site, so it's "Hotel Reservations", not "Hilton Reservations".

```bash Request theme={null}
curl -X POST https://api.deck.co/v2/agents \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hotel Reservations",
    "description": "Fetch hotel reservations"
  }'
```

```json Response theme={null}
{
  "id": "agt_a1b2c3d4...",
  "object": "agent",
  "name": "Hotel Reservations",
  "description": "Fetch hotel reservations",
  "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 or through the API. See [Tasks](https://docs.deck.co/concepts/tasks.md) for guidance on writing prompts and designing input and output schemas.

```bash Request theme={null}
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...",
    "prompt": "Log in and fetch upcoming reservations.",
    "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" }
            }
          }
        }
      }
    }
  }'
```

```json Response theme={null}
{
  "id": "task_x9y8z7...",
  "object": "task",
  "name": "Fetch Reservations",
  "prompt": "Log in and fetch upcoming reservations.",
  "status": "learning",
  "agent_id": "agt_a1b2c3d4...",
  "input_schema": {...},
  "output_schema": {...},
  "storage": null,
  "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`.

**3. Add a source**

A source is a website your agents connect to. The URL goes inside a `website` object.

```bash Request theme={null}
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"
    }
  }'
```

```json Response theme={null}
{
  "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 [Deck Credential Vault](https://docs.deck.co/platform/credential-management.md) so they can be reused across multiple task runs. This example uses `username_password`; see [auth methods](https://docs.deck.co/concepts/credentials.md#auth-methods) for the others.

```bash Request theme={null}
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": "..."
    },
    "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.

```json Response theme={null}
{
  "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.

```bash Request theme={null}
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](https://docs.deck.co/guides/interactions.md) for details.

**2. Receive results**

When the task completes, Deck sends a `task_run.completed` or `task_run.failed` event to your [event destination](https://docs.deck.co/events/destinations-and-deliveries.md). You can also poll `GET /v2/task-runs/{task_run_id}` until `status` is `completed`, `failed`, or `canceled`. 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.

```json Response theme={null}
{
  "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...",
  "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,
  "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

> [card] [Building your auth flow](https://docs.deck.co/guides/building-auth-ui.md)
>
> Build a frontend for collecting credentials.

> [card] [Handling interactions](https://docs.deck.co/guides/interactions.md)
>
> Respond to MFA and verification prompts during execution.

> [card] [Events](https://docs.deck.co/events/events.md)
>
> Subscribe to real-time notifications.

> [card] [Auth Component](https://docs.deck.co/components/auth.md)
>
> Drop-in UI to collect credentials from your users.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.