HTTP API

Most integrations should use @hatched/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

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 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:

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

Response:

{
  "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:

{
  "accepted": true,
  "operation_id": "op_123",
  "status": "pending"
}

POST /api/v1/events

Purpose:

• ingest a customer domain event

Request:

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

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

Response:

{
  "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:

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

Response:

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

POST /api/v1/embed-tokens

Purpose:

• mint a signed token for a read-only widget

7. UX Guardrails for the Dashboard

7.1 Rule templates instead of a rule builder

The V1 panel must offer:

• Pick a trigger
• Pick a reward
• Pick a limit
• Preview impact

The V1 panel must NOT offer:

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

7.2 Publish UX

Every progression editor follows this shape:

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

7.3 Support UX

Support/operator screens must surface:

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

These screens exist for operational confidence, not enterprise complexity.

8. Business Process Decisions

8.1 What we keep centralized

Hatched owns the truth for:

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

8.2 What we leave to the customer

The customer owns:

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

8.3 What we deliberately don't build

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

9. Recommended V1 Motto

"Customer events in, progression out."

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

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

Everything else is secondary.

Endpoints