API reference

Package: @fabricorg/experiments-api-protocol

The hosted API is defined through a zod-backed endpoint registry. The API client consumes the same protocol definitions.

Important route families:

• tenants: /api/v1/tenants/me
• organization helpers: /api/v1/organizations/generate-slug, /api/v1/organizations/resolve
• experiments: /api/v1/orgs/{orgId}/experiments
• manifests: /api/v1/orgs/{orgId}/manifests
• preview links: /api/v1/orgs/{orgId}/preview/sign
• public keys: /.well-known/jwks/{orgId}
• aggregate: /api/v1/orgs/{orgId}/experiments/{experimentId}/aggregate
• API keys: /api/v1/orgs/{orgId}/api-keys
• internal workers: /internal/audit-export/*, /internal/audit-forward/*

Authentication

Browser callers use Better Auth session cookies.

CLI and automation callers can use org API keys:

Authorization: Bearer fx_key_...

Create API keys in Studio at /app/{orgSlug}/settings.

Preview links and public keys

Sign preview token

POST /api/v1/orgs/{orgId}/preview/sign
Content-Type: application/json

{
  "experimentId": "homepage-cta",
  "variantKey": "treatment",
  "ttlSeconds": 900
}

Returns a short-lived JWT plus metadata:

{
  "token": "eyJhbGciOiJFZERTQSIs...",
  "expiresAt": "2026-05-08T20:22:00.000Z",
  "keyId": "init",
  "jti": "..."
}

Studio and fx preview place that token in a URL as:

?fxpreview=<experimentId>:<variantKey>&fxtoken=<jwt>

The token is signed with an org Ed25519 private key. The browser verifies it with public JWKS; no preview secret is embedded in customer HTML.

Public JWKS

GET /.well-known/jwks/{orgId}

Returns active/retiring Ed25519 public keys for manifest and preview-token verification. The Cloudflare manifest worker can proxy this path at the manifest origin.

API key endpoints

List keys

GET /api/v1/orgs/{orgId}/api-keys

Returns active keys with id, name, prefix, createdAt, and lastUsedAt.

Create key

POST /api/v1/orgs/{orgId}/api-keys
Content-Type: application/json

{
  "name": "CLI push from laptop",
  "expiresAt": null
}

Returns the same summary fields plus key. The plaintext key is returned once.

Revoke key

DELETE /api/v1/orgs/{orgId}/api-keys/{keyId}

Returns { "ok": true } when revoked.