The Experiments API lets you manage tests from scripts, CI or internal tools. Everything in the dashboard is available through the API.
Authentication
Create an API token under Settings, with the scopes you need. Send it in the Authorization header.
curl https://api.kerf.dev/v1/experiments \
-H "Authorization: Bearer $KERF_API_TOKEN"Create an experiment
curl -X POST https://api.kerf.dev/v1/experiments \
-H "Authorization: Bearer $KERF_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"key": "short-address-form",
"flag": "new-checkout",
"primary_metric": "orders_per_visitor",
"guardrails": ["payment_success", "page_load_p95"],
"split": { "control": 50, "treatment": 50 }
}'Start and stop
curl -X POST https://api.kerf.dev/v1/experiments/short-address-form/start
curl -X POST https://api.kerf.dev/v1/experiments/short-address-form/stopRead results
{
"status": "running",
"srm": "healthy",
"primary": { "lift": 0.18, "ci": [0.07, 0.29] },
"guardrails": [{ "key": "payment_success", "status": "ok" }]
}Errors
- 400 for invalid input, with a field level message.
- 401 for a missing or expired token.
- 409 when a flag is already attached to a running experiment.
- 429 when you exceed the rate limit. The Retry-After header says how long to wait.
Webhooks
Subscribe to experiment.started, experiment.completed and guardrail.breached to post into your own tools.