### Install Hatched SDK

Source: https://docs.hatched.live/docs/guides/getting-started

Install the SDK using pnpm or npm.

```bash
pnpm add @hatched/sdk-js
# or
npm install @hatched/sdk-js
```

--------------------------------

### Install Dependencies

Source: https://docs.hatched.live/docs/guides/express-integration

Install the necessary packages for @hatched/sdk-js and Express.

```bash
pnpm add @hatched/sdk-js express
```

--------------------------------

### Verify Widget Installation

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

Verifies the installation of a widget.

```APIDOC
## POST /api/v1/widget-sessions/verify-installation

### Description
Verify widget installation.

### Method
POST

### Endpoint
/api/v1/widget-sessions/verify-installation
```

--------------------------------

### Customer Settings Applied Sources Example

Source: https://docs.hatched.live/docs/concepts/token-economy

Example of the resolved token source configuration after applying an onboarding plan, showing 'tokens', 'marketplace', and 'theme' settings.

```json
{
  "tokens":      "plan" | "fallback",
  "marketplace": "plan" | "fallback" | "hybrid",
  "theme":       "fantasy",
  "applied_at":  "2026-04-22T10:30:00Z"
}
```

--------------------------------

### Install @hatched/react-native

Source: https://docs.hatched.live/docs/guides/react-native-integration

Install the main library and optional peer dependencies for React Native projects. For bare React Native, ensure you run `pod install` after installation.

```bash
npx expo install @hatched/react-native
# optional peers — install only the ones you use:
npx expo install react-native-webview react-native-svg
```

--------------------------------

### Cursor Pagination Request Example

Source: https://docs.hatched.live/docs/concepts/pagination

Example of how to pass cursor and limit as query parameters for cursor pagination.

```http
GET /api/v1/widget/notifications?cursor=eyJrIjoiMjAy...&limit=100
```

--------------------------------

### Install Hatched SDK for Next.js

Source: https://docs.hatched.live/docs/guides/nextjs-integration

Install the Hatched JavaScript SDK using pnpm. This is the first step to integrating Hatched into your Next.js project.

```bash
pnpm add @hatched/sdk-js
```

--------------------------------

### Install React Native SDK and Peers

Source: https://docs.hatched.live/docs/reference/react-native

Install the core @hatched/react-native package and optional peer dependencies like react-native-webview and react-native-svg using Expo.

```bash
npx expo install @hatched/react-native
# optional peers
npx expo install react-native-webview react-native-svg
```

--------------------------------

### GET /api/v1/presets

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

Lists available presets.

```APIDOC
## GET /api/v1/presets

### Description
List presets.

### Method
GET

### Endpoint
/api/v1/presets
```

--------------------------------

### GET /api/v1/skill-sets

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

Lists all available skill sets.

```APIDOC
## GET /api/v1/skill-sets

### Description
List all skill sets.

### Method
GET

### Endpoint
/api/v1/skill-sets
```

--------------------------------

### GET /api/v1/public/returning-champion/welcome-back

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

Resolves a Returning Champion welcome-back token to a widget session.

```APIDOC
## GET /api/v1/public/returning-champion/welcome-back

### Description
Resolve a Returning Champion welcome-back token to a widget session.

### Method
GET

### Endpoint
/api/v1/public/returning-champion/welcome-back
```

--------------------------------

### GET /api/v1/presets/{key}

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

Retrieves a specific preset by its key.

```APIDOC
## GET /api/v1/presets/{key}

### Description
Get preset.

### Method
GET

### Endpoint
/api/v1/presets/{key}

### Parameters
#### Path Parameters
- **key** (string) - Required - The unique key of the preset.
```

--------------------------------

### Start egg hatching process

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

Initiates the asynchronous process of hatching an egg.

```APIDOC
## POST /api/v1/eggs/{id}/hatch

### Description
Start the asynchronous hatch process for an egg.

### Method
POST

### Endpoint
/api/v1/eggs/{id}/hatch

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the egg to hatch.
```

--------------------------------

### GET /api/v1/customers/me/beginners-luck/analytics

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

Beginner's Luck winner analytics.

```APIDOC
## GET /api/v1/customers/me/beginners-luck/analytics

### Description
Beginner's Luck winner analytics.

### Method
GET

### Endpoint
/api/v1/customers/me/beginners-luck/analytics
```

--------------------------------

### GET /api/v1/buddy-share/settings

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

Tenant buddy-share settings (toggles + resolved link origin).

```APIDOC
## GET /api/v1/buddy-share/settings

### Description
Tenant buddy-share settings (toggles + resolved link origin).

### Method
GET

### Endpoint
/api/v1/buddy-share/settings
```

