Start here

Quickstart

Create a token in Settings, Developer API, then call the API with it. Everything is JSON over HTTPS. The base URL is https://aistoryhub.co.

cURL

curl https://aistoryhub.co/api/v1/me \
  -H "Authorization: Bearer ash_your_token_here"

Security

Authentication

Every request is authenticated with an API token sent as a bearer token. Tokens are shown once at creation, so store them securely and never expose them in client-side code. Revoke a token any time from your settings.

Header

Authorization: Bearer ash_your_token_here

Permissions

Scopes

A token only grants the scopes you select. Scopes are explicit, so write access does not imply read access. Request the minimum a given integration needs.

account:readRead basic account info (id, email, plan).

stories:readList and read your stories and their chapters.

stories:writeCreate and update stories.

world:readRead world-building entries (characters, locations, lore, factions, items, species, timeline).

world:writeCreate, update, and delete world-building entries.

ai:generateRun AI prose generation. Uses your own connected AI provider key.

ai:reviseRun AI revision passes (improve text, Human Grit Pass). Uses your own connected AI provider key.

ai:editorialRun the Editorial Pass to get structured line and structural notes on a chapter. Uses your own connected AI provider key.

Reference

Endpoints

The ai:* endpoints run on your own connected AI provider key (the same BYOK key the app uses), so usage is billed by your provider, not by AIStoryHub. They accept a JSON body; generate, revise, and grit-pass return { text }, while editorial-pass returns structured notes. The accent-colored code next to each row is the matching MCP tool name.

Account

GET/api/v1/me

The token owner's account.

get_meaccount:read

Stories

GET/api/v1/stories

List your stories (paginated).

list_storiesstories:read

POST/api/v1/stories

Create a story.

create_storystories:write

GET/api/v1/stories/{id}

Fetch a single story.

get_storystories:read

GET/api/v1/stories/{id}/chapters

List a story's chapters.

list_chaptersstories:read

GET/api/v1/stories/{id}/chapters/{chapterId}

Fetch one chapter with its content.

get_chapterstories:read

World

GET/api/v1/stories/{id}/world

List world entries (optional ?type=).

list_world_entriesworld:read

POST/api/v1/stories/{id}/world

Create a world entry.

create_world_entryworld:write

GET/api/v1/stories/{id}/world/{nodeId}

Fetch one world entry.

get_world_entryworld:read

PATCH/api/v1/stories/{id}/world/{nodeId}

Update a world entry.

update_world_entryworld:write

DELETE/api/v1/stories/{id}/world/{nodeId}

Delete a world entry.

delete_world_entryworld:write

POST/api/v1/ai/generate

Generate prose (Generate Pro).

generate_proseai:generate

POST/api/v1/ai/revise

Revise text against an instruction.

revise_textai:revise

POST/api/v1/ai/grit-pass

Run the Human Grit Pass over text.

grit_passai:revise

POST/api/v1/ai/editorial-pass

Get structured editorial notes on a chapter.

editorial_passai:editorial

For AI agents

MCP server

Every endpoint above is also exposed as an MCP tool (the tool name is shown next to each endpoint), so an MCP-aware client, Claude Code, Claude Desktop, Cursor, or your own agent, can call your AIStoryHub account directly. The server speaks Streamable HTTP and is authenticated the same way as the REST API: your ash_ token, sent as a bearer token.

Endpoint

https://aistoryhub.co/mcp/mcp

Add it to Claude Code with a custom header:

CLI

claude mcp add --transport http aistoryhub https://aistoryhub.co/mcp/mcp \
  --header "Authorization: Bearer ash_your_token_here"

This is bearer-token auth, not a full OAuth flow, so it works with any client that lets you set a static header on a remote server. One-click connector UIs that require OAuth discovery (like claude.ai Connectors) aren't supported yet.

Walkthrough

Example: create a story

Request

curl -X POST https://aistoryhub.co/api/v1/stories \
  -H "Authorization: Bearer ash_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"title":"The Lighthouse","genre":"mystery"}'

Response · 201

{
  "id": "b1f2...",
  "title": "The Lighthouse",
  "genre": "mystery",
  "status": "draft",
  "word_count": 0,
  "created_at": "2026-07-16T12:00:00.000Z",
  "updated_at": "2026-07-16T12:00:00.000Z"
}

Handling failures

Errors

Errors return a matching HTTP status and a consistent body.

Error body

{ "error": { "code": "forbidden", "message": "This token is missing the required scope stories:write." } }

401 unauthorizedMissing, malformed, invalid, revoked, or expired token.

403 forbiddenThe token lacks the scope the endpoint requires.

400 invalid_requestThe request body or parameters are invalid.

404 not_foundThe resource does not exist or you do not own it.

429 rate_limitedToo many requests. Retry after the given delay.

Fair use

Rate limits

Requests are rate limited per token by your plan tier. Exceeding the limit returns 429 with a Retry-After header telling you how long to wait. Build in a short backoff and you will rarely see it.

Stability

Versioning

The API is versioned in the URL. You are currently reading the docs for /api/v1. Backwards-compatible changes, such as new endpoints, new optional fields, or new scopes, ship within v1 without notice. Breaking changes, such as removing a field or changing a response shape, will ship under a new version path (/api/v2) rather than altering v1 in place, so existing integrations keep working.

Ready to build?

Generate a scoped token and make your first request in under a minute.

Create a token Back to the app

Build on AIStoryHub, from your own code.