Deck

Faithful to the live Deck API v2.0.0 (captured 2026-06-09). The object shapes, event names, error envelope, IDs and formats below are exactly what real Deck returns — this page is the vocabulary to assert against, not a tutorial on Deck. If you know the API, the only new surface is the control layer at the bottom.

npx prod-break run deck
# url=http://localhost:8801   key=pbw_3f9a…   pack=deck@0.1.0
# → point your Deck client's base URL at the url; everything else is unchanged

Deck ships no SDK and no sandbox, so your app already points a plain HTTP client at https://api.deck.co/v2 — repointing it is a one-line base-URL change (Interception).

Objects

agent ──owns──▶ task ──run──▶ task_run ──in──▶ session
                 │               │
        input/output schema   credential ─▶ source (a website)
                                 │
                          event ─▶ event_destination

task
task_run
session
event
event_destination

{
  "id": "task_P8TAk2", "object": "task", "agent_id": "agt_TkKr",
  "name": "Post item on Marketplace",
  "status": "live",                 // learning | test | live
  "input_schema":  { "type": "object", "properties": { "title": { "type": "string" }, "price": { "type": "number" } } },
  "output_schema": { "type": "object", "properties": { "listing_id": { "type": "string" }, "listing_url": { "type": "string" } } }
}

{
  "id": "trun_8a2", "object": "task_run",
  "task_id": "task_P8TAk2", "agent_id": "agt_TkKr",
  "credential_id": "cred_alice", "session_id": "sess_m25", "workflow_id": null,
  "status": "completed",            // queued|running|interaction_required|review_required|completed|failed|cancelling|canceled
  "result": "success",              // success | failure | unknown   (null until terminal)
  "runtime_ms": 60310,
  "output": { "listing_id": "lst_77c", "listing_url": "https://www.autotrader.ca/a/lst_77c" },
  "errors": [], "interaction": null,
  "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:01:00Z"
}

input / storage / artifacts are omitted unless requested with ?include=input,storage,artifacts.

{
  "id": "sess_m25", "object": "session",
  "status": "idle",                 // queued|running|idle|completing|completed|failed
  "runtime_ms": 716000,
  "created_at": "2026-01-01T00:00:00Z"
}

{
  "id": "evt_v0h", "object": "event",
  "type": "task_run.completed",     // object.action
  "data": { /* subset snapshot of the resource at emit time */ },
  "created_at": "2026-01-01T00:01:00Z"
}

{
  "id": "evtd_1", "object": "event_destination",
  "type": "webhook",                // webhook|aws_sqs|aws_kinesis|aws_s3|aws_eventbridge|gcp_pubsub|rabbitmq|azure_servicebus|hookdeck
  "events": ["task_run.completed", "task_run.failed"],
  "status": "active",               // pending_verification | active | inactive
  "type_config": { "url": "https://you.example/hook", "secret": "whsec_…" }
}

Events

object.action. data is a frozen subset snapshot, and it differs from the REST view: empty fields serialize as "" (not null) and some fields are dropped — workflow_id is the canonical divergence (null over REST, "" in the event).

Resource	Event types
`agent`	`created` · `updated` · `deleted`
`source`	`created` · `updated` · `deleted`
`credential`	`created` · `unverified` · `verified` · `invalid` · `deleted`
`session`	`queued` · `running` · `idle` · `completing` · `completed` · `failed`
`task`	`created` · `updated` · `reset` · `deleted`
`task_run`	`queued` · `running` · `interaction_required` · `review_required` · `completed` · `failed` · `canceling` · `canceled`
`storage`	`created`
`event_destination`	`activated` · `deactivated`
`user`	`created`

task_run.**canceling** is spelled with one L in the event name, while the run status is cancelling (two L). /event-types is the only unpaginated list. Deliveries are signed with the Standard Webhooks scheme (webhook-id / webhook-timestamp / webhook-signature).

Errors

The { type, code, message, field? } element is the same everywhere, but it surfaces in two places — which one you get depends on whether the call failed or the run failed. 1 · A call fails → HTTP error response. Status 401/403/404/409/422/429/500, body is the envelope:

// e.g. GET /tasks/task_xxx with a bad key  → HTTP 401
{ "errors": [ { "type": "request", "code": "api_key_invalid", "message": "The API key is not valid.", "field": null } ],
  "request_id": "req_v0hE8IKbqoap" }

code	HTTP
`request` / `api_key_invalid`	401
`request` / `task_not_found` (any `*_not_found`)	404
`idempotency` / `idempotency_error`	409
`rate_limit` / `rate_limit_exceeded`	429