--------------------------------

### GET /healthz

Source: https://docs.hatched.live/docs/reference/health-version

Liveness probe endpoint. Returns immediately with a 200 status code indicating the process is up. Includes uptime in seconds since process start.

```APIDOC
## GET /healthz

### Description
Liveness probe to check if the process is running.

### Method
GET

### Endpoint
/healthz

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the service is operational.
- **uptime** (integer) - Uptime in seconds since the process started.

### Request Example
```bash
curl https://api.hatched.live/healthz
```

### Response Example
```json
{
  "ok": true,
  "uptime": 4623
}
```
```

--------------------------------

### Hatched SDK Quickstart

Source: https://docs.hatched.live/docs

This snippet demonstrates the basic workflow of creating a buddy, teaching it about your product, and embedding the widget using the Hatched JavaScript SDK.

```javascript
import { HatchedClient } from '@hatched/sdk-js';

const hatched = new HatchedClient({
  apiKey: process.env.HATCHED_API_KEY!,
});

// 1. create a buddy (Greenwave Learning Co. — a new instructional designer)
const egg = await hatched.eggs.create({ userId: 'user_designer_priya' });
await hatched.eggs.updateStatus(egg.eggId, 'ready');
const op = await hatched.eggs.hatch(egg.eggId);
const finished = await hatched.operations.wait(op.operationId);

// 2. teach the buddy about your product
await hatched.events.send({
  eventId: 'lesson_module_review_user_designer_priya_2026_05_03',
  userId: 'user_designer_priya',
  type: 'lesson_completed',
  properties: { score: 94 },
});

// 3. mint a browser token and embed the widget
const session = await hatched.widgetSessions.create({
  buddyId: finished.result.buddyId,
  userId: 'user_designer_priya',
  scopes: ['read', 'events:track'],
  ttlSeconds: 900,
});
```

--------------------------------

### GET /api/v1/customers/me

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

Get customer details.

```APIDOC
## GET /api/v1/customers/me

### Description
Get customer details.

### Method
GET

### Endpoint
/api/v1/customers/me
```

--------------------------------

### GET /readyz

Source: https://docs.hatched.live/docs/reference/health-version

Readiness probe endpoint. Checks if essential dependencies like the database and Redis are reachable. Returns 200 if ready, or 503 if not ready.

```APIDOC
## GET /readyz

### Description
Readiness probe to check if the service and its dependencies (DB, Redis) are ready to serve traffic.

### Method
GET

### Endpoint
/readyz

### Response
#### Success Response (200)
- **ready** (boolean) - Indicates if the service is ready.
- **db** (boolean) - Indicates if the database is reachable.
- **redis** (boolean) - Indicates if Redis is reachable.

#### Error Response (503)
- **ready** (boolean) - `false` if the service or its dependencies are not ready.
- **db** (boolean) - `false` if the database is unreachable.
- **redis** (boolean) - `false` if Redis is unreachable.

### Request Example
```bash
curl -i https://api.hatched.live/readyz
```

### Response Example
```json
{
  "ready": true,
  "db": true,
  "redis": true
}
```
```

--------------------------------

### GET /api/v1/credits/balance

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

Get credit balance.

```APIDOC
## GET /api/v1/credits/balance

### Description
Get credit balance.

### Method
GET

### Endpoint
/api/v1/credits/balance
```

--------------------------------

### Using a Publishable Key

Source: https://docs.hatched.live/docs/concepts/auth-model

Demonstrates initializing the Hatched client with a publishable key and making a valid API call. Publishable keys are scoped and should not be used for sensitive operations.

```javascript
const hatched = new HatchedClient({
  publishableKey: 'hatch_pk_xxxxxxxx',
});

const buddy = await hatched.buddies.get(buddyId);     // ✅ ok
await hatched.events.send({ ... });                    // ❌ PublishableKeyScopeError
```

--------------------------------

### GET /api/v1/config-versions/{id}

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

Get config version.

```APIDOC
## GET /api/v1/config-versions/{id}

### Description
Get config version.

### Method
GET

### Endpoint
/api/v1/config-versions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the config version.
```

--------------------------------

### Token Configuration Example

Source: https://docs.hatched.live/docs/concepts/tokens

Illustrates the configuration of primary and progression tokens with their respective properties and earning rules.

```plaintext
gems  (primary)      — earned from lesson_completed, spent on items + gates.
                       Capped at 500 per week.

mana  (progression)  — earned from quiz_passed, feeds "stage 3 at mana ≥ 1000"
                       evolution readiness. Cannot be spent.
```

