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; each push stores a content-addressed version. By default the body is the raw YAML, not JSON:

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"

An experiment that declares required dependencies (files:, setup.files, setup.skills, or tests[*].files entries with a source) needs its complete package to become a runnable version — ax experiment push resolves and uploads those files for you. A raw-YAML push of the same experiment with nothing else attached is only accepted when it matches the YAML of an existing stored version (an idempotent re-push); otherwise it is rejected with 400 invalid_argument rather than registering an incomplete version.

A caller that has already staged each dependency's content-addressed blob for this org can send the package alongside the YAML with a JSON body instead — send Content-Type: application/json:

curl -X POST \
  -H "Authorization: Bearer $AX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "experiment_yaml": "...",
    "replace_version_files": true,
    "version_files": [
      {
        "dest": "inputs/data.txt",
        "tar_sha256": "<64-hex sha256 of the staged blob>",
        "size_bytes": 1234,
        "source": "data.txt"
      }
    ]
  }' \
  "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, resolved axes, and resources. URL-encode {id} if it contains reserved characters. Each resource is {id, title, url, createdAt, updatedAt}. An experiment with none returns "resources": []. Resources are not in the YAML download.

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

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

Attach one titled link, or several in one request. Title and URL are both required. Same title or same URL twice is allowed. URL-encode {id} if it contains reserved characters.

curl -X POST \
  -H "Authorization: Bearer $AX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Experiment plan","url":"https://docs.google.com/document/d/abc"}' \
  "https://app.514.ax/api/v1/experiments/my-first-experiment/resources"

JSON body: a single {title, url}, or { "resources": [ ... ] } for several. Send one shape, not both.

Responds 201 with { "resources": [ ... ] } (the created rows). Sending both shapes, a non-http URL, or a missing title returns 400 invalid_argument. Unknown experiment: 404 not_found.

PATCH /api/v1/experiments/{id}/resources/{resourceId}

Change a resource's title, URL, or both. At least one field is required. Copy {resourceId} (a UUID) from GET /experiments/{id}.

curl -X PATCH \
  -H "Authorization: Bearer $AX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"v2 experiment plan"}' \
  "https://app.514.ax/api/v1/experiments/my-first-experiment/resources/11111111-1111-4111-8111-111111111111"

Responds with the updated resource and previousTitle. Unknown experiment or resource: 404 not_found. Empty body: 400 invalid_argument.

DELETE /api/v1/experiments/{id}/resources/{resourceId}

Remove a resource. A missing resource id is 404 not_found, not a silent success. Responds 204.

curl -X DELETE \
  -H "Authorization: Bearer $AX_API_KEY" \
  "https://app.514.ax/api/v1/experiments/my-first-experiment/resources/11111111-1111-4111-8111-111111111111"

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}/fork

Copy a registered experiment onto the current data pipeline as a new experiment. Responds 201 with the new experiment's experimentId, name, experimentFingerprint, url, and dataSchema (session_data_v1), plus the sourceExperimentId and sourceExperimentFingerprint it was copied from. No runs are created.

curl -X POST \
  -H "Authorization: Bearer $AX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"newExperimentId": "my-first-experiment-2026", "newName": "My first experiment (2026)"}' \
  "https://app.514.ax/api/v1/experiments/my-first-experiment/fork"

The JSON body is optional.

The fork registers the source's latest stored version (YAML with only id and name rewritten, plus its dependencies) under the new id. The source experiment is only read: its runs, versions, and results are unchanged. Use it when an experiment's results are held in the retired data pipeline and you want to run the same definition again, then submit runs against the new id.

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. Registered experiments that declare files: use the dependencies stored by ax experiment push; the HTTP route does not upload new local files.

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 test_analysis 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; include_test_aware works as well as includeTestAware. Responds with query rows, projection-order columns, compiled SQL, and (when requested) the dry-run estimate, discovered dimensions, or saved-insight receipt. A modeled response also carries excludedTestAwareRuns, the number of runs the default exclusion held back.