API do Abeesys RAG

POST /v1/conhecimento

Insere ou revisa um conhecimento

Exige a API key do tenant.

A Idempotency-Key é a identidade natural do conhecimento, única por tenant. Mesma chave com o mesmo corpo devolve o registro como está (200). Mesma chave com corpo novo é revisão do mesmo registro: a versão sobe e a resposta passa a usar o texto novo (200). Chave nova cria (201). Nunca 409.

O vetor é pedido ao vetorizador antes da gravação. Vetorizador fora, lento ou ainda carregando o modelo: o registro é gravado com indexacao: pendente, responde só pela busca textual, e um worker interno o reprocessa quando o vetorizador volta — sem nunca mexer na publicação.

O vetorizador nunca trunca. Texto que não cabe na janela de tokens dele é recusado com 422 text-exceeds-window, nomeando o limite em tokens, e não deixa registro — nem versão, nem pendência. O limite de caracteres de texto não garante caber na janela: a contagem é em tokens, e quem conta é o vetorizador. Um registro que já estava pendente e o vetorizador recusa por janela passa a indexacao: recusado e não é reprocessado; volta à indexação só com um texto novo na mesma chave (spec 0029).

Marca sugestao segura o registro em rascunho até a marca ser retirada na mesma chave.

Parâmetros

Corpo application/json

KnowledgeInput

{
  "texto": "A remarcação de um agendamento é gratuita até 2 horas antes do horário marcado.",
  "tipo": "observacao",
  "publicacao": "publicado",
  "referencia": "politica:7d41a0"
}

Respostas

• 200 já existia — revisado (versão nova) ou idêntico (sem mudança) application/json Knowledge
• 201 criado application/json Knowledge
• 400 requisição ilegível — corpo que não é JSON, parâmetro malformado application/problem+json Problemhttps://abeesys.com/errors/bad-request
• 401 API key ausente, inválida, ou de tenant desativado — a mesma resposta application/problem+json Problemhttps://abeesys.com/errors/unauthorized
• 422 Entrada que viola o schema ou regra de entrada: enum fora, texto vazio ou acima do limite, campo desconhecido, null onde se pede valor, credencial não cadastrada, texto acima da janela de tokens do vetorizador, ou identidade do vetorizador (repositório, arquivo, quantização, dimensão, pooling, janela) diferente da do índice. Não deixa registro. application/problem+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/text-exceeds-window

GET /v1/conhecimento/{id}

Lê a versão atual de um conhecimento

Exige a API key do tenant.

Parâmetros

Respostas

• 200 o conhecimento application/json Knowledge
• 401 API key ausente, inválida, ou de tenant desativado — a mesma resposta application/problem+json Problemhttps://abeesys.com/errors/unauthorized
• 404 inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found

GET /v1/conhecimento/{id}/versoes

Lista as versões de um conhecimento, da mais nova para a mais antiga

Exige a API key do tenant.

Parâmetros

Respostas

• 200 as versões, ordenadas por versao decrescente application/json KnowledgeVersionList
• 401 API key ausente, inválida, ou de tenant desativado — a mesma resposta application/problem+json Problemhttps://abeesys.com/errors/unauthorized
• 404 inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found

GET /v1/conhecimento/{id}/versoes/{versao}

Abre o texto inserido numa versão — é o caminho da origem de um trecho

Exige a API key do tenant.

Parâmetros

Respostas

• 200 a versão application/json KnowledgeVersion
• 400 requisição ilegível — corpo que não é JSON, parâmetro malformado application/problem+json Problemhttps://abeesys.com/errors/bad-request
• 401 API key ausente, inválida, ou de tenant desativado — a mesma resposta application/problem+json Problemhttps://abeesys.com/errors/unauthorized
• 404 inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found

PUT /v1/conhecimento/{id}/veto

O tenant segura o próprio conhecimento

Exige a API key do tenant.

A partir daqui o conhecimento não sustenta texto nenhum — nem como trecho, nem como origem, nem indo ao modelo. O registro continua publicado: veto não é rascunho. Idempotente.

Parâmetros

Respostas

• 204 vetado
• 401 API key ausente, inválida, ou de tenant desativado — a mesma resposta application/problem+json Problemhttps://abeesys.com/errors/unauthorized
• 404 inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found

DELETE /v1/conhecimento/{id}/veto

Tira o veto — o conhecimento volta sem reinserir

Exige a API key do tenant.

Parâmetros

Respostas

• 204 sem veto
• 401 API key ausente, inválida, ou de tenant desativado — a mesma resposta application/problem+json Problemhttps://abeesys.com/errors/unauthorized
• 404 inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found

POST /v1/perguntas

Pergunta ao conhecimento do tenant que pergunta

Exige a API key do tenant.

A resposta chega em três tempos, nesta ordem e nada fora dela:

1. trechos — o que sustenta, com a origem de cada um, e o desfecho;
2. confianca — o nível, calculado antes do texto, da cobertura textual da pergunta pelos trechos (nunca da distância do vetor), igual para qualquer motor;
3. texto — o texto verificado, sentença a sentença. Sentença sem origem válida sai inteira. Se nenhuma sobrevive, o texto vem vazio.

stream=true (padrão) devolve SSE com os eventos nomeados trechos, confianca e texto, um de cada, nesta ordem. stream=false devolve os três tempos no fim, na mesma ordem.

Perguntar grava só cache da resposta e medição de uso — mesmo quando o consumidor desiste no meio. Não grava conhecimento, veto, nem estado de resposta.