--------------------------------

### Basic React Native Gamification Setup

Source: https://docs.hatched.live/docs/guides/react-native-integration

Set up the HatchedProvider with your API token, base URL, and theme. Then, include various Hatched widgets like BuddyWidget, StreakWidget, LeaderboardWidget, and MarketplaceWidget within the provider.

```jsx
import {
  HatchedProvider,
  BuddyWidget,
  LeaderboardWidget,
  MarketplaceWidget,
  StreakWidget,
} from '@hatched/react-native';

export function GamificationScreen({ token }: { token: string }) {
  return (
    <HatchedProvider
      token={token}
      apiBaseUrl="https://api.hatched.live/api/v1"
      theme="light"
    >
      <BuddyWidget />
      <StreakWidget streakKey="daily_lesson" />
      <LeaderboardWidget scope="team" />
      <MarketplaceWidget />
    </HatchedProvider>
  );
}
```

--------------------------------

### GET /api/v1/customers/me/brag/config

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

Get the Brag Button channel + copy-template config.

```APIDOC
## GET /api/v1/customers/me/brag/config

### Description
Get the Brag Button channel + copy-template config.

### Method
GET

### Endpoint
/api/v1/customers/me/brag/config
```

--------------------------------

### Example Request with Idempotency-Key

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

Demonstrates how to use the Idempotency-Key header for mutating write operations to ensure idempotency.

```http
POST /api/v1/purchases HTTP/1.1
Host: api.hatched.live
Authorization: Bearer hatch_live_********************
Idempotency-Key: some-unique-key-for-this-request
```

--------------------------------

### Example Cursor-Based Pagination

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

Response structure for cursor-based pagination, including nextCursor and hasMore.

```json
{
  "data": [
    // ... items ...
  ],
  "pagination": {
    "nextCursor": "some-opaque-cursor-string",
    "hasMore": true,
    "limit": 20
  }
}
```

--------------------------------

### GET /api/v1/buddies/{id}

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

Get buddy details with full canonical state.

```APIDOC
## GET /api/v1/buddies/{id}

### Description
Get buddy details with full canonical state.

### Method
GET

### Endpoint
/api/v1/buddies/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the buddy.
```

--------------------------------

### Bootstrap Egg Lifecycle with Raw HTTP

Source: https://docs.hatched.live/docs/guides/first-user-bootstrap

This sequence demonstrates bootstrapping a user's egg using raw HTTP requests. It includes creating the egg with `ensure=true`, updating its status to 'ready' if necessary, initiating the hatch operation, and polling for the operation's completion. Note that the status update step can be skipped if the egg is already 'ready'.

```http
POST /api/v1/eggs?ensure=true
{ "user_id": "user_42", "metadata": {} }
# → { "egg_id": "…", "status": "waiting", "buddy_id": null, … }
# (status may already be "ready" if you're reusing an egg — skip the PATCH then.)

PATCH /api/v1/eggs/{egg_id}/status
{ "status": "ready" }

POST /api/v1/eggs/{egg_id}/hatch
# → { "operation_id": "op_…", "status": "pending" }

# Poll every ~2s until status is "completed" (typically 5–45s):
GET /api/v1/operations/{operation_id}
# → { "operation_id": "op_…", "status": "completed", "result": { "buddy_id": "…" }, … }
```

--------------------------------

### Initializing the Buddy Widget (Client-Rendered)

Source: https://docs.hatched.live/docs/reference/widgets/buddy

For client-rendered routes, initialize the widget after the mount element exists using `window.__HATCHED_WIDGET__.init()`. The payload uses `token`, not `embedToken`.

```javascript
window.__HATCHED_WIDGET__?.init({ token });
```

--------------------------------

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

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

Get buddy progression metrics (legacy endpoint).

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

### Description
Get buddy progression metrics (legacy endpoint).

### Method
GET

### Endpoint
/api/v1/buddies/{buddy_id}/progression

### Parameters
#### Path Parameters
- **buddy_id** (string) - Required - The ID of the buddy.
```

--------------------------------

### GET /api/v1/customers/me/feature-config

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

Get the tenant feature_config blob. This retrieves the entire feature configuration for the tenant.

```APIDOC
## GET /api/v1/customers/me/feature-config

### Description
Get the tenant feature_config blob.

### Method
GET

