# HTTP API

> Lean API contract and state machines — V1 scope, endpoints, authentication, and the business processes behind each operation.

Source: https://docs.hatched.live/docs/reference/http-api

> Most integrations should use [`@hatched/sdk-js`](/docs/reference/sdk-js)
> rather than calling these endpoints directly — it handles auth, retries,
> idempotency, error parsing, and edge runtimes for you. Reach for raw HTTP
> only when there's no SDK for your language.

## Quick reference

| | |
| --- | --- |
| **Base URL (production)** | `https://api.hatched.live/api/v1` |
| **Base URL (staging)** | `https://api.staging.hatched.live/api/v1` |
| **Auth** | `Authorization: Bearer <key>` — secret key (`hatch_live_*` / `hatch_test_*`, server-only) or publishable key (`hatch_pk_*`, limited reads). Widgets pass a short-lived session token instead. See [Auth model](/docs/concepts/auth-model). |
| **Casing** | The raw HTTP API uses **`snake_case`** for every request and response field (`user_id`, `buddy_id`, `ttl_seconds`). Sending camelCase is rejected (`property userId should not exist`). [`@hatched/sdk-js`](/docs/reference/sdk-js) is the only place you write camelCase — it converts to `snake_case` on the wire and back on responses. SDK code samples (` ```ts `) use camelCase; raw HTTP samples (` ```http ` / curl) use `snake_case`. (The error envelope below is the one camelCase exception — `requestId`, not `request_id`.) |
| **First-run flow** | Minting a widget token requires an existing `buddy_id` — you can't go from `user_id` straight to a session token. The full path (published config → reuse-or-create egg → ready → hatch → poll operation → persist `buddy_id` → `POST /widget-sessions`) is in [First user bootstrap](/docs/guides/first-user-bootstrap). |
| **Errors** | Always the canonical envelope `{ "error": { "code", "message", "details?", "requestId" } }`. Codes are stable — branch on `code`, not `message`. See [Error codes](/docs/reference/error-codes). |
| **Request correlation** | Every request echoes an `X-Request-Id` header; it also appears in the error envelope, your logs, and outgoing webhook payloads. Include it in support requests. |
| **Idempotency** | Two separate mechanisms. (1) `POST /events` auto-dedupes on the `event_id` you supply — resending is a header-free no-op. (2) Any mutating write (`POST`/`PUT`/`PATCH`/`DELETE`) accepts an `Idempotency-Key` header: the response is cached for 24h, replaying the same key **and** body returns the cached response with an `Idempotency-Replayed: true` header, and reusing the key with a different body returns `409 idempotency_key_conflict`. The coin / token / purchase-item writes flagged `(supports idempotency)` in the [Endpoints](#endpoints) table are exactly these — set an `Idempotency-Key` before you retry them. Only successful responses are cached, so a failed mutation retries fresh. Still guard `POST /eggs` against React Strict Mode / focus re-runs (see the bootstrap guide), or use `?ensure=true`. |
| **Async work** | Image-producing calls (hatch, evolve, equip) return an `operationId`. Poll `GET /operations/{id}` or use `operations.wait(id)` in the SDK. Don't tight-loop. |
| **Pagination** | List endpoints return either `{ data, pagination: { nextCursor, hasMore, limit } }` (cursor-based — pass `cursor`) or `{ data, meta: { page, limit, total } }` (page-based — pass `page`). The key present (`pagination` vs `meta`) tells you which. See [Pagination](/docs/concepts/pagination). |
| **Rate limits** | Per-key quotas; `429` responses carry `Retry-After` and `X-RateLimit-*` headers. The SDK retries with backoff by default. See [Rate limits](/docs/reference/rate-limits). |
| **Billing** | `402` with `code: 'credit_insufficient'`, `event_quota_exceeded`, or `plan_feature_locked` when you hit a billing limit. See [Handling 402](/docs/billing/handling-402). |

The rest of this page is the V1 product contract — scope, state machines, and
the business processes behind each operation. The full machine-generated
endpoint list is in [Endpoints](#endpoints) below.

---

**Goal:** Position Hatched as a narrow-scope product that does one thing exceptionally well, rather than an "enterprise does-everything" platform.

This document clarifies three things:

1. Which business processes V1 definitively supports
2. Which state machines make the system deterministic
3. How the API contracts stay lean and easy to integrate

---

## 1. Product Philosophy

V1 targets for Hatched:

- Not a "platform" where the customer designs their own game
- A service that reliably produces buddy progression from the customer's existing product events

That's why V1 follows these principles:

- **Template-first**: limited rule types instead of a free-form rule language
- **Publish-before-live**: progression config changes are edited in draft, then published
- **Async-by-default**: visual-producing jobs are tracked via operations
- **Read vs write separation**: easy for widgets to read, tighter controls on mutations
- **Canonical state lives in Hatched**: customers may keep a local copy, but Hatched is the source of truth

---

## 2. V1 Scope

### 2.1 Definitely in V1

- Preset plan selection and customization
- Skill set definition
- Coin rules
- Badge rules
- Evolution readiness and evolution trigger
- Item marketplace
- Buddy widget
- Marketplace widget
- Event ingestion
- Webhook delivery
- Multi-buddy support

### 2.2 Not in V1

- Full no-code workflow builder
- Unlimited rule engine with if/else trees
- Cross-customer shared economy
- Buddy-to-buddy social graph
- Full user-level CRM
- Real-time multiplayer / competition engine
- Arbitrary CSS/JS execution on the customer side
- Custom approval flows tailored per customer need

### 2.3 Deliberately limited in V1

- Rule types are picked from fixed enums
- Widget theme is configurable but not an infinite design surface
- Evolution capped at 5 stages
- Token types start with a limited set of system tokens
- Marketplace visibility and requirement logic ships with predefined operators

---

## 3. User-Friendly Business Processes

### 3.1 Customer onboarding

Goal: ship an integration that's live in 10 minutes.

Flow:
1. Customer creates an account
2. Picks a preset plan
3. Lightly edits skill, badge, coin and evolution fields
4. Publishes the draft
5. Receives an API key
6. Sends the first `POST /events` request
7. Generates a widget token and embeds it

UI principles:
- First screen exposes at most 3 major decisions: preset, style, widget theme
- "Advanced" fields are collapsed by default in every editor
- No "empty page" feeling; the starter config from the preset is always visible

### 3.2 Progression config change

Goal: make changes without disturbing existing users' balance.

Flow:
1. Customer opens the draft config
2. Edits skill/badge/coin/evolution fields
3. System shows an impact summary:
   - affects new buddies
   - does not affect existing buddies
   - migration can be run separately on demand
4. Customer publishes
5. New `config_version` becomes active

UI principles:
- "Save" and "Publish" separation must be obvious
- Publish modal uses impact language, not technical jargon
- "This change does not retroactively affect existing buddies" must be clearly shown

### 3.3 Event-driven reward generation

Goal: the customer only sends the event; Hatched computes the reward.

Flow:
1. Customer sends the event via `POST /events`
2. Hatched deduplicates the event
3. Rule engine computes effects
4. Writes coin/token/badge/streak/evolution_ready effects
5. Emits a webhook if needed

UI principles:
- Dashboard shows "recent events" and "generated effects" side by side
- Debug screen gives a clear answer to "why didn't this event produce a reward?"

### 3.4 Hatch / equip / evolve

Goal: make visual-producing flows deterministic and understandable.

Flow:
1. Customer or widget initiates an action
2. API returns an `operation_id`
3. Worker finishes the job
4. Result arrives via webhook or polling

UI principles:
- "Processing..." is a first-class state
- Error messages are action-specific, not generic "Image generation failed"
- The user must not retry the same action in a panic

### 3.5 Widget access

Goal: easy to integrate, but controlled on the write side.

Modes:
- **Read-only embed**: buddy widget, leaderboard
- **Interactive session**: marketplace purchase, equip item

UI principles:
- Embed snippet must be short
- Token generation should feel like a "copy-paste snippet" experience
- A read-only embed should require the minimum possible backend integration

---

## 4. Canonical Domain Concepts

### 4.1 Customer

The B2B tenant that uses Hatched.

Owns:
- plan
- settings
- active_config_version_id

### 4.2 ConfigVersion

Immutable snapshot of progression logic.

Contains:
- skill set
- coin rules
- badge definitions
- evolution rules
- token rules
- marketplace requirements

### 4.3 Egg

The pending object before a buddy is born.

Rules:
- bound to a specific user
- created with a config_version
- transitions to a closed state once hatched

### 4.4 Buddy

A user-owned progression unit.

Rules:
- a user can own multiple buddies
- a buddy is pinned to a single config_version
- its version does not change unless migration happens

### 4.5 EventIngestion

The recorded external domain event from a customer.

Rules:
- `customer_id + event_id` is unique
- the same event does not produce a reward twice

### 4.6 EconomyLedger

Immutable ledger of coin/token mutations.

Rules:
- each row is a credit or a debit
- balance is a computed/projection field
- mutation endpoints write to the ledger

### 4.7 Operation

Record for tracking an asynchronous job.

Types:
- hatch
- equip_item
- evolve

---

## 5. State Machines

### 5.1 ConfigVersion State Machine

States:
- `draft`
- `published`
- `archived`

Transitions:
- `draft -> published`
- `published -> archived`

Rules:
- only one `published` version may be active
- publish creates a new version; it never mutates an existing one

### 5.2 Egg State Machine

States:
- `waiting`
- `ready`
- `hatching`
- `hatched`
- `cancelled`

Transitions:
- `waiting -> ready`
- `ready -> hatching`
- `hatching -> hatched`
- `waiting -> cancelled`
- `ready -> cancelled`

Rules:
- `hatch` may only be initiated from `ready`
- `hatching` persists until the operation completes

### 5.3 Buddy State Machine

The top-level buddy state is kept simple:

- `active`
- `archived`

A buddy's real variables are:
- `evolution_stage`
- `skills`
- `coins`
- `tokens`
- `equipped_items`

Rules:
- an attribute-based model is preferred over a progression state machine
- this keeps the UI simpler

### 5.4 Operation State Machine

States:
- `pending`
- `processing`
- `completed`
- `failed`
- `cancelled`

Transitions:
- `pending -> processing`
- `processing -> completed`
- `processing -> failed`
- `pending -> cancelled`

Rules:
- the client never treats the result as final until it sees `completed/failed`

### 5.5 WidgetSession State Machine

States:
- `issued`
- `active`
- `expired`
- `revoked`

Rules:
- read-only tokens may be longer-lived
- interactive tokens must be short-lived
- interactive tokens operate on scopes

---

## 6. Lean API Contract

### 6.1 Public integration endpoints

#### `POST /api/v1/eggs`

Purpose:
- create a pending egg record for a user

Query params:
- `ensure=true` — return this user's most recent `waiting`/`ready` egg if one
  already exists instead of creating a new one (idempotent first-run bootstrap;
  also dodges the per-user active-egg cap on retries).

Request:
```json
{
  "user_id": "user_123",
  "metadata": {
    "age": 12,
    "level": "beginner"
  }
}
```

Response:
```json
{
  "egg_id": "egg_abc",
  "status": "waiting",
  "visual_variant": 7,
  "config_version_id": "cfg_v12",
  "user_id": "user_123",
  "buddy_id": null,
  "metadata": { "age": 12, "level": "beginner" },
  "created_at": "2026-04-08T10:30:00Z"
}
```

`buddy_id` is `null` until the egg reaches `status: "hatched"`, after which it
carries the hatched buddy's id (same on `GET /api/v1/eggs/{egg_id}` and
`GET /api/v1/eggs`).

Errors:
- `409 no_published_config` — the customer has no published config version yet;
  `details.publish_url` links to the dashboard publish page.
- `409 active_egg_limit` — the per-user active-egg cap is reached; `details.active`
  lists the existing eggs (`egg_id`, `status`, `created_at`) and `details.max` the
  cap. Hatch/cancel one, or retry with `?ensure=true`.

#### `PATCH /api/v1/eggs/{egg_id}/status`

Purpose:
- mark the egg `ready` or cancel it

Allowed statuses:
- `ready`
- `cancelled`

#### `POST /api/v1/eggs/{egg_id}/hatch`

Purpose:
- kick off an async hatch operation

Response:
```json
{
  "accepted": true,
  "operation_id": "op_123",
  "status": "pending"
}
```

#### `POST /api/v1/events`

Purpose:
- ingest a customer domain event

Request:
```json
{
  "event_id": "evt_789",
  "user_id": "user_123",
  "type": "lesson_completed",
  "occurred_at": "2026-04-08T10:30:00Z",
  "audience": "students",
  "properties": {
    "lesson_id": "lesson_456",
    "score": 87
  }
}
```

`audience` is **optional for single-audience customers** (the server applies
the implicit default) but **required once you've defined 2+ audiences** — omit
it then and the call fails with `400 missing_audience`; send an unknown value
and it fails with `400 unknown_audience`. The value must match an audience key
configured in Dashboard → Audiences.

Response:
```json
{
  "accepted": true,
  "event_id": "evt_789",
  "effects": {
    "coins": 10,
    "badges_awarded": [],
    "tokens": [],
    "evolution_ready": false
  }
}
```

#### `GET /api/v1/buddies/{buddy_id}`

Purpose:
- return canonical buddy state

#### `POST /api/v1/buddies/{buddy_id}/evolve`

Purpose:
- start an async evolution operation

#### `PATCH /api/v1/buddies/{buddy_id}/equipped-items`

Purpose:
- start an equip/unequip operation

#### `GET /api/v1/operations/{operation_id}`

Purpose:
- read the status of a hatch/equip/evolve

### 6.2 Manual override endpoints

These endpoints ship in V1 but are not marketed as the "primary flow":

- `PATCH /buddies/{id}/skills`
- `POST /buddies/{id}/coins`
- `POST /buddies/{id}/coins/spend`
- `POST /buddies/{id}/badges`
- `POST /buddies/{id}/tokens`

Use cases:
- admin correction
- migration
- special campaign
- support operation

### 6.3 Widget endpoints

#### `POST /api/v1/widget-sessions`

Purpose:
- mint an interactive widget session token

Request:
```json
{
  "buddy_id": "b3d7c8a0-1234-4f5e-9abc-def012345678",
  "user_id": "user_42",
  "scopes": ["marketplace:purchase", "items:equip"]
}
```

Response:
```json
{
  "token": "wgt_sess_xxx",
  "session_id": "3d7ec5a4-7c47-41aa-a869-2e63e2d0d3c8",
  "expires_at": "2026-04-08T11:00:00Z",
  "scopes": ["marketplace:purchase", "items:equip"]
}
```

#### `POST /api/v1/embed-tokens`

Purpose:
- mint a signed token for a read-only widget

---

## 7. UX Guardrails for the Dashboard

### 7.1 Rule templates instead of a rule builder

The V1 panel must offer:

- Pick a trigger
- Pick a reward
- Pick a limit
- Preview impact

The V1 panel must NOT offer:

- nested if/else
- custom expression language
- event transformation DSL
- arbitrary JSON editor as the primary UX

### 7.2 Publish UX

Every progression editor follows this shape:

- Draft badge
- Unsaved changes indicator
- Publish CTA
- Impact summary
- "Publish a new version" instead of a rollback model

### 7.3 Support UX

Support/operator screens must surface:

- recent events
- effects generated from an event
- operation status
- the user's buddy list
- recent ledger activity

These screens exist for operational confidence, not enterprise complexity.

---

## 8. Business Process Decisions

### 8.1 What we keep centralized

Hatched owns the truth for:

- progression truth
- config version truth
- buddy ownership truth
- operation truth
- ledger truth

### 8.2 What we leave to the customer

The customer owns:

- event production
- user identity mapping
- when a product action emits an event
- maintaining the buddy ID list inside their own product UI
- which widget appears on which screen

### 8.3 What we deliberately don't build

- We do not move the customer's whole business logic into Hatched
- We are not a full BPM/workflow product
- We are not a CRM or engagement automation hub
- We do not build an infinitely configurable admin panel

---

## 9. Recommended V1 Motto

**"Customer events in, progression out."**

That's the strongest, simplest positioning for the product:

- The customer emits events
- Hatched computes progression
- The widget renders the result

Everything else is secondary.

## Endpoints

{/* ENDPOINTS_START */}

{/* AUTO-GENERATED from apps/api/openapi.public.json by apps/docs/scripts/generate-api-reference.ts. Run `pnpm --filter @hatched/api openapi:dump` first if the artifact is stale. */}

| Method | Path | Summary | Tag |
|---|---|---|---|
| `GET` | `/api/v1/analytics/activity-summary` | Get activity summary | Analytics |
| `GET` | `/api/v1/analytics/audiences` | Get audience breakdown | Analytics |
| `GET` | `/api/v1/analytics/custom-events` | Get custom event trends | Analytics |
| `GET` | `/api/v1/analytics/economy-health` | Get economy health | Analytics |
| `GET` | `/api/v1/analytics/economy-summary` | Get economy summary | Analytics |
| `GET` | `/api/v1/analytics/engagement` | Get engagement metrics | Analytics |
| `GET` | `/api/v1/analytics/event-counts` | Per-event counts | Analytics |
| `GET` | `/api/v1/analytics/evolution` | Get evolution timeline | Analytics |
| `GET` | `/api/v1/analytics/feature-activity` | Get feature activity | Analytics |
| `GET` | `/api/v1/analytics/marketplace-funnel` | Get marketplace funnel | Analytics |
| `GET` | `/api/v1/analytics/overview` | Get analytics overview | Analytics |
| `GET` | `/api/v1/analytics/popular-badges` | Get popular badges | Analytics |
| `GET` | `/api/v1/analytics/popular-items` | Get popular items | Analytics |
| `GET` | `/api/v1/analytics/retention` | Get retention metrics | Analytics |
| `GET` | `/api/v1/analytics/roi-metrics` | Get ROI metrics | Analytics |
| `GET` | `/api/v1/analytics/streaks` | Get streak health | Analytics |
| `GET` | `/api/v1/analytics/tokens` | Get per-token economy | Analytics |
| `GET` | `/api/v1/analytics/webhooks` | Get webhook delivery health | Analytics |
| `GET` | `/api/v1/auth/api-keys` | List all active API keys for the current customer | Auth |
| `POST` | `/api/v1/auth/api-keys` | Create a new API key | Auth |
| `DELETE` | `/api/v1/auth/api-keys/{id}` | Revoke an API key by its ID | Auth |
| `POST` | `/api/v1/auth/api-keys/rotate` | Rotate API keys by revoking all existing keys and creating a new one | Auth |
| `GET` | `/api/v1/auth/api-keys/whoami` | Return the identity, plan, capabilities, and scopes of the calling credential | Auth |
| `POST` | `/api/v1/auth/email/verification/request` | Request a fresh dashboard email verification link | Auth |
| `POST` | `/api/v1/auth/email/verify` | Verify dashboard account email with a one-time token | Auth |
| `POST` | `/api/v1/auth/login` | Authenticate and obtain a JWT token | Auth |
| `GET` | `/api/v1/auth/me` | Get the currently authenticated customer profile | Auth |
| `POST` | `/api/v1/auth/password/change` | Change the current dashboard account password | Auth |
| `POST` | `/api/v1/auth/password/reset` | Reset dashboard password with a one-time token | Auth |
| `POST` | `/api/v1/auth/password/reset/request` | Request a dashboard password reset token | Auth |
| `POST` | `/api/v1/auth/publishable-keys` | Issue a browser-safe publishable key (hatch_pk_*) with a scoped set of permissions. | Auth |
| `POST` | `/api/v1/auth/register` | Register a new customer account | Auth |
| `GET` | `/api/v1/auth/sso/callback` | Complete dashboard SSO callback from OIDC provider | Auth |
| `GET` | `/api/v1/auth/sso/config` | Return public dashboard SSO configuration | Auth |
| `GET` | `/api/v1/auth/sso/start` | Start dashboard SSO via generic OIDC | Auth |
| `GET` | `/api/v1/badge-definitions` | List all badge definitions | Badge Definitions |
| `POST` | `/api/v1/badge-definitions` | Create a badge definition | Badge Definitions |
| `DELETE` | `/api/v1/badge-definitions/{id}` | Delete a badge definition | Badge Definitions |
| `GET` | `/api/v1/badge-definitions/{id}` | Get a badge definition | Badge Definitions |
| `PUT` | `/api/v1/badge-definitions/{id}` | Update a badge definition | Badge Definitions |
| `POST` | `/api/v1/badge-definitions/{id}/regenerate-icon` | Queue an AI regeneration for this badge icon | Badge Definitions |
| `POST` | `/api/v1/badge-definitions/generate-icon` | Generate a badge icon with AI | Badge Definitions |
| `POST` | `/api/v1/badge-definitions/upload-icon` | Upload a badge icon | Badge Definitions |
| `POST` | `/api/v1/billing/checkout` | Create checkout session | Billing |
| `GET` | `/api/v1/billing/checkout/session/{id}` | Reconcile a Stripe checkout session | Billing |
| `POST` | `/api/v1/billing/portal` | Create billing portal session | Billing |
| `GET` | `/api/v1/billing/status` | Get billing status | Billing |
| `GET` | `/api/v1/buddies` | List buddies with pagination and optional filters | Buddies |
| `POST` | `/api/v1/buddies/{buddy_id}/appearance/rerender` | Regenerate the buddy stage base image | Buddies |
| `GET` | `/api/v1/buddies/{buddy_id}/badges` | List all badges awarded to a buddy | Buddies |
| `POST` | `/api/v1/buddies/{buddy_id}/badges` | Award a badge to a buddy | Buddies |
| `POST` | `/api/v1/buddies/{buddy_id}/coins` | Earn coins for a buddy (supports idempotency) | Buddies |
| `POST` | `/api/v1/buddies/{buddy_id}/coins/spend` | Spend coins for a buddy (supports idempotency) | Buddies |
| `PATCH` | `/api/v1/buddies/{buddy_id}/equipped-items` | Equip or unequip items on a buddy | Buddies |
| `GET` | `/api/v1/buddies/{buddy_id}/evolution` | Check evolution readiness and progress for a buddy | Buddies |
| `GET` | `/api/v1/buddies/{buddy_id}/evolutions` | Stage transition timeline for a buddy | Buddies |
| `POST` | `/api/v1/buddies/{buddy_id}/evolve` | Trigger asynchronous buddy evolution | Buddies |
| `POST` | `/api/v1/buddies/{buddy_id}/gates/{gate_key}/unlock` | Spend tokens to unlock a gate for a buddy | Gates |
| `GET` | `/api/v1/buddies/{buddy_id}/progression` | Get buddy progression metrics (legacy endpoint) | Buddies |
| `GET` | `/api/v1/buddies/{buddy_id}/progression-metrics` | Get buddy progression metrics (lessons, quizzes, streaks, etc.) | Buddies |
| `POST` | `/api/v1/buddies/{buddy_id}/purchase-item` | Purchase a marketplace item using coins (supports idempotency) | Buddies |
| `GET` | `/api/v1/buddies/{buddy_id}/purchased-items` | List all purchased items for a buddy | Buddies |
| `GET` | `/api/v1/buddies/{buddy_id}/tokens` | Typed token balances (primary + progression) | Buddies |
| `POST` | `/api/v1/buddies/{buddy_id}/tokens` | Earn or spend tokens for a buddy (supports idempotency) | Buddies |
| `POST` | `/api/v1/buddies/{buddy_id}/unlock-item` | Unlock an item without spending coins | Buddies |
| `GET` | `/api/v1/buddies/{buddy_id}/unlocks` | List gates this buddy has unlocked | Gates |
| `GET` | `/api/v1/buddies/{id}` | Get buddy details with full canonical state | Buddies |
| `PATCH` | `/api/v1/buddies/{id}` | Update a buddy name | Buddies |
| `PATCH` | `/api/v1/buddies/{id}/archive` | Archive a buddy (one-way transition from active to archived) | Buddies |
| `POST` | `/api/v1/buddies/{id}/share` | Mint (or fetch) the public share link for a buddy | Buddies |
| `POST` | `/api/v1/buddies/{id}/share/events` | Record a share-sheet funnel event (opened / shared) | Buddies |
| `PATCH` | `/api/v1/buddies/{id}/skills` | Update buddy skill levels (increase, decrease, or set) | Buddies |
| `GET` | `/api/v1/buddies/users/{user_id}/summary` | Get a user summary including buddy count, coins, and badges | Buddies |
| `GET` | `/api/v1/buddy-share/settings` | Tenant buddy-share settings (toggles + resolved link origin) | Buddies |
| `PATCH` | `/api/v1/buddy-share/settings` | Update buddy-share toggles (enabled / show_tenant_name / cta_url) | Buddies |
| `GET` | `/api/v1/buddy-share/stats` | Rolling-window buddy-share funnel for the tenant | Buddies |
| `GET` | `/api/v1/coin-rules` | List all coin rules | Coin Rules |
| `POST` | `/api/v1/coin-rules` | Create a coin rule | Coin Rules |
| `DELETE` | `/api/v1/coin-rules/{id}` | Delete a coin rule | Coin Rules |
| `PUT` | `/api/v1/coin-rules/{id}` | Update a coin rule | Coin Rules |
| `GET` | `/api/v1/coin-rules/{id}/reward-pool/telemetry` | Reward pool telemetry | Coin Rules |
| `GET` | `/api/v1/config-versions` | List config versions | Config Versions |
| `POST` | `/api/v1/config-versions` | Create or open the draft config version | Config Versions |
| `GET` | `/api/v1/config-versions/{id}` | Get config version | Config Versions |
| `PATCH` | `/api/v1/config-versions/{id}` | Update config version | Config Versions |
| `POST` | `/api/v1/config-versions/{id}/clone` | Clone config version | Config Versions |
| `GET` | `/api/v1/config-versions/{id}/impact` | Preview config impact | Config Versions |
| `POST` | `/api/v1/config-versions/{id}/migrate-buddies` | Migrate buddies | Config Versions |
| `POST` | `/api/v1/config-versions/{id}/publish` | Publish config version | Config Versions |
| `GET` | `/api/v1/credits/balance` | Get credit balance | Credits |
| `GET` | `/api/v1/credits/ledger` | List recent AI usage ledger entries | Credits |
| `GET` | `/api/v1/customers/me` |  | Customers |
| `PATCH` | `/api/v1/customers/me` |  | Customers |
| `GET` | `/api/v1/customers/me/analytics/share-funnel` | Public share-page gift funnel (gift CTA + signup wall) | Analytics |
| `POST` | `/api/v1/customers/me/apply-preset` | Apply preset | Presets |
| `POST` | `/api/v1/customers/me/assets/regenerate` | Bulk regenerate AI assets | Customers |
| `PATCH` | `/api/v1/customers/me/audiences` | Replace the customer audience list | Customers |
| `GET` | `/api/v1/customers/me/awards` | Customer-wide HR award audit log | Customers |
| `GET` | `/api/v1/customers/me/beginners-luck/analytics` | Beginner's Luck winner analytics | Customers |
| `POST` | `/api/v1/customers/me/boosters/grant` | Grant a catalog booster to a buddy (admin one-off) | Customers |
| `GET` | `/api/v1/customers/me/brag/by-channel` | Channel × event_kind click / completion matrix | Customers |
| `GET` | `/api/v1/customers/me/brag/config` | Get the Brag Button channel + copy-template config | Customers |
| `PATCH` | `/api/v1/customers/me/brag/config` | Update channel toggles, copy templates and webhook URLs | Customers |
| `GET` | `/api/v1/customers/me/brag/funnel` | Brag funnel aggregate over a date window | Customers |
| `GET` | `/api/v1/customers/me/brag/telemetry.csv` | Export raw brag telemetry as CSV | Customers |
| `POST` | `/api/v1/customers/me/brag/webhook-test` | Send a dummy message to a Slack/Teams webhook URL | Customers |
| `GET` | `/api/v1/customers/me/causes` | List the tenant Cause Counter definitions | Customers |
| `POST` | `/api/v1/customers/me/causes` | Create a Cause Counter definition | Customers |
| `DELETE` | `/api/v1/customers/me/causes/{id}` | Delete a Cause Counter definition | Customers |
| `PATCH` | `/api/v1/customers/me/causes/{id}` | Update a Cause Counter definition | Customers |
| `POST` | `/api/v1/customers/me/causes/{id}/draft` | Stage draft edits for a published Cause Counter definition | Customers |
| `GET` | `/api/v1/customers/me/causes/{id}/preview-30-days` | Project symbolic units from the last 30 days of eligible events for a saved cause | Customers |
| `GET` | `/api/v1/customers/me/causes/{id}/webhook` | HTCH-106 — F4.5 cause webhook config + recent delivery attempts | Customers |
| `PATCH` | `/api/v1/customers/me/causes/{id}/webhook` | HTCH-106 — F4.5 set the cause webhook URL, secret and threshold step | Customers |
| `POST` | `/api/v1/customers/me/causes/{id}/webhook/test` | HTCH-106 — F4.5 send a test cause.threshold_reached event and return the delivery outcome inline | Customers |
| `GET` | `/api/v1/customers/me/causes/analytics` | HTCH-107 — F4.5 Humanity Hero admin analytics: customer-wide and per-team contribution rollups, time series, threshold ETA and webhook delivery health (Planner drawer "Analytics" tab) | Customers |
| `GET` | `/api/v1/customers/me/causes/analytics.csv` | HTCH-107 — download the cause analytics as a CSV attachment | Customers |
| `GET` | `/api/v1/customers/me/causes/audit` | HTCH-71 — paginated Cause Counter change history (drawer) | Customers |
| `GET` | `/api/v1/customers/me/causes/preview-30-days` | HTCH-71 — project symbolic units for an unsaved rate config (the drawer rate builder simulation) | Customers |
| `DELETE` | `/api/v1/customers/me/council/narrative/slots/{slot}` | Retire the live proposal in a slot and restore the default copy | Customers |
| `PUT` | `/api/v1/customers/me/council/narrative/slots/{slot}` | Promote an approved proposal into a live narrative slot | Customers |
| `GET` | `/api/v1/customers/me/council/proposals` | The Council narrative-proposal moderation queue | Customers |
| `PATCH` | `/api/v1/customers/me/council/proposals/{id}` | Approve or reject a pending proposal | Customers |
| `GET` | `/api/v1/customers/me/event-badges` | List event-triggered badge campaigns | Customers |
| `POST` | `/api/v1/customers/me/event-badges` | Create an event-triggered badge campaign | Customers |
| `DELETE` | `/api/v1/customers/me/event-badges/{id}` | Delete an event-triggered badge campaign | Customers |
| `PATCH` | `/api/v1/customers/me/event-badges/{id}` | Update an event-triggered badge campaign | Customers |
| `GET` | `/api/v1/customers/me/feature-config` | Get the tenant feature_config blob | Customers |
| `PATCH` | `/api/v1/customers/me/feature-config/{feature_key}` | Update one feature_config block | Customers |
| `GET` | `/api/v1/customers/me/feature-toggles` | Get the tenant feature toggle state | Customers |
| `PATCH` | `/api/v1/customers/me/feature-toggles` | Update tenant feature toggles | Customers |
| `DELETE` | `/api/v1/customers/me/feature-toggles/draft` | Discard the pending draft toggle map | Customers |
| `POST` | `/api/v1/customers/me/feature-toggles/publish` | Publish the pending draft toggle map | Customers |
| `GET` | `/api/v1/customers/me/flash-sales` | List flash sales for the Planner drawer | Customers |
| `POST` | `/api/v1/customers/me/flash-sales` | Schedule a flash sale | Customers |
| `DELETE` | `/api/v1/customers/me/flash-sales/{id}` | Cancel a flash sale — a running sale clears its discounts | Customers |
| `GET` | `/api/v1/customers/me/founding-cohort/audit` | Paginated Founding Cohort assignment history | Customers |
| `GET` | `/api/v1/customers/me/founding-cohort/audit/export.csv` | Export the full Founding Cohort assignment history as CSV | Customers |
| `POST` | `/api/v1/customers/me/founding-cohort/backfill` | Retroactively mark every currently-eligible buddy (idempotent) | Customers |
| `GET` | `/api/v1/customers/me/founding-cohort/preview` | Project how many buddies the Founding Cohort config would mark. Optional query params preview an unsaved mode/threshold. | Customers |
| `GET` | `/api/v1/customers/me/group-quests` | List the tenant Group Quests (filter by status / team) | Customers |
| `POST` | `/api/v1/customers/me/group-quests` | Create a Group Quest (status: draft) | Customers |
| `DELETE` | `/api/v1/customers/me/group-quests/{questId}` | Delete a Group Quest (draft / cancelled only) | Customers |
| `PATCH` | `/api/v1/customers/me/group-quests/{questId}` | Update a Group Quest — draft fields, active deadline-extension, or cancel | Customers |
| `POST` | `/api/v1/customers/me/group-quests/{questId}/force-resolve` | HTCH-56 — manually resolve a Group Quest now (admin watchdog override) | Customers |
| `POST` | `/api/v1/customers/me/group-quests/{questId}/publish` | Publish a draft Group Quest (draft → active) | Customers |
| `GET` | `/api/v1/customers/me/hosted-surfaces` | List the customer’s hosted surfaces | Customers |
| `POST` | `/api/v1/customers/me/hosted-surfaces` | Create a hosted surface from a template | Customers |
| `GET` | `/api/v1/customers/me/hosted-surfaces/{id}` | Fetch one hosted surface (admin lens) | Customers |
| `PATCH` | `/api/v1/customers/me/hosted-surfaces/{id}` | Update name / theme / layout / mode / widget version | Customers |
| `POST` | `/api/v1/customers/me/hosted-surfaces/{id}/archive` |  | Customers |
| `POST` | `/api/v1/customers/me/hosted-surfaces/{id}/logo` | Upload a hosted surface logo and attach it to the public shell theme | Customers |
| `GET` | `/api/v1/customers/me/hosted-surfaces/{id}/players` |  | Customers |
| `POST` | `/api/v1/customers/me/hosted-surfaces/{id}/players` | Add a player. Provide buddy_id to link an existing buddy or display_name to mint a new one. | Customers |
| `PATCH` | `/api/v1/customers/me/hosted-surfaces/{id}/players/{playerId}` |  | Customers |
| `GET` | `/api/v1/customers/me/hosted-surfaces/{id}/players/{playerId}/access-code` | Re-view a player’s current access code + QR token without rotating them. Returns available:false for players created before encrypted-at-rest storage existed — regenerate once to mint a re-viewable copy. Audited. | Customers |
| `POST` | `/api/v1/customers/me/hosted-surfaces/{id}/players/{playerId}/regenerate-access` |  | Customers |
| `POST` | `/api/v1/customers/me/hosted-surfaces/{id}/publish` |  | Customers |
| `GET` | `/api/v1/customers/me/hosted-surfaces/{id}/readiness` | Per-widget content readiness for the go-live checklist | Customers |
| `GET` | `/api/v1/customers/me/hosted-surfaces/{id}/recipes` |  | Customers |
| `POST` | `/api/v1/customers/me/hosted-surfaces/{id}/recipes` |  | Customers |
| `POST` | `/api/v1/customers/me/hosted-surfaces/{id}/recipes/{key}/run` |  | Customers |
| `POST` | `/api/v1/customers/me/hosted-surfaces/{id}/unpublish` |  | Customers |
| `GET` | `/api/v1/customers/me/kudo-types` | List the effective kudo taxonomy | Customers |
| `POST` | `/api/v1/customers/me/kudo-types` | Create a custom kudo type | Customers |
| `DELETE` | `/api/v1/customers/me/kudo-types/{id}` | Archive a kudo type (soft delete) | Customers |
| `PATCH` | `/api/v1/customers/me/kudo-types/{id}` | Update a kudo type | Customers |
| `POST` | `/api/v1/customers/me/kudo-types/apply-template` | Apply an industry preset taxonomy | Customers |
| `POST` | `/api/v1/customers/me/kudo-types/apply-theme-template` | Apply a theme-aware kudos pack (HTCH-128) | Customers |
| `PATCH` | `/api/v1/customers/me/kudo-types/reorder` | Persist a new display order | Customers |
| `GET` | `/api/v1/customers/me/leaderboard-config` | Get the tenant leaderboard view-mode config | Customers |
| `PATCH` | `/api/v1/customers/me/leaderboard-config` | Update the tenant leaderboard view-mode config | Customers |
| `GET` | `/api/v1/customers/me/leagues/config` | Full tier ladder, cohort/cadence config and season state | Customers |
| `PATCH` | `/api/v1/customers/me/leagues/config` | Update the cohort maths, season cadence and off-season window | Customers |
| `POST` | `/api/v1/customers/me/leagues/seasons` | Schedule the next upcoming season | Customers |
| `POST` | `/api/v1/customers/me/leagues/seasons/{seasonId}/force-close` | Manually trigger the rollover for a season (audit logged) | Customers |
| `POST` | `/api/v1/customers/me/leagues/seasons/preview` | Project the next three season windows (no write) | Customers |
| `PUT` | `/api/v1/customers/me/leagues/tiers` | Bulk-replace the tier ladder — 409 if a removed tier still has buddies | Customers |
| `GET` | `/api/v1/customers/me/lotteries` | List lottery definitions for the Planner | Customers |
| `POST` | `/api/v1/customers/me/lotteries` | Create a lottery definition | Customers |
| `DELETE` | `/api/v1/customers/me/lotteries/{id}` | Soft-delete a lottery (history stays queryable) | Customers |
| `PATCH` | `/api/v1/customers/me/lotteries/{id}` | Update a lottery definition | Customers |
| `GET` | `/api/v1/customers/me/lotteries/{id}/draws` | Past draw history + analytics for a lottery | Customers |
| `GET` | `/api/v1/customers/me/lotteries/{id}/preview-next-draw` | Current-period entry count + next draw time for the preview card | Customers |
| `POST` | `/api/v1/customers/me/lotteries/{id}/simulate-draw` | Simulate a draw with the current entries — no rewards granted | Customers |
| `GET` | `/api/v1/customers/me/mentor-visibility/config` | Get the mentor-visibility config | Customers |
| `PATCH` | `/api/v1/customers/me/mentor-visibility/config` | Update the mentor-visibility config | Customers |
| `GET` | `/api/v1/customers/me/mentor-visibility/directory` | List every active mentor across the tenant’s teams | Customers |
| `DELETE` | `/api/v1/customers/me/mentor-visibility/sessions` | Reset all mentor session logs for the workspace | Customers |
| `GET` | `/api/v1/customers/me/mission-anchor-config` | Get the Mission Anchor admin config | Customers |
| `PATCH` | `/api/v1/customers/me/mission-anchor-config` | Update the Mission Anchor admin config | Customers |
| `GET` | `/api/v1/customers/me/narrative` | Get the tenant narrative state | Customers |
| `PATCH` | `/api/v1/customers/me/narrative` | Update the tenant narrative | Customers |
| `GET` | `/api/v1/customers/me/narrative/audit` | List narrative copy change history | Customers |
| `GET` | `/api/v1/customers/me/octalysis-state` | Get the tenant Octalysis aggregate state | Customers |
| `GET` | `/api/v1/customers/me/onboarding/six-d` | Get the tenant 6D wizard state | Customers |
| `PATCH` | `/api/v1/customers/me/onboarding/six-d` | Patch one or more 6D wizard sections | Customers |
| `POST` | `/api/v1/customers/me/onboarding/six-d` | Apply the full 6D wizard payload | Customers |
| `GET` | `/api/v1/customers/me/onboarding/six-d/audit` | HTCH-137 — Audit timeline | Customers |
| `GET` | `/api/v1/customers/me/onboarding/six-d/drift-stats` | HTCH-137 — Config drift stats | Customers |
| `POST` | `/api/v1/customers/me/onboarding/six-d/skip` | HTCH-137 — Expert skip | Customers |
| `POST` | `/api/v1/customers/me/players/{buddyId}/award` | HR Award Drawer — grant a badge / skill_event / coin / kudo / forced evolution to a buddy | Customers |
| `GET` | `/api/v1/customers/me/players/{buddyId}/awards` | Recent HR awards for a buddy (audit lens) | Customers |
| `GET` | `/api/v1/customers/me/profile-templates` | List profile-page templates (system + custom) | Customers |
| `POST` | `/api/v1/customers/me/profile-templates` | Create a profile-page template | Customers |
| `DELETE` | `/api/v1/customers/me/profile-templates/{id}` | Delete a profile-page template | Customers |
| `PATCH` | `/api/v1/customers/me/profile-templates/{id}` | Update a profile-page template | Customers |
| `POST` | `/api/v1/customers/me/profile-templates/apply-bulk` | Assign a template to many buddies in one statement | Customers |
| `GET` | `/api/v1/customers/me/referral` | Get the current workspace referral link | Customers |
| `PATCH` | `/api/v1/customers/me/settings` |  | Customers |
| `GET` | `/api/v1/customers/me/showrooms` | List the customer’s Showroom pages | Customers |
| `POST` | `/api/v1/customers/me/showrooms` | Create a Showroom page from a template | Customers |
| `GET` | `/api/v1/customers/me/showrooms/{id}` | Fetch one Showroom page (admin lens) | Customers |
| `PATCH` | `/api/v1/customers/me/showrooms/{id}` | Update layout / header / visibility | Customers |
| `POST` | `/api/v1/customers/me/showrooms/{id}/archive` | Archive a Showroom (hidden from list, kept for audit) | Customers |
| `POST` | `/api/v1/customers/me/showrooms/{id}/publish` | Publish a Showroom (status → published) | Customers |
| `POST` | `/api/v1/customers/me/showrooms/{id}/regenerate-qr` | Rotate the QR token, invalidating any printed code | Customers |
| `POST` | `/api/v1/customers/me/showrooms/{id}/unpublish` | Unpublish a Showroom (status → draft) | Customers |
| `GET` | `/api/v1/customers/me/streak-at-risk/analytics` | Streak-at-risk volume + recovery analytics for the Planner drawer | Customers |
| `GET` | `/api/v1/customers/me/surprise-drops` | List surprise-drop definitions for the Planner | Customers |
| `POST` | `/api/v1/customers/me/surprise-drops` | Create a custom surprise drop | Customers |
| `DELETE` | `/api/v1/customers/me/surprise-drops/{id}` | Delete a custom surprise drop | Customers |
| `PATCH` | `/api/v1/customers/me/surprise-drops/{id}` | Update a surprise drop — global templates edit copy-on-write | Customers |
| `GET` | `/api/v1/customers/me/teams` | List the tenant teams with member counts | Customers |
| `POST` | `/api/v1/customers/me/teams` | Create a team | Customers |
| `DELETE` | `/api/v1/customers/me/teams/{teamId}` | Soft-delete a team and archive its memberships | Customers |
| `PATCH` | `/api/v1/customers/me/teams/{teamId}` | Update a team | Customers |
| `GET` | `/api/v1/customers/me/teams/{teamId}/members` | List the active members of a team | Customers |
| `POST` | `/api/v1/customers/me/teams/{teamId}/members` | Add a buddy to a team | Customers |
| `DELETE` | `/api/v1/customers/me/teams/{teamId}/members/{buddyId}` | Remove a buddy from a team (soft leave) | Customers |
| `PATCH` | `/api/v1/customers/me/teams/{teamId}/members/{buddyId}` | Change a member role | Customers |
| `POST` | `/api/v1/customers/me/teams/import` | Bulk-import team memberships from a CSV | Customers |
| `DELETE` | `/api/v1/customers/me/users/{user_id}/data` |  | Customers |
| `GET` | `/api/v1/customers/me/users/{user_id}/summary` |  | Customers |
| `GET` | `/api/v1/customers/me/vacation/analytics` | Vacation usage analytics for the Planner drawer panel | Customers |
| `POST` | `/api/v1/customers/me/widget-theme/suggest` | Suggest widget theme customization | Customers |
| `GET` | `/api/v1/economy/buddies/{buddyId}/ledger` | Get coin ledger for a buddy | Economy |
| `GET` | `/api/v1/eggs` | List eggs with optional user and status filters | Eggs |
| `POST` | `/api/v1/eggs` | Create a new egg for a user | Eggs |
| `GET` | `/api/v1/eggs/{id}` | Get an egg by its ID | Eggs |
| `POST` | `/api/v1/eggs/{id}/hatch` | Start the asynchronous hatch process for an egg | Eggs |
| `PATCH` | `/api/v1/eggs/{id}/status` | Update an egg status to ready or cancelled | Eggs |
| `POST` | `/api/v1/embed-tokens` | Create embed token | Widget Sessions |
| `GET` | `/api/v1/event-types` | List event types | Event Types |
| `POST` | `/api/v1/event-types` | Register an event type | Event Types |
| `DELETE` | `/api/v1/event-types/{id}` | Delete an event type | Event Types |
| `GET` | `/api/v1/event-types/{id}` | Get an event type | Event Types |
| `PUT` | `/api/v1/event-types/{id}` | Update or rename an event type | Event Types |
| `GET` | `/api/v1/events` | List events | Events |
| `POST` | `/api/v1/events` | Ingest event | Events |
| `GET` | `/api/v1/events/{id}` | Get event | Events |
| `GET` | `/api/v1/events/active-users` | List most-active users in a recent window | Events |
| `POST` | `/api/v1/events/admin-trigger` | Trigger an event from the dashboard admin tools | Events |
| `POST` | `/api/v1/events/batch` | Ingest event batch | Events |
| `GET` | `/api/v1/events/types` | List distinct event types | Events |
| `GET` | `/api/v1/gates` | List token gates for this customer | Gates |
| `DELETE` | `/api/v1/gates/{gate_key}` | Delete a token gate | Gates |
| `PUT` | `/api/v1/gates/{gate_key}` | Create or update a token gate | Gates |
| `GET` | `/api/v1/health` | Health check | Health |
| `GET` | `/api/v1/health/live` | Liveness check | Health |
| `GET` | `/api/v1/health/ready` | Readiness check | Health |
| `GET` | `/api/v1/health/version` | Build metadata | Health |
| `GET` | `/api/v1/image-usage` | Get image usage | Image Generation |
| `GET` | `/api/v1/image-usage/report` | Get image usage report | Image Generation |
| `POST` | `/api/v1/marketing/cta` | Record a public marketing CTA click | Marketing |
| `GET` | `/api/v1/marketplaces` | List marketplaces | Marketplace |
| `POST` | `/api/v1/marketplaces` | Create marketplace | Marketplace |
| `GET` | `/api/v1/marketplaces/{id}` | Get marketplace | Marketplace |
| `PUT` | `/api/v1/marketplaces/{id}` | Update marketplace | Marketplace |
| `GET` | `/api/v1/marketplaces/{id}/items` | List items | Marketplace |
| `POST` | `/api/v1/marketplaces/{id}/items` | Create item | Marketplace |
| `DELETE` | `/api/v1/marketplaces/{id}/items/{item_id}` | Delete item | Marketplace |
| `GET` | `/api/v1/marketplaces/{id}/items/{item_id}` | Get item | Marketplace |
| `PUT` | `/api/v1/marketplaces/{id}/items/{item_id}` | Update item | Marketplace |
| `POST` | `/api/v1/marketplaces/{id}/items/{item_id}/regenerate-image` | Queue an AI regeneration for this item image | Marketplace |
| `POST` | `/api/v1/marketplaces/{id}/items/{item_id}/upload-image` | Upload item image | Marketplace |
| `POST` | `/api/v1/marketplaces/{id}/items/import` | Import items | Marketplace |
| `POST` | `/api/v1/marketplaces/{id}/items/reorder` | Reorder items | Marketplace |
| `POST` | `/api/v1/onboarding/sessions` | Create or resume the current onboarding session | Onboarding |
| `PUT` | `/api/v1/onboarding/sessions/{id}/answers` | Patch structured onboarding answers | Onboarding |
| `POST` | `/api/v1/onboarding/sessions/{id}/apply` | Apply the generated plan to the customer (writes gamification config) | Onboarding |
| `POST` | `/api/v1/onboarding/sessions/{id}/generate-guide` | Generate a personalized integration guide | Onboarding |
| `POST` | `/api/v1/onboarding/sessions/{id}/generate-plan` | Generate a gamification plan from the conversation | Onboarding |
| `POST` | `/api/v1/onboarding/sessions/{id}/message` | Send a user message and stream the assistant reply via server-sent events | Onboarding |
| `POST` | `/api/v1/onboarding/sessions/{id}/regenerate-plan` | Regenerate the plan with a variant seed | Onboarding |
| `GET` | `/api/v1/onboarding/sessions/current` | Fetch the current onboarding session | Onboarding |
| `GET` | `/api/v1/onboarding/sessions/preparing-status` | Aggregate asset-generation status for the current customer | Onboarding |
| `POST` | `/api/v1/onboarding/sessions/reset` | Reset the current onboarding session | Onboarding |
| `POST` | `/api/v1/onboarding/sessions/seed-from-description` | Seed onboarding from operator-provided chips + optional description | Onboarding |
| `POST` | `/api/v1/onboarding/sessions/seed-from-repo` | Seed onboarding from a repo-analysis brief produced by a local AI agent | Onboarding |
| `POST` | `/api/v1/onboarding/sessions/seed-from-url` | Seed onboarding from a landing-page URL | Onboarding |
| `POST` | `/api/v1/onboarding/sessions/waitlist` | Join the waitlist for an upcoming onboarding channel | Onboarding |
| `GET` | `/api/v1/operations` | List operations with optional type and status filters | Operations |
| `GET` | `/api/v1/operations/{id}` | Get an operation by its ID | Operations |
| `POST` | `/api/v1/operations/{id}/cancel` | Cancel a pending or processing operation | Operations |
| `GET` | `/api/v1/p/{code}` | Resolve a share code to the rich Profile Page v1 payload | Public Share |
| `GET` | `/api/v1/path-definitions` | List path definitions | Path Definitions |
| `POST` | `/api/v1/path-definitions` | Create a path definition | Path Definitions |
| `DELETE` | `/api/v1/path-definitions/{id}` | Delete a path definition | Path Definitions |
| `GET` | `/api/v1/path-definitions/{id}` | Get a path definition (with steps + sub-steps) | Path Definitions |
| `PUT` | `/api/v1/path-definitions/{id}` | Update a path definition | Path Definitions |
| `POST` | `/api/v1/path-definitions/{id}/activate` | Activate a path (atomic single-active per audience) | Path Definitions |
| `POST` | `/api/v1/path-definitions/{id}/deactivate` | Deactivate a path | Path Definitions |
| `GET` | `/api/v1/path-definitions/{id}/steps` | List steps in a path | Path Definitions |
| `POST` | `/api/v1/path-definitions/{id}/steps` | Create a step in a path | Path Definitions |
| `DELETE` | `/api/v1/path-definitions/{id}/steps/{stepId}` | Delete a step | Path Definitions |
| `PUT` | `/api/v1/path-definitions/{id}/steps/{stepId}` | Update a step | Path Definitions |
| `GET` | `/api/v1/path-definitions/{id}/steps/{stepId}/sub-steps` | List sub-steps within a step | Path Definitions |
| `POST` | `/api/v1/path-definitions/{id}/steps/{stepId}/sub-steps` | Create a sub-step | Path Definitions |
| `DELETE` | `/api/v1/path-definitions/{id}/steps/{stepId}/sub-steps/{subStepId}` | Delete a sub-step | Path Definitions |
| `PUT` | `/api/v1/path-definitions/{id}/steps/{stepId}/sub-steps/{subStepId}` | Update a sub-step | Path Definitions |
| `PUT` | `/api/v1/path-definitions/{id}/steps/{stepId}/sub-steps/reorder` | Reorder sub-steps within a step | Path Definitions |
| `PUT` | `/api/v1/path-definitions/{id}/steps/reorder` | Reorder steps in a path | Path Definitions |
| `GET` | `/api/v1/path-definitions/buddies/{buddyId}/paths/{pathKey}` | Get path runtime payload for a buddy | Path Definitions |
| `POST` | `/api/v1/path-definitions/buddies/{buddyId}/paths/{pathKey}/sub-steps/{subKey}/complete` | Manually mark a sub-step complete (admin) | Path Definitions |
| `GET` | `/api/v1/players/zero` | Read Player Zero status without provisioning it | Widget Sessions |
| `POST` | `/api/v1/players/zero` | Create or get the workspace demo player (Player Zero) | Widget Sessions |
| `GET` | `/api/v1/presets` | List presets | Presets |
| `GET` | `/api/v1/presets/{key}` | Get preset | Presets |
| `GET` | `/api/v1/public/b/{code}` | Resolve a buddy share code to its public card data | Public Share |
| `POST` | `/api/v1/public/b/{code}/events` | Record a share-page funnel event (viewed / cta_clicked) | Public Share |
| `GET` | `/api/v1/public/hall-of-fame-index` | List public Hall of Fame season URLs (paged) | Public Hall of Fame |
| `GET` | `/api/v1/public/hall-of-fame/{tenantSlug}` | List a tenant's finalized Hall of Fame seasons | Public Hall of Fame |
| `GET` | `/api/v1/public/hall-of-fame/{tenantSlug}/{seasonId}` | One finalized season in the public Hall of Fame | Public Hall of Fame |
| `GET` | `/api/v1/public/hosted-surfaces/{slug}` | Resolve a hosted surface slug to its public config (theme, layout, loader URL, auth requirement). | Public Share |
| `POST` | `/api/v1/public/hosted-surfaces/{slug}/session` | Exchange an access code or QR token for a short-lived widget session token. | Public Share |
| `GET` | `/api/v1/public/returning-champion/welcome-back` | Resolve a Returning Champion welcome-back token to a widget session | Public Returning Champion |
| `GET` | `/api/v1/public/share-index` | List public share codes eligible for the sitemap (paged) | Public Share |
| `GET` | `/api/v1/public/showroom/{slug}` | Resolve a Showroom slug to its public view | Public Share |
| `GET` | `/api/v1/public/showroom/{slug}/qr` | Return the QR payload for a Showroom (url + token). PNG rendering is client-side in v1. | Public Share |
| `GET` | `/api/v1/skill-decay-rules` | List skill decay rules | Skill Decay Rules |
| `POST` | `/api/v1/skill-decay-rules` | Create a skill decay rule | Skill Decay Rules |
| `DELETE` | `/api/v1/skill-decay-rules/{id}` | Delete a skill decay rule | Skill Decay Rules |
| `PUT` | `/api/v1/skill-decay-rules/{id}` | Update a skill decay rule | Skill Decay Rules |
| `GET` | `/api/v1/skill-decay-rules/{id}/history` | Recent decay applications for a rule | Skill Decay Rules |
| `GET` | `/api/v1/skill-decay-rules/{id}/preview` | Preview the cumulative effect of a decay rule | Skill Decay Rules |
| `POST` | `/api/v1/skill-decay-rules/run-now` | Trigger a decay sweep immediately for this customer | Skill Decay Rules |
| `GET` | `/api/v1/skill-rules` | List all skill rules | Skill Rules |
| `POST` | `/api/v1/skill-rules` | Create a skill rule | Skill Rules |
| `DELETE` | `/api/v1/skill-rules/{id}` | Delete a skill rule | Skill Rules |
| `PUT` | `/api/v1/skill-rules/{id}` | Update a skill rule | Skill Rules |
| `POST` | `/api/v1/skill-rules/apply-theme-pack` | Apply a theme-aware skill-rule pack (HTCH-128) | Skill Rules |
| `GET` | `/api/v1/skill-sets` | List all skill sets | Skill Sets |
| `POST` | `/api/v1/skill-sets` | Create a skill set | Skill Sets |
| `DELETE` | `/api/v1/skill-sets/{id}` | Delete a skill set | Skill Sets |
| `GET` | `/api/v1/skill-sets/{id}` | Get a skill set | Skill Sets |
| `PUT` | `/api/v1/skill-sets/{id}` | Update a skill set | Skill Sets |
| `POST` | `/api/v1/skill-sets/generate-icon` | Generate a skill icon with AI | Skill Sets |
| `GET` | `/api/v1/stage-assets` | List per-customer stage assets (preset mode buddy art) plus the default library URLs resolved for the customer's creature_style. | Stage Assets |
| `DELETE` | `/api/v1/stage-assets/{stage}` | Remove the preset asset for a stage | Stage Assets |
| `PUT` | `/api/v1/stage-assets/{stage}` | Commit an uploaded object as the preset asset for a stage | Stage Assets |
| `POST` | `/api/v1/stage-assets/{stage}/regenerate` | Queue AI generation for a customer preset stage asset | Stage Assets |
| `POST` | `/api/v1/stage-assets/upload-url` | Issue a presigned PUT URL for a client-side stage asset upload | Stage Assets |
| `GET` | `/api/v1/streak-definitions` | List all streak definitions | Streak Definitions |
| `POST` | `/api/v1/streak-definitions` | Create a streak definition | Streak Definitions |
| `DELETE` | `/api/v1/streak-definitions/{id}` | Delete a streak definition | Streak Definitions |
| `GET` | `/api/v1/streak-definitions/{id}` | Get a streak definition | Streak Definitions |
| `PUT` | `/api/v1/streak-definitions/{id}` | Update a streak definition | Streak Definitions |
| `GET` | `/api/v1/token-config` | List token configurations | Token Config |
| `POST` | `/api/v1/token-config` | Upsert token configuration | Token Config |
| `GET` | `/api/v1/webhook-configs` | List webhook configs | Webhooks |
| `POST` | `/api/v1/webhook-configs` | Create webhook config | Webhooks |
| `DELETE` | `/api/v1/webhook-configs/{id}` | Delete webhook config | Webhooks |
| `GET` | `/api/v1/webhook-configs/{id}` | Get webhook config | Webhooks |
| `PUT` | `/api/v1/webhook-configs/{id}` | Update webhook config | Webhooks |
| `GET` | `/api/v1/webhook-configs/{id}/deliveries` | List webhook deliveries | Webhooks |
| `POST` | `/api/v1/webhook-configs/{id}/deliveries/{deliveryId}/redeliver` | Redeliver webhook | Webhooks |
| `POST` | `/api/v1/webhook-configs/{id}/rotate-secret` | Rotate webhook secret | Webhooks |
| `POST` | `/api/v1/webhook-configs/{id}/test` | Send test webhook | Webhooks |
| `GET` | `/api/v1/webhook-configs/events` | List webhook event types | Webhooks |
| `GET` | `/api/v1/webhook-configs/health` | Get webhook delivery health | Webhooks |
| `POST` | `/api/v1/widget-sessions` | Create session token | Widget Sessions |
| `DELETE` | `/api/v1/widget-sessions/{id}` | Revoke widget session | Widget Sessions |
| `GET` | `/api/v1/widget-sessions/preview` | Create automatic dashboard preview tokens | Widget Sessions |
| `POST` | `/api/v1/widget-sessions/verify-installation` | Verify widget installation | Widget Sessions |
| `POST` | `/api/v1/widget/appearance/rerender` | Rerender stage base | Widget API |
| `GET` | `/api/v1/widget/badges` | Get widget badge catalog | Widget API |
| `GET` | `/api/v1/widget/beginners-luck/result` | Get the buddy's Beginner's Luck result | Beginner's Luck |
| `GET` | `/api/v1/widget/boosters/active` | The buddy’s currently active boosters | Widget |
| `GET` | `/api/v1/widget/boosters/catalog` | Buyable boosters for this tenant | Widget |
| `POST` | `/api/v1/widget/boosters/purchase` | Buy a catalog booster — 400 insufficient_balance when too few coins | Widget |
| `POST` | `/api/v1/widget/brag/share-profile` | Build the Brag Button "share my profile" payload | Widget |
| `POST` | `/api/v1/widget/brag/slack-post` | Send a Win-State brag to the tenant Slack/Teams webhook | Widget |
| `POST` | `/api/v1/widget/brag/telemetry` | Record one brag funnel event | Widget |
| `POST` | `/api/v1/widget/brag/win-state` | Build the full Brag Button Win-State payload + enabled channels | Widget |
| `GET` | `/api/v1/widget/buddy` | Get widget buddy | Widget API |
| `POST` | `/api/v1/widget/buddy/equip-legacy-item` | Temp-equip a legacy crown for the returning-champion scene | Widget |
| `POST` | `/api/v1/widget/buddy/hatched` | Record that the hatch ceremony completed for the widget buddy | Widget API |
| `POST` | `/api/v1/widget/buddy/pause` | Put the current buddy on vacation until a date | Widget |
| `GET` | `/api/v1/widget/buddy/prestige` | Whether the current buddy can prestige, and why not if it cannot | Widget |
| `POST` | `/api/v1/widget/buddy/prestige` | Prestige the current buddy — reset to stage 0 for a prestige level | Widget |
| `PATCH` | `/api/v1/widget/buddy/profile` | Update the buddy public Profile Page preferences | Widget API |
| `POST` | `/api/v1/widget/buddy/resume` | End the current buddy vacation early | Widget |
| `GET` | `/api/v1/widget/buddy/returning-champion` | Get the Returning Champion re-onboarding scene payload | Widget |
| `POST` | `/api/v1/widget/buddy/returning-champion/dismiss` | Dismiss the Returning Champion scene | Widget |
| `PATCH` | `/api/v1/widget/buddy/seo` | Set the per-buddy search-indexing preference | Widget API |
| `POST` | `/api/v1/widget/buddy/share` | Mint (or fetch) the public share link for the widget buddy | Widget API |
| `POST` | `/api/v1/widget/buddy/share/events` | Record a share-sheet funnel event (opened) | Widget API |
| `GET` | `/api/v1/widget/buddy/vacation-status` | Current buddy vacation status | Widget |
| `GET` | `/api/v1/widget/causes/counters` | List symbolic cause counters for the current buddy / team / tenant | Widget |
| `GET` | `/api/v1/widget/causes/surfaces` | HTCH-70 — cause counters grouped per opted-in surface (banner / buddy strip / profile) | Widget |
| `POST` | `/api/v1/widget/council/proposals` | Submit a narrative proposal (Council members only) | Widget |
| `GET` | `/api/v1/widget/council/proposals/mine` | The buddy's own narrative proposals plus Council standing and quota | Widget |
| `POST` | `/api/v1/widget/equip` | Equip or unequip items | Widget API |
| `GET` | `/api/v1/widget/evolutions` | Get widget evolution timeline | Widget API |
| `GET` | `/api/v1/widget/feed/team-events` | The buddy's team feed — cursor-paginated, newest first | Widget |
| `POST` | `/api/v1/widget/feed/team-events/{id}/clap` | Toggle a 👏 clap on a feed item | Widget |
| `GET` | `/api/v1/widget/foundations` | List the tenant's active foundation selections — read-only for widget rendering. | Foundations |
| `GET` | `/api/v1/widget/founding-cohort/status` | Founding Cohort status for the current buddy | Widget |
| `POST` | `/api/v1/widget/free-lunch/{id}/acknowledge` | Acknowledge a Free Lunch banner | Free Lunch |
| `GET` | `/api/v1/widget/free-lunch/notification` | Get the buddy's pending Free Lunch banner | Free Lunch |
| `POST` | `/api/v1/widget/group-quests/{id}/join` | Join a Group Quest — idempotent (already_joined on re-join) | Widget |
| `POST` | `/api/v1/widget/group-quests/{id}/leave` | Leave a Group Quest — the buddy’s prior contribution stays counted | Widget |
| `GET` | `/api/v1/widget/group-quests/active` | List the active Group Quests visible to the current buddy | Widget |
| `DELETE` | `/api/v1/widget/hexad-survey/me` | Delete the buddy raw response (GDPR / consent withdrawal) | Hexad survey |
| `GET` | `/api/v1/widget/hexad-survey/me` | Fetch the current buddy Hexad response | Hexad survey |
| `GET` | `/api/v1/widget/hexad-survey/questions` | List Hexad survey question metadata | Hexad survey |
| `POST` | `/api/v1/widget/hexad-survey/responses` | Submit (or replace) the buddy Hexad survey response | Hexad survey |
| `POST` | `/api/v1/widget/items/{id}/gift` | Gift a marketplace item to a teammate | Widget |
| `POST` | `/api/v1/widget/kudos` | Send a kudos to a teammate | Widget |
| `GET` | `/api/v1/widget/kudos/given` | List the buddy’s most recent sent kudos + lifetime count | Widget |
| `GET` | `/api/v1/widget/kudos/received` | List the buddy’s most recent received kudos | Widget |
| `GET` | `/api/v1/widget/kudos/types` | List the effective kudo taxonomy for the composer | Widget |
| `GET` | `/api/v1/widget/leaderboard` | Get leaderboard | Leaderboard |
| `GET` | `/api/v1/widget/leagues/boss-fight` | The season's Boss Fight challenge — progress, target, leaderboard | Widget |
| `GET` | `/api/v1/widget/leagues/me` | The buddy's live league standing — tier, cohort, countdown | Widget |
| `POST` | `/api/v1/widget/leagues/off-season/scouting-quest` | Start the cohort pre-season scouting quest with a prediction | Widget |
| `POST` | `/api/v1/widget/leagues/off-season/scouting-quest/join` | Join the cohort's already-started scouting quest | Widget |
| `GET` | `/api/v1/widget/leagues/off-season/status` | The off-season window — Mystery Box boost, wardrobe drops, scouting quest | Widget |
| `GET` | `/api/v1/widget/leagues/seasons/{seasonId}/highlights/me` | The buddy's personalized season-closing highlights | Widget |
| `GET` | `/api/v1/widget/leagues/seasons/latest/highlights/me` | The buddy's latest closed season-closing highlights | Widget |
| `GET` | `/api/v1/widget/lottery/active-entries` | The buddy's live lottery entries with their next-draw time | Widget |
| `GET` | `/api/v1/widget/lottery/last-win` | The buddy's most recent lottery win, if any | Widget |
| `GET` | `/api/v1/widget/marketplace` | Get widget marketplace | Widget API |
| `GET` | `/api/v1/widget/marketplace/composition-status` | Poll an outfit composition variant | Widget API |
| `POST` | `/api/v1/widget/marketplace/fomo` | Marketplace FOMO poll | Widget |
| `POST` | `/api/v1/widget/marketplace/items/{id}/track-view` | Track marketplace item impression | Widget API |
| `GET` | `/api/v1/widget/marketplace/outfits` | List saved outfits | Widget API |
| `POST` | `/api/v1/widget/marketplace/outfits` | Save a new outfit | Widget API |
| `DELETE` | `/api/v1/widget/marketplace/outfits/{id}` | Delete a saved outfit | Widget API |
| `PATCH` | `/api/v1/widget/marketplace/outfits/{id}/activate` | Activate a saved outfit | Widget API |
| `POST` | `/api/v1/widget/marketplace/preview-outfit` | Preview an outfit composition | Widget API |
| `POST` | `/api/v1/widget/mentor/availability` | Toggle the current buddy’s mentor availability | Widget |
| `POST` | `/api/v1/widget/mentor/sessions` | Self-report a mentoring session | Widget |
| `GET` | `/api/v1/widget/mentor/sessions/me` | List the buddy’s recent mentor sessions + hour aggregates | Widget |
| `GET` | `/api/v1/widget/mentor/team/{id}/mentors` | List a team’s available mentors with contact deep links | Widget |
| `GET` | `/api/v1/widget/mission-anchor` | Get the Mission Anchor payload | Widget API |
| `POST` | `/api/v1/widget/mystery-box/claim` | Open the Mystery Box — 409 with next_eligible_at when the daily cap is spent | Widget |
| `GET` | `/api/v1/widget/mystery-box/state` | Mystery Box state — eligible / capped / locked | Widget |
| `GET` | `/api/v1/widget/narrative` | Get the tenant narrative | Widget API |
| `GET` | `/api/v1/widget/narrative/arc` | Get the Program Chapters arc | Widget API |
| `GET` | `/api/v1/widget/next-best-action` | Get the single next-best-action recommendation | Widget API |
| `GET` | `/api/v1/widget/notifications` | Paginated notification feed for the current buddy | Widget |
| `POST` | `/api/v1/widget/notifications/{id}/dismiss` | Read + dismiss a single notification (HTCH-76) | Widget |
| `POST` | `/api/v1/widget/notifications/{id}/read` | Mark a single notification read | Widget |
| `POST` | `/api/v1/widget/notifications/{id}/snooze` | Snooze a notification for a number of hours (HTCH-76) | Widget |
| `POST` | `/api/v1/widget/notifications/dismiss-all` | Read + dismiss every notification for the buddy | Widget |
| `GET` | `/api/v1/widget/notifications/unread-count` | Unread, non-dismissed notification count (badge) | Widget |
| `GET` | `/api/v1/widget/operations/{id}` | Get widget operation | Widget API |
| `GET` | `/api/v1/widget/path` | Get the active path for the buddy’s audience | Widget API |
| `GET` | `/api/v1/widget/path/{key}` | Get a specific path for a buddy | Widget API |
| `POST` | `/api/v1/widget/path/{key}/sub-steps/{subKey}/complete` | Manually mark a sub-step complete | Widget API |
| `GET` | `/api/v1/widget/profile/history` | Visual Grave history — faded lost streaks + reclaimable items | Widget |
| `POST` | `/api/v1/widget/profile/history/items/{id}/reclaim` | Earn a relinquished starter-rare back — fires recovery.streak_restored | Widget |
| `GET` | `/api/v1/widget/profile/sunk-cost-summary` | Sunk-Cost 'Your journey so far' summary for the current buddy | Widget |
| `POST` | `/api/v1/widget/profile/sunk-cost-summary/acknowledge` | Acknowledge the Sunk-Cost panel on first open — fires the paired White Hat celebration.milestone_acknowledged (idempotent per buddy) | Widget |
| `POST` | `/api/v1/widget/purchase` | Purchase item | Widget API |
| `POST` | `/api/v1/widget/rendered` | Record a successful widget render | Widget API |
| `GET` | `/api/v1/widget/social-norms/today` | The buddy's positive-framing team norms for today | Widget |
| `GET` | `/api/v1/widget/state` | Get aggregate widget state | Widget API |
| `GET` | `/api/v1/widget/streak/{key}` | Get widget streak | Widget API |
| `POST` | `/api/v1/widget/teams/{id}/leave` | Leave a team — blocked for a sole lead until another is promoted | Widget |
| `GET` | `/api/v1/widget/teams/me` | Get the current buddy’s team, role and members | Widget |
| `GET` | `/api/v1/widget/theme` | Live widget theme | Widget API |
| `GET` | `/api/v1/widget/tokens` | Get the buddy’s token wallet | Widget API |
| `POST` | `/api/v1/widget/track` | Track event from browser | Widget API |
| `GET` | `/healthz` | Liveness probe (top-level alias) | Health |
| `GET` | `/readyz` | Readiness probe (top-level alias) | Health |
| `GET` | `/version` | Build metadata (top-level alias) | Health |

{/* ENDPOINTS_END */}