API

Slides and editing

Add, change, reorder, and delete the slides of an existing deck, or edit a deck with AI.

Base URL: https://heydecks.com

All endpoints require Authorization: Bearer hd_live_… and a Pro plan or higher.

A deck is an ordered list of slides. Each slide has an id, a slide_type (the slide type, e.g. title, stats, codeBlock), an order, a content object whose shape matches that template, and optional notes (speaker notes).

There are two ways to change a deck:

Direct: you supply the exact content. Best when you already know the slide shape.
AI: you supply a natural-language prompt or instruction and heydecks fills in the content. Best when you want the model to do the work. AI calls cost 1 credit each.

#GET /v1/decks/{id}/slides

List a deck's slides.

Shell

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

200 Response

JSON

{
  "slides": [
    {
      "id": "sec_a1b2",
      "slide_type": "title",
      "order": 0,
      "content": { "title": "Q3 board update", "variant": "light" },
      "notes": null
    }
  ]
}

#POST /v1/decks/{id}/slides

Add a slide. Use one of the two modes.

AI mode — describe the slide, the model picks the template and writes the content (costs 1 credit):

Shell

curl -X POST https://heydecks.com/v1/decks/deck_abc123/slides \
  -H "Authorization: Bearer hd_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "a stats row with three growth numbers" }'

Direct mode — supply the template and content yourself:

Shell

curl -X POST https://heydecks.com/v1/decks/deck_abc123/slides \
  -H "Authorization: Bearer hd_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "slide_type": "stats",
    "content": {
      "heading": "By the numbers",
      "stats": [
        { "value": "3x", "label": "faster onboarding" },
        { "value": "98%", "label": "retention" }
      ]
    }
  }'

Placement (optional, both modes): index (0-based) inserts at a position, or after_slide_id inserts right after a slide. Omit both to append at the end. notes sets speaker notes.

201 Response

JSON

{
  "slide": {
    "id": "sec_c3d4",
    "slide_type": "stats",
    "order": 4,
    "content": { "heading": "By the numbers", "stats": [] },
    "notes": null
  }
}

To discover valid slide_type values and the content shape for each, use the MCP server's list_slide_templates tool, or copy the content shape from an existing slide returned by GET /v1/decks/{id}.

#PATCH /v1/decks/{id}/slides/{slideId}

Change a slide's content. content is a partial patch merged onto the current content, so you only send the fields you want to change. Optionally update notes.

Shell

curl -X PATCH https://heydecks.com/v1/decks/deck_abc123/slides/sec_a1b2 \
  -H "Authorization: Bearer hd_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "content": { "title": "Q3 board update (final)" } }'

200 Response — the updated slide.

#DELETE /v1/decks/{id}/slides/{slideId}

Remove a slide. Returns 204 No Content.

Shell

curl -X DELETE https://heydecks.com/v1/decks/deck_abc123/slides/sec_a1b2 \
  -H "Authorization: Bearer hd_live_…"

#POST /v1/decks/{id}/slides/reorder

Reorder the deck. Pass the full set of slide ids in the order you want.

Shell

curl -X POST https://heydecks.com/v1/decks/deck_abc123/slides/reorder \
  -H "Authorization: Bearer hd_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "ordered_slide_ids": ["sec_a1b2", "sec_c3d4", "sec_e5f6"] }'

200 Response — the reordered slides.

#POST /v1/decks/{id}/edit

Change deck content with AI. Give a natural-language instruction and the planner makes the smallest set of edits that satisfies it (update, add, delete, or reorder slides, or rename the deck) instead of redrafting the whole deck. Costs 1 credit, refunded on failure.

Shell

curl -X POST https://heydecks.com/v1/decks/deck_abc123/edit \
  -H "Authorization: Bearer hd_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "instruction": "change the cover title to a sharper one-liner and add a closing CTA" }'

200 Response

JSON

{
  "summary": "Rewrote the cover title and added a closing CTA.",
  "operations": [
    { "op": "update_slide", "slide_id": "sec_a1b2", "content": { "title": "Ship faster, argue less." } },
    { "op": "add_slide", "slide_type": "cta", "content": { "heading": "Start your trial" } }
  ],
  "deck": {
    "id": "deck_abc123",
    "title": "Q3 board update",
    "slides": [ /* full updated slide list */ ]
  }
}

#Errors

Status	`code`	When
`403`	`api_not_on_plan`	The key's plan does not include API access (Pro and up).
`404`	`not_found`	The deck or slide does not exist in your workspace.
`422`	`invalid_input`	Missing `prompt`/`slide_type`, unknown `slide_type`, or a malformed body.
`402`	`insufficient_credits`	Out of credits for an AI call.
`502`	`ai_unavailable`	The model call failed (credits are refunded).