Единый контракт для ваших casa

Машиночитаемый контракт

GET /api/v1/openapi.json возвращает документ OpenAPI 3.1, точно описывающий реализацию этого развёртывания: все пути, схемы, требуемые области доступа и ответы, а также события вебхуков. Он создаётся из работающего каталога операций, который формирует и инструменты MCP, поэтому REST и MCP не расходятся.

curl -s "https://<your host>/api/v1/openapi.json"

Интерфейс охватывает casa и черновики, версии и публикации, записи, каталог шаблонов, импорты, портфели и массовые запуски, домены и планы DNS, переадресацию почты, настройки подписки и контактов, социальные источники, аналитику, акции, оплату, участников команды и вебхуки. GET /workspaces/{id}/capabilities сообщает, что из этого действует, имитируется или ждёт учётных данных в вашем пространстве.

Повторы выполняются осознанно

• Каждое изменение требует заголовка Idempotency-Key длиной от 16 до 128 символов. Повтор запроса с тем же ключом и телом возвращает исходный результат с Idempotent-Replayed: true. Тот же ключ с другим телом даёт 409 idempotency_key_reused.
• Изменения casa требуют If-Match с ETag последнего чтения. Устаревшее значение даёт 412 revision_conflict, и ничего не меняется.
• Публикация принимает точные прочитанные revision_id и expected_digest, чтобы вы публиковали проверенное.

Долгая работа становится заданием

Публикации, массовые запуски и другие медленные операции отвечают 202 с заданием. Опрашивайте GET /workspaces/{id}/jobs/{job_id} не чаще, чем указано в next_poll_after_seconds, или подпишитесь на вебхуки job.updated. Принято не значит завершено: прочитайте state, счётчики и error задания до сообщения об успехе.

Ошибки содержат сведения о проблеме

Ошибки используют application/problem+json со стабильным code, локализованным title, request_id и retryable. Ветвите логику по code, никогда по тексту заголовка.

{
  "type": "https://<your host>/problems/insufficient_scope",
  "title": "This token does not include the permission this action needs.",
  "status": 403,
  "code": "insufficient_scope",
  "request_id": "01M5...",
  "retryable": false,
  "context": { "required_scope": "account:read" }
}

Списки и ограничения

• Конечные точки списков принимают limit (до 100) и cursor предыдущей страницы.
• Каждый токен пространства может выполнять 120 чтений и 30 записей в минуту. При превышении вы получите 429 с заголовком Retry-After.
• Сохраняйте неизвестные поля ответа: новые поля могут появиться без смены версии.