Developer reference - v1

The Scrolls Foundry API

Are you the author? You don't need to read any of this.

Just open your AI assistant - Claude Cowork, Openclaw, or any capable coding/agent assistant - and say: 'Download the skill at https://scrollsfoundry.com/api/v1/skill.md, install and enable it, then start.' It will ask you what you'd like to work on and walk you through everything - including offering to write the book for you. Everything below is for the assistant, not you.

Prefer to install it yourself? Download the skill package (.zip) - one file with everything in it. In Claude, go to Settings -> Capabilities -> Skills, upload the zip, and enable sf. That's it; invoke it as /sf. (This is the reliable route - the skill is a large document, so asking an assistant to copy it back word-for-word can be slow.)

v1 An idea-to-audience pipeline for a book - structure, research, editorial review, illustration, print-ready layout, covers, retail listings, podcasts, a press kit and a subject-matter critic's review. Amazon KDP is one destination; the production and promotion are the same wherever the book is sold. Designed to be driven by an AI assistant (Claude Cowork, Openclaw, or similar). The service never ghostwrites; it designs and reviews (the draft is the author's, or optionally the Cowork agent's own writing).

Private to the author. Every manuscript, cover, illustration and export is kept in the author's own library in our Firebase project on Google Cloud, in London. The author's sign-in and API keys reach it; our support team can open a book only while the author has let them (7 days, logged on the author's Files screen). It is encrypted at rest and in transit. We never use it to train AI models. The author can download all of it, or delete it, at any time.
Pay once per book. One flat $75.00 per book - cheaper than the average commute to work. The Author Pack is a one-time payment, and so is each bolt-on. The public Author Page is optional: it's a subscription at $4.99 a month that you can cancel any time. Every book comes with a generous allowance of attempts at every stage (research is metered per chapter - 3 before the draft, 2 after) so authors can iterate and keep the best version. If a single book runs unusually heavy, extend just that book with a repeatable $19.00 capacity bolt-on - no account suspension, ever.

> AI assistant: start here (set yourself up, then wait for the book)

If a user pointed you at this page and said something like 'go read the instructions and start, then tell me when you're ready,' do exactly this, in order, and report back:

  1. Confirm the API is up. GET https://scrollsfoundry.com/api/v1/openapi.json (no auth) - it returns the full machine-readable spec. Read it; it defines every endpoint and field.
  2. Download, install and enable the ready-made skill. Easiest: GET https://scrollsfoundry.com/api/v1/skill.zip - a single package with SKILL.md + every companion under an sf/ folder; unzip it into your skills directory. Or GET https://scrollsfoundry.com/api/v1/skill.md and save it as sf/SKILL.md. Either way, then enable it. It is named sf, so on Cowork you invoke it as /sf (e.g. /sf help, /sf build "Title"). Its companion files (batch + house-voice references and the Phase 14 distribution toolkit) are fetchable on demand at https://scrollsfoundry.com/api/v1/skill/<path> - e.g. https://scrollsfoundry.com/api/v1/skill/references/batch-build.md (SKILL.md lists them). You do not need to author your own - this skill asks the user every input the API needs (as selectable choices or free-text) and drives the whole flow.
  3. Get the key without pasting secrets. Ask the user to open Profile -> API keys -> Download and drop scrollsfoundry-credentials.env into your working folder (it holds AUTHORS_API_KEY + AUTHORS_API_BASE_URL). If they can't, accept a pasted key and store it as AUTHORS_API_KEY (never print it back). Base URL is https://scrollsfoundry.com.
  4. Verify the key. GET https://scrollsfoundry.com/api/v1/entitlements with Authorization: Bearer $AUTHORS_API_KEY. A 200 means you're authenticated; 401 means the key is wrong.
  5. Files are saved for you. Every studio saves its deliverable to the user's library. To write a file of your own into a book, use /api/v1/library/push.
  6. Run the skill. Open with its first question - 'What would you like to work on?' - offering the studios as choices (or the whole book start-to-finish), then ask that phase's questions and drive the API as the user answers.

Authentication

Mint an API key in the app's Profile page, then send it as a Bearer token on every request:

Authorization: Bearer ak_your_key_here

Machine-readable spec: https://scrollsfoundry.com/api/v1/openapi.json

Series & manuscripts

Build up a catalogue the Cowork machine can reuse. Create a series, then upload manuscripts into it (multiple series can exist per account).

POST /api/v1/series - create a series  -  GET /api/v1/series - list
POST /api/v1/manuscripts - upload (optionally with seriesId + volume)  -  GET /api/v1/manuscripts
POST /api/v1/derive - a NEW book from an existing one: derivation = clone (copy) - fork (copy that diverges) - remix (keep the plan, blank the prose) - sequel/prequel (same series, fresh manuscript) - spinoff (new linked series). Body { parentBookName, newBookName, derivation }.
POST /api/v1/book/delete - delete a book; its files go to the trash, restorable for 30 days. A stored manuscript is kept (/api/v1/manuscripts/delete removes it). Body { bookName }.
curl -X POST https://scrollsfoundry.com/api/v1/series -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" -d '{"name":"Executive Jungle","author":"A. Mercer"}'
# -> { "series": { "id": "series_...", ... } }

curl -X POST https://scrollsfoundry.com/api/v1/manuscripts -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Book Two","text":"Chapter 1 ...","seriesId":"series_...","volume":2}'
# -> { "manuscript": { "id": "book_...", ... } }

One-call workflow

Pass a stored manuscriptId to run everything with series context filled in automatically.

The assistant decides or the app decides. Set "defaultToRecommendation": true and you can omit all creative choices - the app fills cover style, palette, fonts, listing tone and podcast tone from the series' derived voice register, and returns the resolved choices. Omit the flag (or set specific values) to make the choices yourself.

Runs analysis + cover concepts + listing + podcast script for a manuscript.

POST https://scrollsfoundry.com/api/v1/workflow
curl -X POST https://scrollsfoundry.com/api/v1/workflow \
  -H "Authorization: Bearer ak_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Architecting Resilient Systems",
    "author": "Alex Mercer",
    "manuscriptText": "Chapter 1 ...",
    "marketplaceCountry": "US",
    "trimSize": "6\" x 9\"",
    "genre": "Software Engineering",
    "seriesContext": "This book is volume 2 of the Executive Jungle series."
  }'

