Documentazione API

Creare una stanza

Creare una stanza con ponti precaricati opzionali e inviti personali.

POST/api/v1/rooms

Intestazioni

Authorizationrichiesto: Portachiavi API. Vedere autenticazione.
Content-Typerichiesto: application/json
Idempotency-Keyrichiesto: Unico per creazione; 1–128 caratteri ASCII visibili.

Corpo

Invia {} per una stanza predefinita. Massimo 160 KiB; nessun campo sconosciuto.

displaySpectatorLinkboolean · opzionale

Impostare il falso per nascondere il link dello spettatore dai giocatori. L'API restituisce ancora il link.

playersobject[] · opzionale

Fino a quattro inviti personali. Ogni articolo contiene:

externalIdstring · richiesto

L'identificatore del giocatore. 1–128 caratteri; unico all'interno di questa richiesta.

deckobject · opzionale

Deck assegnato al link personale di questo giocatore.

deckliststring · richiesto: Deck text to preload. Fino a 32 KiB.
bracketinteger · opzionale: 1–5. Conservato senza 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
      }
    }
  ]
}'

Risposta

playerInviteUrlcondiviso: Chiunque con il link può aderire a un posto disponibile.
players[].joinUrlpersonale: Invia alla corrispondenza externalId. Carica il loro mazzo assegnato; nessuna prenotazione del sedile o controllo dell'identità.
spectatorLinkstring: Chiunque con questo link può guardare. Quando displaySpectatorLink è falso, i giocatori non possono recuperare il link dall'app.
activationExpiresAtData ISO: Il primo giocatore deve iscriversi entro 24 ore. I giochi attivi continuano oltre questa scadenza.

201 Camera creata

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

Ritiri sicuri

Riutilizzare la stessa chiave e il contenuto per un massimo di 24 ore. Riproduci il reso 200 con Idempotency-Replayed: true. Il contenuto differente restituisce 409; una stanza che è andato restituisce 410.

10 richieste / minuto

Condividi tra le chiavi del tuo account, inclusi i commenti e le richieste respinte. Su 429, attendere Retry-After secondi.

Riferimento di errore Status, codici e un esempio JSON

codici di errore API
Stato	Codice / azione
400	`invalid_request` Controlla JSON, campi e intestazioni richieste.
401	`unauthorized` Utilizzare una chiave API attiva.
403	`forbidden` Conto disabilitato o camere:creare il permesso mancante.
409	`idempotency_conflict` Utilizzare una nuova chiave per diversi contenuti.
410	`room_gone` La stanza è scaduta o è stata cancellata.
413	`body_too_large` Ridurre la richiesta a 160 KiB o meno.
415	`unsupported_media_type` Invia Content-Type: application/json.
429	`rate_limited` Attendere Retry-After secondi.
503	`service_unavailable` Riprovare con lo stesso Idempotency-Key.

409 Risposta di errore

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

Drawspell API