Base
de Questões de Concurso Público.

POST https://qapi.otunac.com/mcp
Q-Api-Key: qb_SuaChaveAqui
Content-Type: application/json

Ao conectar, o agente lista as ferramentas disponíveis (tools/list) junto com nome, descrição e parâmetros de cada uma — sem precisar de chave, igual à documentação pública desta página. Só a execução de uma ferramenta exige autenticação.

Cada chamada de ferramenta (tools/call) carrega o header Q-Api-Key. O servidor valida a chave (ativa, não suspensa) e o saldo de cotas exatamente como a API REST — e só então repassa a chamada para a base de questões.

Em caso de sucesso, a ferramenta devolve o mesmo JSON que o endpoint REST equivalente retornaria. Em caso de erro (chave ausente/inválida, sem saldo, recurso não encontrado), a ferramenta devolve um resultado de erro (isError: true) com uma mensagem legível — o agente lê o motivo e pode agir (avisar o usuário, sugerir recarregar cotas etc.), em vez de travar. Ver Erros no MCP.

claude mcp add --transport http qapi https://qapi.otunac.com/mcp \
  --header "Q-Api-Key: qb_SuaChaveAqui"

Ao conectar o QAPI como servidor MCP no Claude Web, informe a chave no header x-api-key — o Claude Web não aceita o header Q-Api-Key. Use a mesma chave e a mesma URL:

URL:     https://qapi.otunac.com/mcp
Header:  x-api-key: qb_SuaChaveAqui

{
  "mcpServers": {
    "qapi": {
      "type": "http",
      "url": "https://qapi.otunac.com/mcp",
      "headers": {
        "Q-Api-Key": "qb_SuaChaveAqui"
      }
    }
  }
}

Sua chave está disponível em /dashboard (se estiver logado, também aparece pronta pra copiar nos exemplos de código de lá).

Agentes de IA — sobretudo fluxos multi-agente/paralelos, que exploram a base de forma automatizada — tendem a multiplicar o número de requisições em relação a um cliente programático tradicional. O custo em dobro contém abuso sem proibir o uso legítimo.

Se o saldo for insuficiente para o custo em dobro (ex: 1 cota restante, que bastaria para uma requisição REST mas não para uma chamada MCP), a ferramenta recusa a chamada com uma mensagem de erro explicando o motivo — nenhuma cota é debitada nesse caso, sem consumo parcial.

Q-Api-Key: qb_SuaChaveAqui

A chave é prefixada com qb_ seguido de 40 caracteres aleatórios. Mantenha-a em segredo — nunca exponha em código público ou repositórios. Se necessário, redefina-a pelo suporte.

{
  "page":  1,      // página atual
  "size":  10,     // itens nesta página
  "pages": 63,     // total de páginas
  "total": 624,    // total de itens encontrados
  "questoes": [/* array de itens */]
}

Para percorrer todos os resultados, itere de page=1 até page=pages. Cada página consome 1 requisição no seu billing.

GET https://qapi.otunac.com/api/questoes?page=1&size=10&banca=FGV&ano=2024
Q-Api-Key: qb_SuaChaveAqui

{
  "page":  1,
  "size":  10,
  "pages": 63,
  "total": 624,
  "questoes": [
    {
      "_id":      "69a8224af6d9445ec04dad9c",
      "qCode":    "Q-7KD4M2P",  // identificador único e estável da questão
      "orgao":    "TJ/SE",
      "banca":    "FGV",
      "siglaBanca":"FGV",
      "siglaOrgao":"TJ/SE",
      "ano":      2023,
      "cargo":    "Analista Judiciário - Análise de Sistemas",
      "materia":  "Conhecimento Específico",
      "assunto":  "Arquitetura de Computadores",
      "enunciado":"Em sistemas operacionais, a métrica que mede...",
      "opcaoA":   "throughput;",
      "opcaoB":   "tempo de espera;",
      "opcaoC":   "tempo de turnaround;",
      "opcaoD":   "tempo de processador;",
      "opcaoE":   "utilização do processador.",
      "gabarito": "A",
      "comentario":"Throughput é o número de processos...",
      "texto":    "QTXT566467"  // código p/ buscar o texto em /api/texts/:codigo
    }
  ]
}

siglaBanca/siglaOrgao são a sigla resolvida a partir do catálogo (pode vir null quando a instituição não tem sigla cadastrada). A base tem questões salvas ora com o nome completo em banca/orgao, ora com a sigla — o filtro já casa os dois formatos automaticamente, então normalmente você não precisa olhar esses campos pra filtrar.

