Experiments

Every route takes org_id as a query parameter (required only when the key can see several orgs; see Organization scope); it is not repeated in the tables below. Parameters are optional unless marked required.

GET /api/v1/experiments

List registered experiments in the selected org, newest first.

curl -H "Authorization: Bearer $AX_API_KEY" \
  "https://app.514.ax/api/v1/experiments?search=install&limit=20"

POST /api/v1/experiments

Register experiment YAML without running it. The body is the raw YAML, not JSON; each push stores a content-addressed version.

curl -X POST \
  -H "Authorization: Bearer $AX_API_KEY" \
  -H "Content-Type: text/yaml" \
  --data-binary @experiment.yaml \
  "https://app.514.ax/api/v1/experiments"

Responds with the pushed experiment version metadata. Empty bodies return 400 invalid_argument.

GET /api/v1/experiments/{id}

Inspect one registered experiment: metadata and resolved axes. URL-encode {id} if it contains reserved characters.

curl -H "Authorization: Bearer $AX_API_KEY" \
  "https://app.514.ax/api/v1/experiments/my-first-experiment"

GET /api/v1/experiments/{id}/versions

List stored versions, last-pushed first. Each version carries fingerprint, timestamps, creator, runCount, and a first-created ordinal (the vN the CLI shows; re-pushing an older definition keeps its ordinal).

curl -H "Authorization: Bearer $AX_API_KEY" \
  "https://app.514.ax/api/v1/experiments/my-first-experiment/versions"

GET /api/v1/experiments/{id}/yaml

Download the registered YAML.

curl -H "Authorization: Bearer $AX_API_KEY" \
  "https://app.514.ax/api/v1/experiments/my-first-experiment/yaml"

POST /api/v1/experiments/{id}/runs

Submit a run for a registered experiment. Returns 202 Accepted with the submit receipt (runRequestId, pinned version fingerprint and ordinal, variantCount, selected variantIds); run failures surface asynchronously on the request. Poll GET /api/v1/runs/{id} to watch it; there is no watch stream.

curl -X POST \
  -H "Authorization: Bearer $AX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repeat":3,"variantIds":["claude::baseline"]}' \
  "https://app.514.ax/api/v1/experiments/my-first-experiment/runs"

JSON body (optional):

Snake_case spellings (variant_ids, prompt_ids, ...) are also accepted. Unknown selectors, unknown versions, or a selection matching no variants return 400 invalid_argument. Experiments that declare files: staging cannot be staged over HTTP; use the CLI with --file.

POST /api/v1/experiments/{id}/query

Query results in experiment scope: SQL, or the experimental flag-based modeled query. The HTTP mirror of ax experiment query.

curl -X POST \
  -H "Authorization: Bearer $AX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT test_name, exit_code FROM tests WHERE exit_code != 0"}' \
  "https://app.514.ax/api/v1/experiments/my-first-experiment/query"

JSON body:

Experimental modeled fields (no sql; the surface may change):

The CLI-style aliases version, dimensions, and save are also accepted. Responds with query rows, projection-order columns, compiled SQL, and (when requested) the dry-run estimate, discovered dimensions, or saved-insight receipt.