API

This file is generated from FastAPI OpenAPI metadata via python scripts/generate_api_docs.py.

Base URL:

http://127.0.0.1:8008

Health

`GET /health`

Health

curl http://127.0.0.1:8008/health

Readiness

`GET /readyz`

Readyz

curl http://127.0.0.1:8008/readyz

Diagnostics

`GET /api/v1/diagnostics`

Diagnostics

curl http://127.0.0.1:8008/api/v1/diagnostics

Audit

`GET /api/v1/audit`

Get Audit Log

curl "http://127.0.0.1:8008/api/v1/audit?action=api_key_used" ^
  -H "X-API-Key: YOUR_READ_OR_WRITE_KEY"

`GET /api/v1/audit/export`

Export Audit Log

curl "http://127.0.0.1:8008/api/v1/audit/export?action=api_key_created" ^
  -H "X-API-Key: YOUR_WRITE_KEY"

Deterministic analysis

`POST /api/v1/analyze`

Analyze

curl -X POST http://127.0.0.1:8008/api/v1/analyze ^
  -H "Content-Type: application/json" ^
  -d @docs/demo/sample-project.json

`POST /api/v1/calculate`

Calculate

curl -X POST http://127.0.0.1:8008/api/v1/calculate ^
  -H "Content-Type: application/json" ^
  -d "{\"metric_type\":\"binary\",\"baseline_value\":0.042,\"mde_pct\":5,\"alpha\":0.05,\"power\":0.8,\"expected_daily_traffic\":12000,\"audience_share_in_test\":0.6,\"traffic_split\":[50,50],\"variants_count\":2}"

`POST /api/v1/design`

Design

`POST /api/v1/llm/advice`

Llm Advice

Keys

`GET /api/v1/keys`

List Api Keys

curl http://127.0.0.1:8008/api/v1/keys ^
  -H "Authorization: Bearer YOUR_AB_ADMIN_TOKEN"

`POST /api/v1/keys`

Create Api Key

curl -X POST http://127.0.0.1:8008/api/v1/keys ^
  -H "Authorization: Bearer YOUR_AB_ADMIN_TOKEN" ^
  -H "Content-Type: application/json" ^
  -d "{\"name\":\"Partner read key\",\"scope\":\"read\",\"rate_limit_requests\":60,\"rate_limit_window_seconds\":60}"

`DELETE /api/v1/keys/{api_key_id}`

Delete Api Key

curl -X DELETE http://127.0.0.1:8008/api/v1/keys/KEY_ID ^
  -H "Authorization: Bearer YOUR_AB_ADMIN_TOKEN"

`POST /api/v1/keys/{api_key_id}/revoke`

Revoke Api Key

curl -X POST http://127.0.0.1:8008/api/v1/keys/KEY_ID/revoke ^
  -H "Authorization: Bearer YOUR_AB_ADMIN_TOKEN"

Project storage

`GET /api/v1/projects`

List Projects

curl http://127.0.0.1:8008/api/v1/projects

`POST /api/v1/projects`

Create Project

curl http://127.0.0.1:8008/api/v1/projects

`DELETE /api/v1/projects/{project_id}`

Delete Project

`GET /api/v1/projects/{project_id}`

Get Project

`PUT /api/v1/projects/{project_id}`

Update Project

Project activity

`POST /api/v1/projects/{project_id}/analysis`

Record Project Analysis

`POST /api/v1/projects/{project_id}/exports`

Record Project Export

`GET /api/v1/projects/{project_id}/history`

Get Project History

curl "http://127.0.0.1:8008/api/v1/projects/PROJECT_ID/history?analysis_limit=5&export_limit=5"

`POST /api/v1/projects/{project_id}/restore`

Restore Project

curl -X POST http://127.0.0.1:8008/api/v1/projects/PROJECT_ID/restore

`GET /api/v1/projects/{project_id}/revisions`

Get Project Revisions

curl "http://127.0.0.1:8008/api/v1/projects/PROJECT_ID/revisions?limit=5"

Comparison

`GET /api/v1/projects/compare`

Compare Projects

curl "http://127.0.0.1:8008/api/v1/projects/compare?base_id=BASE&candidate_id=CANDIDATE"

`POST /api/v1/projects/compare`

Compare Multiple Projects

curl "http://127.0.0.1:8008/api/v1/projects/compare?base_id=BASE&candidate_id=CANDIDATE"

Workspace

`GET /api/v1/workspace/export`

Export Workspace

curl http://127.0.0.1:8008/api/v1/workspace/export

`POST /api/v1/workspace/import`

Import Workspace

curl -X POST http://127.0.0.1:8008/api/v1/workspace/import ^
  -H "Content-Type: application/json" ^
  -d @workspace-backup.json

`POST /api/v1/workspace/validate`

Validate Workspace

curl -X POST http://127.0.0.1:8008/api/v1/workspace/validate ^
  -H "Content-Type: application/json" ^
  -d @workspace-backup.json

Report export

`POST /api/v1/export/html`

Export Html

`POST /api/v1/export/markdown`

Export Markdown

curl -X POST http://127.0.0.1:8008/api/v1/export/markdown ^
  -H "Content-Type: application/json" ^
  -d @report.json

Other

`POST /api/v1/assignment/preview`

Assignment Preview

`POST /api/v1/experiments/{experiment_id}/assign`

Assign Experiment

`POST /api/v1/experiments/{experiment_id}/conversions`

Ingest Conversions

`GET /api/v1/experiments/{experiment_id}/decision`

Get Decision

Decision Readout — one synthesized ship / no-ship / keep-running verdict over the same live-stats signals (SRM, frequentist effect/CI, Bayesian P(B>A), sequential crossing). No new statistics; see services/decision_service.py.

