Referência da API

Tudo que sua IA — ou você — pode chamar: currículos escolares, o quiz, imagens, PDFs e um indicador de que ainda está trabalhando.

Como autenticar

As chamadas do quiz precisam de Authorization: Bearer mais a chave do quiz. Envie If-Match com a versão atual para que duas gravações não se sobrescrevam. Essas respostas nunca vão para o cache.

Abrir o esquema completo

URL base

https://quiz.ai/api/v1

Como autenticar

Authorization: Bearer <quiz-scoped-key>

Mapa da API

GET
/api/v1

Um mapa da API e os links que vêm a seguir.

Sem chave
GET
/api/v1/openapi.json

O esquema OpenAPI 3.1 completo — útil para ferramentas que saibam lê-lo.

Sem chave

Currículos escolares

GET
/api/v1/curricula

Lista os currículos escolares que conhecemos.

Sem chave
GET
/api/v1/curricula/{curriculumId}

Lê os detalhes de um currículo.

Sem chave
GET
/api/v1/curricula/{curriculumId}/objectives?subject=math&grade=5&limit=100&offset=0

Busca os objetivos de aprendizagem de um currículo por disciplina e ano.

Sem chave

O quiz

GET
/api/v1/target

Veja em qual quiz esta chave pode escrever.

Chave do quiz
GET
/api/v1/quizzes/{quizId}

Lê o quiz atual e o número da versão.

Chave do quiz
PUT
/api/v1/quizzes/{quizId}

Substitui o quiz inteiro de uma vez. Envie If-Match para não sobrescrever um trabalho mais novo.

Chave do quiz
POST
/api/v1/quizzes/{quizId}/publish

Confere o quiz e deixa público. Envie If-Match para não sobrescrever um trabalho mais novo.

Chave do quiz

Imagens

POST
/api/v1/quizzes/{quizId}/images

Envie um PNG, JPEG, GIF ou WebP. Guardamos um WebP estático e limpo.

Chave do quiz
POST
/api/v1/quizzes/{quizId}/images/templates

Desenha a imagem de uma pergunta a partir de um modelo, ou prévia em PNG ou SVG.

Chave do quiz
GET
/api/v1/quizzes/{quizId}/images/{imageId}

Baixa uma imagem guardada. Pedidos Range são aceitos.

Chave do quiz
DELETE
/api/v1/quizzes/{quizId}/images/{imageId}

Apaga uma imagem que nenhuma pergunta está usando.

Chave do quiz
Imagens da pergunta

PDFs e atividade

POST
/api/v1/quizzes/{quizId}/activity

Inicia, atualiza ou para o sinal de «ainda trabalhando» de 90 segundos.

Chave do quiz
GET
/api/v1/quizzes/{quizId}/sheet.pdf?names=Alice,Bob&class=5B&key=0

Baixa uma folha de respostas para imprimir. Você pode acrescentar nomes, turma e gabarito.

Chave do quiz

Salve o quiz inteiro

Sua IA envia o título, a descrição, o idioma e todas as perguntas de uma vez. Enviar o mesmo quiz válido duas vezes é seguro.

HTTP
PUT /api/v1/quizzes/qz_7KF2M9qTx3aB
Authorization: Bearer <quiz-scoped-key>
Content-Type: application/json
If-Match: "0"

{
  "title": "A quick tour of the Solar System",
  "description": "Ten friendly questions for curious adults.",
  "language": "en-gb",
  "questions": [
    {
      "prompt": "Which planet has the shortest year?",
      "choices": ["Mercury", "Venus", "Earth", "Mars"],
      "correctChoiceIndex": 0,
      "explanation": "Mercury orbits the Sun in about 88 Earth days."
    }
  ]
}

Regras das perguntas

  • Cada pergunta precisa de um enunciado claro e de duas a seis opções não vazias.
  • Limites: título 140 caracteres, descrição 1.000, 1–100 perguntas, enunciado 500, cada opção 240, explicação 1.000.
  • correctChoiceIndex é o índice (a partir de zero) da opção certa.
  • A ordem das perguntas é a ordem do array — a primeira da lista é a pergunta 1.
  • Envie o último número de versão no cabeçalho If-Match para duas gravações não se atropelarem.

Publique quando estiver bom

Publicar confere o quiz de novo e te dá um link público estável. Se faltar alguma coisa, corrija, salve de novo e publique.

HTTP
POST /api/v1/quizzes/qz_7KF2M9qTx3aB/publish
Authorization: Bearer <quiz-scoped-key>
If-Match: "1"