Документация API: Drawspell

Создайте комнату

Создайте комнату с дополнительными предварительно загруженными палубами и личными приглашениями.

POST/api/v1/rooms

Заголовки

Authorizationнеобходимый: Ключ Bearer API. См. аутентификация.
Content-Typeнеобходимый: application/json
Idempotency-Keyнеобходимый: Уникальный для каждого творения; 1-128 видимых символов ASCII.

тело

Отправьте {} за комнату по умолчанию. Максимум 160 КиБ; никаких неизвестных полей.

displaySpectatorLinkboolean · необязательный

Установите ложное, чтобы скрыть зрителю ссылку от игроков. API по-прежнему возвращает ссылку.

playersobject[] · необязательный

До четырех личных приглашений. Каждый пункт содержит:

externalIdstring · необходимый

Идентификатор игрока: 1-128 символов; уникальный в этом запросе.

deckobject · необязательный

Палуба, назначенная для личной связи этого игрока.

deckliststring · необходимый: Смс на палубе для предварительной загрузки до 32 киб.
bracketinteger · необязательный: 1-5. храниться без дисплея.

curl https://drawspell.space/api/v1/rooms \
  -H "Authorization: Bearer $DRAWSPELL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: match-123" \
  --data '{
  "displaySpectatorLink": false,
  "players": [
    {
      "externalId": "player-1",
      "deck": {
        "decklist": "1 Sol Ring\n1 Command Tower",
        "bracket": 3
      }
    }
  ]
}'

Ответ

playerInviteUrlделиться: Любой, у кого есть ссылка, может присоединиться к доступному месту.
players[].joinUrlличный: Отправляйте на соответствующие externalId. Загружает назначенную палубу; без бронирования места или проверки личности.
spectatorLinkstring: Всегда возвращался к абоненту API. Любой, у кого есть эта ссылка, может смотреть. Когда displaySpectatorLink ложно, игроки не могут получить ссылку из приложения.
activationExpiresAtДата ISO: Первый игрок должен присоединиться в течение 24 часов. Активные игры продолжаются в течение этого срока.

201 Комната создана

{
  "roomId": "abc123",
  "displaySpectatorLink": false,
  "spectatorLink": "https://drawspell.space/rooms/abc123?st=…",
  "activationExpiresAt": "2026-10-10T18:00:00.000Z",
  "playerInviteUrl": "https://drawspell.space/rooms/abc123?gt=…",
  "players": [
    {
      "externalId": "player-1",
      "joinUrl": "https://drawspell.space/rooms/abc123?invite=…"
    }
  ]
}

Безопасные повторы

Повторное использование одного и того же ключа и контента в течение 24 часов. Повторное воспроизведение возвращает 200 с Idempotency-Replayed: true. Разный контент возвращает 409; комната, которая ушла, возвращает 410.

10 запросов / минута

Общие ключи вашей учетной записи, включая повторные запросы и отклоненные запросы. На 429 подождите Retry-After секунды.

Ссылка на ошибку Статусы, коды и пример JSON

Коды ошибок API
статус	Код/действие
400	`invalid_request` Проверьте JSON, поля и необходимые заголовки.
401	`unauthorized` Используйте активный ключ API.
403	`forbidden` Учетная запись отключена или номера: создайте недостающее разрешение.
409	`idempotency_conflict` Используйте новый ключ для другого контента.
410	`room_gone` Комната истекла или была удалена. Создайте новую.
413	`body_too_large` Уменьшите запрос до 160 КБ или меньше.
415	`unsupported_media_type` Отправьте Content-Type: application/json.
429	`rate_limited` Подождите Retry-After секунд.
503	`service_unavailable` Повторите с тем же Idempotency-Key.

409 Ответ на ошибку

{
  "error": {
    "code": "idempotency_conflict",
    "message": "This Idempotency-Key was already used with different content."
  }
}