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 is included on every paid plan; the free tier is rate-limited. See Authentication for header format and key management.

#Endpoints

MethodPathPurpose
POST/v1/generateTurn a text prompt into a brand-locked deck (async). Costs 100 credits per deck.
POST/v1/imagesGenerate AI images from a prompt (sync). Costs 80 credits per image.
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 slides.
PATCH/v1/decks/{id}Update deck metadata.
DELETE/v1/decks/{id}Permanently delete a deck.
GET/v1/decks/{id}/slidesList a deck's slides.
POST/v1/decks/{id}/slidesAdd a slide, by AI prompt (10 credits) or direct content.
PATCH/v1/decks/{id}/slides/{slideId}Change a slide's content.
DELETE/v1/decks/{id}/slides/{slideId}Remove a slide.
POST/v1/decks/{id}/slides/reorderReorder a deck's slides.
POST/v1/decks/{id}/editEdit deck content with AI from an instruction. Costs 10 credits.
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 50 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 lets your own model design the deck and build it directly with the slide tools, skipping this generate-and-poll loop.

#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.