Returns { analysis, coverConcepts, listing, podcastScript }.

API reference - all endpoints

This is the pure API documentation. The complete, field-by-field machine-readable spec is openapi.json (every request body and field). Every endpoint below is POST unless marked, takes JSON, returns JSON, and needs the Bearer key. The Assistant skill section further down is a separate concern - it wraps these same endpoints in a question-driven flow.

POST /api/v1/ideate - conversational ideation -> { reply, ready, idea? }; body { messages[] }

Book type. Most creative endpoints accept kind = "fiction" or "nonfiction". It changes the output: fiction gets a story arc + characters, authenticity research, character/POV/tension editing, immersive cover art, a spoiler-free blurb and a story-led podcast; non-fiction gets chapter outlines, factual research, argument-clarity editing, clean conceptual covers and benefit-led copy. The app never ghostwrites - it produces structure, research, reviews and marketing, never the prose.

POST /api/v1/architect - Architect: structure. Non-fiction -> premise + chapter outlines; fiction -> logline, beats, characters, themes, setting, POV scenes
POST /api/v1/character-sketch - fiction: build/refine one character (want/need/flaw/ghost/arc/voice)
POST /api/v1/research - Research: grounded per-chapter research + sources
POST /api/v1/match-manuscript - read an upload: is it the right book, and which chapters does it contain?
POST /api/v1/voice-inspirations - suggest authors to blend as voice inspiration for a genre
POST /api/v1/audit - Review (step 6): manuscript audit (ratings, strengths, improvements) plus a slop section - deterministic AI-slop tell counts (em/en dashes, inflated diction, filler phrases) over the whole manuscript - and a factCheck[] section: numbers/dates worth verifying ({claim, issue, severity, suggestion}); for non-fiction these are checked against real-world fact, for fiction only internal contradictions + real facts the story leans on. An LLM estimate (no live web lookup), to verify. Accepts kind + inspiration[]. Detection only; the app never rewrites your prose.
GET /api/v1/slop-rules - the exact AI-slop lexicon the Review flags (inflated words, filler phrases, dash rule). Fetch once and write clean up front so Review comes back with ~0 tells. Open, cacheable.
POST /api/v1/analyze - manuscript analysis  -  POST /api/v1/extract-themes - core themes  -  POST /api/v1/generate-story-arcs - candidate story arcs  -  POST /api/v1/derive-voice-profile - reusable voice profile
POST /api/v1/cover-concepts - multiple cover concept ideas  -  POST /api/v1/cover-image - render artwork
POST /api/v1/listing - retail (KDP-ready) HTML description, categories & 7 keywords
POST /api/v1/illustration-suggestions - which illustrations + where  -  POST /api/v1/generate-illustration - render one in a chosen style
POST /api/v1/podcast-script - spoiler-free two-host podcast script (podcastOptions: host/guest/duration/tone)  -  POST /api/v1/podcast-audio - TTS audio (WAV)
POST /api/v1/promote-outlets - 10 targeted media outlets for a geography  -  POST /api/v1/press-release - one spoiler-free release  -  POST /api/v1/social-pack - 3 social posts (+ image concepts, best day/time)
POST /api/v1/critic-review - a critical review by a subject-matter expert (balanced, rated, blurb-ready quote). Pass reviewerName, or omit it and a name is invented for the marketplaceCountry.
POST /api/v1/reader-fit - Step 14. Evaluate the book against a free-text ideal reader. Pass readerPersona (required) + bookTitle, and any of summary/manuscriptText/genre/kind. Returns { fitScore, verdict, summary, worksWell[], improve[], audienceNotes } (+ readableText) - what already lands for that reader and concrete changes to fit better. Grounded only in the material; invents nothing. Saved as 14-reader-fit_*.txt.
POST /api/v1/agent-pitch - Step 15. A send-ready query email for an agent or publisher. Pass bookTitle, summary, optional authorBio/comps/wordCount/targetName and targetType ("agent"|"publisher"). Returns { subject, greeting, body, signoff, notes[] } (+ readableText, the paste-ready email). Uses ONLY the facts you supply - no invented credentials, comps, sales or praise; flags anything to personalise. Saved as 15-agent-pitch_*.txt.
Output format. The five document artefacts above - listing, promote-outlets, press-release, social-pack, critic-review - take a format field: "txt" (default) returns { format:"txt", text }, the readable plain-text document - save it as a .txt with no JSON; "json" returns the structured object; "both" returns the structured object plus readableText. Default to txt; request json/both only when you need the structured fields (e.g. a social post's imageConcept).
POST /api/v1/layout - assemble a print-ready .docx; citations: none/footnotes/endnotes/references; format decisions: bodyFont, bodyFontSize (half-points, 21=10.5pt), justify (true=flush both edges, default; false=ragged-right), hyphenate
GET/POST /api/v1/author-profile - read/save the active author persona (bio, books, photo, isPenName)
GET/POST /api/v1/account - account type (author/publisher), imprint name & active persona  -  GET/POST /api/v1/authors - manage author personas (pen names / imprints)  -  DELETE /api/v1/authors/{id}
GET/POST /api/v1/author-page - the public /author/{handle} page (also pen-name pages). Layout: heroMode - latest_book (default) leads with the newest cover + a small author inset, persona leads with the author portrait/bio. Publisher pages take the same choice via publisherHeroMode on /account.
GET/POST /api/v1/book/listing - read/pin a book's shopfront cover + blurb + Amazon link  -  POST /api/v1/book/cover-upload - upload a cover (always wins; straight to Storage)  -  POST /api/v1/book/cover-match - bulk-match cover-image filenames to the books missing covers (by name; unmatched are assigned by hand)  -  POST /api/v1/book/blurb - write a card-fit blurb  -  GET /api/v1/book/artefacts - a book's current-artefact manifest (cover/interior/manuscript/...)
GET /api/v1/entitlements  -  POST /api/v1/entitlements/spend - the $75 per-book Author Pack ledger (research metered per chapter: unit+phase)
GET /api/v1/receipts - purchase receipts, each tied to the book it unlocked (non-refundable). One ledger for every channel; aggregate for spend by book, series or pen name.
POST /api/v1/polyaly - Polyaly, the in-app mentor + per-studio subject-matter expert. { messages[], studio? } -> { reply }; studio picks the expert hat (editor, cover art director, metadata strategist, ...). Free, rate-limited; never ghostwrites.
POST /api/v1/library/push - save a deliverable into the user's library (base64 body)  -  GET /api/v1/library/files - list them  -  GET /api/v1/library/file/{id} - download one (for a local mirror)  -  GET /api/v1/library/export - everything as one ZIP

For your AI assistant (Claude Cowork, Openclaw, ...) - the ready-made skill

Don't author your own - use ours. GET https://scrollsfoundry.com/api/v1/skill.md, save it into your skills directory, and enable it. It is a router-based UX emulator: it opens by asking "What would you like to work on?", then surfaces every input the API needs as a question (selectable choices for fixed fields, free-text for open ones), and drives the calls below - including an option to have you write the book as a ghostwriter (your own work; the service still only reviews). The rest of this section documents what that skill does, in case you want to inspect or extend it.

Setup. Ask the user to mint a key on the Profile page and store it as AUTHORS_API_KEY. Base URL: https://scrollsfoundry.com. Send Authorization: Bearer $AUTHORS_API_KEY on every call.

Golden rules. (1) The Scrolls Foundry API never writes the book's prose - it produces structure, research, reviews and marketing. The draft comes from the human author, or optionally from you (see the optional writing step below). (2) Set kind ("fiction"/"nonfiction") on every creative call and keep it consistent for a book. (3) If you offer voice inspiration, use a blend of two or more authors - never one (a single name is rejected). (4) Save every deliverable to the user's library with /library/push so it lands in series -> book. Prefix every filename with its step number so the book's folder always sorts in flow order: 01-ideation, 02-outline, 03-story, 04-research, 05-manuscript, 06-audit, 07-illustration, 08-interior, 09-cover, 10-listing, 11-podcast, 12-promote (then a datestamp, e.g. 10-listing-description_2026-08-05_1200.txt).

Optional: write it yourself, then get it reviewed. With the user's go-ahead, you may take the full design this API produced - premise/logline, chapter outlines or story beats, character sketches, and the per-chapter research - as your brief and write the manuscript yourself, then submit it back to /api/v1/audit (and iterate on the notes). That writing is your agent's work for the user; The Scrolls Foundry service still only designs and reviews. This turns the pipeline into a full idea-to-reviewed-draft loop when the user wants it.

Pipeline (one book):

# 0. (optional) create a series + register the manuscript
POST /api/v1/series           { name, author }
POST /api/v1/manuscripts      { title, author, text, seriesId, volume }

# 1. STRUCTURE - Architect  (ask length first: pages@trim OR words -> targetWords)
POST /api/v1/architect        { topic, brief, genre, kind, targetWords, trimSize }
#    fiction also returns { logline, beats[], characters[], themes[], setting }
#    refine a character:  POST /api/v1/character-sketch { name, role, brief, bookTitle, premise, genre }

# 2. RESEARCH - per chapter/scene
POST /api/v1/research         { chapterTitle, chapterOutline, bookTitle, topic, genre, kind }

# 3. THE DRAFT
#    (a) the human author writes it themselves; OR
#    (b) OPTIONAL - YOU (the assistant) write the manuscript yourself from the
#        design (premise/beats/characters/research above as your brief), then
#        submit it for editorial review. This is YOUR agent's own writing on the
#        user's behalf - The Scrolls Foundry API itself never ghostwrites; it
#        only reviews. Keep kind + the character/voice notes consistent.
#    Either way, when a draft exists, verify it's the right file + which chapters:
POST /api/v1/match-manuscript { manuscriptText, chapters[], bookTitle, topic, genre }

# 4. EDIT - review a chapter or the whole manuscript
POST /api/v1/voice-inspirations { genre }            # optional: pick a BLEND (>=2)
POST /api/v1/audit            { title, author, genre, topic, manuscriptText, kind, inspiration:[a,b] }

# 5. ILLUSTRATE (optional) - suggest where art goes, then draw it in a style
POST /api/v1/illustration-suggestions { bookTitle, premise, genre, kind, chapters[] }
POST /api/v1/generate-illustration    { subject, stylePrompt, styleLabel, aspectRatio }

# 6. PUBLISH - covers, listing, podcast
POST /api/v1/cover-concepts   { title, author, genre, artStyle, colorPalette, coverHero, kind }
POST /api/v1/cover-image      { prompt, title, genre, kind }
POST /api/v1/listing          { title, author, manuscriptText, marketplaceCountry, trimSize, kind }
POST /api/v1/podcast-script   { manuscriptTitle, author, manuscriptText, kind }
POST /api/v1/podcast-audio    { dialogue, hostSpeaker, guestSpeaker }

# 7. SAVE to the user's library
#    Prefix filename with the step number so the book folder sorts in flow order:
#    01-ideation 02-outline 03-story 04-research 05-manuscript 06-audit
#    07-illustration 08-interior 09-cover 10-listing 11-podcast 12-promote (+ _datestamp)
POST /api/v1/library/push     { seriesName, bookName, filename, mimeType, contentBase64 }

# metering (if the user has enabled it): check/spend the per-book Author Pack
GET  /api/v1/entitlements
POST /api/v1/entitlements/spend { bookId, capability }   # 402 { needsPack } if exhausted
#    research is per-chapter: { bookId, capability:"research", unit:chapterId, phase:"before"|"after" }
#    -> 3 attempts before the draft, 2 after the chapter manuscript exists
#    recover:true -> free make-good for a step already charged (a crashed agent left a
#    stub); no extra credit is spent. Only valid once that slot has actually been paid.

What to ask the user at each step

Ask these before calling each studio's endpoint - don't guess. Confirm kind (fiction/non-fiction) once up front and reuse it.

Architect (structure). Fiction or non-fiction? Topic/premise in a sentence or two? Genre? Who's it for and what must it cover? How long - pages (and trim size, e.g. 6x9) or a word count? (Yardstick: a 6x9 book of 220 pages ~ 50,000 words; War and Peace ~ 587,000 words.) Fiction only: which framework - three-act, Hero's Journey, or Save the Cat? -> architect with targetWords.
Story (fiction). Any characters they already have in mind (names/roles)? For each, their outward goal (want), inner need, and flaw? Setting/world rules to stay consistent with? Themes? -> refine via character-sketch.
Research. Which chapter/scene now? Anything specific to verify (period, place, procedure, technical detail)? (Fiction leans to authenticity; non-fiction to facts - set kind.) -> research.
Edit. Is this a chapter or the whole manuscript? Paste it (or a file's text). Optional: name a blend of two or more authors whose voice inspires them (never one) -> pass as inspiration[]. -> match-manuscript then audit.
Illustrate. Do they want illustrations? Which visual style (line, pencil, watercolour, Rembrandt, Van Gogh, woodcut, children's, ...)? Landscape, portrait or square? -> illustration-suggestions then generate-illustration per pick.
Cover. Should the title or the author be the hero? Art style & colour palette preference? Mood in a few words? (Fiction -> immersive genre art; non-fiction -> clean/conceptual - set kind.) -> cover-concepts then cover-image.
List. Which Amazon marketplace (US/UK/...)? Trim size? Tone? (Fiction -> spoiler-free blurb; non-fiction -> benefit-led.) -> listing.
Podcast. Host & guest names/voices? Episode length & tone? Focus topics? (Strictly spoiler-free - fiction AND non-fiction.) -> podcast-script then podcast-audio.
Promote. Target geography? Which of the 10 suggested outlets to pitch, and each outlet's verified send-to address? Angle? -> promote-outlets, then press-release (one per outlet, + a press photo via generate-illustration) and social-pack (render each imageConcept). The author sends the releases themselves.

Skill outline to save: a description ("Idea-to-marketing pipeline for a KDP book via The Scrolls Foundry API; never ghostwrites"), the base URL + key env var, the golden rules above, the per-step questions, and a step function per phase that asks those questions, calls the endpoints in order, sets kind once, pauses for the human to write (or writes it itself if the user asked), and pushes each artefact to the library. Treat a 402 needsPack as "ask the user to buy the $75 Author Pack for this book", and a 507 as "the library is full: ask the user to make room".

All endpoints accept and return JSON. A missing or invalid key returns 401.