# 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** | `POST /events` dedupes on the `event_id` you supply — resending is a no-op. Other writes are not automatically idempotent; don't blind-retry them, and guard `POST /eggs` against React Strict Mode / focus re-runs (see the bootstrap guide). |
| **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, nextCursor }` (cursor-based — pass `cursor`) or `{ data, meta: { page, limit, total } }` (page-based — pass `page`). The field present on the response tells you which. |
| **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",
  "properties": {
    "lesson_id": "lesson_456",
    "score": 87
  }
}
```

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": "bdy_abc123",
  "scopes": ["marketplace:purchase", "items:equip"]
}
```

Response:
```json
{
  "token": "wgt_sess_xxx",
  "expires_at": "2026-04-08T11:00:00Z"
}
```

#### `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 NestJS controllers by apps/docs/scripts/generate-api-reference.ts. */}

| Method | Path | Summary | Source |
|---|---|---|---|
| `GET` | `/api/v1/admin/audit` | Search admin audit log | [`apps/api/src/admin/admin-audit.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-audit.controller.ts) |
| `POST` | `/api/v1/admin/auth/login` | Admin login | [`apps/api/src/admin/admin-auth.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-auth.controller.ts) |
| `POST` | `/api/v1/admin/auth/logout` | Stateless logout (client should drop token) | [`apps/api/src/admin/admin-auth.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-auth.controller.ts) |
| `GET` | `/api/v1/admin/auth/me` | Current admin profile | [`apps/api/src/admin/admin-auth.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-auth.controller.ts) |
| `GET` | `/api/v1/admin/customers` | List customers (search/filter/paginate) | [`apps/api/src/admin/admin-customers.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-customers.controller.ts) |
| `DELETE` | `/api/v1/admin/customers/:id` | Soft-delete a customer (sets deleted_at) | [`apps/api/src/admin/admin-customers.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-customers.controller.ts) |
| `GET` | `/api/v1/admin/customers/:id` | Customer detail (counts, balances) | [`apps/api/src/admin/admin-customers.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-customers.controller.ts) |
| `PATCH` | `/api/v1/admin/customers/:id` | Update customer profile (name/email/settings) | [`apps/api/src/admin/admin-customers.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-customers.controller.ts) |
| `GET` | `/api/v1/admin/customers/:id/api-keys` | List customer API keys | [`apps/api/src/admin/admin-customers.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-customers.controller.ts) |
| `POST` | `/api/v1/admin/customers/:id/api-keys/:keyId/revoke` | Revoke a customer API key | [`apps/api/src/admin/admin-customers.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-customers.controller.ts) |
| `POST` | `/api/v1/admin/customers/:id/api-keys/publishable` | Issue a publishable key for the customer | [`apps/api/src/admin/admin-customers.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-customers.controller.ts) |
| `GET` | `/api/v1/admin/customers/:id/billing` | Billing snapshot (DB + reconciled view) | [`apps/api/src/admin/admin-billing.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-billing.controller.ts) |
| `POST` | `/api/v1/admin/customers/:id/billing/cancel-subscription` | Cancel the customer Stripe subscription | [`apps/api/src/admin/admin-billing.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-billing.controller.ts) |
| `POST` | `/api/v1/admin/customers/:id/billing/refund` | Refund the most recent charge and (optionally) claw back credits | [`apps/api/src/admin/admin-billing.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-billing.controller.ts) |
| `POST` | `/api/v1/admin/customers/:id/billing/sync` | Reconcile DB columns from Stripe | [`apps/api/src/admin/admin-billing.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-billing.controller.ts) |
| `GET` | `/api/v1/admin/customers/:id/credits` | Credit balance + recent transactions | [`apps/api/src/admin/admin-credits.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-credits.controller.ts) |
| `POST` | `/api/v1/admin/customers/:id/credits/adjust` | Apply a signed manual credit adjustment | [`apps/api/src/admin/admin-credits.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-credits.controller.ts) |
| `PATCH` | `/api/v1/admin/customers/:id/event-quota` | Update monthly event quota counters | [`apps/api/src/admin/admin-customers.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-customers.controller.ts) |
| `PATCH` | `/api/v1/admin/customers/:id/features` | Override per-customer feature flags | [`apps/api/src/admin/admin-customers.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-customers.controller.ts) |
| `POST` | `/api/v1/admin/customers/:id/impersonate` | Issue a short-lived read-only dashboard JWT for the customer | [`apps/api/src/admin/admin-impersonate.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-impersonate.controller.ts) |
| `GET` | `/api/v1/admin/customers/:id/onboarding` | Onboarding submission | [`apps/api/src/admin/admin-customers.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-customers.controller.ts) |
| `PATCH` | `/api/v1/admin/customers/:id/plan` | Override plan (no Stripe touch) | [`apps/api/src/admin/admin-customers.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-customers.controller.ts) |
| `POST` | `/api/v1/admin/customers/:id/restore` | Restore a soft-deleted customer | [`apps/api/src/admin/admin-customers.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-customers.controller.ts) |
| `GET` | `/api/v1/admin/operations` | List operations with filters | [`apps/api/src/admin/admin-operations.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-operations.controller.ts) |
| `GET` | `/api/v1/admin/operations/:id` | Operation detail (request/result/error payloads) | [`apps/api/src/admin/admin-operations.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-operations.controller.ts) |
| `GET` | `/api/v1/admin/operations/queue-link` | Short-lived Bull-Board admin URL with token | [`apps/api/src/admin/admin-operations.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-operations.controller.ts) |
| `GET` | `/api/v1/admin/users` | List admin users (super only) | [`apps/api/src/admin/admin-users.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-users.controller.ts) |
| `POST` | `/api/v1/admin/users` | Create a new admin user (super only) | [`apps/api/src/admin/admin-users.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-users.controller.ts) |
| `DELETE` | `/api/v1/admin/users/:id` | Deactivate an admin user | [`apps/api/src/admin/admin-users.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-users.controller.ts) |
| `PATCH` | `/api/v1/admin/users/:id` | Update an admin user | [`apps/api/src/admin/admin-users.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/admin/admin-users.controller.ts) |
| `GET` | `/api/v1/analytics` | Get leaderboard | [`apps/api/src/analytics/analytics.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/analytics/analytics.controller.ts) |
| `GET` | `/api/v1/analytics/activity-summary` | Get activity summary | [`apps/api/src/analytics/analytics.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/analytics/analytics.controller.ts) |
| `GET` | `/api/v1/analytics/audiences` | Get audience breakdown | [`apps/api/src/analytics/analytics.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/analytics/analytics.controller.ts) |
| `GET` | `/api/v1/analytics/custom-events` | Get custom event trends | [`apps/api/src/analytics/analytics.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/analytics/analytics.controller.ts) |
| `GET` | `/api/v1/analytics/economy-health` | Get economy health | [`apps/api/src/analytics/analytics.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/analytics/analytics.controller.ts) |
| `GET` | `/api/v1/analytics/economy-summary` | Get economy summary | [`apps/api/src/analytics/analytics.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/analytics/analytics.controller.ts) |
| `GET` | `/api/v1/analytics/engagement` | Get engagement metrics | [`apps/api/src/analytics/analytics.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/analytics/analytics.controller.ts) |
| `GET` | `/api/v1/analytics/event-counts` | Per-event counts | [`apps/api/src/analytics/analytics.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/analytics/analytics.controller.ts) |
| `GET` | `/api/v1/analytics/evolution` | Get evolution timeline | [`apps/api/src/analytics/analytics.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/analytics/analytics.controller.ts) |
| `GET` | `/api/v1/analytics/marketplace-funnel` | Get marketplace funnel | [`apps/api/src/analytics/analytics.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/analytics/analytics.controller.ts) |
| `GET` | `/api/v1/analytics/overview` | Get analytics overview | [`apps/api/src/analytics/analytics.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/analytics/analytics.controller.ts) |
| `GET` | `/api/v1/analytics/popular-badges` | Get popular badges | [`apps/api/src/analytics/analytics.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/analytics/analytics.controller.ts) |
| `GET` | `/api/v1/analytics/popular-items` | Get popular items | [`apps/api/src/analytics/analytics.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/analytics/analytics.controller.ts) |
| `GET` | `/api/v1/analytics/retention` | Get retention metrics | [`apps/api/src/analytics/analytics.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/analytics/analytics.controller.ts) |
| `GET` | `/api/v1/analytics/roi-metrics` | Get ROI metrics | [`apps/api/src/analytics/analytics.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/analytics/analytics.controller.ts) |
| `GET` | `/api/v1/analytics/streaks` | Get streak health | [`apps/api/src/analytics/analytics.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/analytics/analytics.controller.ts) |
| `GET` | `/api/v1/analytics/tokens` | Get per-token economy | [`apps/api/src/analytics/analytics.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/analytics/analytics.controller.ts) |
| `GET` | `/api/v1/analytics/webhooks` | Get webhook delivery health | [`apps/api/src/analytics/analytics.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/analytics/analytics.controller.ts) |
| `GET` | `/api/v1/auth/api-keys` | List all active API keys for the current customer | [`apps/api/src/auth/auth.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/auth/auth.controller.ts) |
| `POST` | `/api/v1/auth/api-keys` | Create a new API key | [`apps/api/src/auth/auth.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/auth/auth.controller.ts) |
| `DELETE` | `/api/v1/auth/api-keys/:id` | Revoke an API key by its ID | [`apps/api/src/auth/auth.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/auth/auth.controller.ts) |
| `POST` | `/api/v1/auth/api-keys/rotate` | Rotate API keys by revoking all existing keys and creating a new one | [`apps/api/src/auth/auth.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/auth/auth.controller.ts) |
| `POST` | `/api/v1/auth/login` | Authenticate and obtain a JWT token | [`apps/api/src/auth/auth.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/auth/auth.controller.ts) |
| `GET` | `/api/v1/auth/me` | Get the currently authenticated customer profile | [`apps/api/src/auth/auth.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/auth/auth.controller.ts) |
| `POST` | `/api/v1/auth/publishable-keys` | Issue a browser-safe publishable key (hatch_pk_*) with a scoped set of permissions. | [`apps/api/src/auth/auth.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/auth/auth.controller.ts) |
| `POST` | `/api/v1/auth/register` | Register a new customer account | [`apps/api/src/auth/auth.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/auth/auth.controller.ts) |
| `GET` | `/api/v1/badge-definitions` | List all badge definitions | [`apps/api/src/badge-definitions/badge-definitions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/badge-definitions/badge-definitions.controller.ts) |
| `POST` | `/api/v1/badge-definitions` | Create a badge definition | [`apps/api/src/badge-definitions/badge-definitions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/badge-definitions/badge-definitions.controller.ts) |
| `DELETE` | `/api/v1/badge-definitions/:id` | Delete a badge definition | [`apps/api/src/badge-definitions/badge-definitions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/badge-definitions/badge-definitions.controller.ts) |
| `GET` | `/api/v1/badge-definitions/:id` | Get a badge definition | [`apps/api/src/badge-definitions/badge-definitions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/badge-definitions/badge-definitions.controller.ts) |
| `PUT` | `/api/v1/badge-definitions/:id` | Update a badge definition | [`apps/api/src/badge-definitions/badge-definitions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/badge-definitions/badge-definitions.controller.ts) |
| `POST` | `/api/v1/badge-definitions/:id/regenerate-icon` | Queue an AI regeneration for this badge icon | [`apps/api/src/badge-definitions/badge-definitions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/badge-definitions/badge-definitions.controller.ts) |
| `POST` | `/api/v1/badge-definitions/generate-icon` | Generate a badge icon with AI | [`apps/api/src/badge-definitions/badge-definitions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/badge-definitions/badge-definitions.controller.ts) |
| `POST` | `/api/v1/badge-definitions/upload-icon` |  | [`apps/api/src/badge-definitions/badge-definitions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/badge-definitions/badge-definitions.controller.ts) |
| `POST` | `/api/v1/billing/checkout` | Create checkout session | [`apps/api/src/billing/billing.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/billing/billing.controller.ts) |
| `POST` | `/api/v1/billing/override-plan` | Override customer plan | [`apps/api/src/billing/billing.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/billing/billing.controller.ts) |
| `POST` | `/api/v1/billing/portal` | Create billing portal session | [`apps/api/src/billing/billing.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/billing/billing.controller.ts) |
| `GET` | `/api/v1/billing/status` | Get billing status | [`apps/api/src/billing/billing.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/billing/billing.controller.ts) |
| `POST` | `/api/v1/billing/webhook` | Handle Stripe webhook | [`apps/api/src/billing/billing.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/billing/billing.controller.ts) |
| `GET` | `/api/v1/buddies` | List buddies with pagination and optional filters | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `POST` | `/api/v1/buddies/:buddy_id/appearance/rerender` | Regenerate the buddy stage base image | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `GET` | `/api/v1/buddies/:buddy_id/badges` | List all badges awarded to a buddy | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `POST` | `/api/v1/buddies/:buddy_id/badges` | Award a badge to a buddy | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `POST` | `/api/v1/buddies/:buddy_id/coins` | Earn coins for a buddy (supports idempotency) | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `POST` | `/api/v1/buddies/:buddy_id/coins/spend` | Spend coins for a buddy (supports idempotency) | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `PATCH` | `/api/v1/buddies/:buddy_id/equipped-items` | Equip or unequip items on a buddy | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `GET` | `/api/v1/buddies/:buddy_id/evolution` | Check evolution readiness and progress for a buddy | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `GET` | `/api/v1/buddies/:buddy_id/evolutions` | Stage transition timeline for a buddy | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `POST` | `/api/v1/buddies/:buddy_id/evolve` | Trigger asynchronous buddy evolution | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `POST` | `/api/v1/buddies/:buddy_id/gates/:gate_key/unlock` | Spend tokens to unlock a gate for a buddy | [`apps/api/src/gates/gates.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/gates/gates.controller.ts) |
| `GET` | `/api/v1/buddies/:buddy_id/progression` | Get buddy progression metrics (legacy endpoint) | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `GET` | `/api/v1/buddies/:buddy_id/progression-metrics` | Get buddy progression metrics (lessons, quizzes, streaks, etc.) | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `POST` | `/api/v1/buddies/:buddy_id/purchase-item` | Purchase a marketplace item using coins (supports idempotency) | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `GET` | `/api/v1/buddies/:buddy_id/purchased-items` | List all purchased items for a buddy | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `GET` | `/api/v1/buddies/:buddy_id/tokens` | Typed token balances (primary + progression) | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `POST` | `/api/v1/buddies/:buddy_id/tokens` | Earn or spend tokens for a buddy (supports idempotency) | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `POST` | `/api/v1/buddies/:buddy_id/unlock-item` | Unlock an item without spending coins | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `GET` | `/api/v1/buddies/:buddy_id/unlocks` | List gates this buddy has unlocked | [`apps/api/src/gates/gates.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/gates/gates.controller.ts) |
| `GET` | `/api/v1/buddies/:id` | Get buddy details with full canonical state | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `PATCH` | `/api/v1/buddies/:id` | Update a buddy name | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `PATCH` | `/api/v1/buddies/:id/archive` | Archive a buddy (one-way transition from active to archived) | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `PATCH` | `/api/v1/buddies/:id/skills` | Update buddy skill levels (increase, decrease, or set) | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `GET` | `/api/v1/buddies/users/:user_id/summary` | Get a user summary including buddy count, coins, and badges | [`apps/api/src/buddies/buddies.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/buddies.controller.ts) |
| `GET` | `/api/v1/coin-rules` | List all coin rules | [`apps/api/src/coin-rules/coin-rules.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/coin-rules/coin-rules.controller.ts) |
| `POST` | `/api/v1/coin-rules` | Create a coin rule | [`apps/api/src/coin-rules/coin-rules.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/coin-rules/coin-rules.controller.ts) |
| `DELETE` | `/api/v1/coin-rules/:id` | Delete a coin rule | [`apps/api/src/coin-rules/coin-rules.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/coin-rules/coin-rules.controller.ts) |
| `PUT` | `/api/v1/coin-rules/:id` | Update a coin rule | [`apps/api/src/coin-rules/coin-rules.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/coin-rules/coin-rules.controller.ts) |
| `GET` | `/api/v1/config-versions` | List config versions | [`apps/api/src/config-versions/config-versions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/config-versions/config-versions.controller.ts) |
| `POST` | `/api/v1/config-versions` | Create config version | [`apps/api/src/config-versions/config-versions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/config-versions/config-versions.controller.ts) |
| `GET` | `/api/v1/config-versions/:id` | Get config version | [`apps/api/src/config-versions/config-versions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/config-versions/config-versions.controller.ts) |
| `PATCH` | `/api/v1/config-versions/:id` | Update config version | [`apps/api/src/config-versions/config-versions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/config-versions/config-versions.controller.ts) |
| `POST` | `/api/v1/config-versions/:id/clone` | Clone config version | [`apps/api/src/config-versions/config-versions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/config-versions/config-versions.controller.ts) |
| `GET` | `/api/v1/config-versions/:id/impact` | Preview config impact | [`apps/api/src/config-versions/config-versions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/config-versions/config-versions.controller.ts) |
| `POST` | `/api/v1/config-versions/:id/migrate-buddies` | Migrate buddies | [`apps/api/src/config-versions/config-versions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/config-versions/config-versions.controller.ts) |
| `POST` | `/api/v1/config-versions/:id/publish` | Publish config version | [`apps/api/src/config-versions/config-versions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/config-versions/config-versions.controller.ts) |
| `GET` | `/api/v1/credits/balance` | Get credit balance | [`apps/api/src/credits/credits.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/credits/credits.controller.ts) |
| `GET` | `/api/v1/credits/ledger` | List recent AI usage ledger entries | [`apps/api/src/credits/credits.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/credits/credits.controller.ts) |
| `GET` | `/api/v1/customers/me` |  | [`apps/api/src/customers/customers.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/customers/customers.controller.ts) |
| `PATCH` | `/api/v1/customers/me` |  | [`apps/api/src/customers/customers.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/customers/customers.controller.ts) |
| `POST` | `/api/v1/customers/me/apply-preset` | Apply preset | [`apps/api/src/presets/presets.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/presets/presets.controller.ts) |
| `POST` | `/api/v1/customers/me/assets/regenerate` | Bulk regenerate AI assets | [`apps/api/src/customers/customers.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/customers/customers.controller.ts) |
| `PATCH` | `/api/v1/customers/me/audiences` | Replace the customer audience list | [`apps/api/src/customers/customers.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/customers/customers.controller.ts) |
| `PATCH` | `/api/v1/customers/me/settings` |  | [`apps/api/src/customers/customers.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/customers/customers.controller.ts) |
| `DELETE` | `/api/v1/customers/me/users/:user_id/data` |  | [`apps/api/src/customers/customers.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/customers/customers.controller.ts) |
| `GET` | `/api/v1/customers/me/users/:user_id/summary` |  | [`apps/api/src/buddies/customers-summary.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/buddies/customers-summary.controller.ts) |
| `POST` | `/api/v1/customers/me/widget-theme/suggest` | Suggest widget theme customization | [`apps/api/src/customers/customers.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/customers/customers.controller.ts) |
| `POST` | `/api/v1/demo/buddy/:id/evolve` | Evolve the demo visitor buddy | [`apps/api/src/widget-sessions/demo.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/demo.controller.ts) |
| `POST` | `/api/v1/demo/event` | Ingest an event for the current demo visitor | [`apps/api/src/widget-sessions/demo.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/demo.controller.ts) |
| `POST` | `/api/v1/demo/hatch` | Hatch a buddy for the current demo visitor (instant) | [`apps/api/src/widget-sessions/demo.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/demo.controller.ts) |
| `GET` | `/api/v1/demo/operations/:id` | Read the status of an async demo operation | [`apps/api/src/widget-sessions/demo.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/demo.controller.ts) |
| `POST` | `/api/v1/demo/reset` | Archive the current demo visitor buddy and reset state | [`apps/api/src/widget-sessions/demo.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/demo.controller.ts) |
| `POST` | `/api/v1/demo/session` | Start or resume a per-visitor demo session | [`apps/api/src/widget-sessions/demo.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/demo.controller.ts) |
| `GET` | `/api/v1/demo/state` | Read the demo visitor state (buddy + readiness + metrics) | [`apps/api/src/widget-sessions/demo.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/demo.controller.ts) |
| `GET` | `/api/v1/demo/widget-token` | Mint embed token for the public demo tenant (primary Fern) | [`apps/api/src/widget-sessions/demo.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/demo.controller.ts) |
| `GET` | `/api/v1/economy/buddies/:buddyId/ledger` | Get coin ledger for a buddy | [`apps/api/src/economy/economy.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/economy/economy.controller.ts) |
| `GET` | `/api/v1/eggs` | List eggs with optional user and status filters | [`apps/api/src/eggs/eggs.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/eggs/eggs.controller.ts) |
| `POST` | `/api/v1/eggs` | Create a new egg for a user | [`apps/api/src/eggs/eggs.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/eggs/eggs.controller.ts) |
| `GET` | `/api/v1/eggs/:id` | Get an egg by its ID | [`apps/api/src/eggs/eggs.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/eggs/eggs.controller.ts) |
| `POST` | `/api/v1/eggs/:id/hatch` | Start the asynchronous hatch process for an egg | [`apps/api/src/eggs/eggs.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/eggs/eggs.controller.ts) |
| `PATCH` | `/api/v1/eggs/:id/status` | Update an egg status to ready or cancelled | [`apps/api/src/eggs/eggs.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/eggs/eggs.controller.ts) |
| `POST` | `/api/v1/embed-tokens` | Create embed token | [`apps/api/src/widget-sessions/widget-sessions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-sessions.controller.ts) |
| `GET` | `/api/v1/event-types` | List event types | [`apps/api/src/event-types/event-types.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/event-types/event-types.controller.ts) |
| `POST` | `/api/v1/event-types` | Register an event type | [`apps/api/src/event-types/event-types.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/event-types/event-types.controller.ts) |
| `DELETE` | `/api/v1/event-types/:id` | Delete an event type | [`apps/api/src/event-types/event-types.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/event-types/event-types.controller.ts) |
| `GET` | `/api/v1/event-types/:id` | Get an event type | [`apps/api/src/event-types/event-types.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/event-types/event-types.controller.ts) |
| `PUT` | `/api/v1/event-types/:id` | Update or rename an event type | [`apps/api/src/event-types/event-types.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/event-types/event-types.controller.ts) |
| `GET` | `/api/v1/events` | List events | [`apps/api/src/events/events.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/events/events.controller.ts) |
| `POST` | `/api/v1/events` | Ingest event | [`apps/api/src/events/events.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/events/events.controller.ts) |
| `GET` | `/api/v1/events/:id` | Get event | [`apps/api/src/events/events.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/events/events.controller.ts) |
| `GET` | `/api/v1/events/active-users` | List most-active users in a recent window | [`apps/api/src/events/events.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/events/events.controller.ts) |
| `POST` | `/api/v1/events/batch` | Ingest event batch | [`apps/api/src/events/events.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/events/events.controller.ts) |
| `GET` | `/api/v1/events/types` | List distinct event types | [`apps/api/src/events/events.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/events/events.controller.ts) |
| `GET` | `/api/v1/gates` | List token gates for this customer | [`apps/api/src/gates/gates.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/gates/gates.controller.ts) |
| `DELETE` | `/api/v1/gates/:gate_key` | Delete a token gate | [`apps/api/src/gates/gates.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/gates/gates.controller.ts) |
| `PUT` | `/api/v1/gates/:gate_key` | Create or update a token gate | [`apps/api/src/gates/gates.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/gates/gates.controller.ts) |
| `GET` | `/api/v1/health` | Health check | [`apps/api/src/health/health.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/health/health.controller.ts) |
| `GET` | `/api/v1/health/live` | Liveness check | [`apps/api/src/health/health.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/health/health.controller.ts) |
| `GET` | `/api/v1/health/ready` | Readiness check | [`apps/api/src/health/health.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/health/health.controller.ts) |
| `GET` | `/api/v1/image-usage` | Get image usage | [`apps/api/src/images/image-cost.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/images/image-cost.controller.ts) |
| `GET` | `/api/v1/image-usage/report` | Get image usage report | [`apps/api/src/images/image-cost.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/images/image-cost.controller.ts) |
| `GET` | `/api/v1/marketplaces` | List marketplaces | [`apps/api/src/marketplace/marketplace.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/marketplace/marketplace.controller.ts) |
| `POST` | `/api/v1/marketplaces` | Create marketplace | [`apps/api/src/marketplace/marketplace.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/marketplace/marketplace.controller.ts) |
| `GET` | `/api/v1/marketplaces/:id` | Get marketplace | [`apps/api/src/marketplace/marketplace.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/marketplace/marketplace.controller.ts) |
| `PUT` | `/api/v1/marketplaces/:id` | Update marketplace | [`apps/api/src/marketplace/marketplace.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/marketplace/marketplace.controller.ts) |
| `GET` | `/api/v1/marketplaces/:id/items` | List items | [`apps/api/src/marketplace/marketplace.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/marketplace/marketplace.controller.ts) |
| `POST` | `/api/v1/marketplaces/:id/items` | Create item | [`apps/api/src/marketplace/marketplace.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/marketplace/marketplace.controller.ts) |
| `DELETE` | `/api/v1/marketplaces/:id/items/:item_id` | Delete item | [`apps/api/src/marketplace/marketplace.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/marketplace/marketplace.controller.ts) |
| `GET` | `/api/v1/marketplaces/:id/items/:item_id` | Get item | [`apps/api/src/marketplace/marketplace.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/marketplace/marketplace.controller.ts) |
| `PUT` | `/api/v1/marketplaces/:id/items/:item_id` | Update item | [`apps/api/src/marketplace/marketplace.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/marketplace/marketplace.controller.ts) |
| `POST` | `/api/v1/marketplaces/:id/items/:item_id/regenerate-image` | Queue an AI regeneration for this item image | [`apps/api/src/marketplace/marketplace.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/marketplace/marketplace.controller.ts) |
| `POST` | `/api/v1/marketplaces/:id/items/:item_id/upload-image` | Upload item image | [`apps/api/src/marketplace/marketplace.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/marketplace/marketplace.controller.ts) |
| `POST` | `/api/v1/marketplaces/:id/items/import` | Import items | [`apps/api/src/marketplace/marketplace.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/marketplace/marketplace.controller.ts) |
| `POST` | `/api/v1/marketplaces/:id/items/reorder` | Reorder items | [`apps/api/src/marketplace/marketplace.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/marketplace/marketplace.controller.ts) |
| `GET` | `/api/v1/metrics` | Get Prometheus metrics | [`apps/api/src/health/metrics.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/health/metrics.controller.ts) |
| `POST` | `/api/v1/onboarding/sessions` | Create or resume the current onboarding session | [`apps/api/src/onboarding/onboarding.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/onboarding/onboarding.controller.ts) |
| `PUT` | `/api/v1/onboarding/sessions/:id/answers` | Patch structured onboarding answers | [`apps/api/src/onboarding/onboarding.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/onboarding/onboarding.controller.ts) |
| `POST` | `/api/v1/onboarding/sessions/:id/apply` | Apply the generated plan to the customer (writes gamification config) | [`apps/api/src/onboarding/onboarding.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/onboarding/onboarding.controller.ts) |
| `POST` | `/api/v1/onboarding/sessions/:id/generate-guide` | Generate a personalized integration guide | [`apps/api/src/onboarding/onboarding.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/onboarding/onboarding.controller.ts) |
| `POST` | `/api/v1/onboarding/sessions/:id/generate-plan` | Generate a gamification plan from the conversation | [`apps/api/src/onboarding/onboarding.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/onboarding/onboarding.controller.ts) |
| `POST` | `/api/v1/onboarding/sessions/:id/message` | Send a user message and stream the assistant reply via server-sent events | [`apps/api/src/onboarding/onboarding.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/onboarding/onboarding.controller.ts) |
| `POST` | `/api/v1/onboarding/sessions/:id/regenerate-plan` | Regenerate the plan with a variant seed | [`apps/api/src/onboarding/onboarding.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/onboarding/onboarding.controller.ts) |
| `GET` | `/api/v1/onboarding/sessions/current` | Fetch the current onboarding session | [`apps/api/src/onboarding/onboarding.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/onboarding/onboarding.controller.ts) |
| `GET` | `/api/v1/onboarding/sessions/preparing-status` | Aggregate asset-generation status for the current customer | [`apps/api/src/onboarding/onboarding.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/onboarding/onboarding.controller.ts) |
| `POST` | `/api/v1/onboarding/sessions/reset` | Reset the current onboarding session | [`apps/api/src/onboarding/onboarding.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/onboarding/onboarding.controller.ts) |
| `POST` | `/api/v1/onboarding/sessions/seed-from-repo` | Seed onboarding from a repo-analysis brief produced by a local AI agent | [`apps/api/src/onboarding/onboarding.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/onboarding/onboarding.controller.ts) |
| `POST` | `/api/v1/onboarding/sessions/seed-from-url` | Seed onboarding from a landing-page URL | [`apps/api/src/onboarding/onboarding.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/onboarding/onboarding.controller.ts) |
| `POST` | `/api/v1/onboarding/sessions/waitlist` | Join the waitlist for an upcoming onboarding channel | [`apps/api/src/onboarding/onboarding.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/onboarding/onboarding.controller.ts) |
| `GET` | `/api/v1/operations` | List operations with optional type and status filters | [`apps/api/src/operations/operations.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/operations/operations.controller.ts) |
| `GET` | `/api/v1/operations/:id` | Get an operation by its ID | [`apps/api/src/operations/operations.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/operations/operations.controller.ts) |
| `POST` | `/api/v1/operations/:id/cancel` | Cancel a pending or processing operation | [`apps/api/src/operations/operations.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/operations/operations.controller.ts) |
| `GET` | `/api/v1/path-definitions` | List path definitions | [`apps/api/src/paths/paths.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/paths/paths.controller.ts) |
| `POST` | `/api/v1/path-definitions` | Create a path definition | [`apps/api/src/paths/paths.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/paths/paths.controller.ts) |
| `DELETE` | `/api/v1/path-definitions/:id` | Delete a path definition | [`apps/api/src/paths/paths.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/paths/paths.controller.ts) |
| `GET` | `/api/v1/path-definitions/:id` | Get a path definition (with steps + sub-steps) | [`apps/api/src/paths/paths.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/paths/paths.controller.ts) |
| `PUT` | `/api/v1/path-definitions/:id` | Update a path definition | [`apps/api/src/paths/paths.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/paths/paths.controller.ts) |
| `POST` | `/api/v1/path-definitions/:id/activate` | Activate a path (atomic single-active per audience) | [`apps/api/src/paths/paths.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/paths/paths.controller.ts) |
| `POST` | `/api/v1/path-definitions/:id/deactivate` | Deactivate a path | [`apps/api/src/paths/paths.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/paths/paths.controller.ts) |
| `GET` | `/api/v1/path-definitions/:id/steps` | List steps in a path | [`apps/api/src/paths/paths.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/paths/paths.controller.ts) |
| `POST` | `/api/v1/path-definitions/:id/steps` | Create a step in a path | [`apps/api/src/paths/paths.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/paths/paths.controller.ts) |
| `DELETE` | `/api/v1/path-definitions/:id/steps/:stepId` | Delete a step | [`apps/api/src/paths/paths.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/paths/paths.controller.ts) |
| `PUT` | `/api/v1/path-definitions/:id/steps/:stepId` | Update a step | [`apps/api/src/paths/paths.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/paths/paths.controller.ts) |
| `GET` | `/api/v1/path-definitions/:id/steps/:stepId/sub-steps` | List sub-steps within a step | [`apps/api/src/paths/paths.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/paths/paths.controller.ts) |
| `POST` | `/api/v1/path-definitions/:id/steps/:stepId/sub-steps` | Create a sub-step | [`apps/api/src/paths/paths.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/paths/paths.controller.ts) |
| `DELETE` | `/api/v1/path-definitions/:id/steps/:stepId/sub-steps/:subStepId` | Delete a sub-step | [`apps/api/src/paths/paths.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/paths/paths.controller.ts) |
| `PUT` | `/api/v1/path-definitions/:id/steps/:stepId/sub-steps/:subStepId` | Update a sub-step | [`apps/api/src/paths/paths.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/paths/paths.controller.ts) |
| `PUT` | `/api/v1/path-definitions/:id/steps/:stepId/sub-steps/reorder` | Reorder sub-steps within a step | [`apps/api/src/paths/paths.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/paths/paths.controller.ts) |
| `PUT` | `/api/v1/path-definitions/:id/steps/reorder` | Reorder steps in a path | [`apps/api/src/paths/paths.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/paths/paths.controller.ts) |
| `GET` | `/api/v1/path-definitions/buddies/:buddyId/paths/:pathKey` | Get path runtime payload for a buddy | [`apps/api/src/paths/paths.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/paths/paths.controller.ts) |
| `POST` | `/api/v1/path-definitions/buddies/:buddyId/paths/:pathKey/sub-steps/:subKey/complete` | Manually mark a sub-step complete (admin) | [`apps/api/src/paths/paths.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/paths/paths.controller.ts) |
| `GET` | `/api/v1/presets` | List presets | [`apps/api/src/presets/presets.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/presets/presets.controller.ts) |
| `GET` | `/api/v1/presets/:key` | Get preset | [`apps/api/src/presets/presets.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/presets/presets.controller.ts) |
| `GET` | `/api/v1/skill-decay-rules` | List skill decay rules | [`apps/api/src/skill-decay-rules/skill-decay-rules.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/skill-decay-rules/skill-decay-rules.controller.ts) |
| `POST` | `/api/v1/skill-decay-rules` | Create a skill decay rule | [`apps/api/src/skill-decay-rules/skill-decay-rules.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/skill-decay-rules/skill-decay-rules.controller.ts) |
| `DELETE` | `/api/v1/skill-decay-rules/:id` | Delete a skill decay rule | [`apps/api/src/skill-decay-rules/skill-decay-rules.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/skill-decay-rules/skill-decay-rules.controller.ts) |
| `PUT` | `/api/v1/skill-decay-rules/:id` | Update a skill decay rule | [`apps/api/src/skill-decay-rules/skill-decay-rules.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/skill-decay-rules/skill-decay-rules.controller.ts) |
| `GET` | `/api/v1/skill-decay-rules/:id/history` | Recent decay applications for a rule | [`apps/api/src/skill-decay-rules/skill-decay-rules.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/skill-decay-rules/skill-decay-rules.controller.ts) |
| `GET` | `/api/v1/skill-decay-rules/:id/preview` | Preview the cumulative effect of a decay rule | [`apps/api/src/skill-decay-rules/skill-decay-rules.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/skill-decay-rules/skill-decay-rules.controller.ts) |
| `POST` | `/api/v1/skill-decay-rules/run-now` | Trigger a decay sweep immediately for this customer | [`apps/api/src/skill-decay-rules/skill-decay-rules.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/skill-decay-rules/skill-decay-rules.controller.ts) |
| `GET` | `/api/v1/skill-rules` | List all skill rules | [`apps/api/src/skill-rules/skill-rules.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/skill-rules/skill-rules.controller.ts) |
| `POST` | `/api/v1/skill-rules` | Create a skill rule | [`apps/api/src/skill-rules/skill-rules.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/skill-rules/skill-rules.controller.ts) |
| `DELETE` | `/api/v1/skill-rules/:id` | Delete a skill rule | [`apps/api/src/skill-rules/skill-rules.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/skill-rules/skill-rules.controller.ts) |
| `PUT` | `/api/v1/skill-rules/:id` | Update a skill rule | [`apps/api/src/skill-rules/skill-rules.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/skill-rules/skill-rules.controller.ts) |
| `GET` | `/api/v1/skill-sets` | List all skill sets | [`apps/api/src/skill-sets/skill-sets.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/skill-sets/skill-sets.controller.ts) |
| `POST` | `/api/v1/skill-sets` | Create a skill set | [`apps/api/src/skill-sets/skill-sets.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/skill-sets/skill-sets.controller.ts) |
| `DELETE` | `/api/v1/skill-sets/:id` | Delete a skill set | [`apps/api/src/skill-sets/skill-sets.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/skill-sets/skill-sets.controller.ts) |
| `GET` | `/api/v1/skill-sets/:id` | Get a skill set | [`apps/api/src/skill-sets/skill-sets.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/skill-sets/skill-sets.controller.ts) |
| `PUT` | `/api/v1/skill-sets/:id` | Update a skill set | [`apps/api/src/skill-sets/skill-sets.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/skill-sets/skill-sets.controller.ts) |
| `POST` | `/api/v1/skill-sets/generate-icon` | Generate a skill icon with AI | [`apps/api/src/skill-sets/skill-sets.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/skill-sets/skill-sets.controller.ts) |
| `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. | [`apps/api/src/stage-assets/stage-assets.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/stage-assets/stage-assets.controller.ts) |
| `DELETE` | `/api/v1/stage-assets/:stage` | Remove the preset asset for a stage | [`apps/api/src/stage-assets/stage-assets.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/stage-assets/stage-assets.controller.ts) |
| `PUT` | `/api/v1/stage-assets/:stage` | Commit an uploaded object as the preset asset for a stage | [`apps/api/src/stage-assets/stage-assets.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/stage-assets/stage-assets.controller.ts) |
| `POST` | `/api/v1/stage-assets/:stage/regenerate` | Queue AI generation for a customer preset stage asset | [`apps/api/src/stage-assets/stage-assets.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/stage-assets/stage-assets.controller.ts) |
| `POST` | `/api/v1/stage-assets/upload-url` | Issue a presigned PUT URL for a client-side stage asset upload | [`apps/api/src/stage-assets/stage-assets.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/stage-assets/stage-assets.controller.ts) |
| `GET` | `/api/v1/streak-definitions` | List all streak definitions | [`apps/api/src/streaks/streak-definitions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/streaks/streak-definitions.controller.ts) |
| `POST` | `/api/v1/streak-definitions` | Create a streak definition | [`apps/api/src/streaks/streak-definitions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/streaks/streak-definitions.controller.ts) |
| `DELETE` | `/api/v1/streak-definitions/:id` | Delete a streak definition | [`apps/api/src/streaks/streak-definitions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/streaks/streak-definitions.controller.ts) |
| `GET` | `/api/v1/streak-definitions/:id` | Get a streak definition | [`apps/api/src/streaks/streak-definitions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/streaks/streak-definitions.controller.ts) |
| `PUT` | `/api/v1/streak-definitions/:id` | Update a streak definition | [`apps/api/src/streaks/streak-definitions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/streaks/streak-definitions.controller.ts) |
| `GET` | `/api/v1/token-config` | List token configurations | [`apps/api/src/token-config/token-config.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/token-config/token-config.controller.ts) |
| `POST` | `/api/v1/token-config` | Upsert token configuration | [`apps/api/src/token-config/token-config.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/token-config/token-config.controller.ts) |
| `GET` | `/api/v1/webhook-configs` | List webhook configs | [`apps/api/src/webhooks/webhooks.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/webhooks/webhooks.controller.ts) |
| `POST` | `/api/v1/webhook-configs` | Create webhook config | [`apps/api/src/webhooks/webhooks.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/webhooks/webhooks.controller.ts) |
| `DELETE` | `/api/v1/webhook-configs/:id` | Delete webhook config | [`apps/api/src/webhooks/webhooks.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/webhooks/webhooks.controller.ts) |
| `GET` | `/api/v1/webhook-configs/:id` | Get webhook config | [`apps/api/src/webhooks/webhooks.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/webhooks/webhooks.controller.ts) |
| `PUT` | `/api/v1/webhook-configs/:id` | Update webhook config | [`apps/api/src/webhooks/webhooks.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/webhooks/webhooks.controller.ts) |
| `GET` | `/api/v1/webhook-configs/:id/deliveries` | List webhook deliveries | [`apps/api/src/webhooks/webhooks.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/webhooks/webhooks.controller.ts) |
| `POST` | `/api/v1/webhook-configs/:id/deliveries/:deliveryId/redeliver` | Redeliver webhook | [`apps/api/src/webhooks/webhooks.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/webhooks/webhooks.controller.ts) |
| `POST` | `/api/v1/webhook-configs/:id/rotate-secret` | Rotate webhook secret | [`apps/api/src/webhooks/webhooks.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/webhooks/webhooks.controller.ts) |
| `POST` | `/api/v1/webhook-configs/:id/test` | Send test webhook | [`apps/api/src/webhooks/webhooks.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/webhooks/webhooks.controller.ts) |
| `POST` | `/api/v1/widget-sessions` | Create session token | [`apps/api/src/widget-sessions/widget-sessions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-sessions.controller.ts) |
| `DELETE` | `/api/v1/widget-sessions/:id` | Revoke widget session | [`apps/api/src/widget-sessions/widget-sessions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-sessions.controller.ts) |
| `GET` | `/api/v1/widget-sessions/preview` | Create automatic dashboard preview tokens | [`apps/api/src/widget-sessions/widget-sessions.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-sessions.controller.ts) |
| `POST` | `/api/v1/widget/appearance/rerender` | Rerender stage base | [`apps/api/src/widget-sessions/widget-api.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-api.controller.ts) |
| `GET` | `/api/v1/widget/badges` | Get widget badge catalog | [`apps/api/src/widget-sessions/widget-api.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-api.controller.ts) |
| `GET` | `/api/v1/widget/buddy` | Get widget buddy | [`apps/api/src/widget-sessions/widget-api.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-api.controller.ts) |
| `POST` | `/api/v1/widget/equip` | Equip or unequip items | [`apps/api/src/widget-sessions/widget-api.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-api.controller.ts) |
| `GET` | `/api/v1/widget/evolutions` | Get widget evolution timeline | [`apps/api/src/widget-sessions/widget-api.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-api.controller.ts) |
| `GET` | `/api/v1/widget/marketplace` | Get widget marketplace | [`apps/api/src/widget-sessions/widget-api.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-api.controller.ts) |
| `POST` | `/api/v1/widget/marketplace/items/:id/track-view` | Track marketplace item impression | [`apps/api/src/widget-sessions/widget-api.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-api.controller.ts) |
| `GET` | `/api/v1/widget/operations/:id` | Get widget operation | [`apps/api/src/widget-sessions/widget-api.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-api.controller.ts) |
| `GET` | `/api/v1/widget/path` | Get the active path for the buddy’s audience | [`apps/api/src/widget-sessions/widget-api.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-api.controller.ts) |
| `GET` | `/api/v1/widget/path/:key` | Get a specific path for a buddy | [`apps/api/src/widget-sessions/widget-api.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-api.controller.ts) |
| `POST` | `/api/v1/widget/path/:key/sub-steps/:subKey/complete` | Manually mark a sub-step complete | [`apps/api/src/widget-sessions/widget-api.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-api.controller.ts) |
| `POST` | `/api/v1/widget/purchase` | Purchase item | [`apps/api/src/widget-sessions/widget-api.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-api.controller.ts) |
| `GET` | `/api/v1/widget/state` | Get aggregate widget state | [`apps/api/src/widget-sessions/widget-api.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-api.controller.ts) |
| `GET` | `/api/v1/widget/streak/:key` | Get widget streak | [`apps/api/src/widget-sessions/widget-api.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-api.controller.ts) |
| `GET` | `/api/v1/widget/theme` | Live widget theme | [`apps/api/src/widget-sessions/widget-api.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-api.controller.ts) |
| `GET` | `/api/v1/widget/tokens` | Get the buddy’s token wallet | [`apps/api/src/widget-sessions/widget-api.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-api.controller.ts) |
| `POST` | `/api/v1/widget/track` | Track event from browser | [`apps/api/src/widget-sessions/widget-api.controller.ts`](https://github.com/hatched-live/hatched/blob/main/apps/api/src/widget-sessions/widget-api.controller.ts) |

{/* ENDPOINTS_END */}