400 validation errors are the one exception — a different, RFC-9110-style shape (not the envelope):

{ "type": "…", "title": "Invalid input", "status": 400,
  "errors": { "input.price": ["must be a number"] }, "traceId": "…" }

Quirks: an unknown route returns 404 with an empty body (no envelope); a bad filter value or over-range Limit is lenient → 200, never 400. 2 · A run fails → the call succeeds (HTTP 200), the error lives inside the run. result: "failure", output: null, and errors[] holds the same element:

// GET /task-runs/trun_8a2  → HTTP 200
{ "id": "trun_8a2", "status": "failed", "result": "failure", "output": null,
  "errors": [ { "type": "task", "code": "blocked", "message": "Site blocked automated access." } ] }

code	When the run fails because…
`task` / `blocked`	the site blocked automated access
`task` / `task_failed`	the run failed
`task` / `timeout`	it exceeded the 30-min run timeout
`task` / `task_result_unknown`	the outcome couldn’t be determined
`auth` / `auth_invalid`	the credentials were rejected by the source
`source` / `source_blocked` · `source_not_available`	the source itself failed

type taxonomy (full set): api · auth · idempotency · interaction · organization · rate_limit · request · session · source · storage · task. Note api_key_invalid is type request, not auth — auth is only for credential-vs-source failures.

Pinnable values

The fields that originate outside Deck’s logic — the only ones you supply. Everything else (status, result, runtime_ms, ids, timestamps) is engine-derived and unfakeable.

Path	What	Binds at	`null` when
`output`	run result body (shape = task’s `output_schema`)	`completed`	run fails / cancels
`output.<field>`	one output field	`completed`	agent couldn’t fill it
`errors`	failed run’s `errors[]`	`failed`	success arm → `[]`
`interaction`	mid-run challenge (`mfa` / `security_question` / `account_selection`)	`interaction_required`	not paused → `null`
`result`	`success` / `failure` / `unknown`	terminal	non-terminal → `null`

Formats & conventions


IDs	lowercase prefix + 16-char base62 suffix (`trun_Ijz17mHzBrps2bt0`), immutable
Credentials	only `username` reads back; secrets are write-only
Pagination	`{ data[], has_more, next_cursor, request_id }`; param `Limit` (capital L), clamped at 100
Auth	`Authorization: Bearer sk_live_…` (sandbox: the printed `pbw_…` key)
Content-Type	`application/json; charset=utf-8`

Control (prod-break)

The only surface that isn’t real Deck. Everything above is the vendor’s; this is how you make a given outcome happen on demand.

// SETUP — seed your create-once definitions (agents/tasks/sources/credentials); runs reference them by id.
await sandbox.seed("tasks", [{ id: "task_P8TAk2", agent_id: "agt_TkKr", status: "live",
  output_schema: { type: "object", properties: { listing_id: { type: "string" }, listing_url: { type: "string" } } } }]);

// pin an out-of-control value, or force the failure arm
await sandbox.exogenous.on("task_run", "output", { listing_id: "lst_77c", listing_url: "https://…/lst_77c" });
await sandbox.exogenous.on("task_run", "branch", "failed");

// trigger a world event (the site intervened); the matching event + run fields fall out
await sandbox.world.trigger("task_run.interaction_required", { task_run_id: "trun_8a2", interaction: { type: "mfa", /* … */ } });

// arm an inbound API fault — your call gets Deck's real envelope above
await sandbox.faults.arm("task_runs", "create", { status: 401, code: "api_key_invalid" });

// advance the virtual clock — due lifecycle events drain in order
await sandbox.clock.advance("60s");

Event names and behavior are pack-declared — the engine is generic; the Deck vocabulary above lives in this pack.
Control calls hit /__admin__/*. Their errors (e.g. a task_run_id that doesn’t exist → 409) go to your test, not the app under test, and are not Deck’s error envelope. sandbox.world.next() lists the world events whose preconditions currently hold.
No magic test inputs — Deck has none; force outcomes through this surface, never reserved input values.
Concepts: exogenous values · force a branch · world events · the clock · HTTP API.

Pinned against Deck API v2.0.0 (2026-06-09), guarded by contract tests that diff the pack against captured live responses.

Get started

Core concepts

Supported APIs

Testing in CI

Running a live sandbox

Reference

Trust

Objects

Events

Errors

Pinnable values

Formats & conventions

Control (prod-break)

​Objects

​Events

​Errors

​Pinnable values

​Formats & conventions

​Control (prod-break)

Objects

Events

Errors

Pinnable values

Formats & conventions

Control (prod-break)