ScryMaster Docs

API & MCP reference

Everything the Studio can do, your tools can do. The Stories API is a small, stable surface — and the ScryMaster MCP connector wraps it as safe buttons for an AI assistant. This page is the human guide; the machine-readable truth is always /api/v1/openapi.json and the live vocabulary at /api/v1/actions.

Authentication — two front doors, one set of rules

  • In the app: your signed-in session (cookies) — this is what the Studio uses.
  • Programmatic: a personal access token. Mint one in the Studio → ⚙ Settings → Integrations → API tokens (it starts with scry_) and send it as Authorization: Bearer scry_…. Tokens are yours to revoke any time; treat them like passwords.

Both doors call the same server functions with the same ownership checks, save-conflict protection, publish gates, and the official-content delete guard — an assistant can never reach a code path you couldn’t.

The safety contract

  • No clobbering. Reading a draft returns a draftHash; send it back as baseHash when saving or publishing. If the draft changed in between (another tab, another tool), the write is rejected with 409 — re-read, re-apply, re-save.
  • Publish is gated. Validation + IP denylist run server-side; a publish that would discard content players already have is blocked until explicitly confirmed. { dry: true } returns the full verdict with no write.
  • Players never break. Published versions are immutable and runs pin the version they started on — a new release is adoption, never migration.
  • Authorship is recorded. Every create/save/restore/delete/publish lands in the story’s provenance ledger (visible in the publish center’s “Recent activity”) labeled by surface: Studio, MCP, or system.

Core endpoints

GET/POST /api/v1/adventures — list / create drafts
GET/PATCH/DELETE /api/v1/adventures/:id — read / save ({doc|node|rule|listing, baseHash}) / delete
POST …/:id/validate · POST …/:id/simulate — the completeness + playability reports
POST …/:id/publish — publish (or {dry:true} for the verdict)
GET …/:id/versions · POST …/:id/restore — history + restore-into-draft
GET …/:id/activity — the authorship ledger (owner-only)
GET /api/v1/actions · GET /api/v1/openapi.json — vocabulary + spec (public)
GET /api/v1/store · GET /api/v1/adventures/published/:id — the player-facing surface (public)

The MCP connector

The bundled server (mcp/scrymaster.mjs) exposes the surface above as tools. Configure it with SCRYMASTER_TOKEN (your scry_… token) and SCRYMASTER_API_URL=https://scrymaster.com.

  • Grounding: get_vocabulary (works before auth — always call it first).
  • Drafts: list_adventures, get_adventure, create_adventure, save_adventure, delete_adventure, update_listing.
  • Quality: validate_adventure, simulate_adventure.
  • Releases: dry_publish, publish_adventure, list_versions, restore_version.
  • Art & narration: upload_image, set_scene_background, set_choice_image, plus the narration enrichment suite.

The authoring contract a well-behaved assistant follows: get_vocabulary → get_adventure → edit → save_adventure(baseHash) → validate_adventure → simulate_adventure → dry_publish → publish_adventure. Studio panels (Graph, World, Database, State…) are views over the same document — an assistant edits the document itself, at full parity.

Troubleshooting

  • 401 / “invalid or revoked token” — the token is wrong, revoked, or missing the scry_ prefix. Mint a fresh one in ⚙ Settings.
  • 409 on save/publish — the draft changed since you read it. Call get_adventure again, re-apply your edit to the fresh doc, and save with the new hash. Never retry the same call blindly.
  • 422 on publish — the response includes the validation report, denylist hits, or the data-loss report; fix what’s listed (or, for intentional content removal, review the loss report with the story owner and pass confirmDataLoss).
  • 403 deleting — official content (the tutorial) can never be deleted.
  • Vocabulary unreachable — don’t author from memory; fix connectivity first. The engine rejects unknown verbs.

Next: Build with your AI →