### Endpoint
/api/v1/customers/me/feature-config
```

--------------------------------

### Example HTTP Request with Authorization

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

Demonstrates how to make an authenticated request to the Hatched API using a secret key.

```http
GET /api/v1/users/me HTTP/1.1
Host: api.hatched.live
Authorization: Bearer hatch_live_********************
```

--------------------------------

### GET /api/v1/customers/me/feature-toggles

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

Get the tenant feature toggle state. This retrieves the current state of all feature toggles.

```APIDOC
## GET /api/v1/customers/me/feature-toggles

### Description
Get the tenant feature toggle state.

### Method
GET

### Endpoint
/api/v1/customers/me/feature-toggles
```

--------------------------------

### Credit Balance Response

Source: https://docs.hatched.live/docs/billing/credits

Example JSON response showing the breakdown of credits in welcome, paid, and promo pools, along with the total spendable credits and promo expiration.

```json
{
  "welcome": 7,
  "paid": 43,
  "promo": 0,
  "promo_expires_at": null,
  "total_spendable": 50
}
```

--------------------------------

### GET /api/v1/buddies/users/{user_id}/summary

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

Get a user summary including buddy count, coins, and badges.

```APIDOC
## GET /api/v1/buddies/users/{user_id}/summary

### Description
Get a user summary including buddy count, coins, and badges.

### Method
GET

### Endpoint
/api/v1/buddies/users/{user_id}/summary

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The ID of the user.
```

--------------------------------

### POST /api/v1/customers/me/apply-preset

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

Apply preset.

```APIDOC
## POST /api/v1/customers/me/apply-preset

### Description
Apply preset.

### Method
POST

### Endpoint
/api/v1/customers/me/apply-preset
```

--------------------------------

### GET /api/v1/buddies/{buddy_id}/progression-metrics

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

Get buddy progression metrics (lessons, quizzes, streaks, etc.).

```APIDOC
## GET /api/v1/buddies/{buddy_id}/progression-metrics

### Description
Get buddy progression metrics (lessons, quizzes, streaks, etc.).

### Method
GET

### Endpoint
/api/v1/buddies/{buddy_id}/progression-metrics

### Parameters
#### Path Parameters
- **buddy_id** (string) - Required - The ID of the buddy.
```

--------------------------------

### Create and Hatch a Buddy (JavaScript)

Source: https://docs.hatched.live/docs/guides/getting-started

Create a new egg for a user, ensuring reuse if one exists. Update its status to 'ready' if it's 'waiting', then hatch it and wait for the operation to complete to get the buddy ID. Persist the buddyId for future use.

```javascript
const egg = await hatched.eggs.create({ userId: 'user_42', ensure: true });

if (egg.status === 'waiting') {
  await hatched.eggs.updateStatus(egg.eggId, 'ready');
}
const hatchOp = await hatched.eggs.hatch(egg.eggId);
const finished = await hatched.operations.wait(hatchOp.operationId, { timeoutMs: 60_000 });

const buddyId = finished.result.buddyId;
console.log('Buddy ready:', buddyId);
// Persist buddyId against your app user — you need it for the widget session below
// and on every future page load. (See "Persist buddy_id" in the bootstrap guide.)
```

--------------------------------

### Coin Rule Examples

Source: https://docs.hatched.live/docs/concepts/coins

Examples of coin rules mapping event types to coin amounts, including optional caps and conditions.

```plaintext
lesson_completed  → +10 coins (daily cap: 50)
streak_7          → +100 coins (one-time)
checkout_complete → +500 coins (premium audience only)
```

--------------------------------

### Initialize Hatched Client in Browser

Source: https://docs.hatched.live/docs/guides/browser-usage

Instantiate the HatchedClient in a browser environment using a publishable key. Ensure the NEXT_PUBLIC_HATCHED_PK environment variable is set. The baseUrl can be configured for staging environments.

```javascript
import { HatchedClient } from '@hatched/sdk-js';

const hatched = new HatchedClient({
  publishableKey: process.env.NEXT_PUBLIC_HATCHED_PK!,
  // Set this for staging publishable keys.
  baseUrl: process.env.NEXT_PUBLIC_HATCHED_API_BASE_URL,
});
```

--------------------------------

### Complete next.config.mjs CSP Example

Source: https://docs.hatched.live/docs/guides/widget-csp

Configure Content Security Policy headers for all routes in a Next.js application. This policy is designed to work with Hatched widgets out-of-the-box.

```javascript
const csp = [
  "script-src 'self' https://cdn.hatched.live",
  "connect-src 'self' https://api.hatched.live",
  "img-src 'self' https://cdn.hatched.live data:",
  "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com",
  "font-src 'self' data: https://fonts.gstatic.com",
].join('; ');

