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

# Using the API

> Base URL, authentication, request format, and response conventions.

The Deck API is a REST API that accepts JSON request bodies and returns JSON responses. All endpoints require authentication via a Bearer token.

## Base URL

All requests are made against the Deck API at:

```text theme={null}
https://api.deck.co/v2
```

## Authentication

Every request requires an API key passed as a Bearer token in the `Authorization` header. Keys are available in your [Console](https://console.deck.co).

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

## Verify your key

Call the test endpoint to confirm your key is valid.

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

```json theme={null}
{
  "status": "ready",
  "environment": "live",
  "request_id": "req_a1b2c3d4..."
}
```

## Request format

All requests use `Content-Type: application/json`. Pass request bodies as JSON.

```bash 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 and manage hotel bookings"
  }'
```

Path parameters are part of the URL. Query parameters are used for filtering and pagination on list endpoints.

## Response format

Every resource response includes a standard set of fields:

```json theme={null}
{
  "id": "agt_a1b2c3d4...",
  "object": "agent",
  "name": "Hotel Reservations",
  "description": "Fetch and manage hotel bookings",
  "created_at": "2025-01-15T09:00:00Z",
  "updated_at": "2025-01-15T09:00:00Z",
  "request_id": "req_a1b2c3d4..."
}
```

| Field        | Description                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------------------- |
| `id`         | Unique identifier, prefixed by resource type (`agt_`, `src_`, `cred_`, `sess_`, `task_`, `trun_`, etc.) |
| `object`     | Resource type as a string. Useful for parsing polymorphic responses.                                    |
| `created_at` | ISO 8601 timestamp                                                                                      |
| `updated_at` | ISO 8601 timestamp                                                                                      |
| `request_id` | Unique identifier for the API request. Include this when contacting support.                            |

Delete responses return a confirmation object:

```json theme={null}
{
  "id": "agt_a1b2c3d4...",
  "object": "agent",
  "deleted": true,
  "request_id": "req_a1b2c3d4..."
}
```

## Request IDs

Every response includes a `request_id`. When something goes wrong, include this value in support requests so Deck can trace exactly what happened.

## Next steps

<CardGroup cols={2}>
  <Card title="Pagination" icon="arrow-right" href="/api/pagination">
    Cursor-based pagination for list endpoints.
  </Card>

  <Card title="Idempotency" icon="shield-check" href="/api/idempotency">
    Safely retry requests without creating duplicates.
  </Card>

  <Card title="Error handling" icon="circle-exclamation" href="/api/errors">
    Error structure, types, and codes.
  </Card>

  <Card title="Rate limits" icon="gauge-high" href="/api/rate-limits">
    Request limits and retry strategies.
  </Card>
</CardGroup>