Documentación de la API Ø Drawspell

Crear una habitación

Crear una habitación con cubiertas precargadas opcionales y invitaciones personales.

POST/api/v1/rooms

Headers

Authorizationnecesarios: Llave de API. Ver autenticación.
Content-Typenecesarios: application/json
Idempotency-Keynecesarios: Único por creación; 1–128 caracteres visibles de ASCII.

Cuerpo

Envía {} para una habitación predeterminada. Máximo 160 KiB; sin campos desconocidos.

displaySpectatorLinkboolean · opcional

Defaults to true. Establecer falso para ocultar el enlace del espectador de los jugadores. La API todavía devuelve el enlace.

playersobject[] · opcional

Hasta cuatro invitaciones personales. Cada artículo contiene:

externalIdstring · necesarios

Su identificador de reproductor. 1–128 caracteres; único dentro de esta solicitud.

deckobject · opcional

Deck asignado al enlace personal de este jugador.

deckliststring · necesarios: Deck text to preload. Up to 32 KiB.
bracketinteger · opcional: 1–5. Almacenado sin pantalla.

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

Respuesta

playerInviteUrlcompartido: Cualquier persona con el enlace puede unirse a un asiento disponible.
players[].joinUrlpersonal: Enviar a la coincidencia externalId. Carga su cubierta asignada; sin reserva de asiento o control de identidad.
spectatorLinkstring: Siempre regresa al callador de API. Cualquier persona con este enlace puede ver. Cuando displaySpectatorLink es falso, los jugadores no pueden recuperar el enlace de la aplicación.
activationExpiresAtFecha ISO: El primer jugador debe unirse dentro de 24 horas. Los juegos activos continúan más allá de este plazo.

201 Habitación creada

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

Seguras

Reutilizar la misma clave y contenido para hasta 24 horas. Replays devuelve 200 con Idempotency-Replayed: true. Diferente contenido devuelve 409; una habitación que se ha ido devuelve 410.

10 solicitudes / minuto

Compartido a través de las claves de su cuenta, incluyendo retries y peticiones rechazadas. En 429, esperar Retry-After segundos.

Referencia de error Estado, códigos y un ejemplo JSON

Códigos de error API
Situación	Código / acción
400	`invalid_request` Revise JSON, campos y cabeceras requeridas.
401	`unauthorized` Utilice una clave de API activa.
403	`forbidden` Cuenta desactivada o habitaciones:crear permiso desaparecido.
409	`idempotency_conflict` Utilice una nueva clave para diferentes contenidos.
410	`room_gone` La habitación caducó o fue eliminada. Crear una nueva.
413	`body_too_large` Reducir la solicitud a 160 KiB o menos.
415	`unsupported_media_type` Envía Content-Type: application/json.
429	`rate_limited` Espera. Retry-After segundos.
503	`service_unavailable` Entrada con los mismos Idempotency-Key.

409 Respuesta al error

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

Drawspell API