Pular para o conteúdo
openapi.yaml ↓

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 em Authorization: Bearer. O cabeçalho Cookie é ignorado: sozinho ou junto de um bearer inválido, não autentica.
  • assistantToken: oauth2 — Access token opaco emitido por esta API ao assistente (prefixo rag_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 registro invalid_redirect_uri e invalid_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, com Content-Security-Policy: default-src 'none'. Cliente desconhecido, redirect_uri que 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_metadata e scope="rag.read rag.write" (1.10.0); quando havia token, também error="invalid_token" (RFC 6750 §3). https://abeesys.com/errors/unauthorized
  • 403 OriginForbidden — requisição ao /mcp com cabeçalho Origin — proteção contra DNS rebinding https://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-Length antes de o corpo ser lido; sem Content-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 detalhe Recusado. (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" de insertKnowledge (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/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
escopoquerystring de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$nãoRó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.
paginaqueryinteger de 1 a 1000000 · padrão 1não
limitequeryinteger de 1 a 100 · padrão 20não
tipoquerylista de KnowledgeKind equivalencia apelido aplicacao observacao máximo 4 itensnãoum 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)
publicacaoquerylista de Publication publicado rascunho máximo 2 itensnão
indexacaoquerylista de IndexStatus ok pendente recusado máximo 3 itensnão
marcaquerylista de KnowledgeMark negativo sugestao máximo 2 itensnão
arquivadoquerylista de boolean máximo 2 itensnãoAusente: só o que não está arquivado. true: só arquivados. false: o mesmo que ausente. Os dois valores juntos: arquivados e não arquivados.
buscaquerystring de 1 a 200 caracteresnãoFiltro 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).
formaquerylista de KnowledgeForm fato pergunta_resposta procedimento regra definicao relacao aviso registro máximo 8 itensnãosó registros gravados com forma, com uma das formas pedidas (1.11.0)
publicoquerylista de Audience interno cliente máximo 2 itensnãocliente: registros sem publico (o padrão); interno: os marcados como internos (1.11.0)
vigenciaquerylista de Vigency futura vigente encerrada máximo 3 itensnãoPela 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.
etiquetaquerylista de string de 1 a 160 caracteres máximo 10 itensnãoregistros com ao menos uma das etiquetas, normalizada como na gravação (NFC, minúsculas, espaços colapsados, pontas aparadas) (1.11.0)
idiomaquerylista de string de 1 a 35 caracteres máximo 10 itensnãoregistros com um dos idiomas (BCP 47, comparado na caixa canônica) (1.11.0)

Respostas

  • 200 a página application/json KnowledgeList
  • 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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 422 Entrada que viola o schema ou regra de entrada: enum fora, texto vazio ou acima do limite, campo desconhecido, null onde se pede valor, credencial não cadastrada, 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+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
Idempotency-Keyheaderstring de 1 a 255 caracteres · padrão ^[\x21-\x7E]+$simidentidade natural do conhecimento; única por tenant
escopoquerystring de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$nãoRó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

KnowledgeInput

Campos do corpo
CampoTipoObrigatórioDescrição
textostring de 1 a 510 caracteresnãoO 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.
tipoKnowledgeKind equivalencia apelido aplicacao observacaonão
nivelConfidence alta media baixanão
publicacaoPublication publicado rascunhosim
marcaKnowledgeMark negativo sugestaonão
referenciastring de 1 a 512 caracteresnãoid opaco de outro sistema; devolvido intacto, byte a byte, na origem
formaKnowledgeForm fato pergunta_resposta procedimento regra definicao relacao aviso registronão
conteudoKnowledgeContentnão
vigente_destring formato date-timenãoRFC 3339 com fuso; sem fuso é 422. Gravado e devolvido em UTC. Início incluído.
vigente_atestring formato date-timenãoRFC 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.
publicoAudience interno clientenãoAusente é cliente (o comportamento de antes), e cliente é gravado como ausente. Só interno volta na leitura. Conhecimento interno só responde à pergunta com publico: interno.
etiquetaslista de string de 1 a 160 caracteres máximo 10 itensnãoO 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.
fontestring de 1 a 300 caracteresnãoRó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.
idiomastring de 1 a 35 caracteresnãoetiqueta BCP 47 bem formada, gravada na caixa canônica (pt-BR); só metadado e filtro
Exemplo de corpo
{
  "texto": "A remarcação de um agendamento é gratuita até 2 horas antes do horário marcado.",
  "tipo": "observacao",
  "publicacao": "publicado",
  "referencia": "politica:7d41a0"
}

Respostas

  • 200 já existia — revisado (versão nova) ou idêntico (sem mudança) application/json Knowledge
  • 201 criado application/json Knowledge
  • 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público application/problem+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://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" de insertKnowledge (1.5.0, spec 0039). application/problem+json Problemhttps://abeesys.com/errors/conflict
  • 413 Corpo acima de 64 KiB. Recusado pelo Content-Length antes de o corpo ser lido; sem Content-Length, quando a leitura passa do limite. Nada é gravado. application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
idpathstring formato uuidsim
escopoquerystring de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$nãoRó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/json Knowledge
  • 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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 404 inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found
  • 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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
idpathstring formato uuidsim
escopoquerystring de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$nãoRó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

KnowledgeInput

