API do Abeesys RAG
Conhecimento com citação — insira texto curto e pergunte; cada resposta diz de onde veio.
Endereço: https://api.rag.abeesys.com
Contrato 1.15.0 · OpenAPI 3.1.0 · baixar o openapi.yaml
Visão geral do contrato
Plataforma de conhecimento da Abeesys — spec 0025.
Dois contratos de domínio: inserir conhecimento e perguntar. As demais operações são as portas de apoio que a spec exige: listar, ler por id e por versão (o caminho que a origem de um trecho abre), arquivar e desarquivar (spec 0039), pôr e tirar veto, e cuidar das credenciais de modelo do tenant — cadastrar, trocar, ligar, desligar, ordenar, remover e ler o rastro (spec 0044).
A API atende em https://api.rag.abeesys.com (spec 0037), e também na rede privada da plataforma (rag.railway.internal), com o mesmo contrato e a mesma autenticação. Toda rota autenticada exige Authorization: Bearer com a API key do tenant ou uma sessão de pessoa (1.6.0). Cookie é ignorado: não autentica, sozinho nem junto de um bearer. As rotas de saúde e as quatro de documentação (/openapi.yaml, /openapi.json, /llms.txt e /llms-full.txt) não carregam dado de tenant. Pedir link, abrir sessão e aceitar convite também não exigem bearer. O tenant vem só da autenticação — nunca do corpo, da URL ou de um header escolhido pelo cliente.
Conhecimento ou credencial de outro tenant, ou inexistente, é o mesmo 404: a existência de um id ou de um nome não é informação que um tenant ganha.
Mudanças de semântica em 1.3.0 (spec 0044) — leia antes de atualizar o cliente:
- a pergunta sem credencial passa a ser escrita pelas credenciais ligadas do tenant, na ordem de preferência, e só depois pelo hospedado (antes: sempre o hospedado); - credencial nova cadastrada sem ligada: true nasce desligada, e a pergunta que a cita sai do hospedado com motivo: credencial_desligada. As credenciais que já existiam ficaram ligadas; - o enum de saída motivo ganhou credencial_desligada e endereco_recusado, e o motor ganhou tentativas.
Endereço público (spec 0037, 1.4.0):
- Só HTTPS. Requisição sem TLS é recusada (400), não redirecionada: a key não deve trafegar em texto claro. Toda resposta leva Strict-Transport-Security. - Limite de taxa por API key, por endereço de origem e por tentativa de key inválida de uma origem. Acima dele, 429 rate-limited com o cabeçalho Retry-After (segundos). Espere esse tempo antes de repetir; quem repete antes continua recebendo 429. A origem é a que o proxy de borda grava — X-Forwarded-For enviado pelo cliente não muda nada. Um sistema que fala com o rag de um servidor só é uma origem: o limite por origem é maior que o por key, e o da key é o que ele encontra primeiro. - Limite de corpo de 64 KiB em toda rota: acima dele, 413 payload-too-large, antes de o corpo ser lido. - CORS fechado. A API é para servidores; nenhuma resposta autoriza origem de navegador. - Saúde: GET /v1/health responde só {"status":"ok"}. A prontidão detalhada (/v1/health/ready) é da rede privada; pelo endereço público, 404.
Listar e arquivar (spec 0039, 1.5.0):
- GET /v1/conhecimento lista o que está na base, paginado, em atualizado_em descendente com desempate por id descendente. Sem o filtro arquivado, arquivado não aparece. - PUT /v1/conhecimento/{id}/arquivo arquiva; DELETE no mesmo caminho desarquiva. Não existe DELETE /v1/conhecimento/{id}: arquivar não apaga versão nem texto. - Reinserir a chave de um conhecimento arquivado passa a ser 409, e nada muda — a única exceção ao "nunca 409" de insertKnowledge. Nenhum outro caminho de inserção devolve 409. - arquivado entra na leitura e na listagem. Ausente significa false.
Pessoas, login e chaves (spec 0038, 1.6.0):
- a autenticação global passa a ser API key ou sessão. A key de hoje continua válida; - autor.tipo ganha pessoa em KnowledgeEvent e CredentialEvent. É valor novo num enum de saída. A 1.5.0 já anunciou esse valor na descrição. Cliente com switch exaustivo precisa tratar pessoa. A descrição do autor pessoa é o id da pessoa — nunca o e-mail. Não há /v2: o valor já estava nomeado; - rotas novas de entrar, convite, sessão, pessoas, chaves e rastro da conta. Pessoas e chaves exigem sessão: a API key nelas é 403 forbidden, não 401. Entrar e aceitar convite não exigem autenticação. O 202 de pedir link e de convidar é o mesmo corpo exista o e-mail ou não. Link, convite ou sessão recusados — inválido, usado ou vencido — são o mesmo 401, detalhe Recusado..
Base comum e escopo (spec 0028, 1.7.0) — evolução aditiva; quem nunca declara escopo continua exatamente como na 1.6.0:
- o parâmetro de consulta escopo (components/parameters/Scope) entra em toda rota de conhecimento e em POST /v1/perguntas. É um rótulo opaco que o cliente declara em cada chamada (uma loja, uma unidade, uma filial): o rag não o interpreta, não o normaliza e não o cadastra. Ausente é a base comum do tenant. Fora do formato — vazio, repetido, acima de 128 caracteres, com caractere de controle ou com espaço nas pontas — é 422 nomeando escopo, e nada é gravado; - conhecimento inserido sem escopo é a base comum: responde a toda pergunta do tenant, com ou sem escopo, menos onde o escopo o vetou ou sobrepôs. Conhecimento inserido com escopo X só responde à pergunta com escopo X. A pergunta sem escopo recebe só a base; - com escopo X, ler, vetar, arquivar ou listar um conhecimento do escopo Y é o mesmo 404 de inexistente; o da base é visível. Sem escopo, conhecimento de escopo é 404; - a identidade do conhecimento passa a ser (tenant, escopo, Idempotency-Key): a mesma chave em dois escopos são dois registros; - sobreposição (/v1/conhecimento/{id}/sobreposicao): o escopo escreve a versão dele de um conhecimento da base, e na pergunta com aquele escopo responde a dele; - veto do escopo: PUT …/veto?escopo=X sobre a base esconde só de X. O veto aceita um corpo opcional com motivo; sem corpo continua válido; - campos novos de saída, todos opcionais no schema: procedencia (base | escopo), escopo e sobrepoe em Knowledge; procedencia em Origin, cujo caminho passa a levar ?escopo= quando o trecho é do escopo; escopo em KnowledgeEvent.
O que o rag não garante: o escopo vem do cliente. Se o cliente declarar o escopo errado, o rag responde para o escopo declarado. A separação entre os escopos de um mesmo tenant é responsabilidade de quem chama, que tira o escopo da sessão autenticada dele. A separação entre tenants continua sendo a API key.
Fim da exceção de versão. Até a 1.3.0 o rag não tinha consumidor fora deste repositório, e valor novo em enum de saída entrava como versão menor com aviso. A 1.4.0 é a última assim: daqui em diante, valor novo num enum de saída e mudança de semântica seguem a regra de quebra de contrato como em qualquer serviço da plataforma.
Itens resolvidos e formato curto (spec 0036, 1.8.0) — evolução aditiva; quem não manda itens nem formato continua exatamente como na 1.7.0:
- QuestionInput ganha itens (os itens que o sistema cliente já resolveu: referência, preço em centavos com a moeda, quantidade disponível) e formato (padrao | curto); - VerifiedSentence ganha itens (a origem de item: a referência como foi enviada), e origens passa a aceitar zero elementos — só quando a pergunta trouxe itens e a sentença é sustentada só por item. Sem itens na pergunta, origens tem sempre ao menos um elemento e itens não aparece: a resposta tem a mesma forma da 1.7.0.
Os nomes dos campos e dos valores de enum são os da spec (em português), e são estáveis.
MCP e OAuth (spec 0027, 1.9.0) — evolução aditiva; nenhuma rota que existia muda:
- o rag é servidor MCP remoto em POST /mcp (Streamable HTTP, sem estado, JSON-RPC 2.0, só application/json) e servidor de autorização OAuth 2.1 para os assistentes (ChatGPT, Claude): descoberta pela RFC 9728 e pela RFC 8414, autorização com PKCE S256, registro por CIMD (hosts confiáveis) ou DCR restrito, troca e refresh com rotação; - o access token rag_mcp_at_… só autentica /mcp. Como bearer em qualquer rota REST é 401. API key e sessão de pessoa não autenticam /mcp; - o protocolo MCP (métodos, as ferramentas search, fetch e ask, os esquemas) está no README do rag e na documentação pública do portal, não neste contrato; - os endpoints OAuth usam o formato de erro do OAuth (JSON error/error_description, ou a página HTML do /oauth/authorize), e parâmetro desconhecido neles é ignorado — exceção registrada em rules/errors.md. No /mcp, erro de transporte é RFC 9457 e erro de protocolo é JSON-RPC; - rotas novas, com sessão de pessoa, para o portal mostrar e decidir o pedido de autorização e listar e revogar assistentes conectados; - o rastro da conta ganha as ações assistente_autorizado, assistente_revogado e assistente_invalidado, o autor assistente (a invalidação por reuso de código ou de refresh, em que a descrição é o id da autorização) e os campos opcionais assistente e motivo. É valor novo num enum de saída: o único consumidor do rastro hoje é o painel, que não o lê.
1.9.1 (correção do QA da 0027): o 429 de /oauth/token e de /oauth/register passa a sair no JSON do OAuth ({"error":"temporarily_unavailable", …} com Retry-After), como o resto desses endpoints, e não mais em RFC 9457. Vale também quando o limite atingido é o global por origem. Só os assistentes chamam essas rotas, e eles já leem o JSON do OAuth. GET /v1/autorizacoes deixa de listar a autorização que já não emite token (além dos 180 dias, ou de pessoa removida).
Referência contida (spec 0062, 1.9.2) — só descrição, sem campo novo: com itens, uma referência conhecida e não resolvida que aparece inteira dentro de uma referência que está nos itens, na mesma sentença, não derruba a sentença (13884 dentro de RC-13884, com RC-13884 nos itens). Toda outra ocorrência continua derrubando.
Escrita pelo MCP (spec 0064, 1.10.0) — evolução aditiva; nenhuma rota que existia muda:
- escopo OAuth novo, rag.write: criar, editar, arquivar e desarquivar conhecimento da base comum da conta. Sempre concedido junto de rag.read. Pedido sem escopo continua valendo rag.read; o desafio do 401 do /mcp passa a scope="rag.read rag.write"; - exceção registrada: três saídas que eram enum fechado [rag.read] passam a listas abertas — scopes_supported nos dois documentos de descoberta e o scope da resposta do token. Quem lê essas saídas são os assistentes, e pela RFC 6749 §3.3 o escopo é texto separado por espaço, e pela RFC 8414 §2 e pela RFC 9728 §2 scopes_supported é lista de texto, em que o cliente ignora o escopo que não usa. Nenhum outro enum de saída ganha valor; - a leitura do pedido pelo portal mantém escopo = rag.read (o portal anterior recusa outro valor) e ganha niveis_pedidos, lista aberta dos níveis pedidos (ler, escrever); - a aprovação aceita o corpo opcional AuthorizationApproval com o nível escolhido. Sem corpo, só ler (o portal anterior a 1.10.0 aprova assim). Nível que o pedido não trouxe é 422, e o pedido continua aberto; - TokenRequest.scope no refresh: subconjunto do concedido; além dele é invalid_scope, e o refresh apresentado continua valendo; - Authorization.escopos, lista aberta com os escopos concedidos; - campos opcionais de autoria: KnowledgeVersion.autor (quem gravou a versão, a partir da 1.10.0) e KnowledgeEvent.assistente (o assistente que agiu em nome da pessoa do autor). autor.tipo continua pessoa quando foi o assistente; - as quatro ferramentas de escrita do MCP (create_knowledge, update_knowledge, archive_knowledge, unarchive_knowledge), os esquemas, as anotações e o resultado de escopo insuficiente são do protocolo MCP e estão no README do rag e na documentação pública do portal.
Tipos genéricos (spec 0065, 1.11.0) — evolução aditiva; nenhum campo sai, nenhum fica obrigatório, nenhum valor novo em enum de saída que já existia:
- campo novo forma, ao lado de tipo, com oito formas independentes do modelo de negócio: fato, pergunta_resposta, procedimento, regra, definicao, relacao, aviso e registro. Com forma, o conteúdo vai estruturado em conteudo (os campos dependem da forma, KnowledgeContent). Na entrada vai um dos dois: tipo (com texto, o vocabulário de hoje) ou forma (com conteudo). texto e tipo deixam de ser obrigatórios no esquema; a regra "um dos dois" é a do 422; - os quatro tipos de hoje (equivalencia, apelido, aplicacao, observacao) são legado sem prazo de remoção: aceitos e devolvidos exatamente como antes, byte a byte. A correspondência de família, só documentação e rótulo (não muda registro nem filtro): observacao → fato; apelido → definicao; equivalencia e aplicacao → relacao; - registro gravado com forma sai com tipo: observacao e com texto = o texto de lastro derivado do conteudo (só afirmações; a pergunta de uma pergunta_resposta não entra). Todo leitor, legado ou não, tem sempre um texto legível; - forma na saída é lista aberta (e conteudo na saída é esquema aberto): uma forma futura pode aparecer. Cliente que lê uma forma que não conhece a trata como texto livre e lê texto. Na entrada, forma é enum fechado (valor fora é 422); - metadados transversais, todos opcionais, para toda forma e para o legado: validade (vigente_de, vigente_ate; fora dela o registro não responde, e a leitura traz vigencia), público (publico: interno só responde à pergunta que pede publico: interno), etiquetas (organização e filtro da listagem; não entram na busca), fonte (sai na origem do trecho e das sentenças) e idioma (metadado e filtro da listagem); - filtros novos na listagem: forma, publico, vigencia, etiqueta, idioma; - publico na pergunta; forma e publico no trecho; fonte na origem; - rota nova PUT /v1/conhecimento/{id} (reviseKnowledge): edita por id, com o corpo completo da inserção — antes, esse método nesse caminho era 405.
Resposta composta com itens (spec 0063, 1.11.1) — só descrição, sem campo novo: no formato padrão com itens, a resposta traz a frase do item (preço e quantidade, origem no item) e as sentenças das outras partes da pergunta que o conhecimento sustenta (compatibilidade, aplicação, equivalência), cada uma com a própria origem. No curto, a frase do item vem primeiro e a segunda sentença, se houver, é a do conhecimento. A verificação não muda: compatibilidade só sai citando conhecimento.
1.14.0 (spec 0092): só acréscimos. Rotas novas, atrás de uma variável do ambiente.
1.15.0 (spec 0097): só acréscimos, na rede privada e fora desta documentação. Um segredo com prefixo rag_ops não autentica rota nenhuma de conta: em Authorization: Bearer é 401, sem ir ao banco, como o do chat e o do assistente.
Autenticação
Toda chamada leva a API key do tenant no cabeçalho Authorization: Bearer <key>. Sem chave, ou com chave inválida: 401.
apiKey: http bearer — API key do tenant, guardada só como hash. A do CLI e as geradas pela pessoa usam o mesmo esquema. Revogada, a próxima chamada é 401, o mesmo de uma key que nunca existiu.session: http bearer — Sessão de pessoa. Só vale emAuthorization: Bearer. O cabeçalhoCookieé ignorado: sozinho ou junto de um bearer inválido, não autentica.assistantToken: oauth2 — Access token opaco emitido por esta API ao assistente (prefixorag_mcp_at_), depois do consentimento de uma pessoa da conta. Vale 1 h e só autentica/mcp: em qualquer rota REST é 401. API key e sessão não autenticam/mcp.
Sem API key: GET /v1/health, GET /v1/health/ready, POST /v1/entrar, POST /v1/entrar/link, POST /v1/convites/aceitar, GET /.well-known/oauth-protected-resource/mcp, GET /.well-known/oauth-protected-resource, GET /.well-known/oauth-authorization-server, GET /oauth/authorize, POST /oauth/register, POST /oauth/token, GET /mcp, GET /openapi.yaml, GET /openapi.json, GET /llms.txt, GET /llms-full.txt.
curl "$RAG_URL/v1/conhecimento/<id>" \
-H "Authorization: Bearer $RAG_KEY"
Erros
Todo erro sai como application/problem+json (RFC 9457), com type, title, status e detail; no 422, também errors[]. Id de outro tenant responde 404, igual a um id que não existe.
- ProtectedResourceMetadata — o documento do recurso MCP
- OAuthError — Erro do OAuth, no formato JSON do OAuth (não RFC 9457):
invalid_request,invalid_grant(código ou refresh inválido, usado, vencido ou de autorização revogada; verifier errado),invalid_target,unsupported_grant_type,invalid_client, e no registroinvalid_redirect_urieinvalid_client_metadata. - OAuthRateLimited — Acima do limite de taxa no token ou no registro (o limite próprio da rota, ou o global
por origem), no formato JSON do OAuth (1.9.1). No token, as falhas repetidas de uma
origem levam a este 429 antes de o código ser conferido. Repita depois do
Retry-After. - OAuthErrorPage — Página HTML mínima do rag,
no-store, comContent-Security-Policy: default-src 'none'. Cliente desconhecido,redirect_urique não casa ou documento CIMD recusado — não há para onde redirecionar com segurança. Não ecoa nenhum parâmetro. - 401 AssistantUnauthorized — Sem token, ou com API key, sessão, token inválido, vencido, revogado, de outro recurso, de
pessoa removida ou de conta desativada. O desafio leva
resource_metadataescope="rag.read rag.write"(1.10.0); quando havia token, tambémerror="invalid_token"(RFC 6750 §3).https://abeesys.com/errors/unauthorized - 403 OriginForbidden — requisição ao
/mcpcom cabeçalhoOrigin— proteção contra DNS rebindinghttps://abeesys.com/errors/forbidden - 405 MethodNotAllowed — método não aceito na rota
https://abeesys.com/errors/method-not-allowed - 404 AuthorizationRequestNotFound — pedido inexistente, vencido ou já usado — indistinguíveis de propósito
https://abeesys.com/errors/not-found - 404 AuthorizationNotFound — autorização inexistente, já revogada ou de outra conta — indistinguíveis de propósito
https://abeesys.com/errors/not-found - AuthorizationRedirect — para onde o portal manda o navegador
- 413 PayloadTooLarge — Corpo acima de 64 KiB. Recusado pelo
Content-Lengthantes de o corpo ser lido; semContent-Length, quando a leitura passa do limite. Nada é gravado.https://abeesys.com/errors/payload-too-large - 429 RateLimited — Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.https://abeesys.com/errors/rate-limited - 404 RouteNotFound — rota que não existe neste endereço
https://abeesys.com/errors/not-found - 404 CredentialNotFound — credencial inexistente ou de outro tenant — indistinguíveis de propósito
https://abeesys.com/errors/not-found - 400 BadRequest — requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
https://abeesys.com/errors/bad-request - 401 Rejected — Link, convite ou sessão recusados. Inválido, usado ou vencido são o mesmo detalhe —
a resposta não diz qual. Sessão revogada ou de pessoa removida também.
https://abeesys.com/errors/unauthorized - 403 Forbidden — A autenticação é válida, mas a rota exige sessão de pessoa. A API key recebe este
403, não 401.
https://abeesys.com/errors/forbidden - 404 PersonNotFound — pessoa inexistente ou de outra conta — indistinguíveis de propósito
https://abeesys.com/errors/not-found - 404 APIKeyNotFound — chave inexistente ou de outra conta — indistinguíveis de propósito
https://abeesys.com/errors/not-found - 409 LastPerson — a conta ficaria sem pessoa. Sem
errors[].https://abeesys.com/errors/conflict - 409 APIKeyNameTaken — já existe uma chave não revogada com esse nome nesta conta. Sem
errors[].https://abeesys.com/errors/conflict - 401 Unauthorized — API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).https://abeesys.com/errors/unauthorized - 409 Conflict — A chave de idempotência é de um conhecimento arquivado deste tenant. Nada muda — nem
quando o corpo é idêntico ao que já estava gravado. Desarquivar é
DELETE /v1/conhecimento/{id}/arquivo, não uma reinserção. Única exceção ao "nunca 409" deinsertKnowledge(1.5.0, spec 0039).https://abeesys.com/errors/conflict - 404 NotFound — inexistente ou de outro tenant — indistinguíveis de propósito
https://abeesys.com/errors/not-found - 422 ValidationFailed — 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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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.
https://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window
Conhecimento
GET /v1/conhecimento
Lista o conhecimento do tenant
Exige a API key do tenant.
Paginada, em ordem total e estável: atualizado_em descendente, desempate por id descendente. Duas chamadas seguidas devolvem a mesma sequência, mesmo com vários registros no mesmo instante. A ordenação é contrato.
Sem arquivado, a lista é só do que está na base — arquivado não aparece. Filtros diferentes se combinam (e); valores do mesmo filtro se alternam (ou), por vírgula ou pelo parâmetro repetido. busca é conter o termo normalizado (minúsculas, sem acento). Não usa o vetor de busca nem o vetorizador — o ranking é o da pergunta, não o desta lista.
O total responde aos mesmos filtros da página. Página além do fim vem vazia, com o total certo. Parâmetro desconhecido ou fora do formato é 422 nomeando o campo. Não há parâmetro de tenant: a lista é a da API key. Conhecimento de outro tenant não entra, nem no total.
Escopo (1.7.0, spec 0028). Sem escopo, só a base comum. Com escopo X: a base, menos o que X vetou (inclusive o que X arquivou da base) e o que X sobrepôs, mais o conhecimento de X — inclusive as sobreposições. Conhecimento de outro escopo nunca aparece, nem no total.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
escopo | query | string de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$ | não | Rótulo opaco do escopo dentro do tenant (uma loja, uma unidade) — 1.7.0, spec 0028. Ausente:
a base comum. O rag não interpreta, não normaliza e não cadastra o valor: o mesmo texto
byte a byte é o mesmo escopo. Vazio (?escopo=), repetido, acima de 128 caracteres, com
caractere de controle ou com espaço nas pontas é 422 nomeando escopo, e nada é
gravado. O escopo vem de quem chama: o rag responde para o escopo declarado.
|
pagina | query | integer de 1 a 1000000 · padrão 1 | não | |
limite | query | integer de 1 a 100 · padrão 20 | não | |
tipo | query | lista de KnowledgeKind equivalencia apelido aplicacao observacao máximo 4 itens | não | um ou mais tipos, por vírgula ou repetindo o parâmetro. tipo=observacao traz também os
registros gravados com forma, que saem como observacao (1.11.0)
|
publicacao | query | lista de Publication publicado rascunho máximo 2 itens | não | |
indexacao | query | lista de IndexStatus ok pendente recusado máximo 3 itens | não | |
marca | query | lista de KnowledgeMark negativo sugestao máximo 2 itens | não | |
arquivado | query | lista de boolean máximo 2 itens | não | Ausente: só o que não está arquivado. true: só arquivados. false: o mesmo que
ausente. Os dois valores juntos: arquivados e não arquivados.
|
busca | query | string de 1 a 200 caracteres | não | Filtro por conter o termo, depois de normalizar. Não é a busca da pergunta e não
depende do vetorizador. Para registro com forma, o termo é procurado no texto de
busca dele (que inclui, por exemplo, a pergunta de uma pergunta_resposta) (1.11.0).
|
forma | query | lista de KnowledgeForm fato pergunta_resposta procedimento regra definicao relacao aviso registro máximo 8 itens | não | só registros gravados com forma, com uma das formas pedidas (1.11.0) |
publico | query | lista de Audience interno cliente máximo 2 itens | não | cliente: registros sem publico (o padrão); interno: os marcados como internos (1.11.0)
|
vigencia | query | lista de Vigency futura vigente encerrada máximo 3 itens | não | Pela validade, no relógio do rag no instante da chamada (1.11.0). Só traz registros
com validade: o registro sem vigente_de nem vigente_ate não é vigente nem
nenhum dos outros dois. Sem este filtro, a listagem traz vigentes e não vigentes.
|
etiqueta | query | lista de string de 1 a 160 caracteres máximo 10 itens | não | registros com ao menos uma das etiquetas, normalizada como na gravação (NFC, minúsculas, espaços colapsados, pontas aparadas) (1.11.0) |
idioma | query | lista de string de 1 a 35 caracteres máximo 10 itens | não | registros com um dos idiomas (BCP 47, comparado na caixa canônica) (1.11.0) |
Respostas
- 200 a página
application/jsonKnowledgeList - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
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). A mesma chave de um conhecimento arquivado é 409, e nada muda — nem quando o corpo é idêntico ao que já estava gravado (1.5.0, spec 0039). Fora isso, 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.
Escopo (1.7.0, spec 0028). A identidade é por tenant e escopo: a mesma Idempotency-Key em dois escopos são dois registros, e sem escopo é um terceiro (a base). Reinserir a chave de um registro do escopo X declarando Y não revisa o de X — cria o de Y. Sem escopo, o conhecimento entra na base comum; com escopo, só responde às perguntas daquele escopo. Duas inserções simultâneas com a mesma chave no mesmo escopo resolvem para um registro só.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
Idempotency-Key | header | string de 1 a 255 caracteres · padrão ^[\x21-\x7E]+$ | sim | identidade natural do conhecimento; única por tenant |
escopo | query | string de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$ | não | Rótulo opaco do escopo dentro do tenant (uma loja, uma unidade) — 1.7.0, spec 0028. Ausente:
a base comum. O rag não interpreta, não normaliza e não cadastra o valor: o mesmo texto
byte a byte é o mesmo escopo. Vazio (?escopo=), repetido, acima de 128 caracteres, com
caractere de controle ou com espaço nas pontas é 422 nomeando escopo, e nada é
gravado. O escopo vem de quem chama: o rag responde para o escopo declarado.
|
Corpo application/json
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
texto | string de 1 a 510 caracteres | não | O texto indexável, com tipo (legado). Acima de 510 caracteres é 422. Dentro do limite,
o texto ainda precisa caber na janela de tokens do vetorizador: se não couber, 422
text-exceeds-window nomeando o limite em tokens — nunca vetor truncado. Só espaço, ou
caractere de controle, é 422. Com forma, é 422: o conteúdo vai em conteudo.
|
tipo | KnowledgeKind equivalencia apelido aplicacao observacao | não | |
nivel | Confidence alta media baixa | não | |
publicacao | Publication publicado rascunho | sim | |
marca | KnowledgeMark negativo sugestao | não | |
referencia | string de 1 a 512 caracteres | não | id opaco de outro sistema; devolvido intacto, byte a byte, na origem |
forma | KnowledgeForm fato pergunta_resposta procedimento regra definicao relacao aviso registro | não | |
conteudo | KnowledgeContent | não | |
vigente_de | string formato date-time | não | RFC 3339 com fuso; sem fuso é 422. Gravado e devolvido em UTC. Início incluído. |
vigente_ate | string formato date-time | não | RFC 3339 com fuso. Fim excluído: às 23:59:59 ainda vale; no instante de vigente_ate,
não. Com os dois, vigente_de < vigente_ate, senão 422 em vigente_ate. Gravar um
registro já vencido é permitido: ele fica guardado e não responde.
|
publico | Audience interno cliente | não | Ausente é cliente (o comportamento de antes), e cliente é gravado como ausente. Só
interno volta na leitura. Conhecimento interno só responde à pergunta com
publico: interno.
|
etiquetas | lista de string de 1 a 160 caracteres máximo 10 itens | não | O teto de 160 é do valor cru, antes da normalização. Normalizadas (NFC, minúsculas, espaços colapsados, pontas aparadas); cada uma com 1 a 40 caracteres depois de normalizada. Repetidas depois da normalização viram uma, na ordem da primeira. Lista vazia é o mesmo que ausente. Não entram na busca nem na pergunta. |
fonte | string de 1 a 300 caracteres | não | Rótulo citável ou URL; começando por http:// ou https://, URL absoluta válida. Sai
na origem do trecho e das sentenças; não vai ao motor nem à busca.
|
idioma | string de 1 a 35 caracteres | não | etiqueta BCP 47 bem formada, gravada na caixa canônica (pt-BR); só metadado e filtro |
{
"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/jsonKnowledge - 201 criado
application/jsonKnowledge - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 409 A chave de idempotência é de um conhecimento arquivado deste tenant. Nada muda — nem
quando o corpo é idêntico ao que já estava gravado. Desarquivar é
DELETE /v1/conhecimento/{id}/arquivo, não uma reinserção. Única exceção ao "nunca 409" deinsertKnowledge(1.5.0, spec 0039).application/problem+jsonProblemhttps://abeesys.com/errors/conflict - 413 Corpo acima de 64 KiB. Recusado pelo
Content-Lengthantes de o corpo ser lido; semContent-Length, quando a leitura passa do limite. Nada é gravado.application/problem+jsonProblemhttps://abeesys.com/errors/payload-too-large - 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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
GET /v1/conhecimento/{id}
Lê a versão atual de um conhecimento
Exige a API key do tenant.
Com escopo X, o conhecimento da base e o de X são legíveis; o de outro escopo é o mesmo 404 de inexistente. Sem escopo, só a base: conhecimento de escopo é 404. vetado reflete o veto do tenant ou o do escopo declarado (1.7.0, spec 0028).
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim | |
escopo | query | string de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$ | não | Rótulo opaco do escopo dentro do tenant (uma loja, uma unidade) — 1.7.0, spec 0028. Ausente:
a base comum. O rag não interpreta, não normaliza e não cadastra o valor: o mesmo texto
byte a byte é o mesmo escopo. Vazio (?escopo=), repetido, acima de 128 caracteres, com
caractere de controle ou com espaço nas pontas é 422 nomeando escopo, e nada é
gravado. O escopo vem de quem chama: o rag responde para o escopo declarado.
|
Respostas
- 200 o conhecimento
application/jsonKnowledge - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 404 inexistente ou de outro tenant — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
PUT /v1/conhecimento/{id}
Edita um conhecimento por id (substituição completa)
Exige a API key do tenant.
(1.11.0, spec 0065.) Mesmo corpo da inserção (KnowledgeInput), com as mesmas validações e os mesmos 422. Substituição completa: campo opcional ausente fica ausente na versão nova (a referencia que não vier sai). Efeito: o de reinserir, pela chave daquele registro, o corpo novo — versão nova com o mesmo id, ou 200 com o registro como está quando nada muda depois da normalização. Sempre 200, nunca 201: a rota não cria. A versão anterior fica em /versoes. Vetorizador fora: indexacao: pendente, como na inserção. Trocar de tipo para forma, de uma forma para outra ou de forma para tipo é permitido.
Sem Idempotency-Key: a edição já é idempotente (o mesmo corpo de novo não cria versão), e o cabeçalho, se vier, não muda nada. Sem precondição de versão: duas edições simultâneas viram duas versões, e a última responde.
Alcança publicado ou rascunho, com ou sem marca, vetado ou não. Arquivado é 409, e nada muda. Sem escopo, só registro da base; com escopo X, só registro de X, inclusive a sobreposição de X — com o efeito de PUT /v1/conhecimento/{base}/sobreposicao?escopo=X com o mesmo corpo, menos num caso: a sobreposição desfeita é 409 e não volta (revivê-la é pela rota da sobreposição). Registro da base pedido com escopo, de X pedido sem escopo ou com outro, de outro tenant ou inexistente: o mesmo 404, e nada é gravado.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim | |
escopo | query | string de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$ | não | Rótulo opaco do escopo dentro do tenant (uma loja, uma unidade) — 1.7.0, spec 0028. Ausente:
a base comum. O rag não interpreta, não normaliza e não cadastra o valor: o mesmo texto
byte a byte é o mesmo escopo. Vazio (?escopo=), repetido, acima de 128 caracteres, com
caractere de controle ou com espaço nas pontas é 422 nomeando escopo, e nada é
gravado. O escopo vem de quem chama: o rag responde para o escopo declarado.
|
Corpo application/json
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
texto | string de 1 a 510 caracteres | não | O texto indexável, com tipo (legado). Acima de 510 caracteres é 422. Dentro do limite,
o texto ainda precisa caber na janela de tokens do vetorizador: se não couber, 422
text-exceeds-window nomeando o limite em tokens — nunca vetor truncado. Só espaço, ou
caractere de controle, é 422. Com forma, é 422: o conteúdo vai em conteudo.
|
tipo | KnowledgeKind equivalencia apelido aplicacao observacao | não | |
nivel | Confidence alta media baixa | não | |
publicacao | Publication publicado rascunho | sim | |
marca | KnowledgeMark negativo sugestao | não | |
referencia | string de 1 a 512 caracteres | não | id opaco de outro sistema; devolvido intacto, byte a byte, na origem |
forma | KnowledgeForm fato pergunta_resposta procedimento regra definicao relacao aviso registro | não | |
conteudo | KnowledgeContent | não | |
vigente_de | string formato date-time | não | RFC 3339 com fuso; sem fuso é 422. Gravado e devolvido em UTC. Início incluído. |
vigente_ate | string formato date-time | não | RFC 3339 com fuso. Fim excluído: às 23:59:59 ainda vale; no instante de vigente_ate,
não. Com os dois, vigente_de < vigente_ate, senão 422 em vigente_ate. Gravar um
registro já vencido é permitido: ele fica guardado e não responde.
|
publico | Audience interno cliente | não | Ausente é cliente (o comportamento de antes), e cliente é gravado como ausente. Só
interno volta na leitura. Conhecimento interno só responde à pergunta com
publico: interno.
|
etiquetas | lista de string de 1 a 160 caracteres máximo 10 itens | não | O teto de 160 é do valor cru, antes da normalização. Normalizadas (NFC, minúsculas, espaços colapsados, pontas aparadas); cada uma com 1 a 40 caracteres depois de normalizada. Repetidas depois da normalização viram uma, na ordem da primeira. Lista vazia é o mesmo que ausente. Não entram na busca nem na pergunta. |
fonte | string de 1 a 300 caracteres | não | Rótulo citável ou URL; começando por http:// ou https://, URL absoluta válida. Sai
na origem do trecho e das sentenças; não vai ao motor nem à busca.
|
idioma | string de 1 a 35 caracteres | não | etiqueta BCP 47 bem formada, gravada na caixa canônica (pt-BR); só metadado e filtro |
{
"forma": "pergunta_resposta",
"conteudo": {
"pergunta": "Vocês entregam no sábado?",
"resposta": "Não. As entregas são de segunda a sexta, das 8h às 18h."
},
"publicacao": "publicado"
}Respostas
- 200 versão nova, ou o registro como está quando nada mudou
application/jsonKnowledge - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 404 inexistente ou de outro tenant — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 409 A chave de idempotência é de um conhecimento arquivado deste tenant. Nada muda — nem
quando o corpo é idêntico ao que já estava gravado. Desarquivar é
DELETE /v1/conhecimento/{id}/arquivo, não uma reinserção. Única exceção ao "nunca 409" deinsertKnowledge(1.5.0, spec 0039).application/problem+jsonProblemhttps://abeesys.com/errors/conflict - 413 Corpo acima de 64 KiB. Recusado pelo
Content-Lengthantes de o corpo ser lido; semContent-Length, quando a leitura passa do limite. Nada é gravado.application/problem+jsonProblemhttps://abeesys.com/errors/payload-too-large - 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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
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.
Com escopo X, id de outro escopo é 404; sem escopo, id de escopo é 404 (spec 0028).
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim | |
escopo | query | string de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$ | não | Rótulo opaco do escopo dentro do tenant (uma loja, uma unidade) — 1.7.0, spec 0028. Ausente:
a base comum. O rag não interpreta, não normaliza e não cadastra o valor: o mesmo texto
byte a byte é o mesmo escopo. Vazio (?escopo=), repetido, acima de 128 caracteres, com
caractere de controle ou com espaço nas pontas é 422 nomeando escopo, e nada é
gravado. O escopo vem de quem chama: o rag responde para o escopo declarado.
|
Respostas
- 200 as versões, ordenadas por
versaodecrescenteapplication/jsonKnowledgeVersionList - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 404 inexistente ou de outro tenant — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
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.
A origem de um trecho do escopo já traz ?escopo= no caminho. Com escopo X, id de outro escopo é 404; sem escopo, id de escopo é 404 (spec 0028).
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim | |
versao | path | integer de 1 a 2147483647 | sim | |
escopo | query | string de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$ | não | Rótulo opaco do escopo dentro do tenant (uma loja, uma unidade) — 1.7.0, spec 0028. Ausente:
a base comum. O rag não interpreta, não normaliza e não cadastra o valor: o mesmo texto
byte a byte é o mesmo escopo. Vazio (?escopo=), repetido, acima de 128 caracteres, com
caractere de controle ou com espaço nas pontas é 422 nomeando escopo, e nada é
gravado. O escopo vem de quem chama: o rag responde para o escopo declarado.
|
Respostas
- 200 a versão
application/jsonKnowledgeVersion - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 404 inexistente ou de outro tenant — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
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.
Escopo (1.7.0, spec 0028). Sem escopo, sobre a base: esconde de todos os escopos. Com escopo X, sobre a base: esconde só de X — a base continua para os outros escopos e para a pergunta sem escopo. Com escopo X, sobre conhecimento do próprio X: esconde dele. Conhecimento de outro escopo é 404.
O corpo é opcional (1.7.0): sem corpo, como na 1.6.0; com corpo, motivo registra por que, junto do autor e do instante. Repetir o veto não troca o motivo já registrado.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim | |
escopo | query | string de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$ | não | Rótulo opaco do escopo dentro do tenant (uma loja, uma unidade) — 1.7.0, spec 0028. Ausente:
a base comum. O rag não interpreta, não normaliza e não cadastra o valor: o mesmo texto
byte a byte é o mesmo escopo. Vazio (?escopo=), repetido, acima de 128 caracteres, com
caractere de controle ou com espaço nas pontas é 422 nomeando escopo, e nada é
gravado. O escopo vem de quem chama: o rag responde para o escopo declarado.
|
Corpo application/json
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
motivo | string de 1 a 500 caracteres | não | por que o veto foi posto. Opcional; sem caractere de controle. |
{
"motivo": "a loja não trabalha com essa marca"
}Respostas
- 204 vetado
- 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 404 inexistente ou de outro tenant — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 413 Corpo acima de 64 KiB. Recusado pelo
Content-Lengthantes de o corpo ser lido; semContent-Length, quando a leitura passa do limite. Nada é gravado.application/problem+jsonProblemhttps://abeesys.com/errors/payload-too-large - 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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
DELETE /v1/conhecimento/{id}/veto
Tira o veto — o conhecimento volta sem reinserir
Exige a API key do tenant.
Com escopo X sobre a base, tira o veto de X — inclusive o arquivamento da base feito com X, que é o mesmo estado (spec 0028). Sem escopo, tira o veto do tenant. Idempotente.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim | |
escopo | query | string de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$ | não | Rótulo opaco do escopo dentro do tenant (uma loja, uma unidade) — 1.7.0, spec 0028. Ausente:
a base comum. O rag não interpreta, não normaliza e não cadastra o valor: o mesmo texto
byte a byte é o mesmo escopo. Vazio (?escopo=), repetido, acima de 128 caracteres, com
caractere de controle ou com espaço nas pontas é 422 nomeando escopo, e nada é
gravado. O escopo vem de quem chama: o rag responde para o escopo declarado.
|
Respostas
- 204 sem veto
- 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 404 inexistente ou de outro tenant — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
PUT /v1/conhecimento/{id}/arquivo
Arquiva — tira o conhecimento da base sem apagar
Exige a API key do tenant.
É o que "excluir" significa aqui. O conhecimento sai de toda resposta na hora (trecho, origem, texto, negativo) e da listagem padrão. Continua legível por id e por versão, com arquivado: true. Publicação e indexação ficam como estavam. Nenhuma versão é apagada nem reescrita. O arquivamento entra no rastro, com autor e instante.
Não é veto (o veto esconde e mantém na base) e não é rascunho. Idempotente: arquivar de novo não muda nada. Id de outro tenant é o mesmo 404 de inexistente.
Enquanto estiver arquivado, reinserir a mesma chave é 409 (insertKnowledge).
Escopo (1.7.0, spec 0028). Arquivar com escopo atua só naquele escopo. Com escopo X sobre conhecimento do próprio X: arquiva de verdade, como acima. Com escopo X sobre conhecimento da base: equivale a vetá-lo em X — some para X e continua para os outros escopos e para a pergunta sem escopo; o rastro registra o escopo. Arquivar a base para todos é só sem escopo. Com escopo X sobre conhecimento de outro escopo: 404.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim | |
escopo | query | string de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$ | não | Rótulo opaco do escopo dentro do tenant (uma loja, uma unidade) — 1.7.0, spec 0028. Ausente:
a base comum. O rag não interpreta, não normaliza e não cadastra o valor: o mesmo texto
byte a byte é o mesmo escopo. Vazio (?escopo=), repetido, acima de 128 caracteres, com
caractere de controle ou com espaço nas pontas é 422 nomeando escopo, e nada é
gravado. O escopo vem de quem chama: o rag responde para o escopo declarado.
|
Respostas
- 204 arquivado
- 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 404 inexistente ou de outro tenant — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
DELETE /v1/conhecimento/{id}/arquivo
Desarquiva — o conhecimento volta sem reinserir
Exige a API key do tenant.
Devolve o conhecimento ao estado anterior: publicação e indexação como estavam, sem versão nova. A pergunta volta a trazê-lo. O desarquivamento entra no rastro. Idempotente.
Com escopo X sobre a base, desfaz o arquivamento feito com X (o veto de X); não desarquiva a base arquivada sem escopo (spec 0028).
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim | |
escopo | query | string de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$ | não | Rótulo opaco do escopo dentro do tenant (uma loja, uma unidade) — 1.7.0, spec 0028. Ausente:
a base comum. O rag não interpreta, não normaliza e não cadastra o valor: o mesmo texto
byte a byte é o mesmo escopo. Vazio (?escopo=), repetido, acima de 128 caracteres, com
caractere de controle ou com espaço nas pontas é 422 nomeando escopo, e nada é
gravado. O escopo vem de quem chama: o rag responde para o escopo declarado.
|
Respostas
- 204 na base de novo
- 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 404 inexistente ou de outro tenant — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
GET /v1/conhecimento/{id}/rastro
Rastro de arquivamento e desarquivamento
Exige a API key do tenant.
Do mais antigo ao mais novo. Cada linha tem autor e instante. O autor é key da conta quando a mudança veio da API key, operador (CLI) quando veio do CLI de administração e operador (painel) quando veio da página do operador da plataforma (1.15.0, spec 0097). A descrição é texto fixo — nunca a key nem o hash. Versões de conteúdo não estão aqui: elas continuam em /versoes, intactas.
Com escopo X, o rastro traz as linhas sem escopo e as de X; nunca as de outro escopo. Sem escopo, só as linhas sem escopo (spec 0028).
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim | |
escopo | query | string de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$ | não | Rótulo opaco do escopo dentro do tenant (uma loja, uma unidade) — 1.7.0, spec 0028. Ausente:
a base comum. O rag não interpreta, não normaliza e não cadastra o valor: o mesmo texto
byte a byte é o mesmo escopo. Vazio (?escopo=), repetido, acima de 128 caracteres, com
caractere de controle ou com espaço nas pontas é 422 nomeando escopo, e nada é
gravado. O escopo vem de quem chama: o rag responde para o escopo declarado.
|
Respostas
- 200 o rastro
application/jsonKnowledgeEventList - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 404 inexistente ou de outro tenant — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
GET /v1/conhecimento/{id}/sobreposicao
Lê a sobreposição do escopo para um conhecimento da base
Exige a API key do tenant.
A sobreposição desfeita continua legível, com arquivado: true. O escopo que nunca sobrepôs essa base, ou {id} que não é da base, é 404.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim | |
escopo | query | string de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$ | sim | O escopo dono da sobreposição, com as regras de formato de Scope. Ausente é 422
nomeando escopo: sobreposição sem escopo seria a própria base.
|
Respostas
- 200 a sobreposição
application/jsonKnowledge - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 404 inexistente ou de outro tenant — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
PUT /v1/conhecimento/{id}/sobreposicao
O escopo escreve a versão dele de um conhecimento da base
Exige a API key do tenant.
{id} é um conhecimento da base comum do tenant. A sobreposição é um conhecimento do escopo declarado, ligado à base: na pergunta, na listagem e nos negativos daquele escopo responde a versão dele, e a da base não aparece; nos outros escopos e na pergunta sem escopo, a base continua (1.7.0, spec 0028).
A identidade é (tenant, escopo, base), sem Idempotency-Key. A primeira chamada cria (201). A seguinte, com corpo novo, é revisão da mesma sobreposição — a versão sobe, o id é o mesmo (200); com o corpo idêntico, devolve como está (200). Duas chamadas simultâneas resolvem para uma sobreposição só. Depois de desfeita (DELETE), a chamada seguinte volta a mesma sobreposição, desarquivada e revisada, com o desarquivamento no rastro — não cria outra.
A sobreposição em rascunho também esconde a base no escopo: é o escopo dizendo que a base não vale para ele enquanto revisa a dele. A base pode estar arquivada.
escopo é obrigatório (422 nomeando escopo se ausente). {id} que não é da base do tenant — de um escopo, de outro tenant, ou inexistente — é 404. O vetor é pedido como na inserção: vetorizador fora deixa a sobreposição pendente.
O corpo é o da inserção, com forma, conteudo e os metadados (1.11.0, spec 0065), as mesmas validações e os mesmos 422. A sobreposição pode ter forma diferente da base. Fora da validade, ou interna numa pergunta de cliente, a sobreposição continua escondendo a base no escopo: a vaga fica vazia, e a base não volta.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim | |
escopo | query | string de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$ | sim | O escopo dono da sobreposição, com as regras de formato de Scope. Ausente é 422
nomeando escopo: sobreposição sem escopo seria a própria base.
|
Corpo application/json
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
texto | string de 1 a 510 caracteres | não | O texto indexável, com tipo (legado). Acima de 510 caracteres é 422. Dentro do limite,
o texto ainda precisa caber na janela de tokens do vetorizador: se não couber, 422
text-exceeds-window nomeando o limite em tokens — nunca vetor truncado. Só espaço, ou
caractere de controle, é 422. Com forma, é 422: o conteúdo vai em conteudo.
|
tipo | KnowledgeKind equivalencia apelido aplicacao observacao | não | |
nivel | Confidence alta media baixa | não | |
publicacao | Publication publicado rascunho | sim | |
marca | KnowledgeMark negativo sugestao | não | |
referencia | string de 1 a 512 caracteres | não | id opaco de outro sistema; devolvido intacto, byte a byte, na origem |
forma | KnowledgeForm fato pergunta_resposta procedimento regra definicao relacao aviso registro | não | |
conteudo | KnowledgeContent | não | |
vigente_de | string formato date-time | não | RFC 3339 com fuso; sem fuso é 422. Gravado e devolvido em UTC. Início incluído. |
vigente_ate | string formato date-time | não | RFC 3339 com fuso. Fim excluído: às 23:59:59 ainda vale; no instante de vigente_ate,
não. Com os dois, vigente_de < vigente_ate, senão 422 em vigente_ate. Gravar um
registro já vencido é permitido: ele fica guardado e não responde.
|
publico | Audience interno cliente | não | Ausente é cliente (o comportamento de antes), e cliente é gravado como ausente. Só
interno volta na leitura. Conhecimento interno só responde à pergunta com
publico: interno.
|
etiquetas | lista de string de 1 a 160 caracteres máximo 10 itens | não | O teto de 160 é do valor cru, antes da normalização. Normalizadas (NFC, minúsculas, espaços colapsados, pontas aparadas); cada uma com 1 a 40 caracteres depois de normalizada. Repetidas depois da normalização viram uma, na ordem da primeira. Lista vazia é o mesmo que ausente. Não entram na busca nem na pergunta. |
fonte | string de 1 a 300 caracteres | não | Rótulo citável ou URL; começando por http:// ou https://, URL absoluta válida. Sai
na origem do trecho e das sentenças; não vai ao motor nem à busca.
|
idioma | string de 1 a 35 caracteres | não | etiqueta BCP 47 bem formada, gravada na caixa canônica (pt-BR); só metadado e filtro |
{
"texto": "Nesta loja a remarcação é gratuita até 1 hora antes do horário marcado.",
"tipo": "observacao",
"publicacao": "publicado"
}Respostas
- 200 já existia — revisada (versão nova), devolvida à base do escopo, ou idêntica
application/jsonKnowledge - 201 sobreposição criada
application/jsonKnowledge - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 404 inexistente ou de outro tenant — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 413 Corpo acima de 64 KiB. Recusado pelo
Content-Lengthantes de o corpo ser lido; semContent-Length, quando a leitura passa do limite. Nada é gravado.application/problem+jsonProblemhttps://abeesys.com/errors/payload-too-large - 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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
DELETE /v1/conhecimento/{id}/sobreposicao
Desfaz a sobreposição — a base volta ao escopo
Exige a API key do tenant.
Arquiva a sobreposição, com o arquivamento no rastro dela; a base volta a responder no escopo sem reinserir nada. Idempotente: desfazer de novo é 204. O escopo que nunca sobrepôs essa base é 404.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim | |
escopo | query | string de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$ | sim | O escopo dono da sobreposição, com as regras de formato de Scope. Ausente é 422
nomeando escopo: sobreposição sem escopo seria a própria base.
|
Respostas
- 204 desfeita
- 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 404 inexistente ou de outro tenant — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
Perguntas
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:
trechos— o que sustenta, com a origem de cada um, e o desfecho;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. Para trecho de registro gravado comforma, a cobertura é medida sobre o texto de busca do registro (que inclui, por exemplo, a pergunta de umapergunta_resposta, os sinônimos de umadefinicaoe o sujeito de umregistro), e não sobre otextode lastro que o trecho devolve. Para o registro legado e parafato, os dois são o mesmo texto. O nível não decide o que sai na resposta (1.11.0);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 (specs 0034 e 0044):
- não cita credencial e nenhuma está ligada: o hospedado (gemma) — o padrão;
- não cita credencial e há ligadas: as ligadas e não inválidas, na ordem de preferência; depois o hospedado; depois nenhum;
- cita uma credencial ligada: ela; depois o hospedado; depois nenhum;
- cita uma credencial desligada: direto o hospedado, sem chamar o provedor dela (
motivo: credencial_desligada); - cita uma credencial que não existe: 422.
Mudou em 1.3.0: antes, a pergunta sem credencial saía sempre do hospedado; agora sai das credenciais ligadas, na ordem, e o hospedado é a reserva. Quem não quer isso desliga as credenciais, ou passa a citar uma.
Na pergunta que não cita, qualquer falha de uma credencial (provedor fora ou lento, nome que não resolve, 401/403, 402, 429 esgotado, endereço recusado, credencial ilegível) passa à próxima ligada, e só então ao hospedado; o 429 de uma credencial com outra ligada atrás passa adiante sem esperar. Na pergunta que cita, a falha vai direto ao hospedado — as outras ligadas não são chamadas. Se ninguém escrever, 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: as credenciais dividem a janela que sobra, e a do fim tenta o 429 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.
Cache. Resposta em que alguma credencial falhou nesta pergunta (provedor fora ou lento, nome que não resolve, 401/403, 402, 429 esgotado, endereço recusado, ilegível) não vai ao cache: repetir a pergunta quando o provedor voltar dá a resposta dele, não a do hospedado guardada. Credencial desligada é configuração, e credencial que já estava inválida é pulada sem chamada — as duas não são falha desta resposta, e ela vai ao cache; registrar a credencial de novo, ou ligá-la, muda a identidade da pergunta. A configuração da cadeia (quais estão ligadas, em que ordem, com que segredo) faz parte da identidade da pergunta: ligar, desligar, reordenar, trocar ou remover faz a próxima pergunta não receber uma resposta guardada sob a configuração anterior.
Escopo (1.7.0, spec 0028). Sem escopo, a pergunta recebe só a base comum. Com escopo X: a base, menos o que X vetou ou arquivou e o que X sobrepôs, mais o conhecimento de X. Nenhum trecho, origem, negativo ou texto apoiado em conhecimento de outro escopo; o filtro de escopo é aplicado antes do corte de resultados. Cada origem diz a procedencia. O escopo entra na identidade da pergunta (o cache de X não responde a Y) e na medição de uso.
Itens resolvidos e formato curto (1.8.0, spec 0036). O sistema cliente pode mandar, em itens, o que ele já resolveu — referência, preço e quantidade disponível. Os itens são dado da pergunta: não viram conhecimento, não são indexados, não vão ao log e não aparecem nos trechos. O motor os recebe delimitados como dado, nunca como instrução. Na verificação:
- a sentença pode citar um item; o item sustenta a referência, o preço e a quantidade dele, iguais — nada mais. Item nunca sustenta compatibilidade, aplicação, equivalência, negativa (nem "sem estoque") nem a resposta curta "Sim."/"Não."; - o preço é escrito para o motor como R$ 1.234,56; valor de preço ou de quantidade que o item citado não tem, ou tem diferente, derruba a sentença inteira; - com ao menos um item, a sentença que contém uma referência conhecida do tenant (referência de qualquer conhecimento dele, em qualquer estado) que não esteja entre os itens cai inteira — salvo a ocorrência que fica inteira dentro de uma referência que está nos itens, na mesma sentença (1.9.2, spec 0062) —, e valor em reais só sai citando item; - a sentença sustenta-se por item só se a resposta tem trechos: o desfecho "não encontrado", com ou sem itens, não tem texto, e o motor não é chamado.
Sem itens (ausente ou []), nada muda. O nível de confiança não muda com os itens. formato: curto pede uma ou duas frases ao motor e entrega no máximo duas sentenças verificadas, as primeiras que sobrevivem, na ordem do motor. Itens (na ordem enviada) e formato fazem parte da identidade da pergunta no cache.
No formato padrão com itens, a resposta cobre as partes da pergunta que o conhecimento sustenta, além do preço e da quantidade: a frase do item e, em sentenças próprias, o que os trechos dizem sobre o resto (1.11.1, spec 0063). No curto, a frase do item vem primeiro.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
stream | query | boolean padrão true | não | |
escopo | query | string de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$ | não | Rótulo opaco do escopo dentro do tenant (uma loja, uma unidade) — 1.7.0, spec 0028. Ausente:
a base comum. O rag não interpreta, não normaliza e não cadastra o valor: o mesmo texto
byte a byte é o mesmo escopo. Vazio (?escopo=), repetido, acima de 128 caracteres, com
caractere de controle ou com espaço nas pontas é 422 nomeando escopo, e nada é
gravado. O escopo vem de quem chama: o rag responde para o escopo declarado.
|
Corpo application/json
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
pergunta | string de 1 a 1000 caracteres | sim | |
credencial | CredentialName | não | nome da credencial do tenant que escreve o texto. Ausente: as credenciais ligadas do tenant, na ordem de preferência, e depois o modelo hospedado da plataforma (antes de 1.3.0, ausente era sempre o hospedado). Credencial que o tenant não cadastrou é 422. |
itens | lista de ResolvedItem máximo 50 itens | não | itens que o sistema cliente já resolveu (1.8.0, spec 0036). Dado da pergunta: não vira
conhecimento, não é indexado, não vai ao log. Ausente ou []: a pergunta de antes.
Com ao menos um item, o texto só cita referência conhecida do tenant que esteja entre
os itens (ou contida, inteira, numa referência que está nos itens — 1.9.2), e valor em
reais só sai citando item. A ordem faz parte da identidade da
pergunta: é a numeração ([item n]) que o motor vê.
|
formato | string padrao curto padrão "padrao" | não | curto (1.8.0, spec 0036): o motor é instruído a responder em uma ou duas frases, e a
resposta entrega no máximo duas sentenças verificadas. padrao: como na 1.7.0;
com itens, a resposta cobre também as partes da pergunta sustentadas pelo
conhecimento (1.11.1).
|
publico | Audience interno cliente | não | (1.11.0, spec 0065.) Ausente ou cliente: só conhecimento cliente responde.
interno: responde o interno e o cliente. O padrão é o seguro: conhecimento interno
só entra quando o chamador pede. Quem declara é o sistema cliente, a partir da sessão
dele (o atendente logado pede interno; o chat do site não); o rag não sabe quem está do
outro lado. Valor fora do enum é 422, e o motor não é chamado.
|
{
"pergunta": "posso remarcar o agendamento no mesmo dia?",
"credencial": "principal"
}{
"pergunta": "o kit K-200 atende o plano Avançado? quanto custa?",
"formato": "curto",
"itens": [
{
"referencia": "K-200",
"preco": {
"valor": 4500,
"moeda": "BRL"
},
"quantidade_disponivel": 3
}
]
}Respostas
- 200
text/event-streamcomstream=true;application/jsoncomstream=false. Os dois carregam os mesmos três objetos.text/event-streamstring ·application/jsonAnswer - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 413 Corpo acima de 64 KiB. Recusado pelo
Content-Lengthantes de o corpo ser lido; semContent-Length, quando a leitura passa do limite. Nada é gravado.application/problem+jsonProblemhttps://abeesys.com/errors/payload-too-large - 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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
event: trechos
data: {"desfecho":"encontrado","trechos":[...],"negativos":[],"procurado":{...}}
event: confianca
data: {"nivel":"alta"}
event: texto
data: {"resposta_id":"...","texto":"...","sentencas":[...],"motor":{...},"uso":{...}}Credenciais
GET /v1/credenciais
Lista as credenciais de modelo do tenant, na ordem de preferência
Exige a API key do tenant.
Na ordem em que a pergunta sem credencial as tenta: posicao crescente, e o nome desempata. Mostra se cada uma está ligada, o estado dado pelo provedor e quando foi usada e quando falhou pela última vez. Nunca o segredo, nem parte dele.
Respostas
- 200 as credenciais do tenant
application/jsonCredentialList - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
GET /v1/credenciais/{nome}
Lê uma credencial de modelo do tenant, sem o segredo
Exige a API key do tenant.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
nome | path | CredentialName | sim | nome que o tenant dá à credencial, e que ele cita em cada pergunta |
Respostas
- 200 a credencial
application/jsonCredential - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 404 credencial inexistente ou de outro tenant — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
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).
Credencial nova nasce desligada (spec 0044, a partir de 1.3.0), no fim da ordem — a não ser que o mesmo pedido traga ligada: true e, se quiser, a posicao. Uma chave colada por engano não começa a gastar. Desligada, ela não escreve pergunta nenhuma: a que a cita sai do hospedado com motivo: credencial_desligada. Na troca (o nome já existe), ligada e posicao são aplicados quando vierem e mantidos quando não vierem. posicao p põe a credencial em p e empurra uma casa as que estavam em p ou depois.
O número de credenciais por tenant tem limite (configuração do serviço; 20 por padrão), e o cadastro acima dele é 422 dizendo o limite — inclusive com cadastros simultâneos.
Provedor genérico (generico): qualquer provedor que fale o protocolo de *chat completions*, no endereco_base escolhido pelo tenant, com o segredo como portador. O endereço é tratado como hostil: só https, só a porta 443, sem usuário e senha, sem consulta nem fragmento, sem endereço IP literal, e só nomes que resolvem exclusivamente para endereços públicos de internet — nunca rede privada, loopback, link-local, metadados de nuvem, endereço não especificado, espaço compartilhado de operadora, nem os nomes internos (localhost, *.internal), em qualquer grafia. A conferência é feita aqui e de novo a cada chamada, e a conexão vai só ao endereço conferido naquela chamada. Recusa no cadastro é 422 nomeando a regra; nome que não resolve também. A chamada não segue redirecionamento, não passa por proxy e sempre verifica o certificado.
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 enquanto ligada, e a primeira resposta bem-sucedida dela a devolve a válida. Desligá-la é o jeito de parar de tentar. - 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
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
nome | path | CredentialName | sim | nome que o tenant dá à credencial, e que ele cita em cada pergunta |
Corpo application/json
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
provedor | Provider openai deepseek generico | sim | |
endereco_base | BaseURL | não | obrigatório com generico; com os nomeados é 422 |
modelo | string de 1 a 128 caracteres | sim | |
segredo | string de 1 a 512 caracteres · só de entrada | sim | entra, nunca sai — nenhum schema de resposta o contém |
ligada | boolean | não | credencial nova sem este campo nasce desligada (1.3.0); na troca, ausente mantém como estava |
posicao | integer de 1 a 100 | não | posição na ordem de preferência (1 é a primeira); as que estavam nela ou depois descem uma casa. Credencial nova sem este campo vai para o fim; na troca, ausente mantém. |
{
"provedor": "deepseek",
"modelo": "deepseek-chat",
"segredo": "sk-exemplo-falso",
"ligada": true
}{
"provedor": "generico",
"endereco_base": "https://api.exemplo.com/v1",
"modelo": "modelo-exemplo",
"segredo": "sk-exemplo-falso",
"ligada": true,
"posicao": 1
}Respostas
- 204 guardada
- 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 413 Corpo acima de 64 KiB. Recusado pelo
Content-Lengthantes de o corpo ser lido; semContent-Length, quando a leitura passa do limite. Nada é gravado.application/problem+jsonProblemhttps://abeesys.com/errors/payload-too-large - 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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
DELETE /v1/credenciais/{nome}
Remove uma credencial de modelo do tenant
Exige a API key do tenant.
A credencial some da lista e da cadeia, e o segredo cifrado deixa de existir no rag. Uma pergunta que a cite passa a ser 422 (credencial não cadastrada). O rastro do que aconteceu com ela fica.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
nome | path | CredentialName | sim | nome que o tenant dá à credencial, e que ele cita em cada pergunta |
Respostas
- 204 removida
- 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 404 credencial inexistente ou de outro tenant — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
PUT /v1/credenciais/{nome}/ligada
Liga a credencial
Exige a API key do tenant.
Vale na próxima pergunta, em qualquer instância, sem deploy nem reinício. Ligar a que já está ligada responde 204 sem efeito e sem linha nova no rastro.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
nome | path | CredentialName | sim | nome que o tenant dá à credencial, e que ele cita em cada pergunta |
Respostas
- 204 ligada
- 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 404 credencial inexistente ou de outro tenant — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
DELETE /v1/credenciais/{nome}/ligada
Desliga a credencial
Exige a API key do tenant.
Vale na próxima pergunta, inclusive para a que cita a credencial pelo nome: ela sai do hospedado, sem chamar o provedor, com motivo: credencial_desligada. Desligada não é falha — essa resposta vai ao cache. Desligar a já desligada responde 204 sem efeito e sem linha nova no rastro.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
nome | path | CredentialName | sim | nome que o tenant dá à credencial, e que ele cita em cada pergunta |
Respostas
- 204 desligada
- 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 404 credencial inexistente ou de outro tenant — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
PUT /v1/ordem-das-credenciais
Muda a ordem de preferência das credenciais
Exige a API key do tenant.
As credenciais listadas passam às posições 1, 2, 3…, nesta ordem; as não listadas seguem depois delas, na ordem em que estavam. Nome que o tenant não tem é 404; nome repetido é 422. Mesma ordem que a atual responde 204 sem efeito e sem linha nova no rastro. Duas reordenações simultâneas não se misturam: vale uma delas, inteira.
Corpo application/json
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
credenciais | lista de CredentialName de 1 a 100 itens | sim | os nomes, na ordem nova; cada um uma vez só |
{
"credenciais": [
"principal",
"reserva"
]
}Respostas
- 204 ordenadas
- 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 404 credencial inexistente ou de outro tenant — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 413 Corpo acima de 64 KiB. Recusado pelo
Content-Lengthantes de o corpo ser lido; semContent-Length, quando a leitura passa do limite. Nada é gravado.application/problem+jsonProblemhttps://abeesys.com/errors/payload-too-large - 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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
GET /v1/rastro-das-credenciais
O rastro das mudanças nas credenciais do tenant
Exige a API key do tenant.
Cada cadastro, troca, ligar, desligar, reordenação e remoção, com o autor e o instante, do mais antigo para o mais novo — os 200 mais recentes. Um cadastro ou troca que também liga, desliga ou muda a ordem deixa a linha cadastrada/trocada e, depois dela, a ligada/desligada e a reordenada correspondentes. O rastro nunca guarda o segredo, o endereço base, nem a key ou o hash dela.
Respostas
- 200 as mudanças, em ordem
application/jsonCredentialEventList - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
Pessoas
POST /v1/convites/aceitar
Aceita um convite e cria a pessoa nesta conta
Sem API key.
Convite inválido, usado ou vencido é o mesmo 401, detalhe Recusado.. E-mail que já é de outra conta também: quem convidou não fica sabendo. E-mail que já está nesta conta não cria segunda pessoa — o mesmo 204.
Corpo application/json
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
convite | OpaqueToken | sim |
Respostas
- 204 pessoa criada nesta conta, ou ela já estava nesta conta
- 401 Link, convite ou sessão recusados. Inválido, usado ou vencido são o mesmo detalhe —
a resposta não diz qual. Sessão revogada ou de pessoa removida também.
application/problem+jsonProblemhttps://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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window
POST /v1/convites
Convida um e-mail para a conta
Exige a API key do tenant.
Exige sessão. A resposta 202 é o mesmo Accepted de um convite novo, de um e-mail que já está nesta conta e de um e-mail que está em outra. Quem convida não recebe id de convite. API key nesta rota é 403.
Corpo application/json
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
email | EmailAddress | sim |
Respostas
- 202 aceito. O corpo é o mesmo em todo convite aceito na borda.
application/jsonAccepted - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 403 A autenticação é válida, mas a rota exige sessão de pessoa. A API key recebe este
403, não 401.
application/problem+jsonProblemhttps://abeesys.com/errors/forbidden - 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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
{
"status": "aceito"
}GET /v1/pessoas
Lista as pessoas da conta
Exige a API key do tenant.
Só as ativas, em criada_em ascendente com desempate por id ascendente. O e-mail só aparece aqui e no rastro de convite — as duas exigem sessão. Pessoa de outra conta não entra. API key é 403.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
pagina | query | integer de 1 a 1000000 · padrão 1 | não | |
limite | query | integer de 1 a 100 · padrão 20 | não |
Respostas
- 200 a página
application/jsonPersonList - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 403 A autenticação é válida, mas a rota exige sessão de pessoa. A API key recebe este
403, não 401.
application/problem+jsonProblemhttps://abeesys.com/errors/forbidden - 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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
DELETE /v1/pessoas/{id}
Remove uma pessoa da conta
Exige a API key do tenant.
As sessões dela deixam de valer na próxima chamada. A última pessoa ativa é 409. Id de outra conta ou inexistente é 404, o mesmo.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim |
Respostas
- 204 removida
- 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 403 A autenticação é válida, mas a rota exige sessão de pessoa. A API key recebe este
403, não 401.
application/problem+jsonProblemhttps://abeesys.com/errors/forbidden - 404 pessoa inexistente ou de outra conta — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 409 a conta ficaria sem pessoa. Sem
errors[].application/problem+jsonProblemhttps://abeesys.com/errors/conflict - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
GET /v1/rastro-da-conta
Rastro da conta
Exige a API key do tenant.
Do mais antigo ao mais novo. Ações fechadas: chave_gerada, chave_revogada, credencial_trocada, pessoa_convidada, pessoa_removida e, desde a 1.9.0, assistente_autorizado, assistente_revogado e assistente_invalidado e, desde a 1.13.0, convite_encerrado e convite_rodado (a rotação do convite da primeira pessoa pelo job do operador, spec 0076; autor operador (CLI), ou operador (painel) quando é a página do operador da plataforma (spec 0097), sem o nome de quem pediu, que fica no registro interno). Nunca a chave, o hash, o link, o convite, a sessão, nem o token ou o código do assistente. email em pessoa_convidada, convite_encerrado e convite_rodado. pessoa_id só em pessoa_removida. nome quando a ação é de chave ou de credencial. Ligar, desligar, reordenar, remover e cadastrar credencial não entram aqui — estão em GET /v1/rastro-das-credenciais. Trocar o segredo entra nos dois.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
pagina | query | integer de 1 a 1000000 · padrão 1 | não | |
limite | query | integer de 1 a 100 · padrão 20 | não |
Respostas
- 200 a página
application/jsonAccountEventList - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 403 A autenticação é válida, mas a rota exige sessão de pessoa. A API key recebe este
403, não 401.
application/problem+jsonProblemhttps://abeesys.com/errors/forbidden - 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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
Chaves
GET /v1/chaves
Lista as API keys da conta
Exige a API key do tenant.
Sem o valor. Só chaves não revogadas, em criada_em descendente com desempate por id descendente. final ausente na chave migrada do CLI, que nasceu só como hash. ultimo_uso ausente se nunca autenticou.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
pagina | query | integer de 1 a 1000000 · padrão 1 | não | |
limite | query | integer de 1 a 100 · padrão 20 | não |
Respostas
- 200 a página, sem o valor da chave
application/jsonAPIKeyList - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 403 A autenticação é válida, mas a rota exige sessão de pessoa. A API key recebe este
403, não 401.
application/problem+jsonProblemhttps://abeesys.com/errors/forbidden - 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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
POST /v1/chaves
Gera uma API key da conta
Exige a API key do tenant.
O valor chave aparece só nesta resposta. Nome já usado por chave não revogada desta conta é 409. Exige sessão.
Corpo application/json
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
nome | APIKeyName | sim |
Respostas
- 201 chave gerada. O valor não volta em nenhuma outra resposta.
application/jsonIssuedAPIKey - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 403 A autenticação é válida, mas a rota exige sessão de pessoa. A API key recebe este
403, não 401.
application/problem+jsonProblemhttps://abeesys.com/errors/forbidden - 409 já existe uma chave não revogada com esse nome nesta conta. Sem
errors[].application/problem+jsonProblemhttps://abeesys.com/errors/conflict - 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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
DELETE /v1/chaves/{id}
Revoga uma API key da conta
Exige a API key do tenant.
204 inclusive se já estava revogada e o id é desta conta. Outra conta ou id inexistente é 404. A próxima chamada com a chave revogada é 401, detalhe API key inválida. — o mesmo da chave que nunca existiu.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim |
Respostas
- 204 revogada, ou já estava
- 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 403 A autenticação é válida, mas a rota exige sessão de pessoa. A API key recebe este
403, não 401.
application/problem+jsonProblemhttps://abeesys.com/errors/forbidden - 404 chave inexistente ou de outra conta — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
Sessao
POST /v1/entrar
Pede o link de entrada
Sem API key.
A resposta é 202 com o corpo {"status":"aceito"}, exista o e-mail ou não. E-mail malformado é 422 no campo email, sem ecoar o valor. Rajada — por e-mail e por origem — é 429 rate-limited com Retry-After, igual para e-mail existente e inexistente. O envio não espera o provedor: serviço de e-mail fora, o mesmo 202.
Corpo application/json
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
email | EmailAddress | sim |
Respostas
- 202 aceito. O corpo não diz se o e-mail existe.
application/jsonAccepted - 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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
{
"status": "aceito"
}POST /v1/entrar/link
Abre a sessão com o link de uso único
Sem API key.
O valor da sessão não volta em nenhuma outra resposta. Link inválido, usado ou vencido é o mesmo 401, detalhe Recusado., sem dizer qual dos três.
Corpo application/json
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
link | OpaqueToken | sim |
Respostas
- 200 sessão aberta. O valor da sessão não volta em nenhuma outra resposta.
application/jsonSessionIssued - 401 Link, convite ou sessão recusados. Inválido, usado ou vencido são o mesmo detalhe —
a resposta não diz qual. Sessão revogada ou de pessoa removida também.
application/problem+jsonProblemhttps://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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window
GET /v1/sessao
Diz de quem é a sessão deste bearer
Exige a API key do tenant.
Desde 1.12.0 (spec 0071). Devolve a pessoa e a conta desta sessão, e nada de outra. Os dois valores são identificadores opacos: servem para comparar com uma resposta anterior desta rota, não para buscar nada. Sessão vencida, revogada, de pessoa removida ou de conta inativa é o mesmo 401, detalhe Recusado., sem identidade no corpo. API key é 403. Como toda rota com sessão, empurra o vencimento até o teto e entra no limite global por origem (429). Parâmetro de consulta é 422.
Respostas
- 200 a pessoa e a conta desta sessão
application/jsonSessionOwner - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 403 A autenticação é válida, mas a rota exige sessão de pessoa. A API key recebe este
403, não 401.
application/problem+jsonProblemhttps://abeesys.com/errors/forbidden - 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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
{
"pessoa": "6f1c2a9e-3b0d-4c7e-9a51-0d2e8b7c4f10",
"conta": "0b9e7d2c-1a4f-4e83-b6c5-7f3a2d9e1c08"
}POST /v1/sessao/encerrar
Encerra a sessão deste bearer
Exige a API key do tenant.
A próxima chamada com essa sessão é 401, detalhe Recusado., o mesmo da sessão vencida.
Respostas
- 204 sessão encerrada
- 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 403 A autenticação é válida, mas a rota exige sessão de pessoa. A API key recebe este
403, não 401.
application/problem+jsonProblemhttps://abeesys.com/errors/forbidden
Autorizacoes
GET /v1/pedidos-de-autorizacao/{pedido}
O pedido de autorização, para a tela de consentimento
Exige a API key do tenant.
A única leitura sem tenant: o pedido é da plataforma até ser aprovado. Devolve o nome do assistente, o host e a origem do redirect_uri, o escopo e o nome da conta da sessão. Inexistente, vencido ou já usado é o mesmo 404. Exige sessão; API key é 403.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
pedido | path | string padrão ^rag_mcp_rq_[A-Za-z0-9_-]{43}$ | sim | o id do pedido de autorização, que o rag pôs no endereço da tela de consentimento |
Respostas
- 200 o pedido
application/jsonAuthorizationRequestView - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 403 A autenticação é válida, mas a rota exige sessão de pessoa. A API key recebe este
403, não 401.
application/problem+jsonProblemhttps://abeesys.com/errors/forbidden - 404 pedido inexistente, vencido ou já usado — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
POST /v1/pedidos-de-autorizacao/{pedido}/aprovacao
A pessoa aprova o pedido
Exige a API key do tenant.
Cria a autorização na conta e na pessoa da sessão e um código de 60 s. Devolve para onde mandar o navegador: o redirect_uri com code, state e iss. O pedido não pode ser aprovado de novo (404). Exige sessão; API key é 403 — consentir é ato de pessoa.
Corpo opcional (1.10.0): o nível que a pessoa escolheu. Sem corpo, só ler. Nível que o pedido não trouxe (escrever num pedido só de leitura) é 422 com errors[].field = niveis, sem autorização, e o pedido continua aberto.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
pedido | path | string padrão ^rag_mcp_rq_[A-Za-z0-9_-]{43}$ | sim | o id do pedido de autorização, que o rag pôs no endereço da tela de consentimento |
Corpo application/json
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
niveis | lista de string ler escrever de 1 a 2 itens | não | O nível que a pessoa escolheu. Ausente, ou corpo ausente: só ler (é o que o portal
anterior a 1.10.0 manda). escrever vale ler e escrever. escrever num pedido
que não trouxe escrita é 422, e o pedido continua aberto.
|
Respostas
- 200 para onde o portal manda o navegador
application/jsonAuthorizationRedirectTarget - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 403 A autenticação é válida, mas a rota exige sessão de pessoa. A API key recebe este
403, não 401.
application/problem+jsonProblemhttps://abeesys.com/errors/forbidden - 404 pedido inexistente, vencido ou já usado — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 413 Corpo acima de 64 KiB. Recusado pelo
Content-Lengthantes de o corpo ser lido; semContent-Length, quando a leitura passa do limite. Nada é gravado.application/problem+jsonProblemhttps://abeesys.com/errors/payload-too-large - 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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
POST /v1/pedidos-de-autorizacao/{pedido}/recusa
A pessoa recusa o pedido
Exige a API key do tenant.
Consome o pedido e devolve o redirect_uri com error=access_denied, state e iss.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
pedido | path | string padrão ^rag_mcp_rq_[A-Za-z0-9_-]{43}$ | sim | o id do pedido de autorização, que o rag pôs no endereço da tela de consentimento |
Respostas
- 200 para onde o portal manda o navegador
application/jsonAuthorizationRedirectTarget - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 403 A autenticação é válida, mas a rota exige sessão de pessoa. A API key recebe este
403, não 401.
application/problem+jsonProblemhttps://abeesys.com/errors/forbidden - 404 pedido inexistente, vencido ou já usado — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
GET /v1/autorizacoes
Assistentes conectados à conta
Exige a API key do tenant.
As autorizações ativas (código já trocado, não revogadas, de pessoa não removida e com menos de 180 dias desde o consentimento, que é o teto do refresh — 1.9.1), em autorizada_em descendente com desempate por id descendente. Nunca token, código nem hash.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
pagina | query | integer de 1 a 1000000 · padrão 1 | não | |
limite | query | integer de 1 a 100 · padrão 20 | não |
Respostas
- 200 a página
application/jsonAuthorizationList - 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 403 A autenticação é válida, mas a rota exige sessão de pessoa. A API key recebe este
403, não 401.
application/problem+jsonProblemhttps://abeesys.com/errors/forbidden - 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, limite de
credenciais da conta, endereço base do provedor genérico recusado, 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+jsonProblemhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/embedder-identity-mismatchhttps://abeesys.com/errors/validationhttps://abeesys.com/errors/text-exceeds-window - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
DELETE /v1/autorizacoes/{id}
Revoga a autorização de um assistente
Exige a API key do tenant.
Access e refresh deixam de valer na hora: a próxima chamada ao /mcp é 401 e o refresh é invalid_grant. Já revogada, de outra conta ou inexistente é o mesmo 404.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim |
Respostas
- 204 revogada
- 401 API key ausente, inválida, revogada, ou de tenant desativado — a mesma resposta,
detalhe
API key inválida.. Sessão vencida, revogada ou desconhecida na mesma rota devolve o mesmo status com detalheRecusado.(1.6.0).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 403 A autenticação é válida, mas a rota exige sessão de pessoa. A API key recebe este
403, não 401.
application/problem+jsonProblemhttps://abeesys.com/errors/forbidden - 404 autorização inexistente, já revogada ou de outra conta — indistinguíveis de propósito
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
Mcp
GET /.well-known/oauth-protected-resource/mcp
Metadados do recurso MCP (RFC 9728)
Sem API key.
O recurso canônico é <emissor>/mcp, e o servidor de autorização é o próprio rag. O emissor vem da configuração do serviço, nunca do Host da requisição: a resposta é a mesma por qualquer endereço. Sem MCP configurado no ambiente, 404.
Respostas
- 200 o documento do recurso MCP
application/jsonProtectedResourceMetadata - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 404 rota que não existe neste endereço
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
{
"resource": "https://api.rag.abeesys.com/mcp",
"authorization_servers": [
"https://api.rag.abeesys.com"
],
"scopes_supported": [
"rag.read",
"rag.write"
],
"bearer_methods_supported": [
"header"
]
}GET /.well-known/oauth-protected-resource
Metadados do recurso MCP (RFC 9728), no caminho sem sufixo
Sem API key.
O mesmo documento de /.well-known/oauth-protected-resource/mcp.
Respostas
- 200 o documento do recurso MCP
application/jsonProtectedResourceMetadata - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 404 rota que não existe neste endereço
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
{
"resource": "https://api.rag.abeesys.com/mcp",
"authorization_servers": [
"https://api.rag.abeesys.com"
],
"scopes_supported": [
"rag.read",
"rag.write"
],
"bearer_methods_supported": [
"header"
]
}GET /.well-known/oauth-authorization-server
Metadados do servidor de autorização (RFC 8414)
Sem API key.
O documento inteiro, com os onze campos. Só S256, só cliente público (none), CIMD anunciado, iss na resposta de autorização (RFC 9207) e os escopos rag.read e rag.write (1.10.0). Nenhum escopo OIDC é anunciado.
Respostas
- 200 o documento
application/jsonAuthorizationServerMetadata - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 404 rota que não existe neste endereço
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
{
"issuer": "https://api.rag.abeesys.com",
"authorization_endpoint": "https://api.rag.abeesys.com/oauth/authorize",
"token_endpoint": "https://api.rag.abeesys.com/oauth/token",
"registration_endpoint": "https://api.rag.abeesys.com/oauth/register",
"response_types_supported": [
"code"
],
"grant_types_supported": [
"authorization_code",
"refresh_token"
],
"code_challenge_methods_supported": [
"S256"
],
"token_endpoint_auth_methods_supported": [
"none"
],
"scopes_supported": [
"rag.read",
"rag.write"
],
"client_id_metadata_document_supported": true,
"authorization_response_iss_parameter_supported": true
}GET /oauth/authorize
Início da autorização — aberto pelo navegador, por navegação
Sem API key.
Confere, nesta ordem: o cliente (client_id registrado por DCR, ou a URL de um documento CIMD num host confiável), o redirect_uri (igualdade exata com o declarado; no loopback 127.0.0.1, [::1] e localhost, a porta é livre), response_type, PKCE, escopo, resource e state.
- Pedido válido: 302 para a tela de consentimento do portal (<portal>/autorizar/rag_mcp_rq_…). O pedido vence em 15 min. - Cliente desconhecido, redirect_uri que não casa ou documento CIMD recusado: 400 com uma página HTML mínima, no-store, sem redirecionar e sem ecoar parâmetro. - Outro erro: 302 ao redirect_uri com error, error_description, state e iss.
Parâmetro desconhecido é ignorado (RFC 6749 §3.1). Parâmetro conhecido repetido é invalid_request.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
response_type | query | string code | sim | |
client_id | query | string de 1 a 512 caracteres | sim | |
redirect_uri | query | string formato uri · máximo 512 caracteres | sim | |
code_challenge | query | string de 43 a 128 caracteres | sim | |
code_challenge_method | query | string S256 | sim | só S256; plain é recusado |
scope | query | string máximo 256 caracteres | não | Ausente vale rag.read. rag.read rag.write, ou só rag.write, pede escrita: a pessoa
escolhe na tela entre ler e escrever, ou só ler (1.10.0). offline_access é aceito e
ignorado; outro escopo é invalid_scope.
|
state | query | string máximo 1024 caracteres | não | devolvido sem mudança; até 1 KiB |
resource | query | string formato uri · máximo 512 caracteres | sim | RFC 8707. <emissor>/mcp, <emissor> e <emissor>/ (esquema e host sem caixa) são o
mesmo recurso. Outro valor é invalid_target.
|
Respostas
- 302 ao portal (pedido válido), ou ao
redirect_uricomerror,error_description,stateeiss - 400 Página HTML mínima do rag,
no-store, comContent-Security-Policy: default-src 'none'. Cliente desconhecido,redirect_urique não casa ou documento CIMD recusado — não há para onde redirecionar com segurança. Não ecoa nenhum parâmetro.text/htmlstring - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
<!doctype html><title>Pedido recusado</title><p>Este pedido de autorização não pode continuar.</p>POST /oauth/register
Registro dinâmico restrito (RFC 7591) — cliente público
Sem API key.
Só cliente público (token_endpoint_auth_method ausente ou none), sem segredo. redirect_uris só em host confiável por https, ou loopback por http. Metadado desconhecido é ignorado e não volta na resposta. Corpo acima de 16 KiB é invalid_client_metadata. Limite próprio por origem. Cliente que ninguém autorizar em 24 h é descartado.
Corpo application/json
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
redirect_uris | lista de string formato uri · máximo 512 caracteres de 1 a 10 itens | sim | |
client_name | string máximo 200 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F]*$ | não | |
token_endpoint_auth_method | string none | não |
Respostas
- 201 cliente registrado
application/jsonClientRegistration - 400 Erro do OAuth, no formato JSON do OAuth (não RFC 9457):
invalid_request,invalid_grant(código ou refresh inválido, usado, vencido ou de autorização revogada; verifier errado),invalid_target,unsupported_grant_type,invalid_client, e no registroinvalid_redirect_urieinvalid_client_metadata.application/jsonOAuthError - 413 Corpo acima de 64 KiB. Recusado pelo
Content-Lengthantes de o corpo ser lido; semContent-Length, quando a leitura passa do limite. Nada é gravado.application/problem+jsonProblemhttps://abeesys.com/errors/payload-too-large - 429 Acima do limite de taxa no token ou no registro (o limite próprio da rota, ou o global
por origem), no formato JSON do OAuth (1.9.1). No token, as falhas repetidas de uma
origem levam a este 429 antes de o código ser conferido. Repita depois do
Retry-After.application/jsonOAuthError
{
"error": "invalid_grant",
"error_description": "Código ou refresh inválido."
}{
"error": "temporarily_unavailable",
"error_description": "Limite de requisições atingido. Tente de novo em 3 s."
}POST /oauth/token
Troca o código ou o refresh por access e refresh
Sem API key.
Só application/x-www-form-urlencoded. O código vale uma vez, por 60 s; o segundo uso revoga a autorização. O refresh roda a cada uso; o já usado, apresentado de novo, revoga a autorização inteira. O refresh vence com 30 dias sem uso e, em qualquer caso, 180 dias depois do consentimento. resource ausente vale o recurso da autorização. Parâmetro desconhecido é ignorado; parâmetro conhecido repetido é invalid_request. Falhas repetidas de uma origem levam a 429 antes de o código ser conferido. O escopo do token é o da autorização; no refresh, scope pede um subconjunto, e pedir além do concedido é invalid_scope sem consumir o refresh (1.10.0).
Corpo application/x-www-form-urlencoded
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
grant_type | string authorization_code refresh_token | sim | outro valor é unsupported_grant_type |
client_id | string máximo 512 caracteres | sim | |
code | string máximo 200 caracteres | não | rag_mcp_cd_…, com grant_type=authorization_code |
redirect_uri | string máximo 512 caracteres | não | o mesmo do pedido, com grant_type=authorization_code |
code_verifier | string de 43 a 128 caracteres | não | PKCE (RFC 7636), com grant_type=authorization_code |
refresh_token | string máximo 200 caracteres | não | rag_mcp_rt_…, com grant_type=refresh_token |
resource | string máximo 512 caracteres | não | RFC 8707. Ausente vale o recurso da autorização; outro valor é invalid_target |
scope | string máximo 200 caracteres | não | (1.10.0) No authorization_code, ignorado: o escopo é o da autorização. No
refresh_token, ausente vale o escopo da autorização; um subconjunto dele emite o
access com o subconjunto; além dele é invalid_scope, e o refresh apresentado continua
valendo. offline_access é aceito e ignorado.
|
Respostas
- 200 o par novo
application/jsonTokenResponse - 400 Erro do OAuth, no formato JSON do OAuth (não RFC 9457):
invalid_request,invalid_grant(código ou refresh inválido, usado, vencido ou de autorização revogada; verifier errado),invalid_target,unsupported_grant_type,invalid_client, e no registroinvalid_redirect_urieinvalid_client_metadata.application/jsonOAuthError - 413 Corpo acima de 64 KiB. Recusado pelo
Content-Lengthantes de o corpo ser lido; semContent-Length, quando a leitura passa do limite. Nada é gravado.application/problem+jsonProblemhttps://abeesys.com/errors/payload-too-large - 429 Acima do limite de taxa no token ou no registro (o limite próprio da rota, ou o global
por origem), no formato JSON do OAuth (1.9.1). No token, as falhas repetidas de uma
origem levam a este 429 antes de o código ser conferido. Repita depois do
Retry-After.application/jsonOAuthError
{
"error": "invalid_grant",
"error_description": "Código ou refresh inválido."
}{
"error": "temporarily_unavailable",
"error_description": "Limite de requisições atingido. Tente de novo em 3 s."
}GET /mcp
Sem stream iniciado pelo servidor
Sem API key.
Respostas
- 405 método não aceito na rota
application/problem+jsonProblemhttps://abeesys.com/errors/method-not-allowed
POST /mcp
MCP Streamable HTTP, sem estado, JSON-RPC 2.0
Exige a API key do tenant.
O protocolo (métodos, ferramentas search, fetch e ask e, com rag.write, create_knowledge, update_knowledge, archive_knowledge e unarchive_knowledge — 1.10.0 —, esquemas, anotações e o resultado de escopo insuficiente) está no README do rag e na documentação pública do portal. tools/list filtra pelo escopo do token. Resposta application/json, sem SSE e sem Mcp-Session-Id. Erro de protocolo (JSON ilegível, lote, método desconhecido, parâmetro inválido) é 200 com error do JSON-RPC. Notificação é 202 sem corpo. Só o access token rag_mcp_at_… autentica: API key e sessão são 401. Cabeçalho Origin é 403.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
MCP-Protocol-Version | header | string 2025-03-26 2025-06-18 2025-11-25 | não | ausente vale 2025-03-26; valor fora da lista é 400 |
Corpo application/json
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
jsonrpc | string 2.0 | sim | |
id | string,integer | não | ausente na notificação |
method | string máximo 128 caracteres | sim | |
params | object | não |
Respostas
- 200 resposta JSON-RPC, inclusive a de erro de protocolo
application/jsonJsonRpcResponse - 202 notificação aceita, sem corpo
- 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 401 Sem token, ou com API key, sessão, token inválido, vencido, revogado, de outro recurso, de
pessoa removida ou de conta desativada. O desafio leva
resource_metadataescope="rag.read rag.write"(1.10.0); quando havia token, tambémerror="invalid_token"(RFC 6750 §3).application/problem+jsonProblemhttps://abeesys.com/errors/unauthorized - 403 requisição ao
/mcpcom cabeçalhoOrigin— proteção contra DNS rebindingapplication/problem+jsonProblemhttps://abeesys.com/errors/forbidden - 413 Corpo acima de 64 KiB. Recusado pelo
Content-Lengthantes de o corpo ser lido; semContent-Length, quando a leitura passa do limite. Nada é gravado.application/problem+jsonProblemhttps://abeesys.com/errors/payload-too-large - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
Saúde
GET /v1/health
O processo está de pé
Sem API key.
Respostas
- 200 vivo
application/jsonHealth - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
{
"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.
Só na rede privada. Pelo endereço público responde 404, como rota que não existe: o estado do banco e das dependências não é informação pública (spec 0037).
Respostas
- 200 pronto
application/jsonHealth - 404 rota que não existe neste endereço
application/problem+jsonProblemhttps://abeesys.com/errors/not-found - 503 não pronto — banco fora, extensão ausente ou abaixo de 0.8, índice ausente
application/jsonHealth
{
"status": "ok"
}{
"status": "indisponivel",
"motivo": "extensao-vector-ausente"
}Documentação
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/yamlstring - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
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/jsonobject - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
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/plainstring - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
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/plainstring - 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público
application/problem+jsonProblemhttps://abeesys.com/errors/bad-request - 429 Acima do limite de taxa — da API key, do endereço de origem, ou de tentativas de key
inválida da origem. Neste último caso a key não é conferida: o 429 não diz se ela
existe. Repita depois do
Retry-After.application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
Tipos
EmailAddress
string de 3 a 320 caracteres · padrão ^[^@\s<>]+@[^@\s<>]+\.[^@\s<>]+$
Sem caractere de controle. Na borda o valor é aparado e comparado em minúsculas. E-mail malformado é 422 no campo, sem ecoar o valor.
OpaqueToken
string de 1 a 200 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F]+$
segredo opaco, sem caractere de controle. Presente e recusado é 401, sem dizer se é inválido, usado ou vencido.
APIKeyName
string de 1 a 64 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F]+$
nome da chave, de 1 a 64, sem caractere de controle
Accepted
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
status | string aceito | sim |
SessionOwner
objeto
Desde 1.12.0 (spec 0071). Quem é dono da sessão. Opaco: igual entre duas respostas significa a mesma pessoa na mesma conta, e é só o que garante.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
pessoa | string formato uuid | sim | |
conta | string formato uuid | sim |
SessionIssued
objeto
a sessão, uma vez. Não volta em nenhuma outra resposta.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
sessao | OpaqueToken | sim | |
expira_em | string formato date-time | sim | |
expira_no_maximo_em | string formato date-time | sim |
Person
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string formato uuid | sim | |
email | EmailAddress | sim | |
criada_em | string formato date-time | sim |
PersonList
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
items | lista de Person | sim | |
meta | PageMetaCreatedAsc | sim |
PageMetaCreatedAsc
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
total | integer mínimo 0 | sim | |
ordem | string criada_em_id_asc | sim | |
pagina | integer mínimo 1 | sim | |
limite | integer de 1 a 100 | sim |
IssuedAPIKey
objeto
a chave, uma vez. chave não existe em nenhum outro schema de resposta.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string formato uuid | sim | |
nome | APIKeyName | sim | |
chave | string mínimo 1 caracteres | sim | o valor. Só nesta resposta. |
final | string de 4 a 4 caracteres | sim | |
criada_em | string formato date-time | sim |
APIKey
objeto
uma chave não revogada, sem o valor
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string formato uuid | sim | |
nome | APIKeyName | sim | |
final | string de 4 a 4 caracteres | não | ausente na chave migrada do CLI, que nasceu só como hash |
criada_em | string formato date-time | sim | |
ultimo_uso | string formato date-time | não | ausente se a chave nunca autenticou |
APIKeyList
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
items | lista de APIKey | sim | |
meta | PageMetaCreatedDesc | sim |
PageMetaCreatedDesc
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
total | integer mínimo 0 | sim | |
ordem | string criada_em_id_desc | sim | |
pagina | integer mínimo 1 | sim | |
limite | integer de 1 a 100 | sim |
AccountEvent
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
acao | string chave_gerada chave_revogada credencial_trocada pessoa_convidada pessoa_removida assistente_autorizado assistente_revogado assistente_invalidado convite_encerrado convite_rodado | sim | Desde a 1.13.0 (spec 0076): convite_encerrado (o convite aberto da primeira pessoa,
encerrado pela rotação do job) e convite_rodado (o convite novo da rotação). As duas
têm autor operador (operador (CLI), ou operador (painel) desde a 1.15.0) e trazem email. Quem pediu fica no registro
interno do rag, não nesta resposta.
|
autor | objeto | sim | |
autor.tipo | string chave operador pessoa assistente | sim | pessoa — descrição é o id; chave — key da conta; operador —
operador (CLI) ou operador (painel) (1.15.0); assistente (1.9.0) — descrição é o id da autorização, na
invalidação por reuso de código ou de refresh.
|
autor.descricao | string | sim | |
nome | string | não | quando a ação é de chave ou de credencial |
email | EmailAddress | não | em pessoa_convidada, convite_encerrado e convite_rodado |
pessoa_id | string formato uuid | não | só em pessoa_removida |
assistente | string máximo 200 caracteres | não | o nome do assistente, nas ações assistente_* (1.9.0) |
motivo | string reuso_de_refresh reuso_de_codigo pessoa_removida | não | só em assistente_invalidado (1.9.0) |
em | string formato date-time | sim |
AccountEventList
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
items | lista de AccountEvent | sim | |
meta | objeto | sim | |
meta.total | integer mínimo 0 | sim | |
meta.ordem | string mais_antigo_primeiro | sim | |
meta.pagina | integer mínimo 1 | sim | |
meta.limite | integer de 1 a 100 | sim |
AuthorizationServerMetadata
objeto
RFC 8414 §2. O emissor e os endereços vêm da configuração, nunca do Host.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
issuer | string formato uri | sim | |
authorization_endpoint | string formato uri | sim | |
token_endpoint | string formato uri | sim | |
registration_endpoint | string formato uri | sim | |
response_types_supported | lista de string code | sim | |
grant_types_supported | lista de string authorization_code refresh_token | sim | |
code_challenge_methods_supported | lista de string S256 | sim | |
token_endpoint_auth_methods_supported | lista de string none | sim | |
scopes_supported | lista de string máximo 64 caracteres | sim | Lista aberta (1.10.0). Hoje rag.read e rag.write. O cliente ignora escopo que não
conhece (RFC 8414 §2).
|
client_id_metadata_document_supported | boolean | sim | |
authorization_response_iss_parameter_supported | boolean | sim |
ProtectedResourceMetadata
objeto
RFC 9728.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
resource | string formato uri | sim | o recurso canônico, <emissor>/mcp — o endereço a colar no assistente |
authorization_servers | lista de string formato uri | sim | |
scopes_supported | lista de string máximo 64 caracteres | sim | Lista aberta (1.10.0), como em AuthorizationServerMetadata (RFC 9728 §2). |
bearer_methods_supported | lista de string header | sim |
ClientRegistrationRequest
objeto
RFC 7591. Os campos abaixo são os que o rag usa. Qualquer outro metadado (client_uri, logo_uri, grant_types, response_types, application_type, software_id, scope…) é ignorado e não volta na resposta — exceção registrada em rules/errors.md.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
redirect_uris | lista de string formato uri · máximo 512 caracteres de 1 a 10 itens | sim | |
client_name | string máximo 200 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F]*$ | não | |
token_endpoint_auth_method | string none | não |
ClientRegistration
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
client_id | string | sim | rag_cli_…, público |
client_id_issued_at | integer de 0 a 9999999999 | sim | |
client_name | string máximo 200 caracteres | não | |
redirect_uris | lista de string formato uri | sim | |
token_endpoint_auth_method | string none | sim | |
grant_types | lista de string authorization_code refresh_token | sim | |
response_types | lista de string code | sim |
TokenRequest
objeto
application/x-www-form-urlencoded. Parâmetro desconhecido é ignorado; conhecido e repetido é invalid_request.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
grant_type | string authorization_code refresh_token | sim | outro valor é unsupported_grant_type |
client_id | string máximo 512 caracteres | sim | |
code | string máximo 200 caracteres | não | rag_mcp_cd_…, com grant_type=authorization_code |
redirect_uri | string máximo 512 caracteres | não | o mesmo do pedido, com grant_type=authorization_code |
code_verifier | string de 43 a 128 caracteres | não | PKCE (RFC 7636), com grant_type=authorization_code |
refresh_token | string máximo 200 caracteres | não | rag_mcp_rt_…, com grant_type=refresh_token |
resource | string máximo 512 caracteres | não | RFC 8707. Ausente vale o recurso da autorização; outro valor é invalid_target |
scope | string máximo 200 caracteres | não | (1.10.0) No authorization_code, ignorado: o escopo é o da autorização. No
refresh_token, ausente vale o escopo da autorização; um subconjunto dele emite o
access com o subconjunto; além dele é invalid_scope, e o refresh apresentado continua
valendo. offline_access é aceito e ignorado.
|
TokenResponse
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
access_token | string | sim | rag_mcp_at_…, opaco, 1 h |
token_type | string Bearer | sim | |
expires_in | integer de 1 a 3600 | sim | |
refresh_token | string | sim | rag_mcp_rt_…, opaco, de uso único |
scope | string | sim | Escopos concedidos, separados por espaço (RFC 6749 §3.3). Lista aberta (1.10.0): hoje
rag.read ou rag.read rag.write. Um refresh com subconjunto pedido traz o
subconjunto.
|
OAuthError
objeto
RFC 6749 §5.2 e RFC 7591 §3.2.2 — o formato que os assistentes leem. Não é RFC 9457.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
error | string invalid_request invalid_grant invalid_target invalid_scope invalid_client unsupported_grant_type invalid_redirect_uri invalid_client_metadata temporarily_unavailable | sim | temporarily_unavailable só no 429 (1.9.1). |
error_description | string | não |
JsonRpcRequest
objeto
JSON-RPC 2.0. Métodos: initialize, ping, tools/list, tools/call e notifications/initialized. Lote (array) é recusado com −32600.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
jsonrpc | string 2.0 | sim | |
id | string,integer | não | ausente na notificação |
method | string máximo 128 caracteres | sim | |
params | object | não |
JsonRpcResponse
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
jsonrpc | string 2.0 | sim | |
id | string,integer,null | sim | |
result | object | não | |
error | objeto | não | |
error.code | integer de -32768 a -32000 | sim | −32700 JSON ilegível, −32600 requisição inválida ou lote, −32601 método desconhecido, −32602 argumento inválido |
error.message | string | sim |
AuthorizationRequestView
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
assistente | string máximo 200 caracteres | sim | o nome que o cliente declarou, ou o host do client_id |
host | string | sim | o host do redirect_uri — para onde o navegador vai depois |
origem | string | sim | esquema, host e porta do redirect_uri, sem caminho nem query |
escopo | string rag.read | sim | Continua rag.read também quando o assistente pediu escrita (1.10.0). O que ele pediu
está em niveis_pedidos.
|
niveis_pedidos | lista de string máximo 32 caracteres máximo 8 itens | não | Os níveis que o assistente pediu, em linguagem do painel (1.10.0). Lista aberta: hoje
ler e escrever. Sempre traz ler. Com escrever, a tela oferece "Permitir ler e
escrever", "Permitir só ler" e "Recusar".
|
loopback | boolean | sim | o redirect_uri é 127.0.0.1, [::1] ou localhost |
conta | string | sim | o nome da conta da sessão |
AuthorizationRedirectTarget
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
redirecionar | string formato uri | sim | o redirect_uri do pedido com code (ou error=access_denied), state e iss |
AuthorizationApproval
objeto
Corpo opcional de approveAuthorizationRequest (1.10.0).
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
niveis | lista de string ler escrever de 1 a 2 itens | não | O nível que a pessoa escolheu. Ausente, ou corpo ausente: só ler (é o que o portal
anterior a 1.10.0 manda). escrever vale ler e escrever. escrever num pedido
que não trouxe escrita é 422, e o pedido continua aberto.
|
AssistantRef
objeto
O assistente que agiu em nome de uma pessoa da conta (1.10.0, spec 0064).
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
autorizacao_id | string formato uuid | sim | |
cliente | string | sim | o host do documento CIMD, ou o id do cliente DCR. Nunca token, código, hash nem e-mail. |
Authorization
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string formato uuid | sim | |
assistente | string máximo 200 caracteres | sim | |
host | string | sim | |
pessoa_id | string formato uuid | sim | |
pessoa_email | EmailAddress | não | ausente se a pessoa foi removida |
autorizada_em | string formato date-time | sim | |
usada_em | string formato date-time | não | ausente se o assistente nunca chamou o /mcp |
escopos | lista de string máximo 64 caracteres | não | Escopos concedidos nesta autorização (1.10.0). Lista aberta: hoje rag.read e
rag.write. Autorizações anteriores a 1.10.0 trazem [rag.read].
|
AuthorizationList
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
items | lista de Authorization | sim | |
meta | objeto | sim | |
meta.total | integer mínimo 0 | sim | |
meta.ordem | string autorizada_em_id_desc | sim | |
meta.pagina | integer mínimo 1 | sim | |
meta.limite | integer de 1 a 100 | sim |
KnowledgeKind
string equivalencia apelido aplicacao observacao
tipo do conhecimento — enum fechado; valor fora é 422
Confidence
string alta media baixa
Publication
string publicado rascunho
eixo de publicação — decide se o registro pode sustentar texto
IndexStatus
string ok pendente recusado
Eixo de indexação. ok: tem vetor e entra na busca vetorial. pendente: sem vetor ainda — o vetorizador estava fora; responde só pela busca textual, e o worker tenta de novo. recusado: o vetorizador recusou o texto por não caber na janela de tokens; responde só pela busca textual e não é reprocessado — só um texto novo na mesma chave o devolve à indexação.
recusado entrou na versão 1.1.0 (spec 0029). É valor novo num enum de saída: cliente com switch exaustivo precisa tratá-lo. Nenhum registro estava recusado antes dessa versão.
KnowledgeMark
string negativo sugestao
negativo: o cliente registrou que aquilo não serve — considerado, nunca sustenta frase. sugestao: proposta de algoritmo — segurada em rascunho até a marca ser retirada.
Outcome
string encontrado negativo nao_encontrado
Os três desfechos. encontrado: há conhecimento para afirmar. negativo: só um negativo registrado por pessoa. nao_encontrado: não há registro — nunca é tratado como negativa.
SearchState
string ok indisponivel nao_tentada
ok: a busca rodou. indisponivel: o vetorizador não respondeu, ainda carregava o modelo, respondeu com outra identidade, ou a pergunta não coube na janela de tokens dele — a resposta saiu sem busca vetorial. nao_tentada: base vazia.
EngineSource
string tenant hospedado nenhum
quem escreveu o texto — o modelo do tenant, o hospedado da plataforma, ou nenhum
CredentialName
string de 1 a 64 caracteres · padrão ^[a-z0-9][a-z0-9_-]*$
KnowledgeInput
objeto
Vai tipo (com texto, o vocabulário legado) ou forma (com conteudo) — 1.11.0, spec 0065. Até a 1.10.0, texto e tipo eram obrigatórios; a regra agora é a do 422: tipo e forma juntos → 422 em forma; nenhum dos dois, com texto (o corpo legado sem tipo) → 422 em tipo, com a mensagem de antes; nenhum dos dois, sem texto → 422 em forma; texto com forma → 422 em texto; forma sem conteudo → 422 em conteudo; conteudo sem forma → 422 em forma. Para o texto de busca de um conteudo que não cabe na janela do vetorizador, o 422 text-exceeds-window nomeia conteudo.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
texto | string de 1 a 510 caracteres | não | O texto indexável, com tipo (legado). Acima de 510 caracteres é 422. Dentro do limite,
o texto ainda precisa caber na janela de tokens do vetorizador: se não couber, 422
text-exceeds-window nomeando o limite em tokens — nunca vetor truncado. Só espaço, ou
caractere de controle, é 422. Com forma, é 422: o conteúdo vai em conteudo.
|
tipo | KnowledgeKind equivalencia apelido aplicacao observacao | não | |
nivel | Confidence alta media baixa | não | |
publicacao | Publication publicado rascunho | sim | |
marca | KnowledgeMark negativo sugestao | não | |
referencia | string de 1 a 512 caracteres | não | id opaco de outro sistema; devolvido intacto, byte a byte, na origem |
forma | KnowledgeForm fato pergunta_resposta procedimento regra definicao relacao aviso registro | não | |
conteudo | KnowledgeContent | não | |
vigente_de | string formato date-time | não | RFC 3339 com fuso; sem fuso é 422. Gravado e devolvido em UTC. Início incluído. |
vigente_ate | string formato date-time | não | RFC 3339 com fuso. Fim excluído: às 23:59:59 ainda vale; no instante de vigente_ate,
não. Com os dois, vigente_de < vigente_ate, senão 422 em vigente_ate. Gravar um
registro já vencido é permitido: ele fica guardado e não responde.
|
publico | Audience interno cliente | não | Ausente é cliente (o comportamento de antes), e cliente é gravado como ausente. Só
interno volta na leitura. Conhecimento interno só responde à pergunta com
publico: interno.
|
etiquetas | lista de string de 1 a 160 caracteres máximo 10 itens | não | O teto de 160 é do valor cru, antes da normalização. Normalizadas (NFC, minúsculas, espaços colapsados, pontas aparadas); cada uma com 1 a 40 caracteres depois de normalizada. Repetidas depois da normalização viram uma, na ordem da primeira. Lista vazia é o mesmo que ausente. Não entram na busca nem na pergunta. |
fonte | string de 1 a 300 caracteres | não | Rótulo citável ou URL; começando por http:// ou https://, URL absoluta válida. Sai
na origem do trecho e das sentenças; não vai ao motor nem à busca.
|
idioma | string de 1 a 35 caracteres | não | etiqueta BCP 47 bem formada, gravada na caixa canônica (pt-BR); só metadado e filtro |
KnowledgeForm
string fato pergunta_resposta procedimento regra definicao relacao aviso registro
forma do conhecimento na entrada (1.11.0) — enum fechado; valor fora é 422
KnowledgeFormOut
string
Forma do registro (1.11.0). Lista aberta: hoje os oito valores de KnowledgeForm. Cliente trata valor que não conhece como texto livre e lê texto. Ausente no registro gravado com tipo (legado).
ContentText
objeto
fato e aviso
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
texto | string de 1 a 510 caracteres | sim |
ContentQuestionAnswer
objeto
pergunta_resposta
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
pergunta | string de 1 a 300 caracteres | sim | gancho de busca; nunca sustenta frase e não entra no texto de lastro |
resposta | string de 1 a 510 caracteres | sim |
ContentProcedure
objeto
procedimento
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
objetivo | string de 1 a 300 caracteres | sim | |
passos | lista de string de 1 a 300 caracteres de 2 a 15 itens | sim | a ordem é a da lista |
ContentRule
objeto
regra
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
regra | string de 1 a 510 caracteres | sim | |
excecoes | lista de string de 1 a 300 caracteres máximo 10 itens | não | lista vazia é o mesmo que ausente |
ContentDefinition
objeto
definicao
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
termo | string de 1 a 120 caracteres | sim | |
definicao | string de 1 a 510 caracteres | sim | |
sinonimos | lista de string de 1 a 120 caracteres máximo 20 itens | não | repetido (sem diferença de caixa, acento e espaço) ou igual ao termo é 422 |
ContentRelation
objeto
relacao
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
sujeito | string de 1 a 200 caracteres | sim | |
relacao | string de 1 a 80 caracteres | sim | |
objeto | string de 1 a 200 caracteres | sim | |
nota | string de 1 a 510 caracteres | não |
ContentRecord
objeto
registro
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
sujeito | string de 1 a 200 caracteres | sim | |
atributos | lista de objeto de 1 a 30 itens | sim | nome repetido (sem diferença de caixa, acento e espaço) é 422 |
atributos[].nome | string de 1 a 60 caracteres | sim | |
atributos[].valor | string de 1 a 300 caracteres | sim | |
nota | string de 1 a 510 caracteres | não |
KnowledgeContent
qualquer valor
O conteúdo de um registro com forma (1.11.0). Os campos dependem da forma: fato e aviso → ContentText; pergunta_resposta → ContentQuestionAnswer; procedimento → ContentProcedure; regra → ContentRule; definicao → ContentDefinition; relacao → ContentRelation; registro → ContentRecord. Campo de outra forma é 422 nomeando o campo (conteudo.passos); item de lista inválido nomeia o índice, a partir de 0 (conteudo.passos[2]). Todo texto segue a regra de texto: sem caractere de controle (quebra de linha e tabulação permitidas), ao menos uma letra ou número. Os limites são de caracteres; os de 510 seguem o limite configurado do texto.
KnowledgeContentOut
object
O conteúdo de um registro com forma, como foi gravado depois da normalização (1.11.0). Hoje tem um dos formatos de KnowledgeContent, conforme a forma (fato e aviso → texto; pergunta_resposta → pergunta, resposta; procedimento → objetivo, passos; regra → regra, excecoes; definicao → termo, definicao, sinonimos; relacao → sujeito, relacao, objeto, nota; registro → sujeito, atributos, nota). Esquema aberto, como forma na saída: uma forma futura traz campos que não estão aqui. Para forma que não conhece, o cliente ignora conteudo e lê texto.
Audience
string interno cliente
público do conhecimento (1.11.0); cliente é o padrão
Vigency
string futura vigente encerrada
derivada pelo relógio do rag no instante da leitura; nasce com o campo (1.11.0)
Provenance
string base escopo
De onde vem o conhecimento, derivado — nunca declarado pelo cliente (1.7.0, spec 0028). base: inserido sem escopo, a base comum do tenant. escopo: inserido com escopo, ou sobreposição.
VetoInput
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
motivo | string de 1 a 500 caracteres | não | por que o veto foi posto. Opcional; sem caractere de controle. |
Knowledge
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string formato uuid | sim | |
versao | integer mínimo 1 | sim | |
texto | string | sim | O texto do registro. Com forma (1.11.0), é o texto de lastro derivado do conteudo:
só afirmações — a pergunta de uma pergunta_resposta não entra.
|
tipo | KnowledgeKind equivalencia apelido aplicacao observacao | sim | o registro gravado com forma sai sempre observacao (1.11.0) |
nivel | Confidence alta media baixa | não | |
publicacao | Publication publicado rascunho | sim | |
indexacao | IndexStatus ok pendente recusado | sim | |
marca | KnowledgeMark negativo sugestao | não | |
referencia | string | não | |
vetado | boolean | sim | Veto do tenant, ou — com escopo declarado — o veto daquele escopo (1.7.0).
|
arquivado | boolean | não | Ausente significa false (1.5.0, spec 0039). true: fora da base e das respostas,
ainda legível por id e por versão.
|
procedencia | Provenance base escopo | não | |
escopo | string | não | o escopo em que o conhecimento foi inserido; ausente na base (1.7.0) |
sobrepoe | string formato uuid | não | o id do conhecimento da base que esta sobreposição substitui no escopo (1.7.0) |
criado_em | string formato date-time | sim | |
atualizado_em | string formato date-time | sim | |
forma | KnowledgeFormOut | não | |
conteudo | KnowledgeContentOut | não | |
vigente_de | string formato date-time | não | início da validade, em UTC (1.11.0) |
vigente_ate | string formato date-time | não | fim da validade, excluído, em UTC (1.11.0) |
publico | Audience interno cliente | não | só interno aparece; ausente é cliente (1.11.0) |
etiquetas | lista de string | não | normalizadas (1.11.0) |
fonte | string | não | rótulo citável ou URL (1.11.0) |
idioma | string | não | BCP 47 na caixa canônica (1.11.0) |
vigencia | Vigency futura vigente encerrada | não | presente só com validade, pelo relógio do rag no instante da leitura (1.11.0) |
KnowledgeList
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
items | lista de Knowledge | sim | |
meta | objeto | sim | |
meta.total | integer mínimo 0 | sim | |
meta.ordem | string atualizado_em_id_desc | sim | atualizado_em descendente, desempate por id descendente. Contrato desde a 1.5.0.
|
meta.pagina | integer mínimo 1 | sim | |
meta.limite | integer de 1 a 100 | sim |
KnowledgeEvent
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
acao | string arquivado desarquivado | sim | |
autor | objeto | sim | |
autor.tipo | string chave operador pessoa | sim | chave — a API key da conta; operador — quem opera a plataforma, pelo CLI;
pessoa — uma pessoa da conta (1.6.0, spec 0038). Valor novo num enum de
saída: cliente com switch exaustivo precisa tratar pessoa. A 1.5.0 já
anunciou esse valor.
|
autor.descricao | string | sim | key da conta, operador (CLI), operador (painel), ou — quando tipo é pessoa — o id da
pessoa. Nunca a key, o hash nem o e-mail.
|
escopo | string | não | O escopo em que o arquivamento valeu; ausente quando foi sem escopo (1.7.0, spec 0028). |
assistente | AssistantRef | não | Presente quando um assistente agiu em nome da pessoa de autor (1.10.0, spec 0064).
autor.tipo continua pessoa; nenhum valor novo em enum de saída.
|
em | string formato date-time | sim |
KnowledgeEventList
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
items | lista de KnowledgeEvent | sim | |
meta | objeto | sim | |
meta.total | integer mínimo 0 | sim | |
meta.ordem | string mais_antigo_primeiro | sim |
KnowledgeVersion
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string formato uuid | sim | |
versao | integer mínimo 1 | sim | |
texto | string | sim | |
tipo | KnowledgeKind equivalencia apelido aplicacao observacao | sim | |
nivel | Confidence alta media baixa | não | |
publicacao | Publication publicado rascunho | sim | |
marca | KnowledgeMark negativo sugestao | não | |
referencia | string | não | |
criado_em | string formato date-time | sim | |
autor | objeto | não | Quem gravou esta versão (1.10.0, spec 0064). Ausente nas versões gravadas antes da 1.10.0. |
autor.tipo | string chave operador pessoa | sim | o mesmo autor do rastro (KnowledgeEvent) |
autor.descricao | string | sim | key da conta, operador (CLI), operador (painel) ou o id da pessoa — nunca a key, o hash nem o e-mail |
autor.assistente | AssistantRef | não | |
forma | KnowledgeFormOut | não | |
conteudo | KnowledgeContentOut | não | |
vigente_de | string formato date-time | não | início da validade, em UTC (1.11.0) |
vigente_ate | string formato date-time | não | fim da validade, excluído, em UTC (1.11.0) |
publico | Audience interno cliente | não | só interno aparece; ausente é cliente (1.11.0) |
etiquetas | lista de string | não | normalizadas (1.11.0) |
fonte | string | não | rótulo citável ou URL (1.11.0) |
idioma | string | não | BCP 47 na caixa canônica (1.11.0) |
KnowledgeVersionList
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
items | lista de KnowledgeVersion | sim | |
meta | objeto | sim | |
meta.total | integer mínimo 0 | sim | |
meta.ordem | string versao_desc | sim |
Provider
string openai deepseek generico
provedor do modelo. Nos nomeados o endereço é fixo no serviço (openai: https://api.openai.com/v1; deepseek: https://api.deepseek.com). generico é qualquer provedor compatível com *chat completions*, no endereco_base da credencial. deepseek entrou na versão 1.2.0 (spec 0034) e generico na 1.3.0 (spec 0044).
CredentialState
string valida invalida sem_saldo ilegivel
o estado dado pelo provedor. valida; invalida — o provedor recusou o segredo (401/403), não é tentada até ser registrada de novo; sem_saldo — o provedor disse 402, continua sendo tentada enquanto ligada; ilegivel — o segredo guardado não abre com as chaves do serviço (registre de novo).
BaseURL
string formato uri · de 1 a 512 caracteres
endereço base do provedor genérico; o rag chama <endereco_base>/chat/completions. Só https, só a porta 443, sem usuário e senha, sem consulta nem fragmento, sem IP literal, e o nome tem de resolver só para endereços públicos de internet.
CredentialInput
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
provedor | Provider openai deepseek generico | sim | |
endereco_base | BaseURL | não | obrigatório com generico; com os nomeados é 422 |
modelo | string de 1 a 128 caracteres | sim | |
segredo | string de 1 a 512 caracteres · só de entrada | sim | entra, nunca sai — nenhum schema de resposta o contém |
ligada | boolean | não | credencial nova sem este campo nasce desligada (1.3.0); na troca, ausente mantém como estava |
posicao | integer de 1 a 100 | não | posição na ordem de preferência (1 é a primeira); as que estavam nela ou depois descem uma casa. Credencial nova sem este campo vai para o fim; na troca, ausente mantém. |
Credential
objeto
uma credencial de modelo do tenant — sem o segredo
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
nome | CredentialName | sim | |
provedor | Provider openai deepseek generico | sim | |
modelo | string | sim | |
endereco_base | BaseURL | não | só no provedor genérico |
ligada | boolean | sim | |
posicao | integer mínimo 1 | sim | posição na ordem; empate desempata pelo nome |
estado | CredentialState valida invalida sem_saldo ilegivel | sim | |
ultimo_uso | string formato date-time | não | a última vez que o provedor dela escreveu uma resposta |
ultima_falha | string formato date-time | não | a última vez que ela foi tentada e falhou |
atualizado_em | string formato date-time | sim |
CredentialList
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
items | lista de Credential | sim | |
meta | objeto | sim | |
meta.total | integer mínimo 0 | sim | |
meta.ordem | string posicao_nome | sim |
CredentialOrderInput
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
credenciais | lista de CredentialName de 1 a 100 itens | sim | os nomes, na ordem nova; cada um uma vez só |
CredentialEvent
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
acao | string cadastrada trocada ligada desligada reordenada removida | sim | |
credencial | CredentialName | não | a credencial — ausente em reordenada |
provedor | Provider openai deepseek generico | não | o provedor dela — ausente em reordenada |
ordem | lista de CredentialName | não | só em reordenada — a ordem que ficou |
autor | objeto | sim | |
autor.tipo | string chave operador pessoa | sim | chave — a API key da conta; operador — quem opera a plataforma, pelo CLI de
administração; pessoa — uma pessoa da conta (1.6.0, spec 0038). Valor novo
num enum de saída: cliente com switch exaustivo precisa tratar pessoa.
A 1.5.0 já anunciou esse valor.
|
autor.descricao | string | sim | key da conta, operador (CLI), operador (painel), ou — quando tipo é pessoa — o id da
pessoa. Nunca a key, o hash nem o e-mail.
|
em | string formato date-time | sim |
CredentialEventList
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
items | lista de CredentialEvent | sim | |
meta | objeto | sim | |
meta.total | integer mínimo 0 | sim | |
meta.ordem | string mais_antigo_primeiro | sim |
QuestionInput
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
pergunta | string de 1 a 1000 caracteres | sim | |
credencial | CredentialName | não | nome da credencial do tenant que escreve o texto. Ausente: as credenciais ligadas do tenant, na ordem de preferência, e depois o modelo hospedado da plataforma (antes de 1.3.0, ausente era sempre o hospedado). Credencial que o tenant não cadastrou é 422. |
itens | lista de ResolvedItem máximo 50 itens | não | itens que o sistema cliente já resolveu (1.8.0, spec 0036). Dado da pergunta: não vira
conhecimento, não é indexado, não vai ao log. Ausente ou []: a pergunta de antes.
Com ao menos um item, o texto só cita referência conhecida do tenant que esteja entre
os itens (ou contida, inteira, numa referência que está nos itens — 1.9.2), e valor em
reais só sai citando item. A ordem faz parte da identidade da
pergunta: é a numeração ([item n]) que o motor vê.
|
formato | string padrao curto padrão "padrao" | não | curto (1.8.0, spec 0036): o motor é instruído a responder em uma ou duas frases, e a
resposta entrega no máximo duas sentenças verificadas. padrao: como na 1.7.0;
com itens, a resposta cobre também as partes da pergunta sustentadas pelo
conhecimento (1.11.1).
|
publico | Audience interno cliente | não | (1.11.0, spec 0065.) Ausente ou cliente: só conhecimento cliente responde.
interno: responde o interno e o cliente. O padrão é o seguro: conhecimento interno
só entra quando o chamador pede. Quem declara é o sistema cliente, a partir da sessão
dele (o atendente logado pede interno; o chat do site não); o rag não sabe quem está do
outro lado. Valor fora do enum é 422, e o motor não é chamado.
|
ResolvedItem
objeto
um item que o sistema cliente já resolveu (1.8.0, spec 0036). Campo com null é 422.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
referencia | string de 1 a 512 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\u2028\u2029]+$ | sim | texto opaco do cliente (um código de produto, um SKU), sem quebra de linha (inclusive U+0085, U+2028 e U+2029) nem caractere de controle. Devolvido igual, byte a byte, na origem de item. Duas referências iguais sem caixa (e pelas equivalências de grafia da 0054) na mesma pergunta são 422. |
preco | ItemPrice | não | |
quantidade_disponivel | integer formato int64 · de 0 a 9223372036854776000 | não | quantidade disponível. Ausente é "não informado", não zero; 0 é zero. |
ItemPrice
objeto
preço do item: inteiro na unidade mínima da moeda, com a moeda. Só é mostrado e conferido por igualdade; nenhuma conta é feita com ele. Escrito para o motor como R$ 1.234,56.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
valor | integer formato int64 · de 0 a 9223372036854776000 | sim | centavos; 0 é aceito e mostrado como R$ 0,00 |
moeda | string BRL | sim |
ItemOrigin
objeto
origem de item (1.8.0, spec 0036) — o item que sustenta a sentença
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
referencia | string | sim | a referência do item exatamente como foi enviada |
Origin
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
conhecimento_id | string formato uuid | sim | |
versao | integer mínimo 1 | sim | |
referencia | string | não | a referência opaca exatamente como foi inserida |
procedencia | Provenance base escopo | não | |
caminho | string | sim | caminho que abre o texto inserido — GET nele com a mesma API key. Quando a
procedencia é escopo, o caminho já traz ?escopo= (1.7.0).
|
fonte | string | não | a fonte do conhecimento, para o sistema cliente citar; ausente sem fonte (1.11.0) |
Passage
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
texto | string | sim | |
tipo | KnowledgeKind equivalencia apelido aplicacao observacao | sim | |
nivel | Confidence alta media baixa | não | |
via | string vetorial textual | sim | |
origem | Origin | sim | |
forma | KnowledgeFormOut | não | |
publico | Audience interno cliente | não | interno quando a resposta usou conhecimento interno; ausente no cliente (1.11.0) |
Searched
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
pergunta | string | sim | a pergunta normalizada |
termos | lista de string | sim | |
busca_vetorial | SearchState ok indisponivel nao_tentada | sim | |
busca_textual | SearchState ok indisponivel nao_tentada | sim |
Passages
objeto
ConfidenceEvent
objeto
O nível da cobertura textual da pergunta pelos trechos. Para trecho de registro gravado com forma, a cobertura é medida sobre o texto de busca do registro (que inclui, por exemplo, a pergunta de uma pergunta_resposta, os sinônimos de uma definicao e o sujeito de um registro), e não sobre o texto de lastro que o trecho devolve. Para o registro legado e para fato, os dois são o mesmo texto. O nível não decide o que sai na resposta (1.11.0).
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
nivel | Confidence alta media baixa | sim |
EngineReason
string credencial_invalida credencial_ilegivel provedor_indisponivel credencial_sem_saldo limite_de_taxa credencial_desligada endereco_recusado
por que uma credencial do tenant não escreveu: credencial_invalida — o provedor recusou o segredo (401/403), ou ela já estava inválida; credencial_ilegivel — o segredo guardado não abre com as chaves do serviço; provedor_indisponivel — fora do ar, lento, com erro, nome que não resolve, ou sem tempo na janela da cadeia; credencial_sem_saldo — o provedor disse que a conta está sem saldo (402); limite_de_taxa — o provedor limitou a taxa (429) até acabar o tempo das novas tentativas; credencial_desligada — a pergunta citou uma credencial desligada; o provedor não foi chamado. É configuração, não falha; endereco_recusado — o nome do provedor genérico resolveu, naquela chamada, para um endereço fora da internet pública; a chamada não aconteceu e o estado não muda.
credencial_sem_saldo e limite_de_taxa entraram na versão 1.2.0 (spec 0034); credencial_desligada e endereco_recusado, na 1.3.0 (spec 0044). São valores novos num enum de saída: cliente com switch exaustivo precisa tratá-los. Nenhuma resposta podia sair com eles antes dessas versões, e o rag não tinha consumidor fora da plataforma quando entraram.
EngineAttempt
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
credencial | CredentialName | sim | |
motivo | EngineReason credencial_invalida credencial_ilegivel provedor_indisponivel credencial_sem_saldo limite_de_taxa credencial_desligada endereco_recusado | sim |
Engine
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
respondeu | EngineSource tenant hospedado nenhum | sim | |
modelo | string | não | o modelo que escreveu o texto |
credencial | CredentialName | não | a credencial que escreveu o texto, ou a que a pergunta citou |
credencial_falhou | boolean | sim | alguma credencial do tenant foi tentada e falhou, e nenhuma credencial do tenant escreveu o texto. Credencial desligada não conta como falha. |
motivo | EngineReason credencial_invalida credencial_ilegivel provedor_indisponivel credencial_sem_saldo limite_de_taxa credencial_desligada endereco_recusado | não | na pergunta que cita, por que a credencial citada não escreveu; na que não cita, o motivo da última que falhou, quando nenhuma escreveu |
tentativas | lista de EngineAttempt | sim | cada credencial pulada ou que falhou antes de quem escreveu, na ordem em que a cadeia passou por ela (1.3.0). Vazia quando ninguém foi pulado. |
Usage
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
tokens_entrada | integer formato int64 · mínimo 0 | sim | |
tokens_saida | integer formato int64 · mínimo 0 | sim | |
do_cache | boolean | sim | resposta servida do cache — nenhum modelo foi chamado, zero tokens |
VerifiedSentence
objeto
Toda sentença entregue tem ao menos uma origem. Sem itens na pergunta, origens tem sempre ao menos um elemento e itens não aparece (como na 1.7.0). Com itens na pergunta (1.8.0, spec 0036), origens + itens somam ao menos um: a sentença sustentada só por item tem origens vazio.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
texto | string | sim | |
origens | lista de Origin mínimo 0 itens | sim | as origens de conhecimento, na ordem da citação |
itens | lista de ItemOrigin mínimo 1 itens | não | os itens resolvidos que sustentam a sentença, na ordem da citação (1.8.0, spec 0036). Ausente quando nenhum item a sustenta — e sempre ausente na pergunta sem itens. |
VerifiedText
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
resposta_id | string formato uuid | sim | |
texto | string | sim | as sentenças verificadas |
sentencas | lista de VerifiedSentence | sim | |
motor | Engine | sim | |
uso | Usage | sim |
Answer
objeto
os três tempos, na ordem
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
trechos | Passages | sim | |
confianca | ConfidenceEvent | sim | |
texto | VerifiedText | sim |
Health
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
status | string ok indisponivel | sim | |
motivo | string | não |
FieldError
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
field | string | sim | |
message | string | sim |
Problem
objeto
RFC 9457. Nunca carrega segredo, SQL, corpo de provedor ou stack trace.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
type | string formato uri | sim | |
title | string | sim | |
status | integer | sim | |
detail | string | não | |
errors | lista de FieldError | não |