export default {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [{ key: 'Content-Security-Policy', value: csp }],
      },
    ];
  },
};
```

--------------------------------

### onboarding_extract_failed

Source: https://docs.hatched.live/docs/reference/error-codes

The onboarding pipeline could not verify gamification selections from the generated plan. No state was persisted. If a reason was captured, it will be in `err.details.reason`.

```APIDOC
## onboarding_extract_failed

### Description
The onboarding pipeline could not verify the gamification selections extracted from the generated plan.

### HTTP Status
503

### SDK Class
`HatchedError` (base)

### Fix
Retry plan generation after a short backoff.
```

--------------------------------

### 429 Too Many Requests Response Example

Source: https://docs.hatched.live/docs/reference/rate-limits

This is an example of the HTTP response received when a rate limit is exceeded. The `Retry-After` header indicates the duration in seconds to wait before retrying.

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "requestId": "…"
  }
}
```

--------------------------------

### Embed Token Response Example

Source: https://docs.hatched.live/docs/concepts/auth-model

This is an example of the JSON response received after successfully minting an embed token. It includes the token itself, its expiration time, and the mode of operation.

```json
{ "token": "eyJhbGciOi…", "expires_at": "2026-05-05T16:00:00Z", "mode": "read-only" }
```

--------------------------------

### Create Hosted Surface Recipe

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

Creates a new recipe for a hosted surface.

```APIDOC
## POST /api/v1/customers/me/hosted-surfaces/{id}/recipes

### Description
Create a recipe for a hosted surface.

### Method
POST

### Endpoint
/api/v1/customers/me/hosted-surfaces/{id}/recipes

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the hosted surface.
```

--------------------------------

### GET /api/v1/customers/me/founding-cohort/preview

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

Project how many buddies the Founding Cohort configuration would mark. Optional query parameters allow previewing an unsaved mode or threshold.

```APIDOC
## GET /api/v1/customers/me/founding-cohort/preview

### Description
Project how many buddies the Founding Cohort config would mark. Optional query params preview an unsaved mode/threshold.

### Method
GET

### Endpoint
/api/v1/customers/me/founding-cohort/preview

### Parameters
#### Query Parameters
- **mode** (string) - Optional - The mode to preview.
- **threshold** (number) - Optional - The threshold to preview.
```

--------------------------------

### Check Hosted Surface Readiness

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

Checks the per-widget content readiness for a hosted surface's go-live checklist.

```APIDOC
## GET /api/v1/customers/me/hosted-surfaces/{id}/readiness

### Description
Per-widget content readiness for the go-live checklist.

### Method
GET

### Endpoint
/api/v1/customers/me/hosted-surfaces/{id}/readiness

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the hosted surface.
```

--------------------------------

### Get Leaderboard

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

Retrieves the leaderboard data.

```APIDOC
## GET /api/v1/widget/leaderboard

### Description
Get leaderboard.

### Method
GET

### Endpoint
/api/v1/widget/leaderboard
```

--------------------------------

### Liveness Probe

Source: https://docs.hatched.live/docs/reference/health-version

Use this as your Kubernetes livenessProbe. It returns immediately with the process uptime in seconds.

```shell
curl https://api.hatched.live/healthz
# {"ok":true,"uptime":4623}
```

--------------------------------

### GET /api/v1/config-versions

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

List config versions.

```APIDOC
## GET /api/v1/config-versions

### Description
List config versions.

### Method
GET

### Endpoint
/api/v1/config-versions
```

--------------------------------

### onboarding_extract_failed

Source: https://docs.hatched.live/docs/reference/error-codes

The onboarding pipeline could not verify gamification selections.

```APIDOC
## onboarding_extract_failed

### Description
The onboarding pipeline could not verify the gamification selections extracted from the generated plan (HTTP 503). No state was persisted.

### HTTP status
503

### SDK class
`HatchedError` (base)

### Details
`err.details.reason` is present when a reason was captured.

### Fix
Review the onboarding process and gamification selections. Ensure they are valid and correctly extracted. Check `err.details.reason` for specific issues.
```

--------------------------------

### GET /api/v1/coin-rules

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

List all coin rules.

```APIDOC
## GET /api/v1/coin-rules

### Description
List all coin rules.

### Method
GET

### Endpoint
/api/v1/coin-rules
```

--------------------------------

### Onboarding API

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

Endpoints for managing the onboarding process.

```APIDOC
## POST /api/v1/onboarding/sessions

### Description
Create or resume the current onboarding session.

### Method
POST

### Endpoint
/api/v1/onboarding/sessions
```

