API

Generate

POST /v1/generate — turn a text prompt into a brand-locked deck.

#POST /v1/generate

Submit a text prompt. heydecks enqueues a generation job and returns 202 Accepted with a job id. Poll GET /v1/jobs/{id} until the status is succeeded or failed.

Base URL: https://heydecks.com

Requires Pro plan or higher. Costs 10 credits per call. Credits are refunded automatically if the job fails.

#Request body

Name	Type	Required	Description
`input`	string	Yes	The source text — notes, transcript, brief, or any freeform content. Maximum 8 000 characters.
`brand_id`	string	No	ID of a brand in your workspace. The generated deck inherits the brand's palette and typography. Omit to use the workspace's active brand.
`title`	string	No	Override the AI-generated deck title. When omitted, heydecks derives a title from the input.

#Request example

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",
    "title": "Q3 Board Update"
  }'

python

Python

import httpx

resp = httpx.post(
    "https://heydecks.com/v1/generate",
    headers={"Authorization": "Bearer hd_live_…"},
    json={
        "input": "Q3 board update — revenue up 18%, three risks, ask for budget approval",
        "brand_id": "brand_abc",
    },
)
job = resp.json()  # {"job_id": "…", "status": "queued", "poll": "/v1/jobs/…"}

#202 Response

Name	Type	Description
`job_id`	string	The UUID of the queued job. Use this to poll `GET /v1/jobs/{id}`.
`status`	string	Always `"queued"` on the initial response.
`poll`	string	Relative path to poll: `/v1/jobs/{id}`.

JSON

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

#Job lifecycle

Code

queued → running → succeeded
                 → failed

Generation runs asynchronously inside Cloudflare Workers. Typical latency is 10–30 seconds. Poll at a 2-second interval until terminal status.

On succeeded, the job response includes a deck object with the draft URL. The deck is unpublished by default — call POST /v1/decks/{id}/publish to make it live.

On failed, credits are refunded automatically.

#Rate limits

Rate limits apply per user, counted over a rolling 1-second window on generate calls only.

Plan	Requests / second
Pro	1
Team	2
Agent	5
Enterprise	10

Exceeding the limit returns 429 rate_limit. Retry after 1 second.