`POST /api/v1/experiments/{experiment_id}/exclusions`

Ingest Exclusions

Ingest manual deny-list exclusions for the bot / fraud filter (P4.4). First-write-wins per user (the first reason sticks); the live-stats rollup drops excluded users — resolved to their canonical id — from every aggregate, alongside the automatic rate-spike heuristic. The raw events are never deleted, so an exclusion is a reversible read-time filter.

`POST /api/v1/experiments/{experiment_id}/exposures`

Ingest Exposures

`POST /api/v1/experiments/{experiment_id}/holdout`

Ingest Holdout

Ingest holdout members — users held back from the rollout (F5). Recorded as variation_index = -1 exposures (first-write-wins per user); the live-stats read compares the pooled treated arms against this held-back group to measure the rollout’s cumulative effect. Holdout outcomes ride the ordinary conversion stream under the primary metric name.

`POST /api/v1/experiments/{experiment_id}/identities`

Ingest Identities

Ingest anonymous → canonical identity links (P4.3). First-write-wins per anonymous id; the live-stats rollup folds each user’s exposures and conversions onto their canonical id, so a person exposed while anonymous and re-exposed / converting after login is counted once instead of inflating SRM and the conversion rate. A self-link is a no-op and is skipped.

`GET /api/v1/experiments/{experiment_id}/ingestion`

Get Ingestion Summary

`GET /api/v1/experiments/{experiment_id}/live-stats`

Get Live Stats

Phase D — live SRM / frequentist / Bayesian / sequential read over the current deduplicated exposures and conversions. Recomputed on demand (the dashboard polls); there is no separate scheduler process in the local-first MVP.

`POST /api/v1/experiments/{experiment_id}/pre-period`

Ingest Pre Period Values

Ingest per-user pre-experiment covariate values for CUPED (E5). First-write-wins per user; the covariate enables variance reduction on the continuous live-stats.

`POST /api/v1/experiments/{experiment_id}/strata`

Ingest Strata

Ingest one categorical stratum per user for post-stratification (F3b). First-write-wins per user; the stratum lets the live-stats read estimate the effect within each stratum and recombine it, reducing variance when the stratum explains outcome variation.

`POST /api/v1/export/comparison`

Export Comparison

`POST /api/v1/export/html-standalone`

Export Html Standalone

`POST /api/v1/hypotheses/generate`

Generate Hypotheses

`POST /api/v1/multiple-testing`

Multiple Testing

`POST /api/v1/projects/{project_id}/archive`

Archive Project

`GET /api/v1/projects/{project_id}/report/csv`

Get Project Report Csv

`GET /api/v1/projects/{project_id}/report/pdf`

Get Project Report Pdf

`GET /api/v1/projects/{project_id}/report/xlsx`

Get Project Report Xlsx

`POST /api/v1/results`

Results

`POST /api/v1/results/categorical`

Categorical Results

`POST /api/v1/sensitivity`

Sensitivity

`POST /api/v1/simulate/bandit`

Simulate Bandit

`GET /api/v1/slack/status`

Slack Status

`POST /api/v1/srm-check`

Srm Check

`GET /api/v1/templates`

List Templates

`POST /api/v1/templates`

Create Template

`DELETE /api/v1/templates/{template_id}`

Delete Template

`GET /api/v1/templates/{template_id}`

Get Template

`POST /api/v1/templates/{template_id}/use`

Use Template

`GET /api/v1/webhooks`

List Webhooks

`POST /api/v1/webhooks`

Create Webhook

`DELETE /api/v1/webhooks/{subscription_id}`

Delete Webhook

`GET /api/v1/webhooks/{subscription_id}`

Get Webhook

`PATCH /api/v1/webhooks/{subscription_id}`

Update Webhook

`GET /api/v1/webhooks/{subscription_id}/deliveries`

List Webhook Deliveries

`POST /api/v1/webhooks/{subscription_id}/test`

Test Webhook

`POST /slack/commands`

Slack Commands

`POST /slack/events`

Slack Events

`GET /slack/install`

Slack Install

`POST /slack/interactive`

Slack Interactive

`GET /slack/oauth/callback`

Slack Oauth Callback

Validation notes

supported variant count is 2..10
binary baselines must be between 0 and 1
continuous metrics require positive baseline_value and std_dev
traffic_split length must match variants_count
malformed request bodies return 422
domain errors return structured 400
when AB_API_TOKEN, AB_READONLY_API_TOKEN, or database-backed API keys are configured, protected runtime routes still accept Authorization: Bearer or X-API-Key
/docs, /redoc, and /openapi.json remain public even when auth is enabled; only protected API routes and /readyz require a token
AB_READONLY_API_TOKEN is valid only for GET, HEAD, and OPTIONS; mutating routes still require AB_API_TOKEN
/api/v1/keys* requires AB_ADMIN_TOKEN; without it the key-management endpoints return 401
database-backed API keys are stored as SHA-256 hashes, the plaintext secret is returned only once at creation time, and revoked keys are rejected
per-key rate-limit overrides apply only to requests authenticated with a database API key; legacy shared tokens continue to use the global limiter
all API responses include X-Request-ID and X-Process-Time-Ms headers
error responses also include error_code, status_code, request_id, and X-Error-Code
diagnostics expose in-memory runtime counters plus the active guardrail configuration for security headers, rate limiting, auth throttling, and request-body limits
GET /readyz returns 503 when required runtime dependencies are degraded

Contract generation

TypeScript contracts: python scripts/generate_frontend_api_types.py
API docs markdown: python scripts/generate_api_docs.py