Documentação

Guia da BNCC API

Comece a consumir toda a Base Nacional Comum Curricular em minutos. A referência completa de endpoints, schemas e exemplos é gerada automaticamente a partir do contrato OpenAPI — nada aqui é escrito à mão, então nunca diverge do código.

Abrir referência interativa Criar chave gratuita

3 passos: crie uma conta e verifique o e-mail → gere uma API key no portal → chame os endpoints com Authorization: Bearer.

Autenticação por API key

A API de dados é autenticada por API key enviada no cabeçalho Authorization como Bearer. Gere uma key gratuita no portal self-service após verificar seu e-mail.

curl -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  https://bncc.api.br/api/v1/habilidades/EF05MA07

Requisições sem uma API key válida recebem 401.

Exemplos rápidos

Consultar uma habilidade por código

curl -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  https://bncc.api.br/api/v1/habilidades/EM13MAT101

Listar com filtros e paginação

curl -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  "https://bncc.api.br/api/v1/habilidades?etapa=ensino_medio&size=20"

Busca semântica com IA (não-oficial)

curl -X POST https://bncc.api.br/api/v1/busca-semantica \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"query": "quais habilidades de matemática do 5º ano tratam de frações?"}'

As respostas de busca semântica trazem fontes rastreáveis e são sempre marcadas como conteúdo gerado, não-oficial — os dados determinísticos permanecem a fonte da verdade.

Paginação & filtros

Endpoints de listagem aceitam page (a partir de 1) e size (itens por página). A resposta traz os itens junto com os metadados de paginação para você percorrer o conjunto completo.

Parâmetro	Descrição	Padrão
`page`	Número da página (1-based)	`1`
`size`	Itens por página	`20`
`etapa`	Filtro por etapa (`educacao_infantil`, `ensino_fundamental`, `ensino_medio`)	—

A lista completa de filtros por endpoint (componente, ano, eixo, unidade temática) está na referência interativa, sempre em dia com o contrato.

Erros

Erros usam os códigos de status HTTP padrão e um corpo JSON consistente. Respostas de erro nunca expõem stack traces ou detalhes de infraestrutura.

Status	Significado
`400`	Requisição inválida (parâmetro fora do formato)
`401`	API key ausente ou inválida
`404`	Recurso não encontrado (ex.: código de habilidade inexistente)
`422`	Falha de validação de schema
`429`	Limite de uso excedido — veja o cabeçalho `Retry-After`

Limites de uso (rate limiting)

Cota	Limite	Aplica-se a
Determinística	60 requisições/min	Habilidades, competências, taxonomia, sistema
IA (busca semântica)	20 requisições/min e teto de 500/dia	`/api/v1/busca-semantica`

Acima do limite, a API responde 429 com o cabeçalho Retry-After indicando quando tentar novamente. As duas cotas são independentes: exceder a cota de IA não afeta os endpoints determinísticos.

Busca semântica não-oficial

A busca semântica usa IA para encontrar habilidades por significado, não por palavra-chave exata. É um recurso opcional: se a camada de IA estiver indisponível, os endpoints determinísticos continuam funcionando normalmente (degradação graciosa).

Toda resposta traz fontes rastreáveis e é marcada como conteúdo gerado. Ela nunca substitui os dados oficiais da BNCC.

Versionamento

Todos os endpoints ficam sob /api/v1. Mudanças incompatíveis (breaking changes) são publicadas em uma nova versão (/api/v2), nunca dentro da versão atual. Adições retrocompatíveis (novos endpoints, novos campos opcionais) acontecem dentro da versão corrente.