qCode — identificador único da questão. Toda questão tem um código externo no formato Q-XXXXXXX (a letra Q, um hífen e 7 caracteres alfanuméricos maiúsculos, sem 0, O, 1 e I). Ele é estável — nunca muda depois de criado — e único na base. Use-o como chave da questão na sua aplicação, no lugar do _id interno do banco: GET /api/questoes?qCode=Q-7KD4M2P. O mesmo filtro existe na ferramenta MCP get_questoes.

Markdown em enunciado e nas alternativas (opcaoA–opcaoE). As bancas destacam o termo cobrado dentro do próprio enunciado e da alternativa, e entregar texto puro apagava parte desse destaque. Por isso esses campos agora podem conter Markdown (negrito, itálico, sublinhado, listas...). Se você renderizava esses campos como texto simples, as marcações vão aparecer cruas na tela (ex.: **termo**). Ajuste sua aplicação para renderizar Markdown — qualquer biblioteca (marked, markdown-it, react-markdown, python-markdown) resolve; sanitize o HTML resultante antes de exibir.

## cURL
curl -X GET \
  "https://qapi.otunac.com/api/questoes?banca=FGV&materia=Direito+Administrativo&page=1&size=10" \
  -H "Q-Api-Key: qb_SuaChaveAqui"

## cURL — busca por enunciado
curl -X GET \
  "https://qapi.otunac.com/api/questoes?enunciado=direitos+fundamentais&size=10" \
  -H "Q-Api-Key: qb_SuaChaveAqui"

## Python
import requests

r = requests.get(
    "https://qapi.otunac.com/api/questoes",
    params={"banca": "FGV", "materia": "Direito Administrativo", "page": 1, "size": 10},
    headers={"Q-Api-Key": "qb_SuaChaveAqui"}
)
data = r.json()
print(f"Total: {data['total']} questões, {data['pages']} páginas")

## JavaScript
const params = new URLSearchParams({ banca: "FGV", materia: "Direito Administrativo", page: 1, size: 10 });
const r = await fetch(`https://qapi.otunac.com/api/questoes?${params}`, {
  headers: { "Q-Api-Key": "qb_SuaChaveAqui" }
});
const data = await r.json();

GET https://qapi.otunac.com/api/textos/QTXT566467
Q-Api-Key: qb_SuaChaveAqui

{
  "_id":       "69b0cfaa20dadd7d66bfcec9",
  "codigo":    "QTXT566467",
  "titulo":    "A reinvenção da vírgula",
  "texto":     "No começo de 1902, Machado de Assis...",
  "fonte":     "Machado de Assis",
  "createdAt": "2026-03-11T02:12:58.079Z"
}

## Python — buscar questão e carregar seu texto base
import requests

BASE    = "https://qapi.otunac.com/api"
headers = {"Q-Api-Key": "qb_SuaChaveAqui"}

questoes = requests.get(f"{BASE}/questoes", params={"banca": "FGV"}, headers=headers).json()

for q in questoes["questoes"]:
    if q["texto"]:  # campo não vazio → tem texto base
        txt = requests.get(f"{BASE}/textos/{q['texto']}", headers=headers).json()
        print(txt["titulo"], txt["texto"][:200])

GET https://qapi.otunac.com/api/provas?banca=CEBRASPE&ano=2024&page=1&size=10
Q-Api-Key: qb_SuaChaveAqui

{
  "provas": [
    {
      "_id":          "6a164c795e06528a230ff9d4",
      "orgao":         "Polícia Federal",
      "banca":         "CEBRASPE",
      "cargo":         "Delegado Federal",
      "ano":           2024,
      "linkProva":     "https://cdn.exemplo.com/prova.pdf",
      "linkGabarito":  "https://cdn.exemplo.com/gabarito.pdf",
      "createdAt":     "2025-05-30T14:00:00.000Z"
    }
  ],
  "total": 12,
  "page":  1,
  "size":  10,
  "pages": 2
}

GET https://qapi.otunac.com/api/provas/6a164c795e06528a230ff9d4
Q-Api-Key: qb_SuaChaveAqui

{
  "_id":          "6a164c795e06528a230ff9d4",
  "orgao":         "Polícia Federal",
  "banca":         "CEBRASPE",
  "cargo":         "Delegado Federal",
  "ano":           2024,
  "linkProva":     "https://cdn.exemplo.com/prova.pdf",
  "linkGabarito":  "https://cdn.exemplo.com/gabarito.pdf",
  "uploadProva":   { "filename": "pf_2024.pdf", "size": 2048576, "uploadedAt": "2025-05-30T14:00:00.000Z" },
  "uploadGabarito": { "filename": "gabarito_pf_2024.pdf", "size": 512000, "uploadedAt": "2025-05-30T15:00:00.000Z" },
  "createdAt":     "2025-05-30T14:00:00.000Z"
}

