Documentação da API

Referência completa de todos os endpoints da API Qora. Dados educacionais integrados com as principais bancas do país.

Base URL:https://api.useqora.xyz/v1
OpenAPI Spec (Postman)

Autenticação

Todas as requisições devem incluir o header Authorization com sua chave de acesso Bearer. Você pode gerenciar suas chaves (criar, rotacionar, excluir) direto no seu dashboard.

curl -H "Authorization: Bearer qora_sua_chave" \ https://api.useqora.xyz/v1/questions
GET

/health

Verifica a saúde e o tempo de atividade do servidor. Não necessita de autenticação.

{
  "success": true,
  "status": "ok",
  "uptime": 77.45,
  "timestamp": 1782026167212
}
GET

/questions

Lista as questões do banco de dados com suporte a filtros e paginação. Requer token com permissão questions:read.

ParâmetroTipoDescrição
examBoardstringFiltra por banca (ex: ENEM, ITA, FUVEST)
yearstringFiltra pelo ano da prova (ex: 2023)
subjectstringFiltra pela matéria (ex: Matemática)
topicstringFiltra pelo tópico (ex: Progressão Aritmética)
difficultystringeasy, medium, hard
limitnumberResultados por página (Padrão 10)
{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "examBoard": "ENEM",
      "year": 2023,
      "subject": "Matemática",
      "topic": "Progressão Aritmética",
      "statement": "Enunciado da questão...",
      "difficulty": "medium",
      "alternatives": [
        { "id": "a", "text": "Opção A" },
        { "id": "b", "text": "Opção B" }
      ],
      "answerId": "b",
      "explanation": "..."
    }
  ],
  "meta": { "page": 1, "limit": 10, "total": 500, "totalPages": 50, "hasMore": true }
}
GET

/me

Retorna os dados da conta do usuário autenticado, limites de uso e plano.

{
  "success": true,
  "data": {
    "uid": "user_123",
    "name": "João",
    "plan": "premium",
    "dailyLimit": 10000,
    "requestsToday": 150,
    "remainingToday": 9850,
    "keysCount": 2,
    "keys": [...]
  }
}
POST

/admin/login

Inicia uma sessão de administrador verificando as credenciais. Retorna um Bearer token de Admin.

{
  "success": true,
  "token": "uuid_do_token_admin",
  "role": "admin"
}
POST

/admin/questions

Cria uma nova questão na estrutura hierárquica por banca, ano, matéria e tópico. Requer token de administrador.

{
  "examBoard": "ENEM",
  "year": 2023,
  "subject": "Matemática",
  "topic": "Progressão Aritmética",
  "difficulty": "medium",
  "statement": "Enunciado da questão...",
  "alternatives": [
    { "id": "a", "text": "Opção A" },
    { "id": "b", "text": "Opção B" }
  ],
  "answerId": "b",
  "explanation": "Explicação da resposta..."
}
DELETE

/admin/questions/:examBoard/:year/:subject/:topic/:id

Remove uma questão pelo caminho hierárquico exato (usando slugs em minúsculo). Requer token de administrador.

GET

/admin/users

Lista todos os usuários cadastrados na plataforma. Requer token de administrador.

POST

/admin/users/:userId/keys

Cria uma API Key para o usuário especificado com configurações avançadas (limite diário, expiração e restrições de IP).

{
  "token": "qora_minha_chave",
  "label": "Servidor Prod",
  "dailyLimit": 5000,
  "permissions": ["questions:read"]
}