Quizzes Quizzes
API v1 JSON · Bearer Token · UTF-8

API de quizzes

Crie, leia e altere rascunhos, gerencie questões e publique versões usando o mesmo domínio seguro da aplicação web. A mesma API também dá acesso à Wish Store e a métricas da conta — veja a seção Referência.

Começar pela autenticação Usar com IA Ver endpoints

Base URL

/api/v1

Content-Type

application/json

Autorização

Bearer quiz_...

01 · Autenticação

Gere um token de acesso

A forma recomendada é gerar o token pela sua conta. Ele é exibido uma única vez: copie-o, guarde-o como segredo e envie-o no header Authorization das chamadas seguintes. O mesmo token vale para todos os domínios da API (quizzes, loja, métricas, materiais de estudo) — não há um token por domínio.

Pela interface da conta — recomendado

Entre na sua conta, abra Configurações, selecione Tokens e crie uma credencial para sua integração ou agente de IA.

Abrir configurações

Alternativa programática

Em um cliente sob seu controle, também é possível emitir o token diretamente pela API.

Emitir tokenPOST /api/v1/auth/tokens 
curl -X POST https://quizzes.alissonmachado.dev/api/v1/auth/tokens \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "voce@exemplo.com",
    "password": "sua-senha",
    "name": "Meu agente"
  }'
Resposta · 201 Created 
{
  "data": {
    "id": "UUID_DO_TOKEN",
    "name": "Meu agente",
    "token": "quiz_SEGREDO_EXIBIDO_UMA_VEZ",
    "token_type": "Bearer",
    "scopes": ["quizzes:read", "quizzes:write", "quizzes:publish"],
    "expires_at": null
  }
}
Usar o token
curl https://quizzes.alissonmachado.dev/api/v1/quizzes \
  -H 'Authorization: Bearer quiz_SEU_TOKEN'
Escopos emitidos por padrão
Campo Tipo Presença Descrição
quizzes:read scope Leitura Consulta quizzes, versões e valida rascunhos.
quizzes:write scope Escrita Cria, importa e altera quizzes, rascunhos, questões e alternativas.
quizzes:publish scope Publicação Publica uma versão validada.
study:write scope Escrita Importa bundles de materiais de Conteúdos (leitura/EPUB).
store:write scope Escrita Cadastra produtos na Wish Store. Todos os tokens criados atualmente recebem todos os escopos emitidos.

Revogue tokens pela tela de Configurações ou envie DELETE /api/v1/auth/token com o mesmo header Authorization.

DELETE /api/v1/auth/token
token válido 204 · sem corpo

Revoga imediatamente o Bearer token usado nesta requisição. As demais credenciais da conta continuam ativas. Não recebe path params nem body.

Usar com IA

Conecte um assistente de IA

Ao pedir que uma IA crie ou importe quizzes, envie o link desta página e peça que ela consulte os endpoints, a autenticação e o contrato JSON antes de agir. Compartilhe o token somente em uma ferramenta confiável e nunca em conversas públicas.

Link para compartilhar

https://quizzes.alissonmachado.dev/api/docs

Prompt sugerido

Consulte https://quizzes.alissonmachado.dev/api/docs antes de continuar. Siga a API v1 e use o endpoint de importação descrito na documentação.

API REST direta

Funciona quando o assistente consegue fazer requisições HTTP para este domínio. As versões web dos serviços de IA, porém, navegam por proxies com restrições próprias: a chamada pode falhar com erros como Failed to fetch, sem nem retornar um status HTTP.

Servidor MCP

O Model Context Protocol contorna essas restrições: o cliente de IA conecta o servidor como ferramenta nativa e chama a aplicação por conta própria, com o mesmo Bearer token e as mesmas regras de escopo e propriedade da API REST.

POST /api/mcp
Bearer token JSON-RPC 2.0

Servidor MCP stateless sobre o transporte Streamable HTTP. Aceita as mensagens initialize, ping, tools/list e tools/call; notificações respondem 202. GET e DELETE retornam 405 — não há sessões nem streams SSE. Erros de domínio chegam como resultado da ferramenta com isError: true e o mesmo objeto error da API REST em structuredContent.

As ferramentas disponíveis espelham os endpoints REST uma a uma — cada domínio ( Referência abaixo) lista as suas junto com o endpoint equivalente.

Exemplo · chamada de ferramenta 
curl -X POST https://quizzes.alissonmachado.dev/api/mcp \
  -H 'Authorization: Bearer quiz_SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {"name": "list_quizzes", "arguments": {}}
  }'

Como conectar em cada assistente

02 · Contratos

Formato das requisições e respostas

Todos os corpos usam JSON em UTF-8, em qualquer domínio da API. IDs são UUIDs; datas usam ISO 8601. Os modelos de cada domínio (campos e exemplos) ficam na aba correspondente da seção Referência, abaixo.

Sucesso

Respostas com conteúdo usam {"data": ...}. Exclusões bem-sucedidas usam 204 No Content sem corpo.

Atualizações

Corpos de PATCH são parciais. Campos desconhecidos são ignorados. Envie apenas os campos que deseja alterar.

Propriedade

A API mostra somente recursos da conta autenticada. Um recurso inexistente ou de outra conta retorna o mesmo 404.

03 · Referência

Endpoints, modelos e ferramentas MCP por domínio

Escolha um domínio abaixo. Cada aba reúne os modelos de dados, os endpoints REST (abra uma rota para ver corpo, regras e resposta) e as ferramentas MCP equivalentes desse domínio. Todas exigem Bearer token, exceto a emissão inicial em POST /auth/tokens.

04 · Erros

Códigos e formatos de falha

Respostas de erro
Campo Tipo Presença Descrição
401 unauthorized error object Token ausente, inválido, revogado ou expirado Inclui WWW-Authenticate: Bearer realm="quiz-api".
401 invalid_credentials error object Falha ao emitir token E-mail ou senha inválidos.
403 insufficient_scope error object Escopo ausente Inclui required_scope.
404 not_found error object Ausente ou de outra conta Não revela a existência de recursos alheios.
409 version_not_editable error object Estado incompatível Operação de escrita em versão publicada.
409 published_version_required error object Sem base para novo rascunho Não existe versão publicada para copiar.
422 validation_error error + details[] Parâmetros ou conteúdo inválidos As mensagens legíveis ficam em error.details.
422 operation_failed error object Falha não classificada A operação não pôde ser concluída. 
{
  "error": {
    "code": "validation_error",
    "details": [
      "Questão 1: precisa de pelo menos 2 alternativas",
      "Questão 1: marque exatamente 1 alternativa correta"
    ]
  }
}