GET https://qapi.otunac.com/api/concursos?status=editais+publicados&ano=2026&page=1&size=10
Q-Api-Key: qb_SuaChaveAqui

{
  "concursos": [
    {
      "_id":            "6a582f98b7e102f6a66d0e16",
      "orgao": { "_id": "659a1b2c...", "nome": "DATAPREV", "logo": "https://cdn.../logo_dataprev.png", "website": "https://www.dataprev.gov.br" },
      "banca": { "_id": "65b2c3d4...", "nome": "FGV Conhecimento", "logo": "https://cdn.../logo_fgv.png", "website": "https://conhecimento.fgv.br" },
      "descricao":       "Informações sobre o concurso público...",
      "status":          "editais publicados",
      "vagas":           212,
      "cargos":          ["Engenharia", "Advocacia"],
      "requisitos":      "Nível superior",
      "remuneracao":     "até R$ 10.685,44",
      "taxaInscricao":   "110,00",
      "website":         "https://conhecimento.fgv.br/concursos/dataprev26",
      "inicioInscricao": "6 de julho de 2026 às 16h",
      "fimInscricao":    "6 de agosto de 2026 às 16h",
      "dataProva":       "11 de outubro de 2026",
      "horaProva":       null,
      "validade":        "2 anos (podendo ser prorrogado)",
      "ano":             2026,
      "regiao":          "nordeste",
      "estado":          "Paraíba",
      "siglaEstado":     "PB",
      "createdAt":       "2026-07-16T01:10:48.150Z"
    }
  ],
  "total": 2,
  "page":  1,
  "size":  10,
  "pages": 1
}

GET https://qapi.otunac.com/api/concursos/6a582f98b7e102f6a66d0e16
Q-Api-Key: qb_SuaChaveAqui

Retorna a lista fixa de valores aceitos pelo campo status, na ordem do fluxo de um concurso — útil para popular um filtro na sua aplicação.

{
  "status": [
    "solicitado", "autorizado", "banca em definição",
    "banca contratada", "comissão formada", "previsto",
    "anunciado", "editais publicados"
  ]
}

GET https://qapi.otunac.com/api/simulados?banca=FGV&materia=Direito+Constitucional&size=10
Q-Api-Key: qb_SuaChaveAqui

{
  "questoes": [ /* array de questões, na ordem sorteada */ ],
  "total": 137,   // total de questões que batem com o filtro
  "size":  10    // quantidade efetivamente retornada
}

Todos os filtros são opcionais e combináveis — chame sem nenhum para sortear questões de toda a base.

Lista as bancas organizadoras. Use search para filtrar por nome ou sigla — ex: "fgv" encontra "Fundação Getulio Vargas" mesmo que você não digite o nome completo.

GET https://qapi.otunac.com/api/bancas?page=1&size=10&search=fgv
Q-Api-Key: qb_SuaChaveAqui

{
  "bancas": [
    {
      "_id":     "6a2cfe8e4d53df4eac8fe0b4",
      "nome":    "Fundação Getulio Vargas",
      "sigla":   "FGV",
      "logo":    "https://.../logo_fgv.png",
      "website": null
    }
  ],
  "total": 1, "page": 1, "pages": 1
}

sigla/logo/website vêm null quando não cadastrados no catálogo.

Lista os órgãos. Use search para busca parcial por nome ou sigla.

GET https://qapi.otunac.com/api/orgaos?page=1&size=5&search=ces
Q-Api-Key: qb_SuaChaveAqui

{
  "orgaos": [
    {
      "_id":     "659f...",
      "nome":    "Centro de Seleção e de Promoção de Eventos",
      "sigla":   "CESPE",
      "logo":    null,
      "website": null
    }
  ],
  "total": 1, "page": 1, "pages": 1
}

Lista os cargos disponíveis na base.

GET https://qapi.otunac.com/api/cargos?page=1&size=10&search=professor
Q-Api-Key: qb_SuaChaveAqui

{
  "cargos": ["Professor de Ensino Básico", "Professor Adjunto"],
  "total": 2, "page": 1, "pages": 1
}

Lista as matérias e disciplinas disponíveis.

GET https://qapi.otunac.com/api/materias?page=1&size=5&search=Direito
Q-Api-Key: qb_SuaChaveAqui

{
  "materias": ["Direito Administrativo", "Direito Constitucional", "Direito Civil"],
  "total": 3, "page": 1, "pages": 1
}