```APIDOC
## PUT /api/v1/onboarding/sessions/{id}/answers

### Description
Patch structured onboarding answers.

### Method
PUT

### Endpoint
/api/v1/onboarding/sessions/{id}/answers
```

```APIDOC
## POST /api/v1/onboarding/sessions/{id}/apply

### Description
Apply the generated plan to the customer (writes gamification config).

### Method
POST

### Endpoint
/api/v1/onboarding/sessions/{id}/apply
```

```APIDOC
## POST /api/v1/onboarding/sessions/{id}/generate-guide

### Description
Generate a personalized integration guide.

### Method
POST

### Endpoint
/api/v1/onboarding/sessions/{id}/generate-guide
```

```APIDOC
## POST /api/v1/onboarding/sessions/{id}/generate-plan

### Description
Generate a gamification plan from the conversation.

### Method
POST

### Endpoint
/api/v1/onboarding/sessions/{id}/generate-plan
```

```APIDOC
## POST /api/v1/onboarding/sessions/{id}/message

### Description
Send a user message and stream the assistant reply via server-sent events.

### Method
POST

### Endpoint
/api/v1/onboarding/sessions/{id}/message
```

```APIDOC
## POST /api/v1/onboarding/sessions/{id}/regenerate-plan

### Description
Regenerate the plan with a variant seed.

### Method
POST

### Endpoint
/api/v1/onboarding/sessions/{id}/regenerate-plan
```

```APIDOC
## GET /api/v1/onboarding/sessions/current

### Description
Fetch the current onboarding session.

### Method
GET

### Endpoint
/api/v1/onboarding/sessions/current
```

```APIDOC
## GET /api/v1/onboarding/sessions/preparing-status

### Description
Aggregate asset-generation status for the current customer.

### Method
GET

### Endpoint
/api/v1/onboarding/sessions/preparing-status
```

```APIDOC
## POST /api/v1/onboarding/sessions/reset

### Description
Reset the current onboarding session.

### Method
POST

### Endpoint
/api/v1/onboarding/sessions/reset
```

```APIDOC
## POST /api/v1/onboarding/sessions/seed-from-description

### Description
Seed onboarding from operator-provided chips + optional description.

### Method
POST

### Endpoint
/api/v1/onboarding/sessions/seed-from-description
```

```APIDOC
## POST /api/v1/onboarding/sessions/seed-from-repo

### Description
Seed onboarding from a repo-analysis brief produced by a local AI agent.

### Method
POST

### Endpoint
/api/v1/onboarding/sessions/seed-from-repo
```

```APIDOC
## POST /api/v1/onboarding/sessions/seed-from-url

### Description
Seed onboarding from a landing-page URL.

### Method
POST

### Endpoint
/api/v1/onboarding/sessions/seed-from-url
```

```APIDOC
## POST /api/v1/onboarding/sessions/waitlist

### Description
Join the waitlist for an upcoming onboarding channel.

### Method
POST

### Endpoint
/api/v1/onboarding/sessions/waitlist
```

--------------------------------

### Send First Event (curl)

Source: https://docs.hatched.live/docs/guides/getting-started

Send a lesson completion event using curl and pipe the output to jq for pretty-printing and checking acceptance.

```bash
FIRST_EVENT=$(curl -sS -X POST https://api.hatched.live/api/v1/events \
  -H "Authorization: Bearer $HATCHED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ \
    "event_id": "lesson_lsn_1_user_42", \
    "user_id": "user_42", \
    "type": "lesson_completed", \
    "properties": { "lesson_id": "lesson_1", "duration_ms": 300000 } \
  }')

echo "$FIRST_EVENT" | jq .
echo "$FIRST_EVENT" | jq -e '.accepted == true'
```

--------------------------------

### GET /api/v1/skill-rules

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

Lists all available skill rules.

```APIDOC
## GET /api/v1/skill-rules

### Description
List all skill rules.

### Method
GET

### Endpoint
/api/v1/skill-rules
```

--------------------------------

### GET /api/v1/skill-decay-rules

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

Lists all skill decay rules.

```APIDOC
## GET /api/v1/skill-decay-rules

### Description
List skill decay rules.

### Method
GET

### Endpoint
/api/v1/skill-decay-rules
```

--------------------------------

### Create a Showroom page from a template

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

Creates a new Showroom page using a specified template.

```APIDOC
## POST /api/v1/customers/me/showrooms

### Description
Create a Showroom page from a template.

### Method
POST

### Endpoint
/api/v1/customers/me/showrooms
```

--------------------------------

### GET /api/v1/buddy-share/stats

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

Rolling-window buddy-share funnel for the tenant.

