18 · A referência HTTP¶
Toda operação que a API atende está na tabela deste capítulo, agrupada por produto como a referência da API as agrupa. Cada linha abre essa operação na referência, onde você pode ler a sua requisição e a sua resposta por completo e testá-la com a sua própria chave. A tabela se lê sem JavaScript, se imprime e vai junto nas cópias offline deste guia, o que a página interativa não consegue; a página é a metade interativa. As duas são geradas a partir de um único documento.
O documento¶
O contrato é o openapi.yaml, OpenAPI 3.1, servido byte a byte em
api.stalwart.it/openapi.yaml, com um gêmeo em português em
/openapi.pt.yaml, cuja prosa é traduzida e cujo contrato é o mesmo. Este guia foi gerado contra o
documento com este SHA-256:
9ec469bdccaf965e1d7d21182ab1495f890322124c0943fb4b5202ff4ed2916b
Ele também está carimbado no pé de cada página. Para confirmar que o guia e a referência descrevem o mesmo contrato, compare-o com o SHA-256 do arquivo que a API serve.
A URL traz /v1. Acrescentar um campo, um modo, um slug de recusa ou um tipo de evento é uma mudança
compatível; remover ou mudar o tipo de qualquer coisa é /v2.
Todas as operações¶
Construtor de bots¶
Planos¶
Leia o turno de um usuário como um plano de chamadas de ferramentas. Um turno são as palavras do seu usuário, por isso o plano é feito no seu próprio host: pelo runtime licenciado, ou pelo roteador que você executa no seu ambiente, que atende esta rota. O api.stalwart.it não a atende.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
POST /v1/plans |
Planejar as chamadas de ferramentas de um turno | route |
200, 400, 401, 403, 413, 429, 503 |
Catálogos¶
Registre as suas ferramentas a partir de definições de ferramentas do LangChain, da lista de ferramentas de um servidor MCP ou de um documento OpenAPI. Cada registro é uma versão, verificada por lints antes de rotear, e a anterior pode ser restaurada.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
POST /v1/catalogues |
Registrar um catálogo de ferramentas | catalogue |
201, 400, 401, 403, 409, 413, 429, 503 |
GET /v1/catalogues |
Listar as versões do catálogo | catalogue |
200, 401, 403 |
GET /v1/catalogues/{version} |
Ler o catálogo | catalogue |
200, 401, 403, 404 |
POST /v1/catalogues/{version}/restore |
Restaurar o catálogo anterior | catalogue |
201, 401, 403, 404, 429, 503 |
Verificações de ferramentas¶
Verifique uma chamada de ferramenta contra o seu catálogo, o seu rulebook e o histórico da sessão, e receba uma resposta: permitir, confirmar ou recusar. A verificação roda no seu próprio host: no runtime licenciado, ou por estas rotas no roteador que você executa no seu ambiente, para um host que não pode carregar o runtime. O api.stalwart.it não as atende.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
POST /v1/tool-checks |
Verificar uma chamada de ferramenta | tool_check |
200, 400, 401, 403, 413, 429, 503 |
POST /v1/tool-receipts |
Verificar o recibo de uma chamada | tool_check |
200, 400, 401, 403, 413, 429, 503 |
Vocabulário¶
As palavras que o seletor lê, por tenant: publique uma versão, aprenda novas palavras a partir do feedback e reverta.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
GET /v1/vocabulary |
Ler o vocabulário | mine ou packages |
200, 401, 403 |
PUT /v1/vocabulary |
Publicar uma versão do vocabulário | mine |
200, 400, 401, 403 |
POST /v1/vocabulary/mine |
Aprender novas palavras a partir do feedback | mine |
202, 400, 401, 403, 429 |
GET /v1/vocabulary/mine |
Listar as execuções do minerador | mine |
200, 401, 403 |
GET /v1/vocabulary/mine/{run_id} |
Ler uma execução de aprendizado | mine |
200, 401, 403, 404 |
DELETE /v1/vocabulary/mine/{run_id} |
Retirar uma execução de aprendizado | mine |
200, 401, 403, 404 |
POST /v1/vocabulary/revert |
Reverter o vocabulário | mine |
200, 400, 401, 403 |
GET /v1/vocabulary/history |
Listar as versões do vocabulário | mine ou packages |
200, 401, 403 |
Relatórios de feedback e gramática¶
O que seus usuários disseram quando o seletor errou, e as formas de frase que ele não conseguiu ler.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
POST /v1/feedback |
Enviar o feedback dos seus usuários | feedback |
201, 400, 401, 403, 409, 429 |
GET /v1/feedback/export |
Exportar feedback | feedback ou packages |
200, 401, 403 |
GET /v1/grammar-reports/shipped |
Listar as formas lidas atualmente | grammar_report ou mine |
200, 401, 403 |
POST /v1/grammar-reports |
Relatar uma forma de frase não lida | grammar_report |
201, 400, 401, 403, 409 |
GET /v1/feedback/summary |
Resumir o feedback | feedback |
200, 401, 403 |
Planilhas de regras¶
Suas regras de negócio em YAML que uma pessoa consegue ler em voz alta, compiladas no rulebook que a verificação de ferramentas aplica, conferidas contra o seu catálogo e registradas nele.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
POST /v1/rule-sheets/compile |
Compilar uma planilha de regras | catalogue |
200, 400, 401, 403, 409, 413, 429, 503 |
POST /v1/rule-sheets |
Salvar uma planilha de regras | catalogue |
201, 400, 401, 403, 409, 413, 429, 503 |
GET /v1/rule-sheets |
Ler a planilha de regras | catalogue |
200, 401, 403 |
Respostas¶
O que uma resposta pode dizer: as formulações de resultado que substituem uma frase que descreve errado o que foi feito, e as regras de resposta para dados pessoais, redação e ofertas.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
GET /v1/reply-rules |
Ler as regras de resposta | catalogue |
200, 401, 403 |
PUT /v1/reply-rules |
Salvar as regras de resposta | catalogue |
200, 400, 401, 403, 413 |
GET /v1/outcome-phrasings |
Ler as formulações de resultado | catalogue |
200, 401, 403 |
PUT /v1/outcome-phrasings |
Salvar as formulações de resultado | catalogue |
200, 400, 401, 403, 413 |
Precisão¶
O quanto os seus agentes entendem o que as pessoas pedem, desde o primeiro dia: um conjunto de avaliação escrito a partir do seu catálogo, ao lado dos polegares dos seus usuários.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
GET /v1/accuracy |
Ler a precisão | catalogue |
200, 401, 403 |
Caçador de Bugs em Guardrails¶
Analisar uma política¶
Envie um job com mode: hunt e a política -- em Colang 1 ou Colang 2 -- ou um grafo de agentes e o seu catálogo, e leia os achados do job concluído. Os exemplos Caçador de Bugs em Guardrails: analisar uma política em Colang 1 em busca de bugs, Caçador de Bugs em Guardrails: analisar uma política em Colang 2 em busca de bugs e Caçador de Bugs em Guardrails: analisar um grafo de agentes são requisições completas, cada uma com a política no próprio corpo.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
POST /v1/solves |
Enviar um job | a permissão do próprio modo | 200, 202, 400, 401, 403, 409, 413, 429, 503 |
Projetos e análises¶
Um projeto mantém juntas as análises de uma política, de modo que cada análise é comparada com a anterior e um perfil de qualidade pode aplicar um gate a ela.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
POST /v1/projects |
Criar um projeto | hunt |
201, 400, 401, 403, 409 |
GET /v1/projects |
Listar projetos | hunt |
200, 401, 403 |
GET /v1/projects/{id} |
Ler um projeto | hunt |
200, 401, 403, 404 |
PUT /v1/projects/{id}/profile |
Definir o gate de qualidade de um projeto | hunt_details |
200, 400, 401, 403, 404, 409 |
POST /v1/projects/{id}/scans |
Analisar um projeto | hunt |
200, 202, 400, 401, 403, 404, 409, 413, 429 |
GET /v1/projects/{id}/scans |
Listar as análises de um projeto | hunt |
200, 401, 403, 404 |
GET /v1/projects/{id}/scans/{scan_id} |
Ler uma análise | hunt |
200, 401, 403, 404 |
Achados¶
Todos os achados relatados pelas análises de um projeto, com seu histórico, a sua decisão sobre cada um e o que foi tentado contra ele no seu ambiente.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
POST /v1/hunt-attempts |
Registrar uma tentativa em um achado | hunt |
201, 400, 401, 403, 409 |
GET /v1/hunt-attempts |
Listar as tentativas em achados | hunt |
200, 401, 403 |
GET /v1/projects/{id}/findings |
Listar achados | hunt |
200, 400, 401, 403, 404 |
GET /v1/projects/{id}/findings/{fingerprint} |
Ler um achado | hunt_details |
200, 401, 403, 404 |
PATCH /v1/projects/{id}/findings/{fingerprint} |
Fazer a triagem de um achado | hunt_details |
200, 400, 401, 403, 404, 409 |
Verificação de Guardrails¶
Verificar um guardrail¶
Envie um job com mode: guardrail para uma ação e seu contexto, ou batch para uma tabela delas, sobre uma política em Colang 1 ou Colang 2. Os dois exemplos Verificação de Guardrails: esta ação pode ser executada sem este contexto? são requisições completas, um em cada dialeto; o seletor do corpo da requisição lista todos os modos de verificação.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
POST /v1/solves |
Enviar um job | a permissão do próprio modo | 200, 202, 400, 401, 403, 409, 413, 429, 503 |
Verificar um grafo de agentes¶
Envie um job com mode: graph, um grafo de agentes exportado e o catálogo que classifica as suas ferramentas: toda ferramenta alcançada sem a sua verificação, toda escrita sem a sua confirmação, toda regra de ordem, toda ferramenta privilegiada sob contaminação e toda regra de saga são decididas, e cada uma violada volta com um caminho pelo grafo. O exemplo Verificação de Guardrails: verificar um grafo de agentes antes da implantação é uma requisição completa.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
POST /v1/solves |
Enviar um job | a permissão do próprio modo | 200, 202, 400, 401, 403, 409, 413, 429, 503 |
Escrita de Guardrails¶
Escrever um guardrail¶
Envie um job guardrail com um objeto generation no lugar de uma política: uma regra em prosa, seu provedor, modelo e chave. O rascunho é escrito em Colang 2, a menos que você peça Colang 1, verificado como qualquer outra política e reparado onde estiver errado. Sua chave e seu prompt nunca são armazenados. Os dois exemplos Escrita de Guardrails são requisições completas: um redige em Colang 2, o outro pede Colang 1 com generation.dialect.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
POST /v1/solves |
Enviar um job | a permissão do próprio modo | 200, 202, 400, 401, 403, 409, 413, 429, 503 |
Verificação de Random Forests¶
Verificar uma floresta¶
Faça o upload do modelo e de uma tabela de propriedades e, em seguida, envie um job com mode: forest, ou forest_enumeration para buscar em torno de registros reais. O exemplo Verificação de Random Forests é uma requisição completa.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
POST /v1/solves |
Enviar um job | a permissão do próprio modo | 200, 202, 400, 401, 403, 409, 413, 429, 503 |
Jobs e arquivos¶
Jobs¶
Todo produto acima que é executado como job é lido, transmitido e cancelado aqui.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
GET /v1/solves |
Listar jobs | qualquer chave válida | 200, 401 |
GET /v1/solves/{id} |
Ler um job | qualquer chave válida | 200, 400, 401, 404, 413 |
DELETE /v1/solves/{id} |
Cancelar um job | qualquer chave válida | 200, 401, 404 |
GET /v1/solves/{id}/events |
Acompanhar o progresso de um job via stream | qualquer chave válida | 200, 401, 404, 429 |
GET /v1/solves/{job_id}/artifacts |
Listar os artefatos de um job | qualquer chave válida | 200, 401, 404 |
Uploads e artefatos¶
Prepare um arquivo grande demais para ser enviado inline e faça o download do que um job produziu.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
POST /v1/uploads |
Abrir um upload | qualquer chave válida | 201, 400, 401, 413 |
PUT /v1/uploads/{upload_id}/content |
Enviar os bytes de um upload | qualquer chave válida | 200, 400, 401, 413 |
GET /v1/artifacts/{id} |
Fazer download de um artefato | qualquer chave válida | 200, 206, 401, 403, 404, 410 |
GET /v1/artifacts/{id}/access |
Quem leu um artefato | qualquer chave válida | 200, 401, 404 |
Conta¶
Recursos e acesso¶
O que esta chave pode fazer: os modos, perfis e limites, e o acesso ao feed de pacotes.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
GET /v1/packages/entitlement |
Verificar o acesso ao feed de pacotes | qualquer chave válida | 200, 401, 403 |
GET /v1/profiles |
Listar perfis | qualquer chave válida | 200 |
GET /v1/capabilities |
O que esta chave pode fazer | qualquer chave válida | 200 |
GET /v1/account |
A que esta chave está sujeita | qualquer chave válida | 200, 401 |
GET /v1/version |
O que está em execução aqui | qualquer chave válida | 200, 401 |
Runtime local¶
O runtime licenciado na sua máquina chama estas operações: ele é ativado com a sua chave, renova a sua concessão em segundo plano, baixa os seus pacotes e informa as suas contagens. Um turno nunca espera por elas.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
GET /v1/licences |
Ler a licença | runtime |
200, 401, 403 |
GET /v1/licences/keys |
Ler as chaves de licença | nenhuma, pública | 200, 503 |
POST /v1/licences/activate |
Ativar uma licença | runtime |
201, 400, 401, 403, 409, 503 |
POST /v1/licences/refresh |
Renovar uma concessão | runtime |
200, 400, 401, 403, 404, 409, 503 |
POST /v1/licences/release |
Liberar uma instalação | runtime |
200, 400, 401, 403, 404 |
POST /v1/licences/offline |
Ativar uma instalação offline | runtime |
201, 400, 401, 403, 409, 503 |
GET /v1/bundles/{kind} |
Baixar um pacote | runtime |
200, 400, 401, 403, 409, 503 |
POST /v1/usage-reports |
Informar o uso | runtime |
201, 400, 401, 403, 404, 503 |
Cadastro e sessões¶
Abra uma conta com um link enviado por email ou com o Google, mostre que uma solicitação é de uma pessoa e verifique ou encerre a sessão com que o console entra.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
POST /v1/signup |
Cadastrar-se por e-mail | nenhuma, pública | 202, 400, 409, 429, 503 |
GET /v1/signup/challenge |
Obter um desafio de cadastro | nenhuma, pública | 200 |
GET /v1/signup/google |
Cadastrar-se com o Google | nenhuma, pública | 303, 503 |
GET /v1/signup/google/callback |
Retorno do Google | nenhuma, pública | 303, 403, 503 |
GET /v1/session |
Ler a sessão | nenhuma, pública | 200, 401 |
POST /v1/session/end |
Sair em todos os lugares | nenhuma, pública | 204, 400, 401 |
Faturamento¶
Os preços dos planos como o site os mostra, e os webhooks para os quais o Stripe e o provedor de e-mail enviam. Um webhook é assinado, registrado uma única vez e nunca chamado por um cliente.
| Operação | O que faz | Permissão necessária | Status |
|---|---|---|---|
GET /v1/mail/events |
Verificar o webhook do provedor de e-mail | nenhuma, pública | 200 |
HEAD /v1/mail/events |
Verificar o webhook de e-mail, só cabeçalhos | nenhuma, pública | 200 |
POST /v1/mail/events |
Webhook do provedor de e-mail | nenhuma, pública | 200, 400, 401 |
GET /v1/pricing |
Ler os preços | nenhuma, pública | 200 |
POST /v1/billing/webhooks/stripe |
Webhook do Stripe | nenhuma, pública | 200, 400, 401, 503 |
POST /v1/solves está sob todo produto que roda como um job, e aparece uma vez sob cada um deles. A sua
permissão é a permissão do modo que a requisição nomeia
(capítulo 40).
A página de referência, e a sua chave¶
A referência em api.stalwart.it/pt é pública, e lê-la não exige chave. O seu painel Test Request envia requisições reais, com uma chave que você cola. Eis o que ele faz com essa chave, como a própria política e a configuração da página o decidem:
- Uma requisição feita pelo painel é uma chamada real: autenticada, limitada e medida contra a cota da sua chave como qualquer outra. Nunca é um sandbox, nunca é um modo de teste, e não é gratuita.
- A chave é enviada ao host que serviu a página, e a nada mais. O único servidor do painel é a própria
origem da página, e a Content-Security-Policy da página só admite requisições para essa origem: scripts
só dela, sem script em linha; estilos dela, mais os estilos em linha que o renderizador define; fontes e
imagens dela, mais endereços
data:. - A página não guarda chave nenhuma no armazenamento do seu navegador, não carrega nada de terceiros e não envia telemetria. Ela não tem assistente de IA, nem link para um cliente hospedado.
Quem preferir não colar uma chave de produção cria uma para esse fim na página Keys do console, e a revoga depois (capítulo 5). Um servidor editado no painel para apontar para outro host é recusado pela política da página, e o painel não diz nada sobre o porquê (capítulo 15).
Esta tabela é o caminho acessível para o mesmo contrato. A página interativa é do renderizador, e não cabe a nós torná-la acessível; este capítulo é submetido às mesmas verificações de acessibilidade que qualquer outra página do guia.
Os limites¶
- Os links abrem a referência ao vivo, e precisam da rede. Numa cópia offline deste guia, a tabela e o digest estão completos; os links não.
- Uma requisição enviada pela página de referência é uma chamada real, medida.