API Reference

Base URL

The control plane listens on port 8000 by default in a customer self-host deployment. All paths in this reference are relative to that base.

http://localhost:8000

When fronted by the bundled reverse proxy, the same surface is reachable at the deployment’s public hostname.

Authentication

Most endpoints require an API key sent in the X-Gostly-Api-Key header. Generate one from the dashboard at /settings → API Keys, or call POST /v1/api-keys/generate against a seeded session. The raw key is returned once; only the prefix is retrievable afterwards.

curl -H "X-Gostly-Api-Key: gsk_..." \
     http://localhost:8000/v1/transition/jobs

Dashboard surfaces use the session cookie (gostly_session, HttpOnly + SameSite=Lax) instead of the API key. Programmatic / CI callers should always prefer the API key.

Tenancy

Every authenticated request is scoped to a single tenant. Tenant identity is derived from the license key at the API container; Postgres Row-Level Security enforces tenant isolation as a defense-in-depth layer beneath the application’s WHERE clauses. See Security for the structural invariants.

Error envelope

Errors return a structured JSON body with a stable error_code that callers should branch on, plus a human-readable detail for operator dashboards. Tier-gated 403s additionally carry the feature name so a client can render a tier-specific upgrade prompt.

{
  "detail":     "Mock not found",
  "error_code": "not_found"
}

Status → error_code mapping:

• 404 → not_found
• 422 → validation_error
• 403 → tenant_isolation | feature_gated (the latter carries feature)
• 409 → scrubbing_required
• 500 → internal_error (unclassified — alert)

Idempotency

Stripe-style. Side-effecting POSTs accept an Idempotency-Key header (any UUID-ish string the client picks). The server caches the response under (tenant_id, key)for 24h. A retry with the same key replays the cached response without re-firing the side effect — safe to use behind network retries.

# First call — actually enqueues the job
curl -X POST http://localhost:8000/v1/transition/start \
  -H "X-Gostly-Api-Key: gsk_..." \
  -H "Idempotency-Key: ci-build-42" \
  -H "Content-Type: application/json" \
  -d '{"service_id":"stripe"}'
# → 202 {"job_id":"abc-123","status":"queued"}

# Retry with the same key — same response, no new job
curl -X POST http://localhost:8000/v1/transition/start \
  -H "X-Gostly-Api-Key: gsk_..." \
  -H "Idempotency-Key: ci-build-42" \
  -d '{"service_id":"stripe"}'
# → 202 {"job_id":"abc-123","status":"queued"}   ← same job_id

Keys are tenant-scoped, so two tenants picking the same client UUID don’t collide. Don’t use the same key across endpoints intentionally — each (tenant, key) maps to one cached response.

Pagination

List endpoints accept limit + offset query params and return a count field on the current shape. A canonical envelope is being rolled out across endpoints:

{
  "data":     [...],
  "total":    N,
  "limit":    L,
  "offset":   O,
  "has_more": true | false
}

Migrations land one endpoint at a time so each can update its dashboard caller in lockstep. Until then, individual list endpoints carry their per-endpoint shape (mocks, proposals, events, ...) — check the per-section table below for the response key.

Rate limits

The control plane applies per-IP sliding-window limits on expensive operations:

• POST /v1/traffic/normalize — 10 / minute
• POST /v1/training/finetune — 3 / minute
• POST /v1/transition/start — 5 / minute
• POST /v1/eval/run — 6 / minute
• Global ceiling — 600 / minute / IP across all paths

Exceeding a limit returns 429 with a detailstring identifying the bucket. The current implementation is in-process — multi-replica deployments will see per-replica windows. The Caddy / Redis-backed upgrade is a planned follow-up.

Deprecation policy

When a path is renamed, the old path stays live for at least one release cycle. The OpenAPI schema marks deprecated paths with deprecated: true. Active deprecations:

• /v1/sequences/statecharts/* → canonical /v1/statecharts/*. The /v1/sequences/ infix dates back to the dropped recorded-sequences model; statecharts subsume it. New code should use the canonical path.

Health

Two endpoints with different latency contracts:

Dashboards + uptime checkers should hit /v1/health/summary. Reserve /health for when you actually need a fresh probe.

Mode control

Modes: LEARN (record), MOCK (serve recorded), PASSTHROUGH (forward, don’t record), TRANSITIONING(read-only during a LEARN → MOCK pipeline; returns 503 + Retry-After).

Services

A serviceis a registered upstream — the API binds traffic to it via either a hostname or a path prefix.

Mocks library

Traffic + transition

Traffic in LEARN mode flows into a per-service JSONL on the agent’s data volume. The transition pipeline promotes that traffic into the mock library, running PII scrub and pattern extraction along the way.

Drift detection

Drift detection runs schema diffs against your mock library and the live upstream. The dashboard surfaces it at /quality; the API is what powers it.

Statecharts

Statecharts (Bet #3 v2) define per-resource lifecycle for the mock engine — given an action on a resource, advance state and serve the appropriate response. Five bundled fixtures ship out of the box (charge, customer, invoice, order, subscription); tenants can override them or upload custom machines.

Webhooks

Inbound webhook capture + operator-triggered replay. Scheduled / fanout / re-signing replay is v2 (out of scope today).

Training (Pro+)

Per-service LoRA fine-tuning. The inference server spawns training as a background subprocess and webhooks progress back.

Operational