heydecks
DocumentationAPI ReferenceMCP

API

API overview

REST endpoints to generate, manage, and publish decks. Bearer auth, JSON in, JSON out.

The heydecks REST API turns text into brand-locked deck URLs and manages decks and brands programmatically. Every request is JSON over HTTPS with a Bearer API key.

Base URL: https://heydecks.com

#Authentication

Send your API key as a Bearer token on every request:

Shell
Authorization: Bearer hd_live_<prefix>_<secret>

Mint keys at heydecks.com/dashboard/api-keys. REST API access requires a Pro plan or higher — Free and Solo plans receive a 403 api_not_on_plan on every call. See Authentication for header format and key management.

#Endpoints

MethodPathPurpose
POST/v1/generateTurn a text prompt into a brand-locked deck (async). Costs 10 credits.
GET/v1/jobs/{id}Poll an async generation job.
GET/v1/decksList all decks in your workspace.
POST/v1/decksCreate an empty deck.
GET/v1/decks/{id}Fetch a single deck with all sections.
PATCH/v1/decks/{id}Update deck metadata.
DELETE/v1/decks/{id}Permanently delete a deck.
POST/v1/decks/{id}/publishMake a deck publicly accessible.
POST/v1/decks/{id}/unpublishRevert a deck to draft.
GET/v1/brandsList all brands in your workspace.
POST/v1/brandsCreate a new empty brand.
POST/v1/brands/extractExtract a brand from a public URL. Costs 5 credits.

#The generate → poll → publish loop

  1. Generate — POST /v1/generate enqueues a job and returns 202 with a job_id.
  2. Poll — GET /v1/jobs/{id} at a 2-second interval until succeeded or failed.
  3. Publish — POST /v1/decks/{id}/publish makes the draft URL live.

Prefer natural language? The MCP server collapses this loop into a single generate_deck tool call.

#Errors

Every non-2xx response uses one envelope:

JSON
{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits: need 10, have 3 remaining."
  }
}

See Errors for the full code table.