Get started

Quickstart

API key → generate → poll → publish. Four steps, under 60 seconds.

#1. Mint an API key

Sign in at heydecks.com/dashboard/api-keys. Click New key, name it, and copy the plaintext. The key is shown once — store it securely.

Keys are prefixed hd_live_ and require a Pro plan or higher to call the REST API.

#2. POST to /v1/generate

Submit your source text. heydecks enqueues a generation job and returns 202 Accepted immediately.

curl

Shell

curl -X POST https://heydecks.com/v1/generate \
  -H "Authorization: Bearer hd_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Q3 board update — revenue up 18%, three risks, ask for budget approval",
    "brand_id": "brand_abc"
  }'

202 Response

JSON

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "poll": "/v1/jobs/550e8400-e29b-41d4-a716-446655440000"
}

input is required, max 8 000 characters. brand_id and title are optional. Generation costs 10 credits and is refunded automatically on failure.

#3. Poll GET /v1/jobs/{id}

Poll until status is succeeded or failed. Recommended interval: 2 seconds. Generation typically completes in 10–30 seconds.

curl

Shell

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

succeeded

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."
  }
}

failed

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": "…"
  }
}

The job lifecycle is queued → running → succeeded | failed. On failure the 10 credits are refunded automatically.

#4. Publish the deck

The generated deck is a draft. Call publish to make the URL publicly accessible.

curl

Shell

curl -X POST https://heydecks.com/v1/decks/deck_abc123/publish \
  -H "Authorization: Bearer hd_live_…"

200 Response

JSON

{
  "id": "deck_abc123",
  "status": "published",
  "url": "https://heydecks.com/d/q3-board-update",
  "published_at": "2026-06-12T10:01:00.000Z"
}

Share the URL or embed it. To revert to draft, call POST /v1/decks/{id}/unpublish.

#What's next

Authentication — key management, header format, error codes.
Brands — extract a brand from a URL, then pass brand_id to generate.
MCP server — skip the polling loop entirely. generate_deck is one tool call.