Appearance
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=runningOptional 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/experimentsRequest body
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Stable experiment identifier (user-provided) |
name | string | Yes | Human-readable name |
description | string | No | Longer description |
variants | object | Yes | Map of variant name to configuration (structure defined by your deployment) |
metric | string | No | Primary 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}/statusRequest body
| Field | Type | Required | Description |
|---|---|---|---|
status | string | Yes | One 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}/resultsReturns 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/trackRequest body
| Field | Type | Required | Description |
|---|---|---|---|
experiment_id | string | Yes | Experiment id |
event_type | string | Yes | Event name (e.g. impression, conversion) |
event_value | string | No | Optional 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"
}'