API

Sections and editing

Add, change, reorder, and delete the sections 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 sections. Each section has an id, a template_key (the section 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 section 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}/sections

List a deck's sections.

Shell

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

200 Response

JSON

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

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

Add a section. 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/sections \
  -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/sections \
  -H "Authorization: Bearer hd_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "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_section_id inserts right after a section. Omit both to append at the end. notes sets speaker notes.

201 Response

JSON

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

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

#PATCH /v1/decks/{id}/sections/{sectionId}

Change a section'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/sections/sec_a1b2 \
  -H "Authorization: Bearer hd_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "content": { "title": "Q3 board update (final)" } }'

200 Response — the updated section.

#DELETE /v1/decks/{id}/sections/{sectionId}

Remove a section. Returns 204 No Content.

Shell

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

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

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

Shell

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

200 Response — the reordered sections.

#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 sections, 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_section", "section_id": "sec_a1b2", "content": { "title": "Ship faster, argue less." } },
    { "op": "add_section", "template_key": "cta", "content": { "heading": "Start your trial" } }
  ],
  "deck": {
    "id": "deck_abc123",
    "title": "Q3 board update",
    "sections": [ /* full updated section 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 section does not exist in your workspace.
`422`	`invalid_input`	Missing `prompt`/`template_key`, unknown `template_key`, or a malformed body.
`402`	`insufficient_credits`	Out of credits for an AI call.
`502`	`ai_unavailable`	The model call failed (credits are refunded).