API ドキュメント

部屋を作る

オプションのプレロードされたデッキと個人招待で部屋を作成します。

POST/api/v1/rooms

ヘッダー

Authorization必須条件: ベアラー API キー。認証を参照してください。
Content-Type必須条件: application/json
Idempotency-Key必須条件: 作成ごとにユニーク。 1〜128 個の ASCII 文字を表示。

ボディ

デフォルトの部屋に{}を送信してください。最大160 KiB、未知のフィールドはありません。

displaySpectatorLinkboolean · オプション

デフォルトは true です。 false を設定して、プレイヤーのスペクターリンクを非表示にします。 API はリンクを返します。

playersobject[] · オプション

最大4つの個人招待状。各項目には以下が含まれます。

externalIdstring · 必須条件

プレイヤー識別子。 1〜128文字; このリクエスト内で一意。

deckobject · オプション

このプレイヤーの個人的なリンクに割り当てられたデッキ。

deckliststring · 必須条件: デッキテキストをプリロードします。最大32 KiB。
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 が false の場合、プレイヤーはアプリからリンクを取得することができません。
activationExpiresAtISOの日付: 初めてのプレイヤーは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=…"
    }
  ]
}

安全なretries

最大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 KiB以下に減らして下さい。
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."
  }
}

Drawspell APIの特長

認証

部屋を作る

ヘッダー

ボディ

フィードバック

安全なretries

10 リクエスト / 分