Skip to content

Experiments API ​

Create experiments with a caller-chosen id, manage status (draft, running, paused, completed), fetch results, and track events for analysis. All listed routes require an authenticated user (Authentication) unless noted otherwise in product configuration.

Base path: /api

Replace YOUR_TOKEN with your Bearer token. For local development, use http://localhost:8000.

List experiments ​

GET /api/experiments
GET /api/experiments?status=running

Optional status filters the list (for example draft, running, paused, completed).

Example ​

bash
curl -s "https://api.ghostai.com/api/experiments?status=running" \
  -H "Authorization: Bearer YOUR_TOKEN"

Create experiment ​

The experiment id is supplied by the client and must be unique; if an experiment with that id already exists, the API returns 400.

POST /api/experiments

Request body ​

FieldTypeRequiredDescription
idstringYesStable experiment identifier (user-provided)
namestringYesHuman-readable name
descriptionstringNoLonger description
variantsobjectYesMap of variant name to configuration (structure defined by your deployment)
metricstringNoPrimary metric key for analysis

Example ​

bash
curl -X POST "https://api.ghostai.com/api/experiments" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "pricing_header_2026_q2",
    "name": "Pricing page header",
    "description": "Short vs long headline",
    "variants": {
      "control": {"value": "Simple, secure AI"},
      "variant_a": {"value": "Enterprise AI with PII protection"}
    },
    "metric": "signup_click"
  }'

Get experiment ​

GET /api/experiments/{id}

Example ​

bash
curl -s "https://api.ghostai.com/api/experiments/pricing_header_2026_q2" \
  -H "Authorization: Bearer YOUR_TOKEN"

Update experiment status ​

PATCH /api/experiments/{id}/status

Request body ​

FieldTypeRequiredDescription
statusstringYesOne of: draft, running, paused, completed

Example ​

bash
curl -X PATCH "https://api.ghostai.com/api/experiments/pricing_header_2026_q2/status" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "running"}'

Experiment results ​

GET /api/experiments/{id}/results

Returns aggregated metrics for the experiment, or 404 if none exist.

Example ​

bash
curl -s "https://api.ghostai.com/api/experiments/pricing_header_2026_q2/results" \
  -H "Authorization: Bearer YOUR_TOKEN"

Track event ​

Records an analytics event for the authenticated user against an experiment.

POST /api/experiments/track

Request body ​

FieldTypeRequiredDescription
experiment_idstringYesExperiment id
event_typestringYesEvent name (e.g. impression, conversion)
event_valuestringNoOptional payload

Example ​

bash
curl -X POST "https://api.ghostai.com/api/experiments/track" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "experiment_id": "pricing_header_2026_q2",
    "event_type": "cta_click",
    "event_value": "variant_a"
  }'

SOC 2 Type II Certified | BAA Available | HIPAA-Ready