Documentação da API □ Drawspell

Criar um quarto

Crie uma sala com decks pré-carregados opcionais e convites pessoais.

POST/api/v1/rooms

Cabeçalhos

Authorization necessário: Chave API do portador. Veja autenticação.
Content-Type necessário: application/json
Idempotency-Key necessário: Único por criação; 1–128 caracteres ASCII visíveis.

Corpo

Envie {} para uma sala padrão. Máximo 160 KiB; nenhum campo desconhecido.

displaySpectatorLinkboolean · opcional

O padrão é verdadeiro. Defina false para ocultar o link do espectador dos jogadores. A API ainda retorna o link.

playersobject[] · opcional

Até quatro convites pessoais. Cada item contém:

externalIdstring · necessário

O seu identificador de jogador. 1–128 caracteres; único dentro deste pedido.

deckobject · opcional

Deck atribuído ao link pessoal deste jogador.

deckliststring · necessário: Texto do deck para pré-carregamento. Até 32 KiB.
bracketinteger · opcional: 1–5. Armazenado sem visor.

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

Resposta

playerInviteUrl partilhado: Qualquer pessoa com o link pode se juntar a um assento disponível.
players[].joinUrl pessoal: Enviar para o correspondente externalId. Carrega o convés atribuído; nenhuma reserva de assento ou verificação de identidade.
spectatorLinkstring: Sempre retornou ao chamador da API. Qualquer pessoa com este link pode assistir. Quando displaySpectatorLink é falso, os jogadores não podem recuperar o link da aplicação.
activationExpiresAtData ISO: Primeiro jogador deve participar dentro de 24 horas. Jogos ativos continuar após este prazo.

201 Espaço criado

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

Retiradas seguras

Reutilize a mesma chave e conteúdo por até 24 horas. Replays retorna 200 com Idempotency-Replayed: true. Conteúdo diferente retorna 409; uma sala que se foi retorna 410.

10 pedidos / minuto

Compartilhado através das chaves de sua conta, incluindo repetições e pedidos rejeitados. Em 429, espere por Retry-After segundos.

Referência de erro Status, códigos e um exemplo do JSON

Códigos de erro da API
Estado	Código / acção
400	`invalid_request` Verifique JSON, campos e cabeçalhos necessários.
401	`unauthorized` Use uma chave de API ativa.
403	`forbidden` Conta desactivada ou quartos: criar a permissão em falta.
409	`idempotency_conflict` Use uma nova chave para conteúdo diferente.
410	`room_gone` O quarto expirou ou foi apagado. Crie um novo.
413	`body_too_large` Reduza o pedido para 160 KiB ou menos.
415	`unsupported_media_type` Envie Content-Type: application/json.
429	`rate_limited` Espere por Retry-After segundos.
503	`service_unavailable` Tente novamente com os mesmos Idempotency-Key.

409 Resposta de erro

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

API Drawspell