O que existe hoje e o que ainda é plano
Ser direto aqui evita que alguém integre contra algo que não existe. A tabela abaixo separa o que já está funcionando do que ainda está em especificação.
Já existe
- ✓ Catálogo estático de 54 registros, navegável na Biblioteca
- ✓ Busca e filtros por categoria, cultura e região, rodando no navegador
- ✓ Identificação por foto, servida pelo backend real — o navegador nunca vê nenhuma chave de IA
- ✓ Servidor real (
tbka-api) respondendo nos quatro endpoints abaixo, em produção - ✓ Chaves de API funcionais, emitidas manualmente mediante cadastro — ver Termos de uso
Ainda não existe
- ✕ Emissão de chave self-serve (hoje é sempre manual, por pedido)
- ✕ Faturamento ou painel de consumo por app
- ✕ Busca semântica por sintomas (hoje é correspondência por palavra-chave)
- ✕ Este playground ainda simula chamadas lendo os dados do catálogo, em vez de bater no servidor real
Chave de acesso
Toda aplicação autentica com uma chave no cabeçalho Authorization: Bearer <chave>. A API está em produção, mas a emissão de chaves ainda é manual — não existe cadastro self-serve nesta versão. Gere abaixo uma chave no formato final só pra ver como ela se parece; ela não ativa nada.
Chave ilustrativa, não funcional. Ela é gerada aqui mesmo no navegador e não é enviada a nenhum servidor. Pra obter uma chave que funcione de verdade, leia os Termos de uso abaixo e solicite acesso — hoje toda chave é emitida manualmente, uma por uma.
Termos de uso
Regras válidas para toda chave de API emitida, enquanto a TBKA estiver nesta fase de acesso manual e sem faturamento.
Permitido
- ✓ Consultar o catálogo e usar a identificação por foto dentro de uma aplicação própria
- ✓ Citar a fonte ("Dataset TB Knowledge Agro") quando os dados aparecerem publicamente em outro produto
- ✓ Uso comercial, desde que dentro dos limites de requisição da chave
Não permitido
- ✕ Redistribuir ou revender o dataset bruto (os 54 registros) fora de uma aplicação que consuma a API
- ✕ Scraping em massa ou automação que contorne o limite de requisições da chave
- ✕ Compartilhar a própria chave com terceiros — cada aplicação/projeto tem a sua
- ✕ Reintroduzir nome comercial de insumo ou dosagem em cima da resposta da API — o dataset já retorna só categoria de insumo, por exigência legal (Lei 14.785/2023 e Resolução Confea 1.149/2025), e isso não pode ser contornado a jusante
Como pedir uma chave: hoje a emissão é manual — não há formulário automático. Descreva o projeto e o uso pretendido e a chave é gerada e enviada por fora. Limites: cada chave tem um limite padrão de requisições por minuto; se seu caso de uso precisar de mais, informe ao pedir a chave. Revogação: uma chave pode ser revogada a qualquer momento em caso de uso fora destes termos, sem aviso prévio.
Quatro operações cobrem o catálogo inteiro
A base já é pequena e bem tipada — não há necessidade de uma superfície grande de API. Estes quatro endpoints espelham exatamente o que o catálogo já faz na interface.
Listar registros
Retorna registros do catálogo, com os mesmos filtros já disponíveis na Biblioteca.
| Parâmetro | Descrição |
|---|---|
| categoria | Filtra por uma das 8 categorias (ex: Praga, Doença Fúngica) |
| cultura | Café Arábica, Café Conilon, ou ambos |
| regiao | Estadual, Sul ou Norte/Noroeste ES |
| q | Busca livre por nome, sintoma ou espécie científica |
curl https://tbka-api.vercel.app/v1/records \
-H "Authorization: Bearer <chave>" \
-G --data-urlencode "categoria=Praga" \
--data-urlencode "cultura=Café Conilon"
Buscar um registro
Retorna a ficha técnica completa de um registro pelo seu código (ex: CAF-001), com todos os campos exibidos na ficha do catálogo.
| Parâmetro | Descrição |
|---|---|
| id | Código do registro, CAF-001 a CAF-050 |
curl https://tbka-api.vercel.app/v1/records/CAF-001 \ -H "Authorization: Bearer <chave>"
Identificar por sintomas ou foto
Recebe uma descrição textual (e, futuramente, fotos por parte da planta) e retorna até 3 candidatos do catálogo, nunca um diagnóstico fora da base — mesma regra já aplicada na identificação por foto do protótipo.
| Parâmetro | Descrição |
|---|---|
| descricao | Texto livre descrevendo os sintomas observados |
| parte | Opcional: folhas, caule, base, raízes |
curl -X POST https://tbka-api.vercel.app/v1/identify \
-H "Authorization: Bearer <chave>" \
-H "Content-Type: application/json" \
-d '{"descricao": "manchas alaranjadas na folha"}'
Busca por palavra-chave
Em produção, com os mesmos filtros de /v1/records, sem paginação. Faz correspondência por palavra-chave nos campos de texto. Busca por similaridade de sintomas (semântica, sem precisar da palavra exata) é planejada para o dataset v2.0 — ver Roadmap abaixo.
| Parâmetro | Descrição |
|---|---|
| q | Texto livre — busca em nome, sintomas, agente, parte afetada e id |
| categoria | Filtra por categoria (substring) |
| cultura | Filtra por cultura (match exato) |
| regiao | Filtra por região (substring) |
curl "https://tbka-api.vercel.app/v1/records/search?q=amarelecimento" \ -H "Authorization: Bearer SUA_CHAVE"
Simule uma chamada
Roda inteiramente no seu navegador, lendo os mesmos 54 registros do catálogo — não existe uma chamada de rede real acontecendo aqui.
// Escolha um endpoint e clique em "Simular chamada".
Schema de um registro
Todo registro retornado pela API (ou visível no playground acima) segue estes campos, os mesmos usados internamente pelo catálogo.
| Campo | Tipo | Descrição |
|---|---|---|
| id | string | Código do registro, ex: CAF-001 |
| ranking | number | Posição de relevância dentro do dataset |
| categoria | string | Uma ou mais das 8 categorias, separadas por ";" |
| cultura | string | Café Arábica, Café Conilon, ou ambos |
| regiao | string | Abrangência geográfica no Espírito Santo |
| nome | string | Nome popular do problema |
| cientifico | string | Nome científico do agente, quando aplicável |
| agente | string | Organismo ou causa física/química responsável |
| parte | string | Parte da planta tipicamente afetada |
| sint_inicial | string | Sintomas no estágio inicial |
| sint_avancado | string | Sintomas no estágio avançado |
| confianca | number | Confiabilidade de triagem por fotografia, de 0 a 1 |
| manejo_prev | string | Manejo preventivo, por categoria de insumo — nunca marca ou dose |
| manejo_corr | string | Manejo corretivo, por categoria de insumo — nunca marca ou dose |
Do dataset estático à API real
Esta é uma sequência real de versões, na ordem em que estão planejadas — não uma lista decorativa.
54 registros, catálogo estático
Dataset consolidado e navegável na Biblioteca, sem backend — este site é um arquivo único.
Revisão técnica por agrônomo
Validação de cada ficha por um engenheiro agrônomo antes de qualquer uso além de consulta e triagem.
Fotos reais
Substituição das fotos geradas por IA por fotografias de campo confirmadas.
IA treinada + busca semântica
Base para o endpoint /v1/records/search funcionar por similaridade de sintomas, não só palavra-chave.
Backend real
Servidor em produção (tbka-api) respondendo nos quatro endpoints, com autenticação por chave e identificação por foto processada no servidor — já consumível por terceiros, incluindo o TerraBase.