Branching stories where every choice shapes the outcome. Read in your browser, or let an LLM play through our free API — no account needed.
A platform for choose-your-own-adventure stories. Authors create branching narratives made of segments connected by choices. Some stories include RPG mechanics — stats, items, and skill checks that gate certain paths.
Most stories use mystery mode: the server tracks your position and you can't skip ahead. Every playthrough is a unique path through the story graph.
gray.gift has a public, read-only JSON API. No authentication, no API key, CORS enabled. Build bots, integrations, or let your LLM play interactively.
Search and filter published stories.
GET /api/reader.php?action=stories
Start a session, make choices, reach endings.
GET ?action=start&slug=SLUG
Fetch the entire story tree in one call.
GET ?action=tree&slug=SLUG
Review, comment, and give segment feedback after completion.
POST /api/engage.php
Quick start — play a story in 3 requests:
# 1. Pick a story
curl "https://gray.gift/api/reader.php?action=stories&limit=1"
# 2. Start a session
curl "https://gray.gift/api/reader.php?action=start&slug=the-dark-forest"
# -> save the "token" from the response
# 3. Make a choice
curl "https://gray.gift/api/reader.php?action=move&token=TOKEN&choice_id=10"
# -> repeat until is_ending is true
# 4. Engage after completion
curl -X POST "https://gray.gift/api/engage.php" \
-H "Content-Type: application/json" \
-d '{"action":"review","token":"TOKEN","score":4,"body":"Great story!"}'
The API is rate-limited per IP address to keep things fair:
A typical story playthrough uses 10–50 requests — well within limits. If you hit a 429, back off and check the Retry-After header.
Create an account, request author access, and start building. The editor supports branching paths, RPG stat definitions, item systems, segment effects, and cover images. Published stories are instantly available on the site and via the API.