1. Entre na plataforma
Abra a Plataforma Kuberdata, receba o código por e-mail e conclua o onboarding da organização.
Abrir plataformaDados de concursos, com contrato, recibo e rastreabilidade.
Use a Kuberdata para consultar questões, catálogos e modalidades de preparação. Esta página traz o caminho curto para a primeira integração; a referência interativa vem diretamente do contrato OpenAPI.
Abrir referência da APIAmbiente validado: os comandos desta página foram exercitados no staging em 08/11/2026. O host de produção descrito no OpenAPI original ainda não resolve; informe
KUBERDATA_BASE_URL quando ele for disponibilizado. O Basic Auth do staging é uma proteção operacional e nunca deve aparecer em código de cliente.Criar conta e chave
2. Emita uma chave
Em Chaves, crie a chave da integração. O valor bruto aparece uma única vez: guarde-o no cofre do seu servidor.
3. Use no servidor
Envie a chave só em x-api-key. Nunca a coloque em app web, repositório, log ou print.
Primeira chamada com cURL
Operações que entregam questões exigem uma chave de idempotência. Reutilize a mesma chave somente ao repetir exatamente a mesma operação.
export KUBERDATA_BASE_URL="${KUBERDATA_BASE_URL:-https://api-kuberdata.talles.dev/v1}"
export KUBERDATA_API_KEY="<sua-chave-de-servidor>"
# No staging protegido, o operador acrescenta --user com a credencial privada.
curl --fail-with-body "$KUBERDATA_BASE_URL/questions?limit=1" \
-H "Accept: application/json" \
-H "x-api-key: $KUBERDATA_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"A resposta inclui a questão entregue e o recibo de uso. Registre o x-request-id devolvido no cabeçalho para suporte e reconciliação.
Busca semântica
Envie uma intenção em linguagem natural. Você pode combinar filtros canônicos, como banca, disciplina, tópico, escolaridade e ano, quando já tiver seus UUIDs.
curl --fail-with-body -X POST "$KUBERDATA_BASE_URL/search" \
-H "Content-Type: application/json" \
-H "x-api-key: $KUBERDATA_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
--data '{"query":"direito constitucional","limit":1}'A busca devolve data e usage. O débito final acompanha as unidades efetivamente entregues; consulte a carteira e os recibos antes de fazer chamadas de alto volume.
Catálogos e paginação por cursor
Consulte os catálogos primeiro para obter UUIDs estáveis. A próxima página é indicada por nextCursor; envie o valor inteiro, sem tentar decodificá-lo.
# Página 1
curl --fail-with-body "$KUBERDATA_BASE_URL/catalogs/bancas?limit=1"
# Página seguinte: substitua pelo nextCursor retornado
curl --fail-with-body "$KUBERDATA_BASE_URL/catalogs/bancas?limit=1&cursor=<nextCursor>"| Catálogo | Endpoint | Uso |
|---|---|---|
| Bancas | exam_bancas / bancas | Filtrar provas pela organizadora. |
| Disciplinas e tópicos | edict_subjects, edict_topics | Montar filtros e buscas orientadas ao edital. |
| Cargos e instituições | exam_positions, exam_institutions | Contextualizar o concurso. |
| Escolaridade e estilos | education_levels, exam_styles | Refinar o recorte de questões. |
Erros e requestId
Uma resposta de erro contém error, message, statusCode e requestId. O mesmo identificador também vem em x-request-id. Ao abrir um chamado, envie método, caminho, horário e requestId — nunca a chave API ou o corpo completo de uma questão.
400
Parâmetro, cursor ou corpo inválido. Corrija a entrada e gere uma nova chave de idempotência se o pedido mudar.
401 / 403
Chave ausente, expirada ou sem escopo. Revise a chave e a configuração do servidor.
402 / 429
Saldo insuficiente ou limite atingido. Consulte carteira/uso e aplique backoff antes de repetir.
Créditos e cobrança
A carteira mostra créditos disponíveis já líquidos de reservas em processamento. As respostas cobradas carregam recibo com operação, versão de preço, unidades entregues e créditos cobrados; use GET /wallet e GET /usage para conferir o saldo e os eventos da sua própria organização.
Não assuma preço ou teto fixo no cliente: consulte a configuração comercial vigente da sua conta antes de aumentar volume ou ativar uma modalidade nova.
Modalidades do prep-ahead
As modalidades abaixo são leituras do snapshot Kuberdata sob /v1/prep-ahead e exigem o escopo de leitura de questões. Envie snapshot_id quando precisar fixar a fronteira de dados de uma execução.
| Modalidade | Rota | Entrega |
|---|---|---|
| Conteúdo programático | GET /positions/:positionId/programmatic-content | Disciplinas e tópicos do cargo. |
| Status de conteúdo | POST /positions/content-status | Cobertura para uma lista de cargos. |
| Microconteúdo | GET /microcontent | Item concluído mais recente para cargo, disciplina e tópico. |
| Recorrência | GET /topic-recurrence | Recorrência, tendência, ATR e subtópicos. |
| Ranking ATR | GET /atr/ranking | Ranking paginado de tópicos por banca e filtros. |
| Incidência ATR | GET /atr/incidence/options e /papers | Filtros, frescor e provas relacionadas. |
Preço e habilitação são configurados por modalidade e ambiente. Antes de pôr uma delas em produção, confirme o SKU e a política comercial vigentes na sua conta.