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 plan, free included; the free tier is rate-limited to 1 generate request per second. 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.
POST/v1/decks/{id}/exportsMint a short-lived PDF or PPTX download link. Free, works on drafts.
POST/v1/decks/{id}/previewsMint a short-lived PNG link for one slide. Free, works on drafts.
GET/v1/slide-templatesBrowse the 98 slide templates and their content schemas.
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. Preview — POST /v1/decks/{id}/previews returns a PNG of a slide, so you can check the deck before anyone sees it.
  4. Publish — POST /v1/decks/{id}/publish makes the draft URL live.
  5. Export — POST /v1/decks/{id}/exports returns a download link for the PDF or PPTX. No dashboard visit needed.

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.