> ## 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](/api/using-the-api).
## Set up your agent and tasks
Create an agent in the Console or through the API. Scope it to a single use case, like hotel 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": "Hilton Reservations",
"description": "Fetch reservations from Hilton"
}'
```
```json Response theme={null}
{
"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..."
}
```
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.
```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...",
"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": 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](/concepts/tasks) for details on task statuses.
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 [Credential Vault](/platform/credential-management) so they can be reused across multiple task runs.
| Method | Description |
| ------------------- | --------------------- |
| `username_password` | Username and password |
| `none` | No credentials needed |
```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": "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.
```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"
}
}'
```
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](/guides/interactions) for details.
When the task completes, Deck sends a `task_run.completed` or `task_run.failed` event to your [event destination](/events/destinations-and-deliveries). 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.
```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
Build a frontend for collecting credentials.
Respond to MFA and verification prompts during execution.
Subscribe to real-time notifications.