API documentation | Drawspell

Create a room

Create a room with optional preloaded decks and personal invitations.

POST/api/v1/rooms

Headers

Authorizationrequired: Bearer API key. See authentication.
Content-Typerequired: application/json
Idempotency-Keyrequired: Unique per creation; 1–128 visible ASCII characters.

Body

Send {} for a default room. Maximum 160 KiB; no unknown fields.

displaySpectatorLinkboolean · optional

Defaults to true. Set false to hide the spectator link from players. The API still returns the link.

playersobject[] · optional

Up to four personal invitations. Each item contains:

externalIdstring · required

Your player identifier. 1–128 characters; unique within this request.

deckobject · optional

Deck assigned to this player’s personal link.

deckliststring · required: Deck text to preload. Up to 32 KiB.
bracketinteger · optional: 1–5. Stored without display.

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
      }
    }
  ]
}'

Response

playerInviteUrlshared: Anyone with the link can join an available seat.
players[].joinUrlpersonal: Send to the matching externalId. Loads their assigned deck; no seat reservation or identity check.
spectatorLinkstring: Always returned to the API caller. Anyone with this link can watch. When displaySpectatorLink is false, players cannot retrieve the link from the app.
activationExpiresAtISO date: First player must join within 24 hours. Active games continue past this deadline.

201 Room created

{
  "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=…"
    }
  ]
}

Safe retries

Reuse the same key and content for up to 24 hours. Replays return 200 with Idempotency-Replayed: true. Different content returns 409; a room that is gone returns 410.

10 requests / minute

Shared across your account’s keys, including retries and rejected requests. On 429, wait for Retry-After seconds.

Error reference Statuses, codes, and a JSON example

API error codes
Status	Code / action
400	`invalid_request` Check JSON, fields, and required headers.
401	`unauthorized` Use an active API key.
403	`forbidden` Account disabled or rooms:create permission missing.
409	`idempotency_conflict` Use a new key for different content.
410	`room_gone` Room expired or was deleted. Create a new one.
413	`body_too_large` Reduce the request to 160 KiB or less.
415	`unsupported_media_type` Send Content-Type: application/json.
429	`rate_limited` Wait for Retry-After seconds.
503	`service_unavailable` Retry with the same Idempotency-Key.

409 Error response

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

Drawspell API