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

# Create and version modals with the API

> Validate modal views, save drafts, and activate a version for button interactions.

See [availability](/guides/availability) for production and staging endpoints.

## Create and version modals

`modals:read` and `modals:write` are available to members, admins and owners. Validate before saving:

```http theme={null}
POST /v1/modals/validate
Content-Type: application/json
```

```json theme={null}
{
  "title": "Review request",
  "submit_label": "Submit",
  "close_label": "Cancel",
  "blocks": [
    {
      "type": "input",
      "label": { "type": "plain_text", "text": "Reason for {{request}}" },
      "element": { "type": "plain_text_input", "action_id": "reason", "multiline": true }
    }
  ],
  "sample_data": { "request": "this change" }
}
```

Validation returns normalized `blocks`, the builder-compatible `placeholder_mapping`, and a
`compiled_view`. It uses the same compiler as `slack-modal-open`, calls no external service and
spends no credits. For creation, add `name` and POST the same content to `/v1/modals`, optionally
with `activate: true`. Definition and first version commit together or neither exists. The default
is a current draft version, so the web editor can load it. Current does not mean active: activate it before referencing it from an interactive
button; a foreign, draft, inactive or missing modal is rejected during template authoring.

* `GET /v1/modals` lists definitions; `GET /v1/modals/{id}` includes the current version.
* `PATCH /v1/modals/{id}` edits name, description, title and labels; omitted fields stay unchanged.
* `GET /v1/modals/{id}/versions` lists newest first.
* `POST /v1/modals/{id}/versions` appends `blocks`, `sample_data`, and optional `activate`.
* `POST /v1/modals/{id}/versions/{version_id}/activate` atomically selects an existing version.

Block content is versioned. Creating another API draft leaves the existing active version selected. Saving a draft in the browser makes that modal unavailable to opening until it is active again. Check the selected version and status before connecting a button.

Supported authoring blocks are input, section, context and divider, with existing modal directive
containers. Supported inputs are plain-text, static select, checkboxes, radio buttons, date and time
pickers. Title/labels allow 24 characters; compiled views allow at most 100 blocks, following
[Slack's view contract](https://docs.slack.dev/reference/views/modal-views/). The modal compiler's
`if` directive tests a truthy dot path; it does not support the message compiler's operator conditions
or `elseChildren`. Validate representative sample data for every branch. Dynamic data can still
produce an invalid Slack view later; local validation does not call Slack. There is no API endpoint to open a modal independently of a Slack interaction. Test by sending a message with an Open Modal button.

See [Data binding](/guides/modals-data-binding) and [Submissions](/guides/modals-submissions) to complete the workflow.