This page is not yet available in English. Read it in Portuguese

Skip to content
Menu da documentação

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

bash
curl https://aiuby.com/api/v1/openapi.json

OpenAPI 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

http
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:

json
{ "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.

bash
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

LimiteValor
Por chave, somando todas as rotas120 requisições por minuto
Por workspace, somando todas as chaves300 requisições por minuto
Por endereço IP, antes de autenticar600 requisições por minuto
Consulta estruturada ao grafoTeto 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

StatuscodeQuando
400invalid_requestParâmetro ou corpo fora do formato
400question_not_supportedPergunta em linguagem natural na consulta ao grafo
401unauthorizedSem chave, chave inválida, vencida ou revogada
402billing_account_requiredA organização não tem conta de faturamento
402payment_method_requiredA conta de faturamento não tem forma de pagamento válida
402subscription_suspendedMensalidade sem pagamento além do prazo
403forbiddenA chave não tem o escopo da rota ou não está ligada a um workspace
404not_foundRecurso inexistente ou de outro workspace, produto da plataforma não ativo, frente ou módulo não liberado
409conflictO estado atual do recurso não permite a ação
413invalid_requestCorpo acima do teto da rota
429rate_limitedLimite por chave, workspace, IP ou de consultas por hora
500internal_errorErro interno; tente de novo

Nota

A v1 não usa 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.