API

Jobs

GET /v1/jobs/{id} — poll an async generation job.

#GET /v1/jobs/{id}

Returns the current state of a job created by POST /v1/generate. Poll at a 2-second interval until the status reaches a terminal state.

Base URL: https://heydecks.com

#Job statuses

Status	Meaning
`queued`	Job is waiting to start.
`running`	Generation is in progress.
`succeeded`	Deck created. `deck` object is present in the response.
`failed`	Generation failed. `error` object explains the cause. Credits were refunded.

#Request example

Shell

curl https://heydecks.com/v1/jobs/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer hd_live_…"

#Response — succeeded

Name	Type	Description
`id`	string	The job UUID.
`status`	string	`"succeeded"`
`kind`	string	Always `"generate"` for jobs created via `POST /v1/generate`.
`created_at`	string	ISO 8601 timestamp when the job was created.
`updated_at`	string	ISO 8601 timestamp of the last status change.
`deck`	object	Present only when `status` is `"succeeded"`. See deck fields below.
`deck.id`	string	The new deck id. Use this with `POST /v1/decks/{id}/publish`.
`deck.url`	string	Draft URL at `https://heydecks.com/d/{slug}`. Not publicly accessible until published.
`deck.pdf_url`	null	Always `null` from the API. Export PDFs from the dashboard.
`deck.pptx_url`	null	Always `null` from the API. Export PPTX from the dashboard.
`deck.note`	string	Human-readable reminder about publishing and exports.

JSON

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "succeeded",
  "kind": "generate",
  "created_at": "2026-06-12T10:00:00.000Z",
  "updated_at": "2026-06-12T10:00:28.000Z",
  "deck": {
    "id": "deck_abc123",
    "url": "https://heydecks.com/d/q3-board-update",
    "pdf_url": null,
    "pptx_url": null,
    "note": "Export PDFs and PPTX from the dashboard. Call POST /v1/decks/{id}/publish to make the URL publicly accessible."
  }
}

#Response — failed

Name	Type	Description
`error`	object	Present only when `status` is `"failed"`. See error fields below.
`error.code`	string	Machine-readable failure reason, e.g. `"generation_failed"`.
`error.message`	string	Human-readable description of the failure.

JSON

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "kind": "generate",
  "created_at": "2026-06-12T10:00:00.000Z",
  "updated_at": "2026-06-12T10:00:05.000Z",
  "error": {
    "code": "generation_failed",
    "message": "…"
  }
}

A 404 not_found is returned if the job id doesn't exist or belongs to a different user.