REST API overview

The Versuch REST API is the single backend for experiments, feature flags, config, metrics, segments, and usage. Everything you can do in the dashboard, an agent or server can do over HTTP.

Base URL

https://versuch.ai/api/v1

The API is also reachable at https://api.versuch.ai/v1. Both resolve to the same worker.

Authentication

Send your key as a Bearer token:

Authorization: Bearer vsk_live_...

Which key you use depends on the surface. Management endpoints (create/read experiments, flags, metrics, segments, usage) require the secret management key vsk_. SDK and edge endpoints accept the narrower SDK keys.

Key prefix	Where it is safe	Grants access to
vsk_live_…	Server-side / tooling only	All /v1/* management endpoints
ssk_live_…	Server-side only	/v1/config, /v1/evaluate, /v1/events
csk_live_…	Browser (pre-evaluated only)	/v1/client-config, /v1/exposures
vpk_live_…	Browser (public, write-only)	/v1/checkout, event ingest

Caution

vsk_, ssk_, and csk_ are secret to varying degrees. Only vpk_live_… and csk_live_… (which only ever receives pre-evaluated values) are safe to ship in client code. Never put a vsk_ or ssk_ key in the browser.

Keys are matched against a stored hash. The raw secret is also kept AES-encrypted so you can re-reveal it in the dashboard (Install & keys), but it is never returned to the browser.

Error shape

Errors return a non-2xx status with a JSON body. Most routes use:

{ "error": { "code": "not_found", "message": "experiment not found" } }

Some routes use the flatter form:

{ "error": "method_not_allowed", "message": "POST this endpoint" }

Handle both: read error.code if error is an object, otherwise read error as the code string.

Rate limiting

Requests are rate limited per IP and per auth failure. Repeated bad-key attempts are throttled harder than successful calls. If you hit a limit you will get a 429; back off and retry.

Versioning

The API is versioned in the path (/v1). Adding fields and endpoints is a forward-compatible, additive change, so new response fields can appear without a version bump. Breaking changes would ship under a new version prefix.

First request

List the project’s experiments:

curl https://versuch.ai/api/v1/experiments \
  -H "Authorization: Bearer vsk_live_..."

📸 Visual

Placeholder, the Install & keys panel showing the vsk_live_… management key and the reveal action. Source: dashboard (auth).

Reference

Experiments

Create and read A/B tests, set status, assign units, set metrics. Experiments →

Feature flags

Flags, per-environment targeting, and rules. Flags →

Config & evaluate

Client-config, compiled config, SSE, remote evaluate, exposures. Config →

Metrics & events

Metric definitions, track, and batch event ingest. Metrics →

Segments & environments

Reusable segments and environments. Segments →

Usage

Account usage vs plan limit. Usage →