API v1 (engenharia)
API v1
A API pública versionada dos produtos de engenharia: chave e escopo, produto exigido, envelope de resposta, paginação, limites e códigos de erro.
Endereço base: https://aiuby.com/api/v1. As rotas do Gateway de modelos, do Knowledge, dos agentes e do Compute ficam fora da v1 e estão em Visão geral da API.
#Especificação OpenAPI
curl https://aiuby.com/api/v1/openapi.jsonOpenAPI 3.1, sem chave, com o esquema de cada parâmetro, corpo e resposta. Cada operação diz o escopo em x-aiuby-scope e o produto na tag. A referência das rotas lista as mesmas operações.
#Autenticação e produto
Authorization: Bearer aiuby_...- Só chave de API: a sessão da área logada não vale na v1. O cabeçalho é exatamente
Bearer, um espaço e a chave. - A chave precisa ter o escopo da rota e estar ligada a um workspace. A resposta é sempre do workspace da chave.
- A organização precisa do produto da plataforma que libera a rota e de conta de faturamento válida: Cortex; Guard ou Cortex em Security Testing e AI & API Security (o OpenAPI diz em
x-aiuby-products); Agents nas avaliações e nos traces. - A frente de engenharia e cada módulo são liberados por organização. Desligado ou não liberado, a rota responde
404, igual a uma rota que não existe.
#Envelope
Toda resposta, de sucesso ou de erro, tem a mesma forma:
{ "data": { … }, "error": null, "meta": {} }
{ "data": null, "error": { "code": "forbidden", "message": "A credencial não tem o escopo engineering:read." }, "meta": {} }Decida pelo code: ele é estável. A message é para pessoas e pode mudar.
#Paginação
Listas paginadas aceitam limit e cursor. A resposta traz meta.nextCursor; na última página, ele vem null.
curl "https://aiuby.com/api/v1/engineering/catalog?limit=50" -H "Authorization: Bearer $AIUBY_TOKEN"
curl "https://aiuby.com/api/v1/engineering/catalog?limit=50&cursor=$NEXT" -H "Authorization: Bearer $AIUBY_TOKEN"#Limites
| Limite | Valor |
|---|---|
| Por chave, somando todas as rotas | 120 requisições por minuto |
| Por workspace, somando todas as chaves | 300 requisições por minuto |
| Por endereço IP, antes de autenticar | 600 requisições por minuto |
| Consulta estruturada ao grafo | Teto próprio por hora, por chave |
As respostas trazem X-RateLimit-Limit e X-RateLimit-Remaining. Acima do limite: 429 rate_limited com Retry-After: 60.
#Erros
| Status | code | Quando |
|---|---|---|
| 400 | invalid_request | Parâmetro ou corpo fora do formato |
| 400 | question_not_supported | Pergunta em linguagem natural na consulta ao grafo |
| 401 | unauthorized | Sem chave, chave inválida, vencida ou revogada |
| 402 | billing_account_required | A organização não tem conta de faturamento |
| 402 | payment_method_required | A conta de faturamento não tem forma de pagamento válida |
| 402 | subscription_suspended | Mensalidade sem pagamento além do prazo |
| 403 | forbidden | A chave não tem o escopo da rota ou não está ligada a um workspace |
| 404 | not_found | Recurso inexistente ou de outro workspace, produto da plataforma não ativo, frente ou módulo não liberado |
| 409 | conflict | O estado atual do recurso não permite a ação |
| 413 | invalid_request | Corpo acima do teto da rota |
| 429 | rate_limited | Limite por chave, workspace, IP ou de consultas por hora |
| 500 | internal_error | Erro interno; tente de novo |
Nota
403 product_not_active: produto não ativo aparece como 404 not_found. O 403 product_not_active existe no Gateway de modelos (veja Erros).Agente de entrega
agent_environment e agent_unbound são só da rota do agente instalado no cluster: a chave é de outro ambiente, ou de nenhum.
#Versão
Toda resposta traz X-AIUBY-Api-Version: v1. Quando a v1 for aposentada, as respostas passam a trazer Deprecation e Sunset. Hoje nenhuma das duas aparece.