```APIDOC
## GET /api/v1/buddy-share/stats

### Description
Rolling-window buddy-share funnel for the tenant.

### Method
GET

### Endpoint
/api/v1/buddy-share/stats
```

--------------------------------

### POST /api/v1/customers/me/hosted-surfaces

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

Create a hosted surface from a template. This endpoint allows for the creation of new hosted surfaces.

```APIDOC
## POST /api/v1/customers/me/hosted-surfaces

### Description
Create a hosted surface from a template.

### Method
POST

### Endpoint
/api/v1/customers/me/hosted-surfaces

### Parameters
#### Request Body
- **hosted_surface_details** (object) - Required - The details of the hosted surface to create, including the template to use.
```

--------------------------------

### Get Widget Narrative

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

Retrieves the tenant narrative for the widget.

```APIDOC
## GET /api/v1/widget/narrative

### Description
Get the tenant narrative.

### Method
GET

### Endpoint
/api/v1/widget/narrative
```

--------------------------------

### Example HTTP Request with Publishable Key

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

Shows an authenticated request using a publishable key, typically for limited read operations.

```http
GET /api/v1/widgets HTTP/1.1
Host: api.hatched.live
Authorization: Bearer hatch_pk_********************
```

--------------------------------

### Get Widget Marketplace

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

Retrieves data for the widget marketplace.

```APIDOC
## GET /api/v1/widget/marketplace

### Description
Get widget marketplace.

### Method
GET

### Endpoint
/api/v1/widget/marketplace
```

--------------------------------

### Get Widget Buddy

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

Retrieves information about the widget buddy.

```APIDOC
## GET /api/v1/widget/buddy

### Description
Get widget buddy.

### Method
GET

### Endpoint
/api/v1/widget/buddy
```

--------------------------------

### Readiness Probe

Source: https://docs.hatched.live/docs/reference/health-version

Use this as your Kubernetes readinessProbe. It returns 503 if Postgres or Redis is unreachable, ensuring the pod is removed from the load balancer until dependencies are green.

```shell
curl -i https://api.hatched.live/readyz
# HTTP/1.1 200 OK
# {"ready":true,"db":true,"redis":true}
```

--------------------------------

### Get user summary

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

Retrieves a summary of user information.

```APIDOC
## GET /api/v1/customers/me/users/{user_id}/summary

### Description
Get user summary.

### Method
GET

### Endpoint
/api/v1/customers/me/users/{user_id}/summary

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The ID of the user.
```

--------------------------------

### Run Hosted Surface Recipe

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

Executes a specific recipe for a hosted surface.

```APIDOC
## POST /api/v1/customers/me/hosted-surfaces/{id}/recipes/{key}/run

### Description
Run a specific recipe for a hosted surface.

### Method
POST

### Endpoint
/api/v1/customers/me/hosted-surfaces/{id}/recipes/{key}/run

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the hosted surface.
- **key** (string) - Required - The key of the recipe to run.
```

--------------------------------

### GET /api/v1/customers/me/causes

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

List the tenant Cause Counter definitions.

```APIDOC
## GET /api/v1/customers/me/causes

### Description
List the tenant Cause Counter definitions.

### Method
GET

### Endpoint
/api/v1/customers/me/causes
```

--------------------------------

### Example HTTP Request with Session Token

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

Illustrates an authenticated request using a short-lived session token, often used by widgets.

```http
POST /api/v1/widget-sessions HTTP/1.1
Host: api.hatched.live
Authorization: Bearer session_********************
```

--------------------------------

### GET /api/v1/customers/me/brag/telemetry.csv

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

Export raw brag telemetry as CSV.

```APIDOC
## GET /api/v1/customers/me/brag/telemetry.csv

### Description
Export raw brag telemetry as CSV.

### Method
GET

### Endpoint
/api/v1/customers/me/brag/telemetry.csv
```

--------------------------------

### Add Founding Cohort Admin Resource (F2.13)

Source: https://docs.hatched.live/docs/reference/changelog

Adds the tenant-admin `foundingCohort` resource for the Planner "Founding Cohort" drawer. Supports `preview` for projected assignments, `backfill` for retroactive assignment, and `listAudit` for assignment history. Includes new types for cohort modes, previews, and audit entries.

```typescript
Add the Founding Cohort admin resource (F2.13). The tenant-admin `foundingCohort` resource backs the Planner "Founding Cohort" drawer: `preview` projects how many buddies the current eligibility config would mark, `backfill` runs the one-shot retroactive assignment, and `listAudit` reads the assignment history. New exported types `FoundingCohortMode`, `FoundingCohortPreview`, `FoundingCohortBackfillResult` and `FoundingCohortAuditEntry`.
```

