API-1.0: Developer API
Autenticação por credencial com hash, scopes, entitlements, rate limiting, idempotência e rotas lógicas v1.
Como interpretar este documento
Este conteúdo descreve o comportamento técnico e metodológico implementado ou explicitamente planejado no produto. Quando um controle depende de configuração, provider, secret, contrato ou aprovação jurídica, essa dependência deve permanecer visível.
Autenticação
Use Authorization: Bearer aiv_live_.... A chave bruta é exibida somente na criação. O registro persistido contém prefixo e hash SHA-256.
Scopes
Os scopes atuais são runs:read, runs:write, recommendations:read, alerts:read e webhooks:manage. O scope não substitui o entitlement api_access.
Rotas
As rotas lógicas incluem GET /v1/me, GET /v1/runs, GET /v1/runs/:id, POST /v1/runs, GET /v1/catalog/models, GET /v1/catalog/questions, GET /v1/recommendations e GET /v1/alerts.
Contrato do gateway
A função external-api-v1 recebe path em consultas de leitura ou envelope com path, method e body. O endpoint implantado depende do ambiente e permanece como placeholder até a definição de hostname público.
Rate limit
ApiRateLimitBucket aplica janela persistente de um minuto por credencial. Quando o limite é atingido, a API retorna HTTP 429 e headers de rate limit.
Idempotência
POST /v1/runs exige Idempotency-Key. A mesma chave com a mesma requisição pode reproduzir o resultado; reutilização com requisição diferente gera conflito.
Criação de run
Runs criadas pela API passam por entitlement, metodologia, suporte de modelos e regras de grounded search antes de MeasurementRun, MeasurementJobs e accounting serem persistidos.
Identidade da API
Use o endpoint implantado do ambiente# Configure o endpoint implantado da função Base44 no ambiente.
export M2_VISIBILITY_API_ENDPOINT="<external-api-v1-endpoint>"
export API_KEY="aiv_live_..."
curl "$M2_VISIBILITY_API_ENDPOINT?path=/v1/me" \
-H "Authorization: Bearer $API_KEY"
# Estrutura resumida da resposta
{
"api_version": "API-1.0",
"credential": {
"id": "...",
"name": "...",
"key_prefix": "aiv_live_...",
"scopes": ["runs:read"],
"rate_limit_per_minute": 60
},
"plan": {
"code": "enterprise",
"features": ["api_access", "..."]
}
}Criar measurement run
Use o endpoint implantado do ambienteexport M2_VISIBILITY_API_ENDPOINT="<external-api-v1-endpoint>"
export API_KEY="aiv_live_..."
curl -X POST "$M2_VISIBILITY_API_ENDPOINT" \
-H "Authorization: Bearer $API_KEY" \
-H "Idempotency-Key: run-2026-08-18-001" \
-H "Content-Type: application/json" \
-d '{
"path": "/v1/runs",
"method": "POST",
"body": {
"model_ids": ["gemini_3_flash"],
"question_ids": ["<question-id-1>", "<question-id-2>"],
"repetitions": 3,
"measurement_type": "grounded",
"locale": "pt-BR",
"country": "BR",
"language": "pt-BR"
}
}'
# HTTP 202
{
"id": "<measurement-run-id>",
"status": "queued",
"total_jobs": 6,
"measurement_type": "grounded",
"methodology_version": "AIVM-1.0"
}