Lista os assuntos de uma matéria. materia é obrigatório.

GET https://qapi.otunac.com/api/assuntos?materia=Tecnologia+Java&page=1&size=5&search=hibernate
Q-Api-Key: qb_SuaChaveAqui

{
  "materia": "Tecnologia Java",
  "assuntos": ["Hibernate / JPA", "Hibernate Cache"],
  "total": 2, "page": 1, "pages": 1
}

POST https://qapi.otunac.com/api/comentarios
Q-Api-Key: qb_SuaChaveAqui
Content-Type: application/json

{
  "questao":    "69a8224af6d9445ec04dad9c",
  "usuario":    "Maria Souza",
  "comentario": "O gabarito está incorreto, a alternativa correta é a B."
}

{
  "_id":        "6a539f2c790ad5b7852c63ad",
  "questao":    "69a8224af6d9445ec04dad9c",
  "usuario":    "Maria Souza",
  "comentario": "O gabarito está incorreto, a alternativa correta é a B.",
  "createdAt":  "2026-07-12T14:05:32.740Z",
  "updatedAt":  "2026-07-12T14:05:32.740Z"
}

Lista os comentários de uma questão, em ordem cronológica. Lista vazia se a questão ainda não tiver comentários.

GET https://qapi.otunac.com/api/comentarios?questao=69a8224af6d9445ec04dad9c
Q-Api-Key: qb_SuaChaveAqui

{
  "comentarios": [
    { "_id": "...", "usuario": "Maria Souza", "comentario": "O gabarito está incorreto...", "createdAt": "..." }
  ]
}

Atualiza usuario e/ou comentario. Retorna 404 se o ID não existir.

PUT https://qapi.otunac.com/api/comentarios/6a539f2c790ad5b7852c63ad
Q-Api-Key: qb_SuaChaveAqui
Content-Type: application/json

{ "comentario": "Editado: na verdade o gabarito está certo." }

Remove um comentário. Retorna 204 sem corpo. 404 se o ID não existir.

DELETE https://qapi.otunac.com/api/comentarios/6a539f2c790ad5b7852c63ad
Q-Api-Key: qb_SuaChaveAqui

POST https://qapi.otunac.com/api/suporte
Q-Api-Key: qb_SuaChaveAqui
Content-Type: application/json

{
  "incidente":     "Falha no endpoint /api/questoes",
  "descricao":     "Recebendo 500 ao filtrar por banca=FGV.",
  "nomeDoCliente": "João Silva",
  "email":         "[email protected]"
}

{
  "_id":           "6a539f3f790ad5b7852c63b8",
  "incidente":     "Falha no endpoint /api/questoes",
  "descricao":     "Recebendo 500 ao filtrar por banca=FGV.",
  "nomeDoCliente": "João Silva",
  "email":         "[email protected]",
  "createdAt":     "2026-07-12T14:05:51.772Z"
}

Apenas a abertura de chamados é exposta pela API pública — consulta, edição e remoção de chamados ficam restritas à equipe do QAPI.

Cria uma nova conta e retorna a api_key gerada automaticamente — prefixada com qb_.

POST https://qapi.otunac.com/api/auth/register
Content-Type: application/json

{
  "name":     "João Silva",
  "email":    "[email protected]",
  "cpf":      "123.456.789-09",
  "password": "minhasenha123"
}

{
  "message": "Conta criada com sucesso.",
  "api_key": "qb_abc123xyz..."   // guarde esta chave!
}

Autentica com e-mail e senha. Retorna um JWT Bearer token e os dados da conta, incluindo a api_key.

POST https://qapi.otunac.com/api/auth/login
Content-Type: application/json

{
  "email":    "[email protected]",
  "password": "minhasenha123"
}

{
  "token":          "eyJhbGci...",   // JWT — válido por 24h
  "api_key":        "qb_abc123xyz...",
  "api_key_active": true
}

O JWT retornado pode ser usado como Authorization: Bearer <token> em rotas autenticadas da web. Para acesso à API de questões, use sempre o Q-Api-Key header com sua api_key.

{
  "error": "Chave de API inválida ou inexistente."
}

import requests

r = requests.get(
    "https://qapi.otunac.com/api/questions",
    headers={"Q-Api-Key": "qb_SuaChave"}
)

if r.status_code == 200:
    data = r.json()
elif r.status_code == 401:
    raise ValueError("API Key inválida")
elif r.status_code == 402:
    raise PermissionError("Sem créditos — insira cotas para continuar")
elif r.status_code == 403:
    raise PermissionError("Chave suspensa — contate o suporte")
else:
    r.raise_for_status()