API

Decks

List, create, update, publish, and delete decks.

Base URL: https://heydecks.com

All endpoints require Authorization: Bearer hd_live_….

#GET /v1/decks

List all decks in your workspace.

Shell

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

200 Response — array of deck summaries:

JSON

[
  {
    "id": "deck_abc123",
    "title": "Q3 board update",
    "slug": "q3-board-update",
    "status": "published",
    "visibility": "public",
    "url": "https://heydecks.com/d/q3-board-update",
    "updated_at": "2026-06-12T10:00:00.000Z",
    "created_at": "2026-06-01T09:00:00.000Z"
  }
]

url is null for draft decks.

#POST /v1/decks

Create an empty deck. Add sections via the MCP server or the dashboard editor.

Name	Type	Required	Description
`title`	string	Yes	Deck title.

Shell

curl -X POST https://heydecks.com/v1/decks \
  -H "Authorization: Bearer hd_live_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "New deck"}'

201 Response:

JSON

{
  "id": "deck_xyz789",
  "title": "New deck",
  "slug": "new-deck",
  "status": "draft",
  "visibility": "public",
  "created_at": "2026-06-12T12:00:00.000Z"
}

#GET /v1/decks/{id}

Fetch a single deck with all section instances and their content.

Shell

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

200 Response:

JSON

{
  "id": "deck_abc123",
  "title": "Q3 board update",
  "slug": "q3-board-update",
  "status": "published",
  "visibility": "public",
  "brand_id": "brand_xyz",
  "locale": "en",
  "url": "https://heydecks.com/d/q3-board-update",
  "sections": [
    {
      "id": "sec_001",
      "template_key": "title",
      "order": 0,
      "content": {
        "title": "Q3 board update",
        "subtitle": "June 2026"
      },
      "notes": null
    }
  ],
  "created_at": "2026-06-01T09:00:00.000Z",
  "updated_at": "2026-06-12T10:00:00.000Z"
}

#PATCH /v1/decks/{id}

Update deck metadata. Pass only the fields you want to change.

Name	Type	Required	Description
`title`	string	No	New title.
`slug`	string	No	New URL slug. Must be unique in your workspace. Auto-suffixed (`-2`, `-3` …) on conflict.
`visibility`	string	No	`"public"` \| `"password"` \| `"expiring"`
`brand_id`	string	No	Attach a different brand by id.

Shell

curl -X PATCH https://heydecks.com/v1/decks/deck_abc123 \
  -H "Authorization: Bearer hd_live_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "Q3 Board Update (final)", "visibility": "public"}'

200 Response — updated deck metadata (same shape as the GET, without sections).

#DELETE /v1/decks/{id}

Permanently delete a deck and all its sections. Returns 204 No Content.

Shell

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

Warning — Deletion is permanent. There is no undo via the API. Use the dashboard to restore from version history.

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

Make a deck publicly accessible at its slug URL.

Shell

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

200 Response:

JSON

{
  "id": "deck_abc123",
  "status": "published",
  "url": "https://heydecks.com/d/q3-board-update",
  "published_at": "2026-06-12T10:01:00.000Z"
}

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

Revert a deck to draft. The public URL stops resolving immediately.

Shell

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

200 Response:

JSON

{
  "id": "deck_abc123",
  "status": "draft"
}