> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodostatus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Design API Overview

> Versioned draft, validation, publish, and history for status page design and layout

<Info>
  These endpoints are available at `https://kodostatus.com/api/v1` and support API key auth via `X-API-Key`.
</Info>

## Workflow

1. Read current state: `GET /status-pages/{id}/design`
2. Create or update draft: `PUT /status-pages/{id}/design/draft`
3. Validate draft: `POST /status-pages/{id}/design/draft/validate`
4. Publish draft: `POST /status-pages/{id}/design/publish`
5. Audit history: `GET /status-pages/{id}/design/versions`

## Endpoints

| Method | Endpoint                                         | Docs                                             |
| ------ | ------------------------------------------------ | ------------------------------------------------ |
| GET    | `/status-pages/{id}/design`                      | [Get Design State](./design-get-state)           |
| PUT    | `/status-pages/{id}/design/draft`                | [Upsert Design Draft](./design-upsert-draft)     |
| POST   | `/status-pages/{id}/design/draft/validate`       | [Validate Design Draft](./design-validate-draft) |
| POST   | `/status-pages/{id}/design/publish`              | [Publish Design Draft](./design-publish)         |
| GET    | `/status-pages/{id}/design/versions`             | [List Design Versions](./design-list-versions)   |
| GET    | `/status-pages/{id}/design/versions/{versionId}` | [Get Design Version](./design-get-version)       |

## Notes

* Custom template mode is plan-gated (`PLAN_RESTRICTED` if unavailable).
* Publish uses optimistic locking with `expected_draft_version_id` and executes via an atomic database transaction.
* `theme_tokens` and `layout` use strict validation — unknown fields are rejected with a `400` error.
* Version history uses cursor pagination by `version_number`.
* Valid version states: `draft`, `published`, `archived`.