Documentation de l'API Drawspell

Créer une chambre

Créez une salle avec des ponts préchargés en option et des invitations personnelles.

POST/api/v1/rooms

En-têtes

Authorization requis: Clé API au porteur. Voir authentification.
Content-Type requis: application/json
Idempotency-Key requis: Unique par création; 1–128 caractères ASCII visibles.

Corps

Envoyer {} pour une pièce par défaut. Maximum 160 KiB; pas de champs inconnus.

displaySpectatorLinkboolean · facultatif

Par défaut à true. Définissez false pour masquer le lien de spectateur des joueurs. L'API retourne toujours le lien.

playersobject[] · facultatif

Jusqu'à quatre invitations personnelles. Chaque article contient:

externalIdstring · requis

Votre identifiant de lecteur. 1–128 caractères; unique dans cette requête.

deckobject · facultatif

Deck assigné à ce joueur est un lien personnel.

deckliststring · requis: Texte de pont à précharger. Jusqu'à 32 KiB.
bracketinteger · facultatif: 1–5. Stocké sans affichage.

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

Réponse

playerInviteUrl partagé: N'importe qui avec le lien peut rejoindre un siège disponible.
players[].joinUrlpersonnel: Envoyer à la externalId correspondante. Charge leur pont assigné; pas de réservation de siège ou de vérification d'identité.
spectatorLinkstring: Toujours retourné à l'appelant API. Quiconque avec ce lien peut regarder. Lorsque displaySpectatorLink est faux, les joueurs ne peuvent pas récupérer le lien de l'application.
activationExpiresAtDate ISO: Le premier joueur doit se joindre dans les 24 heures. Les jeux actifs continuent après cette date limite.

201 Chambre créée

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

Services de sécurité

Réutiliser la même clé et le même contenu pendant jusqu'à 24 heures. Replays retourner 200 avec Idempotency-Replayed: true. Différents contenus retourne 409; une pièce qui est partie retourne 410.

10 requêtes / minute

Partagez les clés de votre compte, y compris les relevés et les demandes rejetées. Sur 429, attendez Retry-After secondes.

Référence d'erreur Statuts, codes et exemple JSON

Codes d'erreur de l'API
État	Code / action
400	`invalid_request` Vérifiez JSON, les champs et les en-têtes requis.
401	`unauthorized` Utilisez une clé API active.
403	`forbidden` Compte désactivé ou chambres: créer la permission manquante.
409	`idempotency_conflict` Utilisez une nouvelle clé pour différents contenus.
410	`room_gone` La chambre a expiré ou a été supprimée. Créez une nouvelle chambre.
413	`body_too_large` Réduire la demande à 160 KiB ou moins.
415	`unsupported_media_type` Envoyez Content-Type: application/json.
429	`rate_limited` Attendez Retry-After secondes.
503	`service_unavailable` Réessayez avec le même Idempotency-Key.

409 Réponse d'erreur

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