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.

voice:readRead your Voiceprint library (Style Lab profiles) and see which one is pinned to a story.

voice:writeCreate, update, and delete Voiceprints, and pin one to a story.

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.

skills:readBrowse the skills catalog and load the prose body of any skill this connection has installed.

memory:readRead durable memories saved about the account or a story.

memory:writeSave, update, and delete durable memories about the account or a story.

rules:readRead your saved Story Rules library.

rules:writeCreate, update, and delete Story Rules. Does not publish to the community gallery.

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

PATCH/api/v1/stories/{id}

Update a story's bible fields, including the outline (logline/arc/theme/ending/notes).

update_storystories:write

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 and beats.

get_chapterstories:read

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

Create a chapter or scene, ready to draft into.

create_chapterstories:write

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

Update a chapter/scene's title, content, or beats.

update_chapterstories:write

POST/api/v1/stories/{id}/chapters/{chapterId}/apply-edit

Literal patch: replace one exact, unique text span. No AI rewrite.

apply_editstories:write

POST/api/v1/stories/{id}/manuscript/find-replace

Deterministic find/replace, one chapter or the whole manuscript.

find_replacestories:write

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

Delete a chapter or scene, with confirmation.

delete_chapterstories:write

World

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

List world entries (optional ?type=, paginated).

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

Voice

GET/api/v1/voiceprints

List your Voiceprint library (paginated).

list_voiceprintsvoice:read

POST/api/v1/voiceprints

Create a Voiceprint (33 style dials).

create_voiceprintvoice:write

GET/api/v1/voiceprints/{id}

Fetch a single Voiceprint.

get_voiceprintvoice:read

PATCH/api/v1/voiceprints/{id}

Update a Voiceprint's fields.

update_voiceprintvoice:write

DELETE/api/v1/voiceprints/{id}

Delete a Voiceprint, with confirmation.

delete_voiceprintvoice:write

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

Fetch the story's pinned Voiceprint, if any.

get_story_voicevoice:read

PATCH/api/v1/stories/{id}/voice

Pin or clear the story's Voiceprint.

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

POST/api/v1/ai/self-check

Score a chapter or pasted passage for AI tells, 0-100. No AI model call.

self_checkstories:read

Skills

GET/api/v1/skills

List the first-party skills catalog.

list_catalog_skillsskills:read

GET/api/v1/skills/{slug}

Load the prose body of a skill this connection has installed.

load_skillskills:read

GET/api/v1/skills/{slug}/export

Download an installed skill as a Claude Code SKILL.md file.

—skills:read

Memory

GET/api/v1/memory

List durable memories (optional ?story_id=).

list_memoriesmemory:read

POST/api/v1/memory

Save or update a memory by name.

remembermemory:write

DELETE/api/v1/memory/{name}

Delete a memory (optional ?story_id=).

forget_memorymemory:write

Story Rules

GET/api/v1/rules

List your Story Rules library (paginated).

list_rulesrules:read

POST/api/v1/rules

Create or update a rule by name.

create_rulerules:write

GET/api/v1/rules/{id}

Fetch a single rule.

get_rulerules:read

PATCH/api/v1/rules/{id}

Update a rule's fields.

update_rulerules:write

DELETE/api/v1/rules/{id}

Delete a rule, with confirmation.

delete_rulerules:write

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, ChatGPT, 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

New to MCP or just want the one-click path? See the step-by-step Claude Desktop install guide with screenshots. Otherwise, add it to Claude Code with a custom header:

Claude Code CLI

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

Claude Desktop and Cursor both accept the same url + headers shape for a remote HTTP server:

Desktop / Cursor config

{
  "mcpServers": {
    "aistoryhub": {
      "url": "https://aistoryhub.co/mcp/mcp",
      "headers": {
        "Authorization": "Bearer ash_your_token_here"
      }
    }
  }
}

Both snippets above work with any client that lets you set a static header on a remote server. Create a token in Settings, Developer API and both appear there with your real token already filled in.

claude.ai Connectors and Claude Desktop's one-click "Add connector" also work directly against https://aistoryhub.co/mcp/mcp — no manual token step. AIStoryHub runs a real OAuth 2.1 authorization server (RFC 8414 metadata, PKCE-only, dynamic client registration): connecting prompts you to sign in and approve the requested permissions, and the resulting connection shows up in Settings, Developer API right alongside manually-created tokens, revocable the same way.

ChatGPT supports the same shape of connector under Settings, Apps, Advanced settings, Developer mode (Pro, Plus, Business, Enterprise, and Education accounts): add a custom connector pointed at the endpoint above and OpenAI drives the same OAuth 2.1 flow.

Skills you install onto a connection (in Settings, Skills) can also be pulled down as real SKILL.md files, usable in any local project's .claude/skills/ directory, independent of the live MCP session:

cURL

curl https://aistoryhub.co/api/v1/skills/editor-in-chief/export \
  -H "Authorization: Bearer ash_your_token_here" \
  -o SKILL.md

The export is a snapshot of the revision installed at download time — a skill's prose can change later (a first-party skill gets revised, or you edit your own), so re-download to pick up the current version.

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.

409 confirmation_requiredThe action is destructive (delete_world_entry) or the resource changed since you last read it (update_world_entry with expected_updated_at). Not a failure — retry the same request with confirm: true.

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.