{"openapi":"3.1.0","info":{"title":"BNCC API","description":"API pública e gratuita que expõe **toda a Base Nacional Comum Curricular (BNCC)**\ndo Brasil — Educação Infantil, Ensino Fundamental e Ensino Médio, incluindo o\nComplemento de Computação — de forma estruturada e navegável.\n\n## Autenticação\nOs endpoints de dados exigem uma **API key** enviada no cabeçalho\n`Authorization: Bearer SUA_CHAVE`. Crie uma chave gratuita no\n[portal self-service](/portal/signup) após verificar seu e-mail. Requisições sem\nchave válida recebem `401`.\n\n## Limites de uso\n- **Determinística** (habilidades, competências, taxonomia, sistema): `60 req/min`.\n- **Busca semântica com IA**: `20 req/min` e teto de `500/dia`.\n\nAcima do limite a API responde `429` com o cabeçalho `Retry-After`. As duas cotas\nsão independentes.\n\n## Dados oficiais × derivados\nOs dados determinísticos preservam fielmente a nomenclatura e a estrutura oficiais\nda BNCC. Conteúdos gerados por IA (busca semântica, resumos) são **sempre marcados\ncomo não-oficiais** e nunca substituem a fonte da verdade.\n\n## Versionamento\nTodos os endpoints ficam sob `/api/v1`. Mudanças incompatíveis são publicadas em\numa nova versão de caminho (`/api/v2`), nunca dentro da versão atual.\n\n> Guia de início rápido, exemplos e receitas: **[/guia](/guia)**.","version":"1.1.0","contact":{"name":"BNCC API","url":"https://github.com/eumakerdev/bncc_api"},"license":{"name":"MIT","url":"https://github.com/eumakerdev/bncc_api/blob/main/LICENSE"},"x-logo":{"url":"/static/logo.svg","altText":"BNCC API"}},"servers":[{"url":"https://bncc.api.br","description":"Produção"},{"url":"http://localhost:8000","description":"Desenvolvimento local"}],"paths":{"/api/v1/habilidades":{"get":{"tags":["Habilidades"],"summary":"Listar habilidades com filtros e paginação","description":"Lista as habilidades oficiais da BNCC (EI/EF/EM), com filtros opcionais por etapa, ano, área, componente, competência geral e eixo de Computação. Requer API key (`Authorization: Bearer <key>`) e consome a cota determinística (60 req/min, burst 10).","operationId":"list_habilidades_api_v1_habilidades_get","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"etapa","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/EtapaEnsino"},{"type":"null"}],"description":"Etapa de ensino","title":"Etapa"},"description":"Etapa de ensino"},{"name":"ano","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Ano escolar (ex.: '5')","title":"Ano"},"description":"Ano escolar (ex.: '5')"},{"name":"area_conhecimento","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/AreaConhecimento"},{"type":"null"}],"description":"Área de conhecimento","title":"Area Conhecimento"},"description":"Área de conhecimento"},{"name":"componente","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ComponenteCurricular"},{"type":"null"}],"description":"Componente curricular","title":"Componente"},"description":"Componente curricular"},{"name":"competencia_geral","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10,"minimum":1},{"type":"null"}],"description":"Competência geral (1-10)","title":"Competencia Geral"},"description":"Competência geral (1-10)"},{"name":"eixo","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/EixoComputacao"},{"type":"null"}],"description":"Eixo do Complemento de Computação (EI/EF)","title":"Eixo"},"description":"Eixo do Complemento de Computação (EI/EF)"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Página (>=1)","default":1,"title":"Page"},"description":"Página (>=1)"},{"name":"size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Itens por página (1-100)","default":20,"title":"Size"},"description":"Itens por página (1-100)"}],"responses":{"200":{"description":"Página de habilidades que casam com os filtros informados.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"401":{"description":"API key ausente, inválida ou revogada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Cota determinística excedida (60/min, burst 10).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/habilidades/{codigo}":{"get":{"tags":["Habilidades"],"summary":"Buscar habilidade por código oficial (EI/EF/EM)","description":"Busca uma habilidade pelo código oficial (formatos EI##XX##, EF##XX## ou EM13XXX###/EM13XX##). Requer API key e consome a cota determinística (60 req/min, burst 10).","operationId":"get_habilidade_api_v1_habilidades__codigo__get","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"codigo","in":"path","required":true,"schema":{"type":"string","description":"Código oficial da habilidade (EI/EF/EM).","title":"Codigo"},"description":"Código oficial da habilidade (EI/EF/EM).","examples":{"ensino_fundamental":{"summary":"Matemática — 5º ano","value":"EF05MA07"}}}],"responses":{"200":{"description":"Dados completos da habilidade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Habilidade"}}}},"400":{"description":"Código malformado (não casa com nenhum formato oficial EI/EF/EM).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Habilidade inexistente no snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente, inválida ou revogada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Cota determinística excedida (60/min, burst 10).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/habilidades/{codigo}/relacoes":{"get":{"tags":["Habilidades"],"summary":"Relações navegáveis de uma habilidade (FR-005)","description":"Retorna as relações navegáveis de uma habilidade — competências gerais e específicas associadas, objetos de conhecimento e demais vínculos curriculares (FR-005). Requer API key e consome a cota determinística.","operationId":"get_habilidade_relacoes_api_v1_habilidades__codigo__relacoes_get","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"codigo","in":"path","required":true,"schema":{"type":"string","description":"Código oficial da habilidade (EI/EF/EM).","title":"Codigo"},"description":"Código oficial da habilidade (EI/EF/EM).","examples":{"ensino_fundamental":{"summary":"Matemática — 5º ano","value":"EF05MA07"}}}],"responses":{"200":{"description":"Grafo de relações (competências gerais/específicas, objetos de conhecimento e habilidades correlatas) da habilidade.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Habilidade Relacoes Api V1 Habilidades  Codigo  Relacoes Get"}}}},"400":{"description":"Código malformado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Habilidade inexistente no snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente, inválida ou revogada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Cota determinística excedida (60/min, burst 10).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/competencias/gerais":{"get":{"tags":["Competências"],"summary":"Listar as 10 competências gerais","description":"Lista as 10 competências gerais oficiais da BNCC, aplicáveis a todas as etapas de ensino. Requer API key e consome a cota determinística.","operationId":"get_competencias_gerais_api_v1_competencias_gerais_get","responses":{"200":{"description":"As 10 competências gerais da BNCC, transversais às três etapas.","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/CompetenciaGeral"},"type":"array","title":"Response Get Competencias Gerais Api V1 Competencias Gerais Get"}}}},"401":{"description":"API key ausente, inválida ou revogada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Cota determinística excedida (60/min, burst 10).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/api/v1/competencias/gerais/{numero}":{"get":{"tags":["Competências"],"summary":"Buscar competência geral por número (1-10)","description":"Busca uma das 10 competências gerais oficiais pelo número (1-10). Requer API key e consome a cota determinística.","operationId":"get_competencia_geral_api_v1_competencias_gerais__numero__get","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"numero","in":"path","required":true,"schema":{"type":"integer","description":"Número da competência geral (1-10)","title":"Numero"},"description":"Número da competência geral (1-10)","examples":{"exemplo":{"summary":"Competência 1 — Conhecimento","value":1}}}],"responses":{"200":{"description":"Dados completos da competência geral.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetenciaGeral"}}}},"404":{"description":"Número fora de 1-10 ou competência inexistente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key ausente, inválida ou revogada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Cota determinística excedida (60/min, burst 10).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/competencias/especificas":{"get":{"tags":["Competências"],"summary":"Listar competências específicas (filtros: area/componente/etapa)","description":"Lista competências específicas de área/componente curricular, com filtros opcionais por área de conhecimento, componente e etapa de ensino. Requer API key e consome a cota determinística.","operationId":"get_competencias_especificas_api_v1_competencias_especificas_get","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"area","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/AreaConhecimento"},{"type":"null"}],"description":"Área de conhecimento","title":"Area"},"description":"Área de conhecimento"},{"name":"componente","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ComponenteCurricular"},{"type":"null"}],"description":"Componente curricular","title":"Componente"},"description":"Componente curricular"},{"name":"etapa","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/EtapaEnsino"},{"type":"null"}],"description":"Etapa de ensino","title":"Etapa"},"description":"Etapa de ensino"}],"responses":{"200":{"description":"Competências específicas que casam com os filtros informados.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CompetenciaEspecifica"},"title":"Response Get Competencias Especificas Api V1 Competencias Especificas Get"}}}},"401":{"description":"API key ausente, inválida ou revogada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Cota determinística excedida (60/min, burst 10).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/taxonomia":{"get":{"tags":["Taxonomia"],"summary":"Árvore da taxonomia oficial da BNCC","description":"Retorna a árvore de taxonomia oficial da BNCC, usada para navegação e documentação (FR-005): etapas de ensino, áreas de conhecimento, componentes curriculares, unidades temáticas e objetos de conhecimento, além dos campos de experiência da Educação Infantil. Requer API key e consome a cota determinística (60 req/min, burst 10).","operationId":"get_taxonomia_api_v1_taxonomia_get","responses":{"200":{"description":"Estrutura navegável completa: etapas → áreas → componentes → unidades temáticas/objetos de conhecimento (e campos de experiência na EI).","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Taxonomia Api V1 Taxonomia Get"}}}},"401":{"description":"API key ausente, inválida ou revogada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Cota determinística excedida (60/min, burst 10).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/api/v1/sistema/versao-dados":{"get":{"tags":["Sistema"],"summary":"Metadados do snapshot da BNCC (versão, checksum, contagens)","description":"Expõe metadados de rastreabilidade do snapshot estático da BNCC (FR-025): versão, data de publicação, checksum SHA-256 de cada fonte oficial e contagens por etapa/componente. Requer API key e consome a cota determinística.","operationId":"get_versao_dados_api_v1_sistema_versao_dados_get","responses":{"200":{"description":"Versão do snapshot, checksums das fontes oficiais e contagens (FR-025).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotMetadata"}}}},"401":{"description":"API key ausente, inválida ou revogada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Cota determinística excedida (60/min, burst 10).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/api/v1/sistema/health":{"get":{"tags":["Sistema"],"summary":"Liveness check (público)","description":"Verificação de vivacidade (liveness) simples e pública — não requer API key nem autenticação. Não verifica dependências externas; use `/readiness` para isso.","operationId":"health_api_v1_sistema_health_get","responses":{"200":{"description":"Indicador simples de que o processo está no ar.","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Health Api V1 Sistema Health Get"}}}}}}},"/api/v1/sistema/readiness":{"get":{"tags":["Sistema"],"summary":"Readiness check (DB best-effort)","description":"Verificação de prontidão pública — checa o banco da plataforma e o snapshot da BNCC de forma best-effort. A camada de IA (ChromaDB/embeddings) é reportada separadamente e sua indisponibilidade **não** torna o serviço `not_ready`, pois os endpoints determinísticos permanecem 100% funcionais (Princípio VII / SC-009).","operationId":"readiness_api_v1_sistema_readiness_get","responses":{"200":{"description":"Status agregado de prontidão e status por componente.","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Readiness Api V1 Sistema Readiness Get"}}}}}}},"/api/v1/auth/signup":{"post":{"tags":["Autenticação"],"summary":"Criar conta de desenvolvedor","description":"Cria uma conta de desenvolvedor do portal e dispara um e-mail de verificação de uso único. A conta permanece `email_verified=false` até a confirmação (necessária para gerar API keys — FR-007). Não usa API key, apenas e-mail/senha.","operationId":"signup_api_v1_auth_signup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupRequest"},"examples":{"padrao":{"summary":"Cadastro padrão","value":{"email":"dev@example.com","password":"SenhaForte123"}}}}},"required":true},"responses":{"201":{"description":"Conta criada (ainda não verificada); e-mail de verificação disparado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupResponse"}}}},"400":{"description":"Payload inválido (e-mail malformado ou senha fora da política).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Não foi possível concluir o cadastro (e-mail já em uso).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Muitas tentativas de cadastro deste IP.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/auth/verify-email":{"post":{"tags":["Autenticação"],"summary":"Confirmar e-mail via token de verificação","description":"Consome o token de verificação de uso único enviado por e-mail no cadastro e marca a conta como verificada. Necessário antes de gerar API keys (FR-007).","operationId":"verify_email_api_v1_auth_verify_email_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyEmailRequest"},"examples":{"padrao":{"summary":"Token recebido por e-mail","value":{"token":"a1b2c3d4e5f6"}}}}},"required":true},"responses":{"200":{"description":"Confirmação de que o e-mail da conta foi verificado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyEmailResponse"}}}},"400":{"description":"Token de verificação inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"Token de verificação expirado ou já utilizado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Muitas tentativas deste IP.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/auth/login":{"post":{"tags":["Autenticação"],"summary":"Autenticar e iniciar sessão do portal","description":"Autentica com e-mail/senha e retorna um JWT de sessão do portal (também definido como cookie httponly `session`). Falha de credencial ou e-mail não verificado retornam a mesma mensagem (anti-enumeração — Princípio V / FR-023).","operationId":"login_api_v1_auth_login_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"},"examples":{"padrao":{"summary":"Login padrão","value":{"email":"dev@example.com","password":"SenhaForte123"}}}}},"required":true},"responses":{"200":{"description":"Token de sessão (JWT); também é definido como cookie httponly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginResponse"}}}},"401":{"description":"Credenciais inválidas ou e-mail não verificado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Muitas tentativas de login deste IP.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/auth/logout":{"post":{"tags":["Autenticação"],"summary":"Encerrar a sessão do portal","description":"Remove o cookie de sessão httponly. Idempotente — sempre retorna 200.","operationId":"logout_api_v1_auth_logout_post","responses":{"200":{"description":"Confirmação de logout; o cookie de sessão é removido.","content":{"application/json":{"schema":{"additionalProperties":{"type":"boolean"},"type":"object","title":"Response Logout Api V1 Auth Logout Post"}}}}}}},"/api/v1/auth/me":{"get":{"tags":["Autenticação"],"summary":"Dados da conta autenticada","description":"Retorna os dados da conta associada à sessão do portal atual (header `Authorization: Bearer <jwt>` ou cookie `session`).","operationId":"me_api_v1_auth_me_get","responses":{"200":{"description":"Dados básicos da conta do desenvolvedor autenticado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountMe"}}}},"401":{"description":"Sessão ausente, inválida ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"SessionAuth":[]}]}},"/api/v1/keys":{"get":{"tags":["API Keys"],"summary":"Listar as API keys da conta","description":"Lista as API keys da conta autenticada (ativas e revogadas), sem expor segredo ou hash. Exige sessão do portal.","operationId":"list_keys_api_v1_keys_get","responses":{"200":{"description":"Keys da conta autenticada (sem segredo/hash).","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ApiKeyResponse"},"type":"array","title":"Response List Keys Api V1 Keys Get"}}}},"401":{"description":"Sessão ausente, inválida ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"SessionAuth":[]}]},"post":{"tags":["API Keys"],"summary":"Criar uma nova API key","description":"Gera uma nova API key para a conta autenticada. Exige sessão do portal **com e-mail verificado** (FR-007). O segredo completo é exibido **uma única vez**, nesta resposta — apenas o prefixo é recuperável depois.","operationId":"create_key_api_v1_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyRequest"},"examples":{"padrao":{"summary":"Key de produção","value":{"name":"Minha key de produção"}}}}},"required":true},"responses":{"201":{"description":"Key criada; o segredo completo (`key`) só aparece nesta resposta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreatedResponse"}}}},"401":{"description":"Sessão ausente, inválida ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"E-mail não verificado — verifique o e-mail antes de criar keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"SessionAuth":[]}]}},"/api/v1/keys/{key_id}":{"delete":{"tags":["API Keys"],"summary":"Revogar uma API key","description":"Revoga (soft-delete) uma API key da conta autenticada. Apenas o proprietário da key pode revogá-la; keys de outras contas ou inexistentes retornam 404 (não confirma existência alheia).","operationId":"revoke_key_api_v1_keys__key_id__delete","security":[{"SessionAuth":[]}],"parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","description":"Identificador da API key a revogar.","title":"Key Id"},"description":"Identificador da API key a revogar."}],"responses":{"204":{"description":"Key revogada com sucesso (sem corpo)."},"401":{"description":"Sessão ausente, inválida ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"API key inexistente ou pertencente a outra conta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/keys/{key_id}/usage":{"get":{"tags":["Uso","Uso"],"summary":"Uso por API key (buckets determinístico/IA)","description":"Retorna as métricas de uso da API key informada, por bucket (`deterministic` e `ai`): consumo na janela atual e no dia, e os limites vigentes. A key consultada deve pertencer à conta autenticada. Exige sessão do portal.","operationId":"key_usage_api_v1_keys__key_id__usage_get","security":[{"SessionAuth":[]}],"parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","description":"Identificador da API key.","title":"Key Id"},"description":"Identificador da API key."}],"responses":{"200":{"description":"Contadores de uso e limites por bucket (determinístico e IA) da key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyUsageResponse"}}}},"401":{"description":"Sessão ausente, inválida ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"API key inexistente ou pertencente a outra conta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/usage":{"get":{"tags":["Uso","Uso"],"summary":"Uso agregado da conta","description":"Retorna o uso agregado do dia corrente para todas as API keys da conta autenticada (consumo determinístico e de IA). Exige sessão do portal.","operationId":"account_usage_api_v1_usage_get","responses":{"200":{"description":"Total de keys e consumo agregado (determinístico e IA) do dia.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountUsageResponse"}}}},"401":{"description":"Sessão ausente, inválida ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"SessionAuth":[]}]}},"/api/v1/busca-semantica":{"post":{"tags":["Busca Semântica"],"summary":"Busca semantica com IA (conteudo nao-oficial)","description":"Responde uma pergunta em linguagem natural com texto **gerado por IA** (claramente marcado como **nao-oficial**, `oficial=false`) acompanhado das **fontes oficiais rastreaveis** da BNCC (codigo + relevancia). Correspondencias abaixo do limiar de similaridade nao sao apresentadas como oficiais; na ausencia de correspondencia confiavel a resposta sinaliza isso em vez de inventar.","operationId":"busca_semantica_api_v1_busca_semantica_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuscaSemanticaRequest"}}},"required":true},"responses":{"200":{"description":"Resposta gerada por IA (nao-oficial) com fontes oficiais rastreaveis, ou aviso de ausencia de correspondencia confiavel.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuscaSemanticaResponse"}}}},"400":{"description":"Query invalida (vazia/curta/longa) ou payload invalido."},"401":{"description":"API key ausente, invalida ou revogada."},"429":{"description":"Cota de IA excedida (bucket ai: 20/min ou 500/dia)."},"503":{"description":"Camada de IA indisponivel (acionavel)."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}}},"components":{"schemas":{"AccountMe":{"properties":{"account_id":{"type":"string","title":"Account Id"},"email":{"type":"string","format":"email","title":"Email"},"email_verified":{"type":"boolean","title":"Email Verified"}},"type":"object","required":["account_id","email","email_verified"],"title":"AccountMe"},"AccountUsageResponse":{"properties":{"account_id":{"type":"string","title":"Account Id"},"total_keys":{"type":"integer","title":"Total Keys"},"deterministic_used_today":{"type":"integer","title":"Deterministic Used Today"},"ai_used_today":{"type":"integer","title":"Ai Used Today"}},"type":"object","required":["account_id","total_keys","deterministic_used_today","ai_used_today"],"title":"AccountUsageResponse"},"ApiKeyCreatedResponse":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"prefix":{"type":"string","title":"Prefix"},"key":{"type":"string","title":"Key","description":"Segredo completo — exibido apenas nesta resposta"}},"type":"object","required":["id","name","prefix","key"],"title":"ApiKeyCreatedResponse","description":"Segredo `key` exibido UMA única vez, na criação."},"ApiKeyResponse":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"prefix":{"type":"string","title":"Prefix"},"status":{"type":"string","title":"Status"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At"}},"type":"object","required":["id","name","prefix","status","created_at"],"title":"ApiKeyResponse"},"AreaConhecimento":{"type":"string","enum":["linguagens","matematica","ciencias_natureza","ciencias_humanas","ensino_religioso","computacao"],"title":"AreaConhecimento","description":"Áreas de conhecimento da BNCC."},"Body_dashboard_create_key_portal_keys_post":{"properties":{"name":{"type":"string","title":"Name"}},"type":"object","required":["name"],"title":"Body_dashboard_create_key_portal_keys_post"},"Body_login_submit_portal_login_post":{"properties":{"email":{"type":"string","title":"Email"},"password":{"type":"string","title":"Password"}},"type":"object","required":["email","password"],"title":"Body_login_submit_portal_login_post"},"Body_onboarding_submit_portal_onboarding_post":{"properties":{"step":{"type":"integer","title":"Step"},"resposta":{"items":{"type":"string"},"type":"array","title":"Resposta","default":[]}},"type":"object","required":["step"],"title":"Body_onboarding_submit_portal_onboarding_post"},"Body_signup_submit_portal_signup_post":{"properties":{"email":{"type":"string","title":"Email"},"password":{"type":"string","title":"Password"}},"type":"object","required":["email","password"],"title":"Body_signup_submit_portal_signup_post"},"BucketUsage":{"properties":{"used_this_minute":{"type":"integer","title":"Used This Minute","default":0},"limit_per_minute":{"type":"integer","title":"Limit Per Minute"},"used_today":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Used Today"},"limit_per_day":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit Per Day"}},"type":"object","required":["limit_per_minute"],"title":"BucketUsage"},"BuscaSemanticaRequest":{"properties":{"query":{"type":"string","maxLength":500,"minLength":3,"title":"Query","description":"Pergunta ou busca em linguagem natural (3-500 caracteres)."},"max_resultados":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Max Resultados","description":"Numero maximo de fontes a considerar (1-20).","default":5},"incluir_contexto":{"type":"boolean","title":"Incluir Contexto","description":"Se verdadeiro, enriquece a resposta com o contexto das fontes.","default":true}},"type":"object","required":["query"],"title":"BuscaSemanticaRequest","description":"Corpo da requisicao de busca semantica.","example":{"incluir_contexto":true,"max_resultados":5,"query":"Qual habilidade de matematica do 5o ano aborda fracoes?"}},"BuscaSemanticaResponse":{"properties":{"resposta":{"type":"string","title":"Resposta","description":"Texto gerado (nao-oficial) pela IA."},"fontes":{"items":{"$ref":"#/components/schemas/DocumentoFonte"},"type":"array","title":"Fontes","description":"Documentos oficiais rastreaveis usados/citados."},"documentos_consultados":{"type":"integer","title":"Documentos Consultados","description":"Total de documentos considerados na recuperacao.","default":0},"tempo_processamento":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Tempo Processamento","description":"Tempo de processamento em segundos."},"oficial":{"type":"boolean","title":"Oficial","description":"Sempre False: o texto gerado NAO e dado oficial (FR-016).","default":false},"aviso":{"type":"string","title":"Aviso","description":"Aviso de nao-oficialidade do conteudo gerado.","default":"Conteudo gerado por IA a partir de fontes oficiais da BNCC. A redacao da resposta NAO e um documento oficial - consulte os codigos citados em `fontes` para o texto oficial."}},"type":"object","required":["resposta"],"title":"BuscaSemanticaResponse","description":"Resposta da busca semantica - conteudo gerado, marcado como nao-oficial.","example":{"aviso":"Conteudo gerado por IA a partir de fontes oficiais da BNCC. A redacao da resposta NAO e um documento oficial - consulte os codigos citados em `fontes` para o texto oficial.","documentos_consultados":5,"fontes":[{"codigo":"EF05MA03","relevancia":0.91,"tipo":"habilidade","titulo":"Habilidade EF05MA03 - Matematica"}],"oficial":false,"resposta":"As habilidades relacionadas a fracoes no 5o ano incluem a EF05MA03... (conteudo nao-oficial gerado por IA)","tempo_processamento":1.23}},"CompetenciaEspecifica":{"properties":{"codigo":{"type":"string","title":"Codigo","description":"Código único da competência específica"},"numero":{"type":"integer","title":"Numero","description":"Número dentro da área/componente"},"area_conhecimento":{"$ref":"#/components/schemas/AreaConhecimento","description":"Área de conhecimento"},"componente":{"anyOf":[{"$ref":"#/components/schemas/ComponenteCurricular"},{"type":"null"}],"description":"Componente curricular (se aplicável)"},"descricao":{"type":"string","title":"Descricao","description":"Descrição da competência específica"},"etapa":{"$ref":"#/components/schemas/EtapaEnsino","description":"Etapa de ensino"}},"type":"object","required":["codigo","numero","area_conhecimento","descricao","etapa"],"title":"CompetenciaEspecifica","description":"Competência específica de área/componente (EI/EF/EM).","example":{"area_conhecimento":"matematica","codigo":"EFMAT01","componente":"matematica","descricao":"Reconhecer que a Matemática é uma ciência humana...","etapa":"ensino_fundamental","numero":1}},"CompetenciaGeral":{"properties":{"numero":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Numero","description":"Número da competência (1-10)"},"titulo":{"type":"string","title":"Titulo","description":"Título da competência"},"descricao":{"type":"string","title":"Descricao","description":"Descrição completa da competência"}},"type":"object","required":["numero","titulo","descricao"],"title":"CompetenciaGeral","description":"Competência geral da BNCC (1..10, transversal às etapas).","example":{"descricao":"Valorizar e utilizar os conhecimentos historicamente construídos sobre o mundo físico, social, cultural e digital...","numero":1,"titulo":"Conhecimento"}},"ComponenteCurricular":{"type":"string","enum":["lingua_portuguesa","arte","educacao_fisica","lingua_inglesa","matematica","ciencias","geografia","historia","ensino_religioso","computacao"],"title":"ComponenteCurricular","description":"Componentes curriculares da BNCC."},"CreateApiKeyRequest":{"properties":{"name":{"type":"string","maxLength":120,"minLength":1,"title":"Name"}},"type":"object","required":["name"],"title":"CreateApiKeyRequest"},"DocumentoFonte":{"properties":{"codigo":{"type":"string","title":"Codigo","description":"Codigo oficial da habilidade/competencia."},"tipo":{"type":"string","title":"Tipo","description":"Tipo do documento (habilidade | competencia)."},"relevancia":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Relevancia","description":"Similaridade coseno (0-1)."},"titulo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Titulo","description":"Titulo legivel do documento (quando disponivel)."}},"type":"object","required":["codigo","tipo","relevancia"],"title":"DocumentoFonte","description":"Fonte oficial rastreavel citada na resposta.\n\nDefinicao propria de US4 (nao importar de `app/models/bncc.py`)."},"EixoComputacao":{"type":"string","enum":["pensamento_computacional","mundo_digital","cultura_digital"],"title":"EixoComputacao","description":"Eixos do Complemento de Computação à BNCC (Educação Infantil e Ensino\nFundamental). O Ensino Médio não é organizado por eixos, mas por competências\nespecíficas de Computação (ver `Habilidade.competencia_especifica`)."},"ErrorResponse":{"properties":{"detail":{"type":"string","title":"Detail","description":"Descrição do erro"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Código interno do erro"},"timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timestamp","description":"Timestamp do erro"}},"type":"object","required":["detail"],"title":"ErrorResponse","description":"Modelo padrão para respostas de erro."},"EtapaEnsino":{"type":"string","enum":["educacao_infantil","ensino_fundamental","ensino_medio"],"title":"EtapaEnsino","description":"Etapas de ensino da BNCC."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Habilidade":{"properties":{"codigo":{"type":"string","title":"Codigo","description":"Código oficial (EI/EF/EM)"},"descricao":{"type":"string","title":"Descricao","description":"Descrição completa da habilidade"},"etapa":{"$ref":"#/components/schemas/EtapaEnsino","description":"Etapa de ensino"},"anos":{"items":{"type":"string"},"type":"array","title":"Anos","description":"Anos escolares"},"area_conhecimento":{"$ref":"#/components/schemas/AreaConhecimento","description":"Área de conhecimento"},"componente":{"anyOf":[{"$ref":"#/components/schemas/ComponenteCurricular"},{"type":"null"}],"description":"Componente curricular (ausente no EM, organizado por área)"},"competencias_gerais":{"items":{"type":"integer"},"type":"array","title":"Competencias Gerais","description":"Competências gerais relacionadas (1-10)"},"competencias_especificas":{"items":{"type":"string"},"type":"array","title":"Competencias Especificas","description":"Códigos de competências específicas"},"objetos_conhecimento":{"items":{"type":"string"},"type":"array","title":"Objetos Conhecimento","description":"Objetos de conhecimento relacionados"},"campo_experiencia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Campo Experiencia","description":"Campo de experiência (Educação Infantil)"},"itinerario":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Itinerario","description":"Itinerário formativo (Ensino Médio)"},"unidade_tematica":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unidade Tematica","description":"Unidade temática (Ensino Fundamental)"},"eixo":{"anyOf":[{"$ref":"#/components/schemas/EixoComputacao"},{"type":"null"}],"description":"Eixo do Complemento de Computação (EI/EF): pensamento_computacional, mundo_digital ou cultura_digital. Ausente no Ensino Médio, que é organizado por competências específicas de Computação."}},"type":"object","required":["codigo","descricao","etapa","area_conhecimento"],"title":"Habilidade","description":"Habilidade da BNCC — suporta EI, EF e EM.","example":{"anos":["5"],"area_conhecimento":"matematica","codigo":"EF05MA07","competencias_especificas":[],"competencias_gerais":[1,2,4],"componente":"matematica","descricao":"Resolver e elaborar problemas de adição e subtração...","etapa":"ensino_fundamental","objetos_conhecimento":[]}},"KeyUsageResponse":{"properties":{"api_key_id":{"type":"string","title":"Api Key Id"},"deterministic":{"$ref":"#/components/schemas/BucketUsage"},"ai":{"$ref":"#/components/schemas/BucketUsage"}},"type":"object","required":["api_key_id","deterministic","ai"],"title":"KeyUsageResponse"},"LoginRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"password":{"type":"string","title":"Password"}},"type":"object","required":["email","password"],"title":"LoginRequest"},"LoginResponse":{"properties":{"access_token":{"type":"string","title":"Access Token"},"token_type":{"type":"string","title":"Token Type","default":"bearer"},"expires_in_minutes":{"type":"integer","title":"Expires In Minutes"}},"type":"object","required":["access_token","expires_in_minutes"],"title":"LoginResponse"},"PaginatedResponse":{"properties":{"items":{"items":{},"type":"array","title":"Items","description":"Items da página atual"},"total":{"type":"integer","title":"Total","description":"Total de items"},"page":{"type":"integer","title":"Page","description":"Página atual"},"size":{"type":"integer","title":"Size","description":"Tamanho da página"},"pages":{"type":"integer","title":"Pages","description":"Total de páginas"}},"type":"object","required":["items","total","page","size","pages"],"title":"PaginatedResponse","description":"Resposta paginada genérica.","example":{"items":[],"page":1,"pages":5,"size":20,"total":100}},"SignupRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"password":{"type":"string","title":"Password","description":"Mínimo 10 caracteres, com letras e números"}},"type":"object","required":["email","password"],"title":"SignupRequest"},"SignupResponse":{"properties":{"account_id":{"type":"string","title":"Account Id"},"email":{"type":"string","format":"email","title":"Email"},"email_verified":{"type":"boolean","title":"Email Verified","default":false}},"type":"object","required":["account_id","email"],"title":"SignupResponse"},"SnapshotMetadata":{"properties":{"versao":{"type":"string","title":"Versao","description":"Versão do snapshot (ex.: v1)"},"data_publicacao":{"type":"string","title":"Data Publicacao","description":"Data de publicação (ISO)"},"checksum_fontes":{"additionalProperties":{"type":"string"},"type":"object","title":"Checksum Fontes","description":"SHA-256 de cada fonte oficial"},"contagens":{"additionalProperties":true,"type":"object","title":"Contagens","description":"Contagens por etapa/componente"},"missing_sources":{"items":{"type":"string"},"type":"array","title":"Missing Sources","description":"Fontes oficiais ausentes (ex.: educacao_infantil)"}},"type":"object","required":["versao","data_publicacao"],"title":"SnapshotMetadata","description":"Metadados de rastreabilidade do snapshot versionado (FR-025)."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VerifyEmailRequest":{"properties":{"token":{"type":"string","minLength":8,"title":"Token"}},"type":"object","required":["token"],"title":"VerifyEmailRequest"},"VerifyEmailResponse":{"properties":{"email_verified":{"type":"boolean","title":"Email Verified","default":true}},"type":"object","title":"VerifyEmailResponse"}},"securitySchemes":{"ApiKeyAuth":{"type":"http","description":"API key gerada no portal self-service, enviada como 'Authorization: Bearer <key>'. Requerida pelos endpoints de dados e busca semântica.","scheme":"bearer"},"SessionAuth":{"type":"http","description":"JWT de sessão do portal (login self-service). Não usar para chamadas de API de dados/IA — use ApiKeyAuth.","scheme":"bearer"}}},"tags":[{"name":"Habilidades","description":"Habilidades da BNCC por código oficial (EI/EF/EM), com filtros, paginação e relações navegáveis."},{"name":"Competências","description":"Competências gerais e específicas por componente e etapa."},{"name":"Taxonomia","description":"Vocabulário estruturante: etapas, componentes, unidades temáticas e eixos."},{"name":"Busca Semântica","description":"Busca por significado com IA. **Conteúdo não-oficial** e rastreável por `fontes`; degrada graciosamente se a camada de IA estiver indisponível."},{"name":"Autenticação","description":"Cadastro, login e verificação de e-mail para acesso ao portal."},{"name":"API Keys","description":"Emissão e revogação de chaves de API (mostradas apenas na criação)."},{"name":"Uso","description":"Consumo e limites de uso por chave."},{"name":"Sistema","description":"Saúde, versão e metadados operacionais da API."}]}