gray.gift

# gray.gift > Interactive fiction platform where readers make choices that shape the story. gray.gift hosts branching, choose-your-own-adventure stories. Authors create stories made of segments connected by choices. Some stories include RPG mechanics (stats, items, skill checks). ## Reader API A public, read-only JSON API is available at `/api/reader.php` — no authentication required. Responses are JSON. Each segment includes both `body` (raw Markdown — use this to save tokens) and `body_html` (rendered HTML — ignore unless you need formatting). ### Mystery Mode Most stories have **mystery mode** enabled (default). Mystery mode means you must play through the story sequentially using server-tracked sessions — no skipping ahead or reading the whole story at once. The server tracks your position, RPG stats, and inventory. Check the `mystery_mode` field on any story to know which play style to use. ### Endpoints - `GET ?action=stories` — browse/search published stories (includes `mystery_mode` flag) - `GET ?action=story&slug=SLUG` — story details, tags, RPG config - `GET ?action=start&slug=SLUG` — **start a mystery mode session** (returns token + first segment) - `GET ?action=move&token=TOKEN&choice_id=ID` — **make a choice** (advances session, returns next segment) - `GET ?action=state&token=TOKEN` — **get current session state** (segment, RPG state, history) - `GET ?action=segment&id=ID` — read a segment directly (blocked for mystery mode stories) - `GET ?action=choice&id=ID` — follow a choice directly (blocked for mystery mode stories) - `GET ?action=tree&slug=SLUG` — full story graph (blocked for mystery mode stories) - `GET ?action=tags` — list all tags ### Playing a mystery mode story (recommended) 1. Find a story via `action=stories` — look for `"mystery_mode": true` 2. Start a session: `action=start&slug=SLUG` → save the `token` 3. Read the segment, review available choices (each has an `available` flag) 4. Make a choice