A API Kuberdata, para quem vai ligar o sistema.
Teste agora, sem chave, com questões reais de um acervo de amostra. Depois, a referência das rotas que o seu servidor vai chamar com a chave do cliente.
Faça uma chamada de verdade, aqui mesmo.
Estas chamadas vão para as rotas /v1/sample: mesmo formato da API paga, num acervo de amostra separado, pequeno e sem ligação com o acervo de produção. Não precisa de chave e não gasta crédito. Há um limite de chamadas por minuto para cada visitante.
O que você quer pedir?
A API de homologação tem uma senha da equipe na porta de entrada. Por isso esta página chama a amostra por uma ponte própria (/api/kd/sample/…), que acrescenta só essa senha e nunca chave de cliente. O curl acima mostra a chamada como ela é na API.
Seis regras que valem para todas as rotas.
| Assunto | Como funciona |
|---|---|
| Endereço | https://api.kuberdata.pro/v1 (homologação). Respostas em JSON, UTF-8. |
| Chave | No header x-api-key: sk-kbd_…. O dono cria em Chaves para conectar seu sistema. Use só no servidor: nunca no navegador, no aplicativo, no repositório ou em log. |
| Repetição sem cobrança | Toda rota que entrega questão exige Idempotency-Key (8 a 255 caracteres: letras, números, . _ : -). Repetir o mesmo pedido com a mesma chave devolve o mesmo resultado e cobra zero. Pedido novo, chave nova. |
| Custo | 0,3 crédito por questão entregue (Q01) e 0,5 por resultado de busca (S01), na versão de preço 2026-11-04. Cada resposta traz o recibo: usage_receipt_id na lista e X-Usage-Receipt-Id no header. A reserva é pelo limit; a cobrança é só do que veio. |
| Páginas | A lista devolve next_cursor. Para a próxima página, mande o mesmo filtro com cursor. Quando vem null, acabou. |
| Questão sem mudança | Abrir uma questão devolve ETag. Mande de volta em If-None-Match: se nada mudou, a resposta é 304, sem corpo e sem cobrança. |
const resposta = await fetch('https://api.kuberdata.pro/v1/questions?limit=20', {
headers: {
'x-api-key': process.env.KUBERDATA_API_KEY,
'Idempotency-Key': crypto.randomUUID(),
},
});
const pagina = await resposta.json();
// pagina.items: as questões · pagina.next_cursor: a próxima páginaAs rotas que o seu servidor vai chamar.
Todas pedem x-api-key, menos as listas de nomes. A coluna de escopo diz que permissão a chave precisa ter.
Questões
GET/v1/questionsListar questões com filtro0,3 / questão
Escopo questions:read. Header Idempotency-Key obrigatório. Devolve items, next_cursor, snapshot_id, snapshot_expires_at e usage_receipt_id.
| Parâmetro | O que é |
|---|---|
exam_banca_id | Banca. De onde vem: GET /v1/catalogs/exam_bancas · ver a lista agora |
edict_subject_id | Disciplina. De onde vem: GET /v1/catalogs/edict_subjects · ver a lista agora |
edict_topic_id | Tópico da disciplina. De onde vem: GET /v1/catalogs/edict_topics com edict_subject_id · ver a lista agora |
exam_subtopic_id | Subtópico. De onde vem: ainda não há lista pública de subtópicos; use o ID que você já tem. |
exam_position_id | Cargo. De onde vem: GET /v1/catalogs/exam_positions · ver a lista agora |
education_level_id | Escolaridade. De onde vem: GET /v1/catalogs/education_levels · ver a lista agora |
exam_institution_id | Órgão. De onde vem: GET /v1/catalogs/exam_institutions · ver a lista agora |
year_from | Ano mínimo da prova (1900 a 2200) |
limit | Quantas questões, de 1 a 100 (padrão 20) |
cursor | O next_cursor da página anterior |
snapshot_id | Fixa a versão do acervo entre páginas (opcional) |
GET/v1/questions/{id}Abrir uma questão0,3 · 304 grátis
De onde vem o {id}: o campo id de cada item de GET /v1/questions ou de POST /v1/search.
Escopo questions:read. Header Idempotency-Key obrigatório; If-None-Match opcional. Devolve a questão inteira: enunciado (statement), alternativas (item_a a item_e), gabarito (correct_option), comentários (explanation_text e explanation_a a explanation_e), os IDs de banca, disciplina, tópico, cargo, órgão e escolaridade, o ano (source_year) e os subtópicos (topic_subtopics).
POST/v1/searchBuscar por assunto0,5 / resultado
Escopo search:read. Header Idempotency-Key obrigatório. Corpo JSON com query (3 a 1.000 letras), limit (1 a 100, padrão 20) e os mesmos filtros da lista (exam_banca_id, edict_subject_id, edict_topic_id, education_level_id, exam_institution_id, year_from). Busca pelo sentido; se não achar nada parecido, cai para a busca por palavras. Cada resultado traz similarity, de 0 a 1.
| Campo de ID no corpo | O que é |
|---|---|
exam_banca_id | Banca. De onde vem: GET /v1/catalogs/exam_bancas · ver a lista agora |
edict_subject_id | Disciplina. De onde vem: GET /v1/catalogs/edict_subjects · ver a lista agora |
edict_topic_id | Tópico da disciplina. De onde vem: GET /v1/catalogs/edict_topics com edict_subject_id · ver a lista agora |
education_level_id | Escolaridade. De onde vem: GET /v1/catalogs/education_levels · ver a lista agora |
exam_institution_id | Órgão. De onde vem: GET /v1/catalogs/exam_institutions · ver a lista agora |
{ "query": "controle de constitucionalidade", "limit": 10, "year_from": 2020 }GET/v1/catalogs/{catalog}Listas de nomes para os menusgrátis · sem chave
Devolve items com id e name. Listas: exam_bancas, edict_subjects, edict_topics (filtre com edict_subject_id), exam_styles, exam_positions, exam_institutions e education_levels. Parâmetros limit (até 100) e cursor.
Saldo, consumo e chaves
GET/v1/walletSaldo de créditosgrátis
Escopo wallet:read. Devolve availableCredits (o que dá para gastar agora), includedCredits (da assinatura, vence no fim do ciclo), extraCredits (comprados à parte, não vencem) e updatedAt.
GET/v1/usageConsumo, pedido a pedidográtis
Escopo usage:read. Parâmetro limit (1 a 100, padrão 30). Cada item traz a operação, o código de preço (priceSku), a versão do preço, quantas unidades vieram, o preço de cada uma, o total cobrado e a data.
GET/v1/access/keysListar as chavesgrátis
Escopo keys:read. Mostra nome, os 4 últimos caracteres, escopos, limite por minuto e datas de criação e revogação. Nunca devolve a chave.
POST/v1/access/keysCriar outra chavegrátis
Escopo keys:write. Corpo com label e scopes (questions:read, search:read, wallet:read, usage:read, keys:read, keys:write, billing:write). A chave nova vem em value só nesta resposta.
DELETE/v1/access/keys/{id}Revogar uma chavegrátis
Escopo keys:write. A chave para de funcionar na mesma hora.
Créditos extras e recarga automática
POST/v1/billing/checkoutComprar um pacote extrao valor do pacote
Escopo billing:write. Header Idempotency-Key obrigatório. Corpo com packageCode. Devolve checkoutUrl, a página de pagamento da Stripe. O crédito entra quando a Stripe confirma o pagamento, não na volta da página.
GET · POST/v1/billing/auto-reloadVer ou ligar a recarga automáticagrátis
Escopo billing:write. Para ligar, mande o saldo que dispara, o pacote, o máximo de recargas e o teto em reais por mês, com a versão do consentimento. Usa o cartão já salvo na assinatura. O mais simples é o dono ligar pela plataforma, em Cobrança › Recarga automática.
POST/v1/billing/auto-reload/revokeDesligar a recarga automáticagrátis
Escopo billing:write. Desliga na hora.
Pré-edital
| Rota | O que entrega |
|---|---|
GET /v1/prep-ahead/positions/{positionId}/programmatic-content | Conteúdo programático do cargo |
GET /v1/prep-ahead/positions/content-status | Situação do conteúdo dos cargos |
GET /v1/prep-ahead/microcontent | Microconteúdo de um tópico |
GET /v1/prep-ahead/topic-recurrence | Tópicos que mais caem para um cargo |
GET /v1/prep-ahead/atr/… | Rankings, incidência e histórico de tópicos por banca |
De onde vêm os IDs do pré-edital: exam_banca_id, edict_subject_id, edict_topic_id e education_level_id saem das listas de GET /v1/catalogs/{catalog}; edict_position_id/positionId (cargo de edital) e topicId (tópico canônico) ainda não têm lista pública.
O preço do pré-edital está na tabela de preços da plataforma. Parâmetros e respostas completos no openapi.yaml.
As mesmas rotas, sem chave, num acervo pequeno.
Servem para testar o formato antes de pagar. A resposta é igual à da rota paga; muda só o acervo, que é de amostra. Não pedem x-api-key nem Idempotency-Key, não cobram e têm limite de chamadas por minuto por visitante (passou do limite, volta 429 com Retry-After).
| Rota da amostra | Equivale a |
|---|---|
GET /v1/sample/questions | GET /v1/questions |
GET /v1/sample/questions/{id} | GET /v1/questions/{id} |
POST /v1/sample/search | POST /v1/search |
GET /v1/sample/catalogs/{catalog} | GET /v1/catalogs/{catalog}, com os nomes da amostra |
O que cada código quer dizer.
Todo erro vem em JSON com error, message, statusCode e, quando há, requestId. Guarde o requestId para pedir ajuda.
| Código | O que houve | O que fazer |
|---|---|---|
400 | Parâmetro errado ou faltando (por exemplo, sem Idempotency-Key) | Leia o message e corrija o pedido |
401 | Chave faltando, errada ou revogada | Confira o header x-api-key |
402 | Sem crédito para o que foi pedido | Peça menos questões, compre um extra ou ligue a recarga automática |
403 | A chave não tem o escopo, ou a assinatura não está ativa | Crie uma chave com o escopo certo; confira a assinatura |
404 | A questão ou a rota não existe | Confira o ID e o caminho |
409 | A mesma Idempotency-Key foi usada com outro pedido, ou o pedido ainda está em andamento | Pedido novo, chave nova; se estiver em andamento, espere e repita |
410 | A versão do acervo (snapshot_id) venceu | Comece de novo sem snapshot_id e sem cursor |
429 | Muitas chamadas seguidas | Espere os segundos de Retry-After |
5xx | Erro do lado da Kuberdata | Tente de novo com a mesma Idempotency-Key: não cobra duas vezes |