AX HTTP API
Resource-shaped HTTP API mirroring the AX CLI command structure.
The AX HTTP API lives at https://app.514.ax/api/v1/ (use your platform host
if it differs). It mirrors the CLI grammar: nouns in the path, the HTTP method
as the verb.
Routes are additive-only within v1: a breaking change would ship as /api/v2/
alongside it.
Authentication
Every route requires an AX API key (the same keys the CLI uses) in the
Authorization header:
curl -H "Authorization: Bearer $AX_API_KEY" \
https://app.514.ax/api/v1/whoamiCreate one from your organization's API-key settings in the platform. Anything
else, including cookies and browser sessions, returns 401 unauthenticated.
Organization scope
Most routes operate inside one organization. If your key can see more than one
org, pass ?org_id= on every org-scoped route:
curl -H "Authorization: Bearer $AX_API_KEY" \
"https://app.514.ax/api/v1/experiments?org_id=org_..."Single-org keys can omit it. GET /api/v1/whoami never needs it; use it to
discover the org ids your key can see.
Errors
Errors return JSON:
{ "error": "invalid_argument", "message": "experiment_id is required" }| Connect code | HTTP status |
|---|---|
invalid_argument | 400 |
unauthenticated | 401 |
permission_denied | 403 |
not_found | 404 |
already_exists | 409 |
failed_precondition | 412 |
resource_exhausted | 429 |
unavailable | 503 |
internal | 500 |
Responses
Successful responses are the same protobuf JSON the CLI's --json output is
built from. Field names are lowerCamelCase; request bodies also accept
snake_case.
Route index
| Routes | Covers | CLI equivalent |
|---|---|---|
| Experiments | List, register, inspect, query, versions, YAML, submit runs. | ax experiment ... |
| Runs | List, view, cancel, query, captured tests. | ax run ... |
| Insights | List, create, execute, edit, delete saved insights. | ax insight ... |
| Secrets | List metadata, set, delete (values are never returned). | ax secret ... |
| Credits | Prepaid credit balance and usage spend for a billing cycle. | ax credit balance / ax credit spend |
| Identity | Who am I, and which orgs can this key see. | ax auth status |
Not in the HTTP API
Local authoring (ax experiment create / validate / schema / variants),
file staging (files: experiments; use the CLI's --file), watch streams
(poll GET /api/v1/runs/{id} instead), and insight export are CLI-side. Org,
API-key, and LLM-provider administration are CLI and platform settings flows
today; they will be documented here when they land under /api/v1/.
Legacy /api/v1/results* routes remain mounted for backward compatibility;
new work should use POST /api/v1/experiments/{id}/query and
POST /api/v1/runs/{id}/query.