Using the API - Deck Docs

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:

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.

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.

curl https://api.deck.co/v2/test \
  -H "Authorization: Bearer sk_live_your_key_here"

{
  "status": "ready",
  "environment": "live",
  "request_id": "req_a1b2c3d4..."
}

Request format

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

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:

{
  "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:

{
  "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

Pagination

Cursor-based pagination for list endpoints.

Idempotency

Safely retry requests without creating duplicates.

Error handling

Error structure, types, and codes.

Rate limits

Request limits and retry strategies.

​Base URL

​Authentication

​Verify your key

​Request format

​Response format

​Request IDs

​Next steps