API-1.0: Developer API
Hashed credentials, scopes, entitlements, rate limiting, idempotency and logical v1 routes.
How to interpret this document
This content describes technical and methodological behavior that is implemented or explicitly planned in the product. When a control depends on configuration, a provider, a secret, a contract or legal approval, that dependency must remain visible.
Authentication
Use Authorization: Bearer aiv_live_.... The raw key is shown only at creation. The persisted record stores a prefix and SHA-256 hash.
Scopes
Current scopes are runs:read, runs:write, recommendations:read, alerts:read and webhooks:manage. A scope does not replace the api_access entitlement.
Routes
Logical routes include GET /v1/me, GET /v1/runs, GET /v1/runs/:id, POST /v1/runs, GET /v1/catalog/models, GET /v1/catalog/questions, GET /v1/recommendations and GET /v1/alerts.
Gateway contract
The external-api-v1 function accepts path for reads or an envelope containing path, method and body. The deployed endpoint is environment-specific and remains a placeholder until a public API hostname is defined.
Rate limit
ApiRateLimitBucket enforces a persistent one-minute window per credential. When the limit is exceeded, the API returns HTTP 429 and rate-limit headers.
Idempotency
POST /v1/runs requires Idempotency-Key. Reusing the same key with the same canonical request can replay the result; reusing it with a different request returns a conflict.
Run creation
API-created runs pass through entitlement, methodology, model-support and grounded-search checks before MeasurementRun, MeasurementJobs and usage accounting are persisted.
API identity
Use the deployed endpoint for your environment# Configure the deployed Base44 function endpoint in your environment.
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"
# Simplified response shape
{
"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", "..."]
}
}Create measurement run
Use the deployed endpoint for your environmentexport 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": "en-US",
"country": "US",
"language": "en"
}
}'
# HTTP 202
{
"id": "<measurement-run-id>",
"status": "queued",
"total_jobs": 6,
"measurement_type": "grounded",
"methodology_version": "AIVM-1.0"
}