Campos do corpo
CampoTipoObrigatórioDescrição
textostring de 1 a 510 caracteresnãoO 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.
tipoKnowledgeKind equivalencia apelido aplicacao observacaonão
nivelConfidence alta media baixanão
publicacaoPublication publicado rascunhosim
marcaKnowledgeMark negativo sugestaonão
referenciastring de 1 a 512 caracteresnãoid opaco de outro sistema; devolvido intacto, byte a byte, na origem
formaKnowledgeForm fato pergunta_resposta procedimento regra definicao relacao aviso registronão
conteudoKnowledgeContentnão
vigente_destring formato date-timenãoRFC 3339 com fuso; sem fuso é 422. Gravado e devolvido em UTC. Início incluído.
vigente_atestring formato date-timenãoRFC 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.
publicoAudience interno clientenãoAusente é cliente (o comportamento de antes), e cliente é gravado como ausente. Só interno volta na leitura. Conhecimento interno só responde à pergunta com publico: interno.
etiquetaslista de string de 1 a 160 caracteres máximo 10 itensnãoO 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.
fontestring de 1 a 300 caracteresnãoRó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.
idiomastring de 1 a 35 caracteresnãoetiqueta BCP 47 bem formada, gravada na caixa canônica (pt-BR); só metadado e filtro
Exemplo de corpo
{
  "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/json Knowledge
  • 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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 404 inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found
  • 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" de insertKnowledge (1.5.0, spec 0039). application/problem+json Problemhttps://abeesys.com/errors/conflict
  • 413 Corpo acima de 64 KiB. Recusado pelo Content-Length antes de o corpo ser lido; sem Content-Length, quando a leitura passa do limite. Nada é gravado. application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
idpathstring formato uuidsim
escopoquerystring de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$nãoRó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 versao decrescente application/json KnowledgeVersionList
  • 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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 404 inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found
  • 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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
idpathstring formato uuidsim
versaopathinteger de 1 a 2147483647sim
escopoquerystring de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$nãoRó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/json KnowledgeVersion
  • 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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 404 inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found
  • 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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
idpathstring formato uuidsim
escopoquerystring de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$nãoRó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

VetoInput

Campos do corpo
CampoTipoObrigatórioDescrição
motivostring de 1 a 500 caracteresnãopor que o veto foi posto. Opcional; sem caractere de controle.
Exemplo de corpo
{
  "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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 404 inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found
  • 413 Corpo acima de 64 KiB. Recusado pelo Content-Length antes de o corpo ser lido; sem Content-Length, quando a leitura passa do limite. Nada é gravado. application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
idpathstring formato uuidsim
escopoquerystring de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$nãoRó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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 404 inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found
  • 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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
idpathstring formato uuidsim
escopoquerystring de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$nãoRó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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 404 inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found
  • 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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
idpathstring formato uuidsim
escopoquerystring de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$nãoRó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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 404 inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found
  • 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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
idpathstring formato uuidsim
escopoquerystring de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$nãoRó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/json KnowledgeEventList
  • 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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 404 inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found
  • 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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
idpathstring formato uuidsim
escopoquerystring de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$simO 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/json Knowledge
  • 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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 404 inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found
  • 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+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
idpathstring formato uuidsim
escopoquerystring de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$simO 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

KnowledgeInput

Campos do corpo
CampoTipoObrigatórioDescrição
textostring de 1 a 510 caracteresnãoO 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.
tipoKnowledgeKind equivalencia apelido aplicacao observacaonão
nivelConfidence alta media baixanão
publicacaoPublication publicado rascunhosim
marcaKnowledgeMark negativo sugestaonão
referenciastring de 1 a 512 caracteresnãoid opaco de outro sistema; devolvido intacto, byte a byte, na origem
formaKnowledgeForm fato pergunta_resposta procedimento regra definicao relacao aviso registronão
conteudoKnowledgeContentnão
vigente_destring formato date-timenãoRFC 3339 com fuso; sem fuso é 422. Gravado e devolvido em UTC. Início incluído.
vigente_atestring formato date-timenãoRFC 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.
publicoAudience interno clientenãoAusente é cliente (o comportamento de antes), e cliente é gravado como ausente. Só interno volta na leitura. Conhecimento interno só responde à pergunta com publico: interno.
etiquetaslista de string de 1 a 160 caracteres máximo 10 itensnãoO 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.
fontestring de 1 a 300 caracteresnãoRó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.
idiomastring de 1 a 35 caracteresnãoetiqueta BCP 47 bem formada, gravada na caixa canônica (pt-BR); só metadado e filtro
Exemplo de corpo
{
  "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/json Knowledge
  • 201 sobreposição criada application/json Knowledge
  • 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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 404 inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found
  • 413 Corpo acima de 64 KiB. Recusado pelo Content-Length antes de o corpo ser lido; sem Content-Length, quando a leitura passa do limite. Nada é gravado. application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
idpathstring formato uuidsim
escopoquerystring de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$simO 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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 404 inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found
  • 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+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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+json Problemhttps://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:

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

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

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

Quem escreve o texto (specs 0034 e 0044):

  1. não cita credencial e nenhuma está ligada: o hospedado (gemma) — o padrão;
  2. não cita credencial e há ligadas: as ligadas e não inválidas, na ordem de preferência; depois o hospedado; depois nenhum;
  3. cita uma credencial ligada: ela; depois o hospedado; depois nenhum;
  4. cita uma credencial desligada: direto o hospedado, sem chamar o provedor dela (motivo: credencial_desligada);
  5. 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

Parâmetros
NomeOndeTipoObrigatórioDescrição
streamqueryboolean padrão truenão
escopoquerystring de 1 a 128 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\s]([^\x00-\x1F\x7F-\x9F]*[^\x00-\x1F\x7F-\x9F\s])?$nãoRó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

QuestionInput

Campos do corpo
CampoTipoObrigatórioDescrição
perguntastring de 1 a 1000 caracteressim
credencialCredentialNamenãonome 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.
itenslista de ResolvedItem máximo 50 itensnãoitens 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ê.
formatostring padrao curto padrão "padrao"nãocurto (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).
publicoAudience interno clientenã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.
Exemplo de corpo
{
  "pergunta": "posso remarcar o agendamento no mesmo dia?",
  "credencial": "principal"
}
Exemplo de corpo
{
  "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-stream com stream=true; application/json com stream=false. Os dois carregam os mesmos três objetos. text/event-stream string · application/json Answer
  • 400 requisição ilegível — corpo que não é JSON, parâmetro malformado, ou requisição sem TLS pelo endereço público application/problem+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 413 Corpo acima de 64 KiB. Recusado pelo Content-Length antes de o corpo ser lido; sem Content-Length, quando a leitura passa do limite. Nada é gravado. application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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+json Problemhttps://abeesys.com/errors/rate-limited
Resposta 200 · text/event-stream
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/json CredentialList
  • 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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
nomepathCredentialNamesimnome que o tenant dá à credencial, e que ele cita em cada pergunta

Respostas

  • 200 a credencial application/json Credential
  • 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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 404 credencial inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
nomepathCredentialNamesimnome que o tenant dá à credencial, e que ele cita em cada pergunta

Corpo application/json

CredentialInput

Campos do corpo
CampoTipoObrigatórioDescrição
provedorProvider openai deepseek genericosim
endereco_baseBaseURLnãoobrigatório com generico; com os nomeados é 422
modelostring de 1 a 128 caracteressim
segredostring de 1 a 512 caracteres · só de entradasimentra, nunca sai — nenhum schema de resposta o contém
ligadabooleannãocredencial nova sem este campo nasce desligada (1.3.0); na troca, ausente mantém como estava
posicaointeger de 1 a 100nãoposiçã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.
Exemplo de corpo
{
  "provedor": "deepseek",
  "modelo": "deepseek-chat",
  "segredo": "sk-exemplo-falso",
  "ligada": true
}
Exemplo de corpo
{
  "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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 413 Corpo acima de 64 KiB. Recusado pelo Content-Length antes de o corpo ser lido; sem Content-Length, quando a leitura passa do limite. Nada é gravado. application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
nomepathCredentialNamesimnome 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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 404 credencial inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
nomepathCredentialNamesimnome 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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 404 credencial inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
nomepathCredentialNamesimnome 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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 404 credencial inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://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+json Problemhttps://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

CredentialOrderInput

Campos do corpo
CampoTipoObrigatórioDescrição
credenciaislista de CredentialName de 1 a 100 itenssimos nomes, na ordem nova; cada um uma vez só
Exemplo de corpo
{
  "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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 404 credencial inexistente ou de outro tenant — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found
  • 413 Corpo acima de 64 KiB. Recusado pelo Content-Length antes de o corpo ser lido; sem Content-Length, quando a leitura passa do limite. Nada é gravado. application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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+json Problemhttps://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/json CredentialEventList
  • 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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://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+json Problemhttps://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

Campos do corpo
CampoTipoObrigatórioDescrição
conviteOpaqueTokensim

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+json Problemhttps://abeesys.com/errors/unauthorized
  • 422 Entrada que viola o schema ou regra de entrada: enum fora, texto vazio ou acima do limite, campo desconhecido, null onde se pede valor, credencial não cadastrada, 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+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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

Campos do corpo
CampoTipoObrigatórioDescrição
emailEmailAddresssim

Respostas

  • 202 aceito. O corpo é o mesmo em todo convite aceito na borda. application/json Accepted
  • 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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://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+json Problemhttps://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+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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+json Problemhttps://abeesys.com/errors/rate-limited
Resposta 202 · application/json
{
  "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

Parâmetros
NomeOndeTipoObrigatórioDescrição
paginaqueryinteger de 1 a 1000000 · padrão 1não
limitequeryinteger de 1 a 100 · padrão 20não

Respostas

  • 200 a página application/json PersonList
  • 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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://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+json Problemhttps://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+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
idpathstring formato uuidsim

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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/forbidden
  • 404 pessoa inexistente ou de outra conta — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found
  • 409 a conta ficaria sem pessoa. Sem errors[]. application/problem+json Problemhttps://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
paginaqueryinteger de 1 a 1000000 · padrão 1não
limitequeryinteger de 1 a 100 · padrão 20não

Respostas

  • 200 a página application/json AccountEventList
  • 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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://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+json Problemhttps://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+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
paginaqueryinteger de 1 a 1000000 · padrão 1não
limitequeryinteger de 1 a 100 · padrão 20não

Respostas

  • 200 a página, sem o valor da chave application/json APIKeyList
  • 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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://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+json Problemhttps://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+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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+json Problemhttps://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

Campos do corpo
CampoTipoObrigatórioDescrição
nomeAPIKeyNamesim

Respostas

  • 201 chave gerada. O valor não volta em nenhuma outra resposta. application/json IssuedAPIKey
  • 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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/forbidden
  • 409 já existe uma chave não revogada com esse nome nesta conta. Sem errors[]. application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
idpathstring formato uuidsim

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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/forbidden
  • 404 chave inexistente ou de outra conta — indistinguíveis de propósito application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/rate-limited

Sessao

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/json SessionOwner
  • 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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://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+json Problemhttps://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+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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+json Problemhttps://abeesys.com/errors/rate-limited
Resposta 200 · application/json
{
  "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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
pedidopathstring padrão ^rag_mcp_rq_[A-Za-z0-9_-]{43}$simo id do pedido de autorização, que o rag pôs no endereço da tela de consentimento

Respostas

  • 200 o pedido application/json AuthorizationRequestView
  • 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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/forbidden
  • 404 pedido inexistente, vencido ou já usado — indistinguíveis de propósito application/problem+json Problemhttps://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
pedidopathstring padrão ^rag_mcp_rq_[A-Za-z0-9_-]{43}$simo id do pedido de autorização, que o rag pôs no endereço da tela de consentimento

Corpo application/json

AuthorizationApproval

Campos do corpo
CampoTipoObrigatórioDescrição
niveislista de string ler escrever de 1 a 2 itensnãoO 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/json AuthorizationRedirectTarget
  • 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+json Problemhttps://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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/forbidden
  • 404 pedido inexistente, vencido ou já usado — indistinguíveis de propósito application/problem+json Problemhttps://abeesys.com/errors/not-found
  • 413 Corpo acima de 64 KiB. Recusado pelo Content-Length antes de o corpo ser lido; sem Content-Length, quando a leitura passa do limite. Nada é gravado. application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
pedidopathstring padrão ^rag_mcp_rq_[A-Za-z0-9_-]{43}$simo 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/json AuthorizationRedirectTarget
  • 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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/forbidden
  • 404 pedido inexistente, vencido ou já usado — indistinguíveis de propósito application/problem+json Problemhttps://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
paginaqueryinteger de 1 a 1000000 · padrão 1não
limitequeryinteger de 1 a 100 · padrão 20não

Respostas

  • 200 a página application/json AuthorizationList
  • 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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://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+json Problemhttps://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+json Problemhttps://abeesys.com/errors/validation https://abeesys.com/errors/embedder-identity-mismatch https://abeesys.com/errors/validation https://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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
idpathstring formato uuidsim

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 detalhe Recusado. (1.6.0). application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/forbidden
  • 404 autorização inexistente, já revogada ou de outra conta — indistinguíveis de propósito application/problem+json Problemhttps://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+json Problemhttps://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/json ProtectedResourceMetadata
  • 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+json Problemhttps://abeesys.com/errors/bad-request
  • 404 rota que não existe neste endereço application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/rate-limited
Resposta 200 · application/json
{
  "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/json ProtectedResourceMetadata
  • 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+json Problemhttps://abeesys.com/errors/bad-request
  • 404 rota que não existe neste endereço application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/rate-limited
Resposta 200 · application/json
{
  "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/json AuthorizationServerMetadata
  • 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+json Problemhttps://abeesys.com/errors/bad-request
  • 404 rota que não existe neste endereço application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/rate-limited
Resposta 200 · application/json
{
  "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

Parâmetros
NomeOndeTipoObrigatórioDescrição
response_typequerystring codesim
client_idquerystring de 1 a 512 caracteressim
redirect_uriquerystring formato uri · máximo 512 caracteressim
code_challengequerystring de 43 a 128 caracteressim
code_challenge_methodquerystring S256simsó S256; plain é recusado
scopequerystring máximo 256 caracteresnãoAusente 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.
statequerystring máximo 1024 caracteresnãodevolvido sem mudança; até 1 KiB
resourcequerystring formato uri · máximo 512 caracteressimRFC 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_uri com error, error_description, state e iss
  • 400 Página HTML mínima do rag, no-store, com Content-Security-Policy: default-src 'none'. Cliente desconhecido, redirect_uri que não casa ou documento CIMD recusado — não há para onde redirecionar com segurança. Não ecoa nenhum parâmetro. text/html string
  • 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+json Problemhttps://abeesys.com/errors/rate-limited
Resposta 400 · text/html
<!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

ClientRegistrationRequest

Campos do corpo
CampoTipoObrigatórioDescrição
redirect_urislista de string formato uri · máximo 512 caracteres de 1 a 10 itenssim
client_namestring máximo 200 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F]*$não
token_endpoint_auth_methodstring nonenão

Respostas

  • 201 cliente registrado application/json ClientRegistration
  • 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 registro invalid_redirect_uri e invalid_client_metadata. application/json OAuthError
  • 413 Corpo acima de 64 KiB. Recusado pelo Content-Length antes de o corpo ser lido; sem Content-Length, quando a leitura passa do limite. Nada é gravado. application/problem+json Problemhttps://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/json OAuthError
Resposta 400 · application/json
{
  "error": "invalid_grant",
  "error_description": "Código ou refresh inválido."
}
Resposta 429 · application/json
{
  "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

TokenRequest

Campos do corpo
CampoTipoObrigatórioDescrição
grant_typestring authorization_code refresh_tokensimoutro valor é unsupported_grant_type
client_idstring máximo 512 caracteressim
codestring máximo 200 caracteresnãorag_mcp_cd_…, com grant_type=authorization_code
redirect_uristring máximo 512 caracteresnãoo mesmo do pedido, com grant_type=authorization_code
code_verifierstring de 43 a 128 caracteresnãoPKCE (RFC 7636), com grant_type=authorization_code
refresh_tokenstring máximo 200 caracteresnãorag_mcp_rt_…, com grant_type=refresh_token
resourcestring máximo 512 caracteresnãoRFC 8707. Ausente vale o recurso da autorização; outro valor é invalid_target
scopestring máximo 200 caracteresnã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/json TokenResponse
  • 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 registro invalid_redirect_uri e invalid_client_metadata. application/json OAuthError
  • 413 Corpo acima de 64 KiB. Recusado pelo Content-Length antes de o corpo ser lido; sem Content-Length, quando a leitura passa do limite. Nada é gravado. application/problem+json Problemhttps://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/json OAuthError
Resposta 400 · application/json
{
  "error": "invalid_grant",
  "error_description": "Código ou refresh inválido."
}
Resposta 429 · application/json
{
  "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+json Problemhttps://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

Parâmetros
NomeOndeTipoObrigatórioDescrição
MCP-Protocol-Versionheaderstring 2025-03-26 2025-06-18 2025-11-25nãoausente vale 2025-03-26; valor fora da lista é 400

Corpo application/json

JsonRpcRequest

Campos do corpo
CampoTipoObrigatórioDescrição
jsonrpcstring 2.0sim
idstring,integernãoausente na notificação
methodstring máximo 128 caracteressim
paramsobjectnão

Respostas

  • 200 resposta JSON-RPC, inclusive a de erro de protocolo application/json JsonRpcResponse
  • 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+json Problemhttps://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_metadata e scope="rag.read rag.write" (1.10.0); quando havia token, também error="invalid_token" (RFC 6750 §3). application/problem+json Problemhttps://abeesys.com/errors/unauthorized
  • 403 requisição ao /mcp com cabeçalho Origin — proteção contra DNS rebinding application/problem+json Problemhttps://abeesys.com/errors/forbidden
  • 413 Corpo acima de 64 KiB. Recusado pelo Content-Length antes de o corpo ser lido; sem Content-Length, quando a leitura passa do limite. Nada é gravado. application/problem+json Problemhttps://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+json Problemhttps://abeesys.com/errors/rate-limited

Saúde

GET /v1/health

O processo está de pé

Sem API key.

Respostas

  • 200 vivo application/json Health
  • 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+json Problemhttps://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+json Problemhttps://abeesys.com/errors/rate-limited
Resposta 200 · application/json
{
  "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/json Health
  • 404 rota que não existe neste endereço application/problem+json Problemhttps://abeesys.com/errors/not-found
  • 503 não pronto — banco fora, extensão ausente ou abaixo de 0.8, índice ausente application/json Health
Resposta 200 · application/json
{
  "status": "ok"
}
Resposta 503 · application/json
{
  "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/yaml string
  • 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+json Problemhttps://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+json Problemhttps://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/json object
  • 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+json Problemhttps://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+json Problemhttps://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/plain string
  • 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+json Problemhttps://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+json Problemhttps://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/plain string
  • 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+json Problemhttps://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+json Problemhttps://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

Campos de Accepted
CampoTipoObrigatórioDescrição
statusstring aceitosim

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.

Campos de SessionOwner
CampoTipoObrigatórioDescrição
pessoastring formato uuidsim
contastring formato uuidsim

SessionIssued

objeto

a sessão, uma vez. Não volta em nenhuma outra resposta.

Campos de SessionIssued
CampoTipoObrigatórioDescrição
sessaoOpaqueTokensim
expira_emstring formato date-timesim
expira_no_maximo_emstring formato date-timesim

Person

objeto

Campos de Person
CampoTipoObrigatórioDescrição
idstring formato uuidsim
emailEmailAddresssim
criada_emstring formato date-timesim

PersonList

objeto

Campos de PersonList
CampoTipoObrigatórioDescrição
itemslista de Personsim
metaPageMetaCreatedAscsim

PageMetaCreatedAsc

objeto

Campos de PageMetaCreatedAsc
CampoTipoObrigatórioDescrição
totalinteger mínimo 0sim
ordemstring criada_em_id_ascsim
paginainteger mínimo 1sim
limiteinteger de 1 a 100sim

IssuedAPIKey

objeto

a chave, uma vez. chave não existe em nenhum outro schema de resposta.

Campos de IssuedAPIKey
CampoTipoObrigatórioDescrição
idstring formato uuidsim
nomeAPIKeyNamesim
chavestring mínimo 1 caracteressimo valor. Só nesta resposta.
finalstring de 4 a 4 caracteressim
criada_emstring formato date-timesim

APIKey

objeto

uma chave não revogada, sem o valor

Campos de APIKey
CampoTipoObrigatórioDescrição
idstring formato uuidsim
nomeAPIKeyNamesim
finalstring de 4 a 4 caracteresnãoausente na chave migrada do CLI, que nasceu só como hash
criada_emstring formato date-timesim
ultimo_usostring formato date-timenãoausente se a chave nunca autenticou

APIKeyList

objeto

Campos de APIKeyList
CampoTipoObrigatórioDescrição
itemslista de APIKeysim
metaPageMetaCreatedDescsim

PageMetaCreatedDesc

objeto

Campos de PageMetaCreatedDesc
CampoTipoObrigatórioDescrição
totalinteger mínimo 0sim
ordemstring criada_em_id_descsim
paginainteger mínimo 1sim
limiteinteger de 1 a 100sim

AccountEvent

objeto

Campos de AccountEvent
CampoTipoObrigatórioDescrição
acaostring chave_gerada chave_revogada credencial_trocada pessoa_convidada pessoa_removida assistente_autorizado assistente_revogado assistente_invalidado convite_encerrado convite_rodadosimDesde 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.
autorobjetosim
autor.tipostring chave operador pessoa assistentesimpessoa — 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.descricaostringsim
nomestringnãoquando a ação é de chave ou de credencial
emailEmailAddressnãoem pessoa_convidada, convite_encerrado e convite_rodado
pessoa_idstring formato uuidnãosó em pessoa_removida
assistentestring máximo 200 caracteresnãoo nome do assistente, nas ações assistente_* (1.9.0)
motivostring reuso_de_refresh reuso_de_codigo pessoa_removidanãosó em assistente_invalidado (1.9.0)
emstring formato date-timesim

AccountEventList

objeto

Campos de AccountEventList
CampoTipoObrigatórioDescrição
itemslista de AccountEventsim
metaobjetosim
meta.totalinteger mínimo 0sim
meta.ordemstring mais_antigo_primeirosim
meta.paginainteger mínimo 1sim
meta.limiteinteger de 1 a 100sim

AuthorizationServerMetadata

objeto

RFC 8414 §2. O emissor e os endereços vêm da configuração, nunca do Host.

Campos de AuthorizationServerMetadata
CampoTipoObrigatórioDescrição
issuerstring formato urisim
authorization_endpointstring formato urisim
token_endpointstring formato urisim
registration_endpointstring formato urisim
response_types_supportedlista de string codesim
grant_types_supportedlista de string authorization_code refresh_tokensim
code_challenge_methods_supportedlista de string S256sim
token_endpoint_auth_methods_supportedlista de string nonesim
scopes_supportedlista de string máximo 64 caracteressimLista 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_supportedbooleansim
authorization_response_iss_parameter_supportedbooleansim

ProtectedResourceMetadata

objeto

RFC 9728.

Campos de ProtectedResourceMetadata
CampoTipoObrigatórioDescrição
resourcestring formato urisimo recurso canônico, <emissor>/mcp — o endereço a colar no assistente
authorization_serverslista de string formato urisim
scopes_supportedlista de string máximo 64 caracteressimLista aberta (1.10.0), como em AuthorizationServerMetadata (RFC 9728 §2).
bearer_methods_supportedlista de string headersim

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.

Campos de ClientRegistrationRequest
CampoTipoObrigatórioDescrição
redirect_urislista de string formato uri · máximo 512 caracteres de 1 a 10 itenssim
client_namestring máximo 200 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F]*$não
token_endpoint_auth_methodstring nonenão

ClientRegistration

objeto

Campos de ClientRegistration
CampoTipoObrigatórioDescrição
client_idstringsimrag_cli_…, público
client_id_issued_atinteger de 0 a 9999999999sim
client_namestring máximo 200 caracteresnão
redirect_urislista de string formato urisim
token_endpoint_auth_methodstring nonesim
grant_typeslista de string authorization_code refresh_tokensim
response_typeslista de string codesim

TokenRequest

objeto

application/x-www-form-urlencoded. Parâmetro desconhecido é ignorado; conhecido e repetido é invalid_request.

Campos de TokenRequest
CampoTipoObrigatórioDescrição
grant_typestring authorization_code refresh_tokensimoutro valor é unsupported_grant_type
client_idstring máximo 512 caracteressim
codestring máximo 200 caracteresnãorag_mcp_cd_…, com grant_type=authorization_code
redirect_uristring máximo 512 caracteresnãoo mesmo do pedido, com grant_type=authorization_code
code_verifierstring de 43 a 128 caracteresnãoPKCE (RFC 7636), com grant_type=authorization_code
refresh_tokenstring máximo 200 caracteresnãorag_mcp_rt_…, com grant_type=refresh_token
resourcestring máximo 512 caracteresnãoRFC 8707. Ausente vale o recurso da autorização; outro valor é invalid_target
scopestring máximo 200 caracteresnã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

Campos de TokenResponse
CampoTipoObrigatórioDescrição
access_tokenstringsimrag_mcp_at_…, opaco, 1 h
token_typestring Bearersim
expires_ininteger de 1 a 3600sim
refresh_tokenstringsimrag_mcp_rt_…, opaco, de uso único
scopestringsimEscopos 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.

Campos de OAuthError
CampoTipoObrigatórioDescrição
errorstring invalid_request invalid_grant invalid_target invalid_scope invalid_client unsupported_grant_type invalid_redirect_uri invalid_client_metadata temporarily_unavailablesimtemporarily_unavailable só no 429 (1.9.1).
error_descriptionstringnão

JsonRpcRequest

objeto

JSON-RPC 2.0. Métodos: initialize, ping, tools/list, tools/call e notifications/initialized. Lote (array) é recusado com −32600.

Campos de JsonRpcRequest
CampoTipoObrigatórioDescrição
jsonrpcstring 2.0sim
idstring,integernãoausente na notificação
methodstring máximo 128 caracteressim
paramsobjectnão

JsonRpcResponse

objeto

Campos de JsonRpcResponse
CampoTipoObrigatórioDescrição
jsonrpcstring 2.0sim
idstring,integer,nullsim
resultobjectnão
errorobjetonão
error.codeinteger de -32768 a -32000sim−32700 JSON ilegível, −32600 requisição inválida ou lote, −32601 método desconhecido, −32602 argumento inválido
error.messagestringsim

AuthorizationRequestView

objeto

Campos de AuthorizationRequestView
CampoTipoObrigatórioDescrição
assistentestring máximo 200 caracteressimo nome que o cliente declarou, ou o host do client_id
hoststringsimo host do redirect_uri — para onde o navegador vai depois
origemstringsimesquema, host e porta do redirect_uri, sem caminho nem query
escopostring rag.readsimContinua rag.read também quando o assistente pediu escrita (1.10.0). O que ele pediu está em niveis_pedidos.
niveis_pedidoslista de string máximo 32 caracteres máximo 8 itensnãoOs 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".
loopbackbooleansimo redirect_uri é 127.0.0.1, [::1] ou localhost
contastringsimo nome da conta da sessão

AuthorizationRedirectTarget

objeto

Campos de AuthorizationRedirectTarget
CampoTipoObrigatórioDescrição
redirecionarstring formato urisimo redirect_uri do pedido com code (ou error=access_denied), state e iss

AuthorizationApproval

objeto

Corpo opcional de approveAuthorizationRequest (1.10.0).

Campos de AuthorizationApproval
CampoTipoObrigatórioDescrição
niveislista de string ler escrever de 1 a 2 itensnãoO 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).

Campos de AssistantRef
CampoTipoObrigatórioDescrição
autorizacao_idstring formato uuidsim
clientestringsimo host do documento CIMD, ou o id do cliente DCR. Nunca token, código, hash nem e-mail.

Authorization

objeto

Campos de Authorization
CampoTipoObrigatórioDescrição
idstring formato uuidsim
assistentestring máximo 200 caracteressim
hoststringsim
pessoa_idstring formato uuidsim
pessoa_emailEmailAddressnãoausente se a pessoa foi removida
autorizada_emstring formato date-timesim
usada_emstring formato date-timenãoausente se o assistente nunca chamou o /mcp
escoposlista de string máximo 64 caracteresnãoEscopos 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

Campos de AuthorizationList
CampoTipoObrigatórioDescrição
itemslista de Authorizationsim
metaobjetosim
meta.totalinteger mínimo 0sim
meta.ordemstring autorizada_em_id_descsim
meta.paginainteger mínimo 1sim
meta.limiteinteger de 1 a 100sim

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.

Campos de KnowledgeInput
CampoTipoObrigatórioDescrição
textostring de 1 a 510 caracteresnãoO 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.
tipoKnowledgeKind equivalencia apelido aplicacao observacaonão
nivelConfidence alta media baixanão
publicacaoPublication publicado rascunhosim
marcaKnowledgeMark negativo sugestaonão
referenciastring de 1 a 512 caracteresnãoid opaco de outro sistema; devolvido intacto, byte a byte, na origem
formaKnowledgeForm fato pergunta_resposta procedimento regra definicao relacao aviso registronão
conteudoKnowledgeContentnão
vigente_destring formato date-timenãoRFC 3339 com fuso; sem fuso é 422. Gravado e devolvido em UTC. Início incluído.
vigente_atestring formato date-timenãoRFC 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.
publicoAudience interno clientenãoAusente é cliente (o comportamento de antes), e cliente é gravado como ausente. Só interno volta na leitura. Conhecimento interno só responde à pergunta com publico: interno.
etiquetaslista de string de 1 a 160 caracteres máximo 10 itensnãoO 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.
fontestring de 1 a 300 caracteresnãoRó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.
idiomastring de 1 a 35 caracteresnãoetiqueta 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

Campos de ContentText
CampoTipoObrigatórioDescrição
textostring de 1 a 510 caracteressim

ContentQuestionAnswer

objeto

pergunta_resposta

Campos de ContentQuestionAnswer
CampoTipoObrigatórioDescrição
perguntastring de 1 a 300 caracteressimgancho de busca; nunca sustenta frase e não entra no texto de lastro
respostastring de 1 a 510 caracteressim

ContentProcedure

objeto

procedimento

Campos de ContentProcedure
CampoTipoObrigatórioDescrição
objetivostring de 1 a 300 caracteressim
passoslista de string de 1 a 300 caracteres de 2 a 15 itenssima ordem é a da lista

ContentRule

objeto

regra

Campos de ContentRule
CampoTipoObrigatórioDescrição
regrastring de 1 a 510 caracteressim
excecoeslista de string de 1 a 300 caracteres máximo 10 itensnãolista vazia é o mesmo que ausente

ContentDefinition

objeto

definicao

Campos de ContentDefinition
CampoTipoObrigatórioDescrição
termostring de 1 a 120 caracteressim
definicaostring de 1 a 510 caracteressim
sinonimoslista de string de 1 a 120 caracteres máximo 20 itensnãorepetido (sem diferença de caixa, acento e espaço) ou igual ao termo é 422

ContentRelation

objeto

relacao

Campos de ContentRelation
CampoTipoObrigatórioDescrição
sujeitostring de 1 a 200 caracteressim
relacaostring de 1 a 80 caracteressim
objetostring de 1 a 200 caracteressim
notastring de 1 a 510 caracteresnão

ContentRecord

objeto

registro

Campos de ContentRecord
CampoTipoObrigatórioDescrição
sujeitostring de 1 a 200 caracteressim
atributoslista de objeto de 1 a 30 itenssimnome repetido (sem diferença de caixa, acento e espaço) é 422
atributos[].nomestring de 1 a 60 caracteressim
atributos[].valorstring de 1 a 300 caracteressim
notastring de 1 a 510 caracteresnã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

Campos de VetoInput
CampoTipoObrigatórioDescrição
motivostring de 1 a 500 caracteresnãopor que o veto foi posto. Opcional; sem caractere de controle.

Knowledge

objeto

Campos de Knowledge
CampoTipoObrigatórioDescrição
idstring formato uuidsim
versaointeger mínimo 1sim
textostringsimO 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.
tipoKnowledgeKind equivalencia apelido aplicacao observacaosimo registro gravado com forma sai sempre observacao (1.11.0)
nivelConfidence alta media baixanão
publicacaoPublication publicado rascunhosim
indexacaoIndexStatus ok pendente recusadosim
marcaKnowledgeMark negativo sugestaonão
referenciastringnão
vetadobooleansimVeto do tenant, ou — com escopo declarado — o veto daquele escopo (1.7.0).
arquivadobooleannãoAusente significa false (1.5.0, spec 0039). true: fora da base e das respostas, ainda legível por id e por versão.
procedenciaProvenance base escoponão
escopostringnãoo escopo em que o conhecimento foi inserido; ausente na base (1.7.0)
sobrepoestring formato uuidnãoo id do conhecimento da base que esta sobreposição substitui no escopo (1.7.0)
criado_emstring formato date-timesim
atualizado_emstring formato date-timesim
formaKnowledgeFormOutnão
conteudoKnowledgeContentOutnão
vigente_destring formato date-timenãoinício da validade, em UTC (1.11.0)
vigente_atestring formato date-timenãofim da validade, excluído, em UTC (1.11.0)
publicoAudience interno clientenãosó interno aparece; ausente é cliente (1.11.0)
etiquetaslista de stringnãonormalizadas (1.11.0)
fontestringnãorótulo citável ou URL (1.11.0)
idiomastringnãoBCP 47 na caixa canônica (1.11.0)
vigenciaVigency futura vigente encerradanãopresente só com validade, pelo relógio do rag no instante da leitura (1.11.0)

KnowledgeList

objeto

Campos de KnowledgeList
CampoTipoObrigatórioDescrição
itemslista de Knowledgesim
metaobjetosim
meta.totalinteger mínimo 0sim
meta.ordemstring atualizado_em_id_descsimatualizado_em descendente, desempate por id descendente. Contrato desde a 1.5.0.
meta.paginainteger mínimo 1sim
meta.limiteinteger de 1 a 100sim

KnowledgeEvent

objeto

Campos de KnowledgeEvent
CampoTipoObrigatórioDescrição
acaostring arquivado desarquivadosim
autorobjetosim
autor.tipostring chave operador pessoasimchave — 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.descricaostringsimkey da conta, operador (CLI), operador (painel), ou — quando tipo é pessoa — o id da pessoa. Nunca a key, o hash nem o e-mail.
escopostringnãoO escopo em que o arquivamento valeu; ausente quando foi sem escopo (1.7.0, spec 0028).
assistenteAssistantRefnãoPresente 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.
emstring formato date-timesim

KnowledgeEventList

objeto

Campos de KnowledgeEventList
CampoTipoObrigatórioDescrição
itemslista de KnowledgeEventsim
metaobjetosim
meta.totalinteger mínimo 0sim
meta.ordemstring mais_antigo_primeirosim

KnowledgeVersion

objeto

Campos de KnowledgeVersion
CampoTipoObrigatórioDescrição
idstring formato uuidsim
versaointeger mínimo 1sim
textostringsim
tipoKnowledgeKind equivalencia apelido aplicacao observacaosim
nivelConfidence alta media baixanão
publicacaoPublication publicado rascunhosim
marcaKnowledgeMark negativo sugestaonão
referenciastringnão
criado_emstring formato date-timesim
autorobjetonãoQuem gravou esta versão (1.10.0, spec 0064). Ausente nas versões gravadas antes da 1.10.0.
autor.tipostring chave operador pessoasimo mesmo autor do rastro (KnowledgeEvent)
autor.descricaostringsimkey da conta, operador (CLI), operador (painel) ou o id da pessoa — nunca a key, o hash nem o e-mail
autor.assistenteAssistantRefnão
formaKnowledgeFormOutnão
conteudoKnowledgeContentOutnão
vigente_destring formato date-timenãoinício da validade, em UTC (1.11.0)
vigente_atestring formato date-timenãofim da validade, excluído, em UTC (1.11.0)
publicoAudience interno clientenãosó interno aparece; ausente é cliente (1.11.0)
etiquetaslista de stringnãonormalizadas (1.11.0)
fontestringnãorótulo citável ou URL (1.11.0)
idiomastringnãoBCP 47 na caixa canônica (1.11.0)

KnowledgeVersionList

objeto

Campos de KnowledgeVersionList
CampoTipoObrigatórioDescrição
itemslista de KnowledgeVersionsim
metaobjetosim
meta.totalinteger mínimo 0sim
meta.ordemstring versao_descsim

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

Campos de CredentialInput
CampoTipoObrigatórioDescrição
provedorProvider openai deepseek genericosim
endereco_baseBaseURLnãoobrigatório com generico; com os nomeados é 422
modelostring de 1 a 128 caracteressim
segredostring de 1 a 512 caracteres · só de entradasimentra, nunca sai — nenhum schema de resposta o contém
ligadabooleannãocredencial nova sem este campo nasce desligada (1.3.0); na troca, ausente mantém como estava
posicaointeger de 1 a 100nãoposiçã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

Campos de Credential
CampoTipoObrigatórioDescrição
nomeCredentialNamesim
provedorProvider openai deepseek genericosim
modelostringsim
endereco_baseBaseURLnãosó no provedor genérico
ligadabooleansim
posicaointeger mínimo 1simposição na ordem; empate desempata pelo nome
estadoCredentialState valida invalida sem_saldo ilegivelsim
ultimo_usostring formato date-timenãoa última vez que o provedor dela escreveu uma resposta
ultima_falhastring formato date-timenãoa última vez que ela foi tentada e falhou
atualizado_emstring formato date-timesim

CredentialList

objeto

Campos de CredentialList
CampoTipoObrigatórioDescrição
itemslista de Credentialsim
metaobjetosim
meta.totalinteger mínimo 0sim
meta.ordemstring posicao_nomesim

CredentialOrderInput

objeto

Campos de CredentialOrderInput
CampoTipoObrigatórioDescrição
credenciaislista de CredentialName de 1 a 100 itenssimos nomes, na ordem nova; cada um uma vez só

CredentialEvent

objeto

Campos de CredentialEvent
CampoTipoObrigatórioDescrição
acaostring cadastrada trocada ligada desligada reordenada removidasim
credencialCredentialNamenãoa credencial — ausente em reordenada
provedorProvider openai deepseek genericonãoo provedor dela — ausente em reordenada
ordemlista de CredentialNamenãosó em reordenada — a ordem que ficou
autorobjetosim
autor.tipostring chave operador pessoasimchave — 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.descricaostringsimkey da conta, operador (CLI), operador (painel), ou — quando tipo é pessoa — o id da pessoa. Nunca a key, o hash nem o e-mail.
emstring formato date-timesim

CredentialEventList

objeto

Campos de CredentialEventList
CampoTipoObrigatórioDescrição
itemslista de CredentialEventsim
metaobjetosim
meta.totalinteger mínimo 0sim
meta.ordemstring mais_antigo_primeirosim

QuestionInput

objeto

Campos de QuestionInput
CampoTipoObrigatórioDescrição
perguntastring de 1 a 1000 caracteressim
credencialCredentialNamenãonome 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.
itenslista de ResolvedItem máximo 50 itensnãoitens 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ê.
formatostring padrao curto padrão "padrao"nãocurto (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).
publicoAudience interno clientenã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.

Campos de ResolvedItem
CampoTipoObrigatórioDescrição
referenciastring de 1 a 512 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F\u2028\u2029]+$simtexto 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.
precoItemPricenão
quantidade_disponivelinteger formato int64 · de 0 a 9223372036854776000nãoquantidade 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.

Campos de ItemPrice
CampoTipoObrigatórioDescrição
valorinteger formato int64 · de 0 a 9223372036854776000simcentavos; 0 é aceito e mostrado como R$ 0,00
moedastring BRLsim

ItemOrigin

objeto

origem de item (1.8.0, spec 0036) — o item que sustenta a sentença

Campos de ItemOrigin
CampoTipoObrigatórioDescrição
referenciastringsima referência do item exatamente como foi enviada

Origin

objeto

Campos de Origin
CampoTipoObrigatórioDescrição
conhecimento_idstring formato uuidsim
versaointeger mínimo 1sim
referenciastringnãoa referência opaca exatamente como foi inserida
procedenciaProvenance base escoponão
caminhostringsimcaminho que abre o texto inserido — GET nele com a mesma API key. Quando a procedencia é escopo, o caminho já traz ?escopo= (1.7.0).
fontestringnãoa fonte do conhecimento, para o sistema cliente citar; ausente sem fonte (1.11.0)

Passage

objeto

Campos de Passage
CampoTipoObrigatórioDescrição
textostringsim
tipoKnowledgeKind equivalencia apelido aplicacao observacaosim
nivelConfidence alta media baixanão
viastring vetorial textualsim
origemOriginsim
formaKnowledgeFormOutnão
publicoAudience interno clientenãointerno quando a resposta usou conhecimento interno; ausente no cliente (1.11.0)

Searched

objeto

Campos de Searched
CampoTipoObrigatórioDescrição
perguntastringsima pergunta normalizada
termoslista de stringsim
busca_vetorialSearchState ok indisponivel nao_tentadasim
busca_textualSearchState ok indisponivel nao_tentadasim

Passages

objeto

Campos de Passages
CampoTipoObrigatórioDescrição
desfechoOutcome encontrado negativo nao_encontradosim
trechoslista de Passagesimo que pode sustentar texto, cada um com origem
negativoslista de Passagesimnegativos registrados que foram considerados — nunca sustentam frase
procuradoSearchedsim

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).

Campos de ConfidenceEvent
CampoTipoObrigatórioDescrição
nivelConfidence alta media baixasim

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

Campos de EngineAttempt
CampoTipoObrigatórioDescrição
credencialCredentialNamesim
motivoEngineReason credencial_invalida credencial_ilegivel provedor_indisponivel credencial_sem_saldo limite_de_taxa credencial_desligada endereco_recusadosim

Engine

objeto

Campos de Engine
CampoTipoObrigatórioDescrição
respondeuEngineSource tenant hospedado nenhumsim
modelostringnãoo modelo que escreveu o texto
credencialCredentialNamenãoa credencial que escreveu o texto, ou a que a pergunta citou
credencial_falhoubooleansimalguma credencial do tenant foi tentada e falhou, e nenhuma credencial do tenant escreveu o texto. Credencial desligada não conta como falha.
motivoEngineReason credencial_invalida credencial_ilegivel provedor_indisponivel credencial_sem_saldo limite_de_taxa credencial_desligada endereco_recusadonãona 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
tentativaslista de EngineAttemptsimcada 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

Campos de Usage
CampoTipoObrigatórioDescrição
tokens_entradainteger formato int64 · mínimo 0sim
tokens_saidainteger formato int64 · mínimo 0sim
do_cachebooleansimresposta 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.

Campos de VerifiedSentence
CampoTipoObrigatórioDescrição
textostringsim
origenslista de Origin mínimo 0 itenssimas origens de conhecimento, na ordem da citação
itenslista de ItemOrigin mínimo 1 itensnãoos 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

Campos de VerifiedText
CampoTipoObrigatórioDescrição
resposta_idstring formato uuidsim
textostringsimas sentenças verificadas
sentencaslista de VerifiedSentencesim
motorEnginesim
usoUsagesim

Answer

objeto

os três tempos, na ordem

Campos de Answer
CampoTipoObrigatórioDescrição
trechosPassagessim
confiancaConfidenceEventsim
textoVerifiedTextsim

Health

objeto

Campos de Health
CampoTipoObrigatórioDescrição
statusstring ok indisponivelsim
motivostringnão

FieldError

objeto

Campos de FieldError
CampoTipoObrigatórioDescrição
fieldstringsim
messagestringsim

Problem

objeto

RFC 9457. Nunca carrega segredo, SQL, corpo de provedor ou stack trace.

Campos de Problem
CampoTipoObrigatórioDescrição
typestring formato urisim
titlestringsim
statusintegersim
detailstringnão
errorslista de FieldErrornão