API文件 QQDrawspell

建立一間房

建立可選擇的預載甲板和個人邀請的房間。

POST/api/v1/rooms

信頭

Authorization需要: Bearer API 按鍵。看認證.
Content-Type需要: application/json
Idempotency-Key需要: 單一建立; 1–128 可见 ASCII 字元。

体

傳送 {} 默认的房間。最大 160 KB;沒有未知的字段。

displaySpectatorLinkboolean · 選擇性

預設為真。設定錯誤以隱藏玩家的觀眾連結。 API 仍會傳回連結。

playersobject[] · 選擇性

最多四份個人邀請函,每份都包含:

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 假的, 玩家無法從應用程式中取回連結。
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=…"
    }
  ]
}

安全重試

重用相同的金鑰和內容最多24小時。 replays return 200 与 Idempotency-Replayed: true。不同的內容返回 409; 已消失的房間 410.

10 個要求/ 分鐘

分享您的帳號的金鑰, 包括回覆和拒絕的請求。 On 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( API )

認證

建立一間房

信頭

体

答复

安全重試

10 個要求/ 分鐘