--------------------------------

### GET /api/v1/customers/me/brag/funnel

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

Brag funnel aggregate over a date window.

```APIDOC
## GET /api/v1/customers/me/brag/funnel

### Description
Brag funnel aggregate over a date window.

### Method
GET

### Endpoint
/api/v1/customers/me/brag/funnel
```

--------------------------------

### Mount Feed Widget

Source: https://docs.hatched.live/docs/reference/widgets/feed

Include this script to load the widget and the HTML element to mount it. Use a `data-session-token` to enable clapping functionality.

```html
<script src="https://cdn.hatched.live/widget.js" data-embed-token="EMBED_TOKEN" defer></script>

<div data-hatched-mount="feed"></div>
```

--------------------------------

### GET /api/v1/customers/me/awards

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

Customer-wide HR award audit log.

```APIDOC
## GET /api/v1/customers/me/awards

### Description
Customer-wide HR award audit log.

### Method
GET

### Endpoint
/api/v1/customers/me/awards
```

--------------------------------

### GET /api/v1/config-versions/{id}/impact

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

Preview config impact.

```APIDOC
## GET /api/v1/config-versions/{id}/impact

### Description
Preview config impact.

### Method
GET

### Endpoint
/api/v1/config-versions/{id}/impact

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the config version.
```

--------------------------------

### GET /api/v1/coin-rules/{id}/reward-pool/telemetry

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

Reward pool telemetry.

```APIDOC
## GET /api/v1/coin-rules/{id}/reward-pool/telemetry

### Description
Reward pool telemetry.

### Method
GET

### Endpoint
/api/v1/coin-rules/{id}/reward-pool/telemetry

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the coin rule.
```

--------------------------------

### Rate Limit Headers Example

Source: https://docs.hatched.live/docs/reference/rate-limits

These headers provide information about the current rate limit status. `X-RateLimit-Limit` shows the limit, `X-RateLimit-Remaining` shows remaining requests, and `X-RateLimit-Reset` indicates when the limit resets.

```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 98
X-RateLimit-Reset: 1745327400
```

--------------------------------

### Get Mission Anchor Payload

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

Retrieves the Mission Anchor payload.

```APIDOC
## GET /api/v1/widget/mission-anchor

### Description
Get the Mission Anchor payload.

### Method
GET

### Endpoint
/api/v1/widget/mission-anchor
```

--------------------------------

### Mounting the Buddy Widget

Source: https://docs.hatched.live/docs/reference/widgets/buddy

Include this script tag to load the widget. Use `data-session-token` for interactive mode or `data-embed-token` for read-only mode.

```html
<script src="https://cdn.hatched.live/widget.js" data-session-token="SESSION_TOKEN" defer></script>

<div data-hatched-mount="buddy"></div>
```

--------------------------------

### Get Widget Evolution Timeline

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

Fetches the evolution timeline for the widget.

```APIDOC
## GET /api/v1/widget/evolutions

### Description
Get widget evolution timeline.

### Method
GET

### Endpoint
/api/v1/widget/evolutions
```

--------------------------------

### Example Page-Based Pagination

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

Response structure for page-based pagination, including page, limit, and total.

```json
{
  "data": [
    // ... items ...
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}
```

--------------------------------

### Get Webhook Configuration

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

Retrieves a specific webhook configuration by its ID.

```APIDOC
## GET /api/v1/webhook-configs/{id}

### Description
Get webhook config.

### Method
GET

### Endpoint
/api/v1/webhook-configs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier for the webhook configuration.
```

--------------------------------

### Handle Evolution Ready Event (TypeScript)

Source: https://docs.hatched.live/docs/guides/getting-started

Send a lesson completion event and check if evolution is ready. If so, initiate the buddy evolution process and wait for its completion.

```typescript
const effects = await hatched.events.send({
  eventId: 'lesson_lsn_2_user_42',
  userId: 'user_42',
  type: 'lesson_completed',
});

if (effects.evolutionReady) {
  const evolveOp = await hatched.buddies.evolve('bdy_abc');
  await hatched.operations.wait(evolveOp.operationId);
}
```

--------------------------------

### Mount the Marketplace Widget

Source: https://docs.hatched.live/docs/reference/widgets/marketplace

Include this script and div to mount the marketplace widget on your page. Ensure the session token is correctly provided.

```html
<script src="https://cdn.hatched.live/widget.js" data-session-token="SESSION_TOKEN" defer></script>

<div data-hatched-mount="marketplace"></div>
```