Quem escreve o texto (spec 0034): a credencial do tenant, se a pergunta cita uma; o modelo hospedado da plataforma se ela falhar ou se a pergunta não citar nenhuma; nenhum, se os dois falharem — e aí os trechos e o nível saem do mesmo jeito, sem texto, nunca 500. A cadeia inteira tem um teto somado de tempo (35 s por padrão, configuração do serviço), com uma reserva para o hospedado: o 429 do provedor da credencial é tentado de novo, com espera crescente, só enquanto sobra a reserva do hospedado — esgotado, o hospedado responde com motivo: limite_de_taxa. Os dois primeiros tempos (trechos e nível) não esperam o motor.

Resposta em que a credencial do tenant falhou (credencial_falhou: true, qualquer motivo) não vai ao cache: repetir a pergunta quando o provedor voltar dá a resposta dele, não a do hospedado guardada.

Parâmetros

Corpo application/json

QuestionInput

{
  "pergunta": "posso remarcar o agendamento no mesmo dia?",
  "credencial": "principal"
}

Respostas

• 200 text/event-stream com stream=true; application/json com stream=false. Os dois carregam os mesmos três objetos. text/event-stream string · application/json Answer
• 400 requisição ilegível — corpo que não é JSON, parâmetro malformado application/problem+json Problemhttps://abeesys.com/errors/bad-request
• 401 API key ausente, inválida, ou de tenant desativado — a mesma resposta application/problem+json Problemhttps://abeesys.com/errors/unauthorized
• 422 Entrada que viola o schema ou regra de entrada: enum fora, texto vazio ou acima do limite, campo desconhecido, null onde se pede valor, credencial não cadastrada, texto acima da janela de tokens do vetorizador, ou identidade do vetorizador (repositório, arquivo, quantização, dimensão, pooling, janela) diferente da do índice. Não deixa registro. application/problem+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/text-exceeds-window

event: trechos
data: {"desfecho":"encontrado","trechos":[...],"negativos":[],"procurado":{...}}

event: confianca
data: {"nivel":"alta"}

event: texto
data: {"resposta_id":"...","texto":"...","sentencas":[...],"motor":{...},"uso":{...}}

PUT /v1/credenciais/{nome}

Cadastra ou troca uma credencial de modelo do tenant

Exige a API key do tenant.

Só troca — nunca devolve o segredo, em nenhuma rota, nem em erro. Cifrada em repouso (ADR 0006).

O provedor da credencial responde, e o estado dela muda (spec 0034):

- 401/403 — fica inválida e deixa de ser tentada; as perguntas que a citam saem do hospedado com motivo: credencial_invalida. - 402 (sem saldo) — fica sem saldo, que não é inválida: ela continua sendo tentada a cada pergunta, e a primeira resposta bem-sucedida dela a devolve a válida. Enquanto o provedor disser 402, o hospedado responde, com motivo: credencial_sem_saldo. - 429 (limite de taxa) — o estado não muda (ver askQuestion).

Registrar de novo — inválida ou sem saldo — a traz de volta válida. Resposta já em cache dessa credencial (da mesma revisão) é servida também enquanto ela está sem saldo: o cache não chama o provedor.

Parâmetros

Corpo application/json

CredentialInput

{
  "provedor": "openai",
  "modelo": "gpt-4o-mini",
  "segredo": "sk-exemplo-falso"
}

Respostas

• 204 guardada
• 400 requisição ilegível — corpo que não é JSON, parâmetro malformado application/problem+json Problemhttps://abeesys.com/errors/bad-request
• 401 API key ausente, inválida, ou de tenant desativado — a mesma resposta application/problem+json Problemhttps://abeesys.com/errors/unauthorized
• 422 Entrada que viola o schema ou regra de entrada: enum fora, texto vazio ou acima do limite, campo desconhecido, null onde se pede valor, credencial não cadastrada, texto acima da janela de tokens do vetorizador, ou identidade do vetorizador (repositório, arquivo, quantização, dimensão, pooling, janela) diferente da do índice. Não deixa registro. application/problem+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/text-exceeds-window

GET /v1/health

O processo está de pé

Sem API key.

Respostas

• 200 vivo application/json Health

{
  "status": "ok"
}

GET /v1/health/ready

Pronto para receber tráfego

Sem API key.

200 só com o banco alcançável, a extensão vector instalada em versão 0.8 ou maior (scan iterativo) e o índice HNSW presente. Sem a extensão o serviço não entra no ar — ADR 0005. O vetorizador não entra aqui: ele fora é degradação, não indisponibilidade.

Respostas

• 200 pronto application/json Health
• 503 não pronto — banco fora, extensão ausente ou abaixo de 0.8, índice ausente application/json Health

{
  "status": "ok"
}

{
  "status": "indisponivel",
  "motivo": "extensao-vector-ausente"
}

GET /openapi.yaml

Este contrato, em YAML

Sem API key.

Os bytes exatos de contract/openapi.yaml do commit que está no ar. Não exige API key: não carrega dado de tenant.

Respostas

• 200 o contrato application/yaml string

GET /openapi.json

Este contrato, em JSON

Sem API key.

O mesmo contrato do /openapi.yaml, convertido no arranque, na mesma ordem.

Respostas

• 200 o contrato application/json object

GET /llms.txt

Índice curto para agentes (llmstxt.org)

Sem API key.

Gerado deste contrato no arranque — o que o serviço faz, onde está e cada rota.

Respostas

• 200 o índice text/plain string

GET /llms-full.txt

Documentação completa para agentes

Sem API key.

Gerada deste contrato no arranque: rotas, parâmetros, campos, enums, respostas, tipos de erro e exemplos, num arquivo só de texto.

Respostas

• 200 a documentação text/plain string