API-Dokumentation | Drawspell

Erstellen Sie einen Raum

Erstellen Sie einen Raum mit optionalen vorinstallierten Decks und persönlichen Einladungen.

POST/api/v1/rooms

Kopfzeilen

Authorizationerforderlich: Bearer-API-Schlüssel, siehe Authentifizierung.
Content-Typeerforderlich: application/json
Idempotency-Keyerforderlich: Einzigartig pro Schöpfung; 1–128 sichtbare ASCII-Zeichen.

Körper

Senden Sie {} für einen Standardraum. Maximal 160 KiB; keine unbekannten Felder.

displaySpectatorLinkboolean · fakultativ

Standardmäßig wahr. Setze false, um den Zuschauer-Link vor den Spielern zu verbergen. Die API gibt den Link immer noch zurück.

playersobject[] · fakultativ

Bis zu vier persönliche Einladungen; jeder Artikel enthält:

externalIdstring · erforderlich

Ihre Spielerkennung. 1–128 Zeichen; eindeutig in dieser Anfrage.

deckobject · fakultativ

Deck, das dem persönlichen link dieses spielers zugewiesen ist.

deckliststring · erforderlich: Decktext zum Vorladen. Bis zu 32 KiB.
bracketinteger · fakultativ: 1–5. Ohne Display gespeichert.

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

Antwort

playerInviteUrlgeteilt: Jeder mit dem Link kann sich einem verfügbaren Platz anschließen.
players[].joinUrlpersönlich: Senden Sie an die passende externalId. Ladet ihr zugewiesenes Deck; keine Sitzplatzreservierung oder Identitätskontrolle.
spectatorLinkstring: Jeder mit diesem Link kann zuschauen. Wenn displaySpectatorLink falsch ist, können Spieler den Link nicht aus der App abrufen.
activationExpiresAtISO-Datum: Der erste Spieler muss innerhalb von 24 Stunden beitreten. Aktive Spiele werden nach Ablauf dieser Frist fortgesetzt.

201 Raum geschaffen

{
  "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

Wiederverwendung des gleichen Schlüssels und Inhalts für bis zu 24 Stunden. Wiedergaben geben 200 mit Idempotency-Replayed: true zurück. Unterschiedliche Inhalte geben 409 zurück; ein verschwundener Raum gibt 410 zurück.

10 Anfragen / Minute

Über die schlüssel ihres kontos geteilt, einschließlich retries und abgelehnte anfragen. 429, warte auf Retry-After Sekunden.

Fehlerreferenz Status, Codes und ein JSON-Beispiel

API-Fehlercodes
Status	Code/Aktion
400	`invalid_request` Überprüfen Sie JSON, Felder und erforderliche Header.
401	`unauthorized` Verwenden Sie einen aktiven API-Schlüssel.
403	`forbidden` Konto deaktiviert oder rooms:Erstelle Berechtigung fehlt.
409	`idempotency_conflict` Verwenden Sie einen neuen Schlüssel für unterschiedliche Inhalte.
410	`room_gone` Der Raum ist abgelaufen oder wurde gelöscht. Erstelle einen neuen.
413	`body_too_large` Reduzieren Sie die Anforderung auf 160 KiB oder weniger.
415	`unsupported_media_type` Content-Type: application/json senden.
429	`rate_limited` Warten Sie Retry-After Sekunden.
503	`service_unavailable` Wiederholen Sie mit dem gleichen Idempotency-Key.

409 Fehlermeldung

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