{"openapi":"3.0.3","info":{"title":"The Scrolls Foundry API","version":"1.0.0","description":"Generate KDP covers, listings, and podcasts from a manuscript. Authenticate with a Bearer API key minted in the app's Profile page. METERING: the book-production steps (architect, research, edit/audit/analyze, cover-concepts, cover-image, listing, podcast-script, podcast-audio, promote-outlets, press-release, social-pack) are metered against a $75 per-book Author Pack. Enforcement is server-side: each metered call charges a per-book credit ITSELF, so you MUST pass `bookId` on every metered call (research also needs `unit`=chapterId and `phase`='before'|'after'). A metered call for an un-purchased book returns 402 { needsPack }; omitting bookId returns 400 { needsBookId }. PAYMENTS ARE WEB-ONLY: Author Packs and $19 capacity bolt-ons are bought at scrollsfoundry.com - there is no API/checkout purchase flow; on 402/429 direct the user to buy online, then retry. `POST /api/v1/entitlements/spend` is a read-only preflight (checks status, never consumes). Superusers are exempt from packs but capped at 99 runs per step per 24h (429 { superadminCap:true }). OUTPUT FORMAT: the document artefacts (listing, promote-outlets, press-release, social-pack, critic-review) accept `format` - 'txt' (DEFAULT) returns { format:'txt', text } (the readable plain-text document, so you store a .txt without JSON), 'json' returns the structured object, 'both' returns the structured object plus readableText. Save the .txt as the primary human file; only keep JSON when you passed format:'json'/'both'."},"servers":[{"url":"https://scrollsfoundry.com"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer"}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/api/v1/series":{"post":{"summary":"Create a series","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"author":{"type":"string"},"description":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}},"get":{"summary":"List your series (with book counts)","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/manuscripts":{"post":{"summary":"Upload a manuscript, optionally into a series","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"author":{"type":"string"},"text":{"type":"string"},"seriesId":{"type":"string"},"volume":{"type":"integer"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}},"get":{"summary":"List your manuscripts (optional ?seriesId=)","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/workflow":{"post":{"summary":"Run the full author workflow (analysis + cover concepts + listing + podcast). Pass a manuscriptId to use a stored manuscript + its series context. Set defaultToRecommendation:true to let the app choose cover style/palette/fonts, listing tone and podcast tone from the series voice register.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"manuscriptId":{"type":"string"},"defaultToRecommendation":{"type":"boolean"},"title":{"type":"string"},"author":{"type":"string"},"manuscriptText":{"type":"string"},"marketplaceCountry":{"type":"string"},"trimSize":{"type":"string"},"genre":{"type":"string"},"seriesContext":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/audit":{"post":{"summary":"Audit: review a manuscript with 10-point ratings, strengths and improvements. Pass kind ('fiction'|'nonfiction') to adapt the metric set, and inspiration[] (a BLEND of >= 2 author names - 0 or >= 2, never 1) to add an 'Inspiration Value' score.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"title":{"type":"string"},"author":{"type":"string"},"genre":{"type":"string"},"topic":{"type":"string"},"manuscriptText":{"type":"string"},"kind":{"type":"string"},"inspiration":{"type":"array"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/writing-report":{"post":{"summary":"Writing reports (FREE, no model call, no per-book credit): deterministic ProWritingAid-style prose metrics - readability (Flesch + Flesch-Kincaid grade), sentence-length variety, sticky glue-heavy sentences, overused crutch words (-ly adverbs, filler, POV filter words), nearby echoes, dialogue-tag habits, passive voice, cliches, a coarse pacing profile and a composite polish score. Pass manuscriptText, or chapters[] for per-chapter pacing. Measurements only - never rewrites.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"manuscriptText":{"type":"string"},"chapters":{"type":"array"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/architect":{"post":{"summary":"Architect: design a book's structure. Non-fiction -> premise + chapter outlines. Fiction (kind:'fiction') -> logline, story beats, character sketches, themes, setting and a POV scene breakdown. Pass targetWords (+ trimSize) to size the chapter count and per-chapter budget. Never writes prose.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"title":{"type":"string"},"topic":{"type":"string"},"brief":{"type":"string"},"genre":{"type":"string"},"voiceRegister":{"type":"string"},"seriesContext":{"type":"string"},"kind":{"type":"string"},"storyFramework":{"type":"string"},"targetWords":{"type":"integer"},"trimSize":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/research":{"post":{"summary":"Research for a chapter. Only phase:'before' (and ground!==false) does a fresh Google Search; phase:'after' - or ground:false when the per-book grounding budget is exhausted - reasons over the supplied context instead (cost control). kind:'fiction' returns authenticity research; otherwise factual grounding. Never writes prose.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"chapterTitle":{"type":"string"},"chapterOutline":{"type":"string"},"bookTitle":{"type":"string"},"topic":{"type":"string"},"genre":{"type":"string"},"seriesContext":{"type":"string"},"kind":{"type":"string"},"phase":{"type":"string"},"ground":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/match-manuscript":{"post":{"summary":"Read an uploaded manuscript against a book's chapters: detect whether it belongs to the book (relatedness) and which chapters it contains (coverage + per-section mapping). Only classifies.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"manuscriptText":{"type":"string"},"chapters":{"type":"array"},"bookTitle":{"type":"string"},"topic":{"type":"string"},"genre":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/voice-inspirations":{"post":{"summary":"Suggest real authors (popular / bestselling / acclaimed) to blend as voice inspiration for a genre. Send the chosen names (>= 2) to /audit as inspiration[].","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"genre":{"type":"string"},"topic":{"type":"string"},"bookTitle":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/character-sketch":{"post":{"summary":"Fiction: build or refine ONE character around the want/need/flaw spine (name, role, want, need, flaw, ghost, arc, voice). Never writes prose.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":"string"},"brief":{"type":"string"},"bookTitle":{"type":"string"},"premise":{"type":"string"},"genre":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/illustration-suggestions":{"post":{"summary":"Suggest which illustrations a book should include and WHERE (placement, caption, subject, rationale). Fiction -> scene/character art; non-fiction -> diagrams/maps/figures. PASS THE FINISHED CHAPTER TEXT in chapters[].content (not just the outline) - the planner grounds each figure in what the chapter ACTUALLY establishes, so it never asserts a claim the finished chapter refutes and, where a chapter overturns an expected claim, redraws the figure to the chapter's real finding (rival options / 'not this way' / 'the texts do not decide') and never invents data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookTitle":{"type":"string"},"premise":{"type":"string"},"topic":{"type":"string"},"genre":{"type":"string"},"kind":{"type":"string"},"chapters":{"type":"array (each { title, outline?, content? } - content is the finished chapter text)"},"count":{"type":"integer"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/generate-illustration":{"post":{"summary":"Render one illustration from a subject + a style preset. PASS kind: 'fiction' | 'nonfiction' - it changes the render mode. NON-FICTION renders a CREDIBLE, ACCURATE explanatory FIGURE (a clear labelled diagram/chart of exactly the concept in `subject`, with short correctly-spelled labels allowed) - NOT decorative or fanciful art; the subject must therefore name a real concept and its parts. FICTION renders a wordless scene in the chosen style. If kind is omitted it defaults to the non-fiction figure treatment. For non-fiction pass the figure's `caption` too - the renderer is told NOT to draw that caption (or any title/sentence/gibberish) inside the image; only short, exact structural labels are allowed, so text stays clean and never duplicates the caption printed beneath the figure. aspectRatio: landscape|portrait|square. The prompt hard-negatives book/page/frame cues, so the result is a standalone graphic (never a photo of art on a book page). For FICTION character consistency, pass referenceImages: an array (max 4) of data-URL images - typically the first render of a recurring character - and the model keeps that character's face/build/clothing across illustrations (returns usedReferences). Send the SAME stylePrompt for every image in a series so the whole set is one style.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string"},"stylePrompt":{"type":"string"},"styleLabel":{"type":"string"},"aspectRatio":{"type":"string"},"kind":{"type":"string"},"caption":{"type":"string"},"referenceImages":{"type":"array"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/analyze":{"post":{"summary":"Analyze a manuscript (themes, audience, takeaways)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"title":{"type":"string"},"author":{"type":"string"},"text":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/extract-themes":{"post":{"summary":"Extract the core themes of a manuscript or premise (input to cover/blurb/marketing direction).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"title":{"type":"string"},"text":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/generate-story-arcs":{"post":{"summary":"Propose candidate story arcs from a manuscript's text and themes. text is required (400 without it); themes usually comes from extract-themes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"title":{"type":"string"},"author":{"type":"string"},"text":{"type":"string"},"themes":{"type":"array"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/derive-voice-profile":{"post":{"summary":"Derive a reusable house/author voice profile from sample text or inspirations.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"text":{"type":"string"},"inspiration":{"type":"array"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/slop-rules":{"get":{"summary":"The canonical AI-slop lexicon the Review report's `slop` section flags - { inflatedWords[], fillerPhrases[], dashes, preserve }. Fetch once (cacheable, no auth) and avoid these while drafting so Review comes back with ~0 tells; write clean rather than reworking after review.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/cover-concepts":{"post":{"summary":"Generate multiple cover concept ideas -> { concepts[], seriesBaseDesign, recommendedConceptId }. coverHero ('title'|'author') sets which element dominates; kind ('fiction'|'nonfiction') steers art direction. moodDescription + userPrompt are free-text creative direction (userPrompt is the author's plain-language brief). SERIES: pass seriesName (and volume) - the first volume ESTABLISHES a distinctive seriesBaseDesign (palette/typography/layout/motif/hook) so a series looks unlike others; pass that seriesBaseDesign back on later volumes to keep them consistent. AUTONOMOUS: set autonomous:true (bulk/factory mode) with audience + contentSummary and the app decides confidently from genre/audience/content and returns recommendedConceptId to render directly - no user input needed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"},"author":{"type":"string"},"trimSize":{"type":"string"},"genre":{"type":"string"},"artStyle":{"type":"string"},"colorPalette":{"type":"string"},"coverHero":{"type":"string"},"moodDescription":{"type":"string"},"kind":{"type":"string"},"userPrompt":{"type":"string"},"seriesName":{"type":"string"},"volume":{"type":"integer"},"seriesBaseDesign":{"type":"object"},"autonomous":{"type":"boolean"},"audience":{"type":"string"},"contentSummary":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/cover-image":{"post":{"summary":"Render a finished, FLAT front-cover (never a 3-D mockup): the model makes TEXTLESS artwork, then the server typesets your exact title/subtitle/author over it in a FIXED SERIES TEMPLATE - a reserved top masthead (series-name kicker + title + subtitle) and a reserved bottom author band, so type never floats over the busiest art and every volume is laid out identically. Deterministic text, no hallucinated names. Returns { imageUrl (the composed cover, data URL), artUrl (the textless artwork), isAiGenerated, composed }. Pass series (printed as the masthead kicker + optional seriesStyle anchor) to keep a series consistent while each book stays unique. aspectRatio defaults to a tall book proportion (2:3); kind nudges art direction. Set overlayText:false to get the raw textless artwork instead (e.g. to typeset text yourself). FICTION character lock-in: pass referenceImages (data URLs, max 4) - the same recurring-character renders used for the interior illustrations - and the cover hero is rendered as the SAME character(s), so the cover matches the inside. referenceImages are read ONLY when kind==='fiction' (a non-fiction concept cover has no recurring character).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"prompt":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"},"author":{"type":"string"},"series":{"type":"string"},"seriesStyle":{"type":"string"},"genre":{"type":"string"},"artStyle":{"type":"string"},"colorPalette":{"type":"string"},"kind":{"type":"string"},"aspectRatio":{"type":"string"},"overlayText":{"type":"boolean"},"referenceImages":{"type":"array"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/listing":{"post":{"summary":"Generate a KDP listing (HTML description, categories, 7 keywords) + printed back-cover blurb & ~200-word bio (from authorBio), PLUS market-aware price guidance. Pass priceCountry + currency (defaults to the marketplace's currency) and optional pageCount to get pricing:{ country, currency, ebook{low,recommended,high}, paperback{...}, rationale, royaltyNote } - an ideal list price from genre norms, comparable titles, length and royalty bands (never invents competitors or sales figures). kind:'fiction' produces a spoiler-free blurb + trope categories; otherwise benefit-driven copy.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"},"author":{"type":"string"},"manuscriptText":{"type":"string"},"marketplaceCountry":{"type":"string"},"trimSize":{"type":"string"},"genre":{"type":"string"},"listingTone":{"type":"string"},"seriesContext":{"type":"string"},"kind":{"type":"string"},"authorBio":{"type":"string"},"priceCountry":{"type":"string"},"currency":{"type":"string"},"pageCount":{"type":"integer"},"format":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/podcast-script":{"post":{"summary":"Generate a two-host podcast script - strictly SPOILER-FREE (fiction & non-fiction). podcastOptions carries { durationMinutes, customTone, hostName, guestName, guestRole }. Response includes distributionTips[] - actionable ways to use the finished podcast to promote the book (post clips to social, upload to YouTube/Spotify, etc.). Show them to the user.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"manuscriptTitle":{"type":"string"},"author":{"type":"string"},"manuscriptText":{"type":"string"},"podcastOptions":{"type":"object"},"seriesContext":{"type":"string"},"kind":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/podcast-audio":{"post":{"summary":"Synthesize multi-speaker podcast audio (returns a WAV data URL). dialogue is the script's dialogue[] array. Part of the podcast step: once the book's podcast credit is spent (by podcast-script), audio calls are metered but not charged again; otherwise the first call uses it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"dialogue":{"type":"array"},"hostSpeaker":{"type":"string"},"guestSpeaker":{"type":"string"},"hostVoiceName":{"type":"string"},"guestVoiceName":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/compose-cover":{"post":{"summary":"Stamp the FIXED SERIES TEMPLATE (reserved masthead: series-name kicker + title + subtitle, and a reserved bottom author band) over cover artwork you ALREADY have - the SAME compositor cover-image uses, so covers are identical across web, Android and the API. Use it to re-typeset a cover WITHOUT regenerating the art (e.g. to fix an old cover, or after picking art): NOT metered (no image-model call). `art` is the textless artwork as a data: URL or an image URL. Pass `series` (printed as the masthead kicker) + `title`/`subtitle`/`author`; `aspectRatio` defaults to 2:3. Returns { imageUrl (the composed cover, data URL), composed }.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"art":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"},"author":{"type":"string"},"series":{"type":"string"},"aspectRatio":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/promote-outlets":{"post":{"summary":"Suggest EXACTLY 10 targeted media outlets to pitch, tailored to the book + target geography. Each: { name, type, geography, audience, whyRelevant, pitchAngle, contactHint }. contactHint is a general submission route, NOT a verified address - the author confirms and sends in their own name. geography is required. Also returns readableText - the pitch list as a plain-text document; save it as the primary human file (12-promote-outlets_*.txt).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"bookTitle":{"type":"string"},"subtitle":{"type":"string"},"author":{"type":"string"},"genre":{"type":"string"},"kind":{"type":"string"},"summary":{"type":"string"},"geography":{"type":"string"},"angle":{"type":"string"},"format":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/press-release":{"post":{"summary":"Write ONE spoiler-free, industry-standard press release for the book, in the author's name -> { headline, subheadline, dateline, body, boilerplate, callToAction }. Never fabricates credentials/awards/sales; leaves [DATE]/[BUY LINK]/[your email] placeholders. Also returns readableText - the release as a plain-text document to save as the primary human file (12-press-release_*.txt).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"bookTitle":{"type":"string"},"subtitle":{"type":"string"},"author":{"type":"string"},"authorBio":{"type":"string"},"publisher":{"type":"string"},"genre":{"type":"string"},"kind":{"type":"string"},"summary":{"type":"string"},"geography":{"type":"string"},"angle":{"type":"string"},"releaseDate":{"type":"string"},"format":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/social-pack":{"post":{"summary":"Build EXACTLY 3 ready-to-post, spoiler-free social posts forming a launch mini-campaign -> { posts:[{ platform, role, caption, hashtags[], imageConcept{subject,stylePrompt,aspectRatio}, bestDay, bestTime, schedulingRationale, postingInstructions }], calendarNote, generalInstructions }. Render each imageConcept via /generate-illustration to get the complementary promo image. Also returns readableText - the whole pack as a plain-text document to save as the primary human file (12-social-pack_*.txt).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"bookTitle":{"type":"string"},"subtitle":{"type":"string"},"author":{"type":"string"},"genre":{"type":"string"},"kind":{"type":"string"},"summary":{"type":"string"},"geography":{"type":"string"},"format":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/critic-review":{"post":{"summary":"The final Promote deliverable - a CRITICAL review in the persona of a subject-matter EXPERT in the book's field: balanced strengths + honest critiques, a 1-5 rating, and a blurb-ready pull quote -> { reviewerName, reviewerNameInvented, reviewerCredential, rating, headline, review, strengths[], critiques[], verdict, pullQuote, marketplace, disclaimer }. Pass reviewerName to name the critic; when omitted (API/Cowork usually have none) a fitting name is INVENTED for the primary country of marketplaceCountry (e.g. UK -> a British reviewer). Clearly labelled AI appraisal; never fabricates real-world facts/sales and never poses as a real person. Also returns readableText - the review as a plain-text document to save as the primary human file (13-critic-review_*.txt).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookTitle":{"type":"string"},"subtitle":{"type":"string"},"author":{"type":"string"},"genre":{"type":"string"},"kind":{"type":"string"},"summary":{"type":"string"},"manuscriptText":{"type":"string"},"marketplaceCountry":{"type":"string"},"reviewerName":{"type":"string"},"format":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/ideate":{"post":{"summary":"Conversational ideation. Send the running chat as messages[] ({role:'user'|'assistant', content}); returns { reply, ready, idea? } - when ready, idea has { workingTitle, premise, topic, genre, kind, audience, angles[] } to carry into Architect.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/layout":{"post":{"summary":"Assemble a print-ready, Amazon-ready .docx (returns base64). Author/publisher are the user's own (publisher omitted when blank); never writes an ISBN. citations: 'none'|'footnotes'|'endnotes'|'references' references the research sources. Each chapter: { title, content, sources?[] }. To EMBED interior illustrations (from the Illustrate step) pass images:[{ chapterIndex (0-based), dataUrl ('data:image/png;base64,...' - the 07-illustration bytes), afterParagraph? (0/omitted = under the chapter title, N = after the Nth body paragraph), caption? }]. Omit images ONLY when the book is intentionally text-only - a book that has 07-illustration deliverables but is assembled with no images silently drops them. FORMAT DECISIONS (the author's typographic choices; sensible house defaults apply when omitted): bodyFont (interior typeface, e.g. 'Georgia' (default), 'Garamond', 'Palatino Linotype', 'Cambria', 'Times New Roman'; falls back to Georgia if a device lacks the face), bodyFontSize (half-points - 21 = 10.5pt default, 22 = 11pt, 24 = 12pt), justify (true = flush both edges, the print default; false = ragged-right/flush-left), hyphenate (true = auto-hyphenate long words to even out justified spacing; default false). These are also persisted via /book-config so the same look is reused across the app, API and Cowork.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"subtitle":{"type":"string"},"author":{"type":"string"},"publisher":{"type":"string"},"year":{"type":"integer"},"dedication":{"type":"string"},"chapters":{"type":"array"},"alsoBy":{"type":"array"},"trimWidthIn":{"type":"number"},"trimHeightIn":{"type":"number"},"citations":{"type":"string"},"bodyFont":{"type":"string"},"bodyFontSize":{"type":"integer"},"justify":{"type":"boolean"},"hyphenate":{"type":"boolean"},"images":{"type":"array"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/asset":{"post":{"summary":"Record ONE studio deliverable in the source of truth (its bytes are already in the library / the Cowork local mirror). This is what makes a deliverable appear on the shelf, in the RECORD panel and in the meter - the record is the truth, the file is the payload. bookName + kind required; kind is the studio kind (ideation/outline/chapter-structure/research/manuscript/audit/illustration/cover/listing/podcast/promo). runId = ONE id per studio run: pass the SAME runId for every file a step produces so a bundle (List's parts, Research's per-chapter files) groups as one attempt; a re-run gets a new runId. Increments the book's per-kind attempt ledger once per new run. Pass driveFileId/driveFileName (the library file id and name; the field keeps its old name), coworkPath (local mirror), sources[] on research (for citations), channel (e.g. 'cowork'). Returns { asset, bookId }.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookName":{"type":"string"},"seriesName":{"type":"string"},"author":{"type":"string"},"kind":{"type":"string"},"runId":{"type":"string"},"channel":{"type":"string"},"status":{"type":"string"},"driveFileId":{"type":"string"},"driveFileName":{"type":"string"},"webViewLink":{"type":"string"},"coworkPath":{"type":"string"},"caption":{"type":"string"},"sources":{"type":"array"},"afterParagraph":{"type":"integer"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}},"get":{"summary":"List asset records for the signed-in user, or one book with ?bookId=. Returns { assets[] } - each { id, bookId, kind, runId, version, channel, createdAt, status, driveFileId, driveFileName, coworkPath, sources[] }.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/reconcile":{"post":{"summary":"Reconcile the user's library. Firestore is the SOURCE OF TRUTH (it anchors billing) and is NEVER overwritten, rebuilt, or deleted - one simple, always-additive flow: (0) COLLAPSE DUPLICATES - merge redundant index rows an earlier keying left behind: one canonical record per book title and per (penName+isPenName) persona, folding the duplicates' visibility/attribution in and repointing every reference (no file is touched); (1) force Firestore out - a record whose library file is gone is REPORTED for the user to restore (Recently deleted on the Files screen, or a re-run), never deleted (Firestore wins); (2) fold in files in the library with no record - each is ADDED existence-only (NEVER charges the meter). Run it from a Cowork session to also sweep that session's local mirror and CREATE the author / publisher-persona / pen-name records for personas the account doesn't yet have. The optional `source` field is accepted for backward-compatibility but grants no store authority over Firestore. Returns { filesPresent, recorded, created, cleared, deduped:{ books, personas }, report:{ ingested[], missingFiles[], deduped, note } }.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/book/framework":{"get":{"summary":"STAGE 00 - DEFINE - read a book's operating framework + the options to edit it. Pass ?bookName=. -> { framework:{ bookName, seriesName, standalone, authorId, authorName, isPenName, showOnPage, showOnPublisherPage, showOnAuthorPage, publisherName }, options:{ isPublisher, series:[{id,name,description}], authors:[{id,penName,isPenName}] }, publisherMatch:{ name, matched, handle?, publisherName? } }. `authors` lists ONLY this account's personas, one row per name. publisherMatch soft-matches the imprint name to an app publisher account (a link, never a gate).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"STAGE 00 - DEFINE - agree/edit a book's operating framework (idempotent; additive - nothing is deleted). Set: seriesName (assign existing or create new) OR standalone:true; authorId (an existing persona) OR newPenName (+ newIsPenName) to create one; showOnAuthorPage (persona surfaces on the main author page). PAGE VISIBILITY is TWO independent per-book gates: showOnPage (this book on the AUTHOR/persona page) and showOnPublisherPage (this book on the imprint's PUBLISHER page - publisher accounts). publisherName (imprint, publisher accounts - soft-matched). editSeries:{id,name?,description?} renames/edits an existing series. Returns the same shape as GET.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookName":{"type":"string"},"seriesName":{"type":"string"},"standalone":{"type":"boolean"},"authorId":{"type":"string"},"newPenName":{"type":"string"},"newIsPenName":{"type":"boolean"},"showOnAuthorPage":{"type":"boolean"},"showOnPage":{"type":"boolean"},"showOnPublisherPage":{"type":"boolean"},"publisherName":{"type":"string"},"editSeries":{"type":"object"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/book/listing":{"get":{"summary":"SHOPFRONT LISTING - read what a reader sees for this book on the author/publisher page. Pass ?bookId= and/or ?bookName= (resolved by id first, then title). -> { bookId, blurb, coverFileId, asin, covers:[{fileId,name,dataUrl}] } - covers are up to 6 optimised thumbnails (gathered across title twins + the pinned cover) to choose from; blurb defaults to the book's logline/premise until set; asin is the stored Amazon product code (if any).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"SHOPFRONT LISTING - pin the cover + blurb + Amazon link for this book. { bookId | bookName, coverFileId? (one of the fileIds from GET), blurb? (max 600), amazonUrl? (a full Amazon link OR a raw ASIN - only the ASIN is stored, so the public /buy/<asin> link geo-routes each reader to their own country's Amazon; pass '' to clear) }. Writes to every same-title record so the imprint page + shopfront agree. -> { ok, bookId, blurb, coverFileId, asin }.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"bookName":{"type":"string"},"coverFileId":{"type":"string"},"blurb":{"type":"string"},"amazonUrl":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/book/cover-upload":{"post":{"summary":"SHOPFRONT COVER - upload a cover image for a produced book. An explicit upload ALWAYS wins: the optimised image is written straight to the book's single public Firebase Storage slot AND any carried-forward cover is unpinned, so the uploaded cover is exactly what the public pages serve (carrying a fresh cover forward later re-pins and overwrites it). Rejects non-images / pixel bombs by header before storing. Requires Firebase Storage configured (412 otherwise). { bookId | bookName, imageDataUrl ('data:image/*;base64,...') } -> { ok, bookId, uploaded:true }.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"bookName":{"type":"string"},"imageDataUrl":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/book/cover-match":{"post":{"summary":"BULK COVER MATCH (by filename) - for a publisher importing already-written books. Send the FILENAMES of a set of cover images and the server maps each to a book that has NO cover yet, purely by name: a cleanly named file (e.g. 'The Salt Road.png') matches its title. Deterministic and free - no image bytes are sent, no model call. Anything that doesn't match a title comes back as method:'none' to assign by eye. { images:[{ id, filename }] (up to 200) } -> { matches:[{ id, bookId, bookName, method:'filename'|'none', confidence }], candidates:[{ bookId, title, seriesName }] }. The caller confirms/edits the mapping, then uploads each via /book/cover-upload. (Reading a cover by sight to match it is a Cowork/skill job.) Not per-book metered.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"images":{"type":"array"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/book/artefacts":{"get":{"summary":"ARTEFACT MANIFEST - the authoritative record of a book's CURRENT artefact per role (cover, interior, manuscript, listing, podcastScript, illustrations[]), each tracing its library file id and, for covers, the Firebase Storage mirror + state (mirrored | pending | none). A fast projection over the asset ledger; use it to know a book's cover state and hand off the right file. Pass ?bookId= and/or ?bookName= -> { artefacts }.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/book/blurb":{"post":{"summary":"Write a tight, hook-first shopfront blurb that FITS the small author/publisher card (<=160 chars, never truncated): jumps straight to the point, no 'This book/volume...' throat-clearing, grounded only in the book's own material. { bookId | bookName } -> { blurb }. Not metered. Then pin it via /book/listing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"bookName":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/buy/{asin}":{"get":{"summary":"PUBLIC (no auth) country-agnostic Amazon buy link: /buy/<asin> redirects each visitor to the same book on THEIR local Amazon store (by CDN country header, else a timezone sniff). Use it as the buy button href on your own pages; the ASIN comes from /book/listing.","responses":{"302":{"description":"Redirect to the visitor's local Amazon"}}}},"/api/v1/author-profile":{"get":{"summary":"Read the ACTIVE author persona as a profile: { profile: { penName, bio, books[], photoDataUrl, isPenName, authorId } }. For author accounts this is the single author; for publisher accounts it's the active persona.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Save the active author persona (bio capped at 500 words; penName is the only required field - bio & photo are optional and never fabricated). isPenName marks a pseudonym. Feeds the printed back-cover bio and the 'Also by the author' page. Optionally target a specific persona with authorId.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"penName":{"type":"string"},"bio":{"type":"string"},"books":{"type":"array"},"photoDataUrl":{"type":"string"},"isPenName":{"type":"boolean"},"authorId":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/account":{"get":{"summary":"Read the account: { accountType: 'author'|'publisher', publisherName, publisherHandle, publisherTagline, publisherHeroMode ('latest_book'|'persona'), publisherDesign{layout,background,font}, publisherLogoDataUrl (the imprint logo shown on /publisher/{handle}, '' if none), activeAuthorId, authors[{id,penName,isPenName,bio,photoDataUrl,handle,books[],isDefault,showOnPublisherPage,showOnAuthorPage}] }. An 'author' account has one persona; a 'publisher' manages many under one login, one library and one bill.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Update the account: accountType ('author'|'publisher'), publisherName (imprint), publisherHandle (public page at /publisher/{handle}, unique; a publisher's ONE public page, with its authors grouped on it, online only while the publisher account's Author Page subscription is active - else it answers 404 not available, noindex, and leaves the sitemap), publisherTagline, publisherHeroMode ('latest_book' (default) leads the publisher page with the imprint's newest release cover + the book's author as an inset; 'persona' leads with just the imprint name/tagline), publisherDesign{layout,background,font} (the look of /publisher/{handle} - layout in [grid,mosaic,listing,headline,magazine,spotlight], background in [paper,cream,sand,slate,ink,midnight] (each is a LIGHT/DARK PAIR - the public page renders the half matching the visitor's OS via prefers-color-scheme), font in [classic,modern,elegant,editorial,humanist,grotesque] - the imprint /publisher/{handle} page look, INDEPENDENT of each author page's own theme), publisherLogoDataUrl (imprint logo shown on the public publisher page - a 'data:image/*;base64,...' string; pass '' to clear), and/or activeAuthorId. -> { accountType, publisherName, publisherHandle, publisherTagline, publisherHeroMode, publisherDesign, publisherLogoDataUrl, activeAuthorId }.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"accountType":{"type":"string"},"publisherName":{"type":"string"},"publisherHandle":{"type":"string"},"publisherTagline":{"type":"string"},"publisherHeroMode":{"type":"string"},"publisherDesign":{"type":"object"},"publisherLogoDataUrl":{"type":"string"},"activeAuthorId":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/authors":{"get":{"summary":"List the account's author personas -> { authors:[{id,penName,isPenName,bio,photoDataUrl,handle,books[],isDefault,showOnPublisherPage,showOnAuthorPage}] }.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Create or update an author persona (penName required; bio/photo optional; isPenName marks a pseudonym; handle for /author/{handle}; makeDefault promotes it). showOnPublisherPage lists a publisher's author on /publisher/{handle} (default true); showOnAuthorPage surfaces a pen name on the account's MAIN author page as 'also writing as' (default false, opt-in). Pass id to update. -> { author }.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"penName":{"type":"string"},"isPenName":{"type":"boolean"},"bio":{"type":"string"},"photoDataUrl":{"type":"string"},"handle":{"type":"string"},"books":{"type":"array"},"makeDefault":{"type":"boolean"},"showOnPublisherPage":{"type":"boolean"},"showOnAuthorPage":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/authors/check-handle":{"get":{"summary":"Check an author persona handle's availability (global) -> { handle, available, reason? }. Pass ?handle=.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/author-page":{"get":{"summary":"Read the author's public-homepage config -> { page|null, handleSuggestion, books[{bookId,title,subtitle}] (platform books), profileBooks[{title,year}] (also-by titles you can add as external books), canPublish, hasPack, subscribed (Author Page subscription active), live (published and online) }. The rendered page lives at /author/{handle} (web only); this manages it. Pass ?authorId= to read a MANAGED persona's page instead of your own - how a publisher sets up the public page for an author it represents on the app (403 if you don't manage that persona). Response then also carries { authorId, penName }.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Save the author page (also the layout for pen-name/persona pages). handle (>=3 chars, slugified, unique). published requires >=1 Author Pack AND an active Author Page subscription (USD 4.99 a month) on the owning account, else 402 { error, needsAuthorPack?, needsAuthorPageSubscription?, subscribeSku:'author-page', checkoutUrl? } (save it as a draft instead). The public page is online only while that subscription is active; when it ends the page answers as not available (nothing is deleted) and comes back on resubscribe. A page already published can still be saved while the subscription is off (it stays offline; the answer carries live:false and a notice). books[] entries are platform (bookId -> its cover in the library) or external ({external:true,title,coverFileId,buyKind:'amazon'|'url'|'universal',asin,buyUrl}); covers are NEVER hotlinked - ingest via /author-page/cover-ingest. heroMode ('latest_book' (default) leads the page with the newest book cover + a small author inset; 'persona' leads with the author portrait/bio; a page with no cover falls back to persona automatically). Also: tagline, theme{template,accent,layout,background,font} (THIS page's look - layout in [grid,mosaic,listing,headline,magazine,spotlight], background in [paper,cream,sand,slate,ink,midnight], font in [classic,modern,elegant,editorial,humanist,grotesque]; each author/pen-name page owns its theme independently - no inheritance from the imprint's publisherDesign; the author PORTRAIT shown by heroMode 'persona' is the persona's photoDataUrl, set via /authors or /author-profile), press[{quote,source,url}], contactEmail, socials[{label,url}]. A PUBLISHER account makes no author pages (owner, 2026-10-13): from a publisher account (with or without authorId) this answers 403 { error, publisherAccount:true }; its one public page is /publisher/{handle}, with its authors grouped on it, set up via /account. Pages a publisher made before are no longer served (nothing is deleted). Pass authorId to save a persona's page you co-edit through a claim; the owning account's pack and Author Page subscription gate publishing; only the OWNER's subscription keeps a page online. IMPORTANT precedence: once the real author CLAIMS their page (POST /api/v1/identity/claim, then approved -> pages merge and the handle 301-redirects to the author's own page, or a takeover makes the author the sole editor), the AUTHOR'S decisions always override the publisher's here. -> { page, url, live, notice? }.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string"},"published":{"type":"boolean"},"tagline":{"type":"string"},"heroMode":{"type":"string"},"theme":{"type":"object"},"books":{"type":"array"},"press":{"type":"array"},"contactEmail":{"type":"string"},"socials":{"type":"array"},"authorId":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/author-page/check-handle":{"get":{"summary":"Check a handle's availability -> { handle, available, reason? }. Pass ?handle= (and optionally ?authorId= when checking a managed persona's own handle).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/author-page/cover-ingest":{"post":{"summary":"Save an EXTERNAL book's cover into the author's library (never hotlinked): pass imageUrl (downloaded server-side) OR imageDataUrl (an upload). -> { coverFileId, previewDataUrl }. Put coverFileId on the matching external book in /author-page. 503 if the library can't be reached.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"imageUrl":{"type":"string"},"imageDataUrl":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/author-page/crawl-press":{"post":{"summary":"Fetch a review/interview link and extract ONE tasteful pull-quote + source via AI -> { quote, source, url }. Never invents praise (404 if none found). Add the result to the page's press[].","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/publish-profiles":{"get":{"summary":"List every supported publishing platform -> { profiles:[{ id, name, region, category, units, formats{interior[],coverPdf,epub}, trims[{id,label,wIn,hIn}], note }], maxPlatforms }. Covers KDP, IngramSpark, Lulu, Pothi, Notion Press, B&N Press, BookBaby, Blurb, D2D Print, Kobo, Apple Books, Google Play, Draft2Digital, PublishDrive, StreetLib.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/publish-pack":{"post":{"summary":"Prepare a book for up to 3 platforms at once (superusers unlimited). For each { platformId, trimId } we generate every format that platform accepts - reflowable EPUB, print PDF at the trim, and/or DOCX - and save one folder per platform in the library under <book>/publish/<platform>/ (publisher accounts group these under an <author> layer). Returns each file as base64 too. Pass the manuscript as chapters[{title,content}] + book metadata; authorId attributes the pack to a persona (defaults to the active one).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"subtitle":{"type":"string"},"author":{"type":"string"},"publisher":{"type":"string"},"year":{"type":"integer"},"dedication":{"type":"string"},"alsoBy":{"type":"array"},"seriesName":{"type":"string"},"bookName":{"type":"string"},"authorId":{"type":"string"},"chapters":{"type":"array"},"platforms":{"type":"array"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/polyaly":{"post":{"summary":"Polyaly - the in-app mentor + per-studio subject-matter expert. Send { messages:[{role:'user'|'assistant', content}], studio? } -> { reply }. `studio` is the current screen/tab key (e.g. 'cover', 'editor', 'listing'); Polyaly answers as that expert (cover art director, developmental editor, metadata strategist, ...) AND explains how to use the app. FREE (no Author Pack); lightly rate-limited. Never ghostwrites the user's book.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array"},"studio":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/entitlements":{"get":{"summary":"Read the Author Pack ledger for the key's owner: { enforced, pack{priceGbp,credits}, packBalance (pre-bought packs not yet assigned to a book), books{bookId:{purchased,credits}}, usage{books{bookId:{pct,grounding,groundingCap,boltOns}},strikes,suspended}, fairUse{groundingCap,boltOnPriceGbp} }. CONSUMPTION AGAINST QUOTA ONLY - model cost/margin is never exposed to a user (pct is the % of a book's allowance used).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/usage":{"get":{"summary":"Per-book CONSUMPTION against quota: books{bookId:{pct (0-100, % of the book's allowance used),grounding,groundingCap,boltOns}}, strikes, groundingCap, boltOnPriceGbp (USD 19, field name is legacy), superuser, exempt. No model cost/money is ever returned to a user - cost is superadmin-only (see /admin/usage).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/admin/usage":{"get":{"summary":"SUPERADMIN ONLY (403 otherwise): every user side by side - { rows:[{ userId, label, accountType, superuser, gated, bookCount, books[{bookId,cents,pct,grounding,boltOns}], modelCostCents, grounding, boltOns, packBalance, booksUnlocked, payments{count,totalPence,currency,lastAt} }], totals{users,modelCostCents,revenuePence,payments} }. This is the ONLY surface that exposes model cost (operator margin view) - never returned to a normal user.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/receipts":{"get":{"summary":"The key owner's purchase receipts, one server-authoritative ledger every channel reads -> { receipts:[{ id, reference, createdAt, kind:'pack'|'capacity', amountPence, currency, bookId?, bookTitle?, seriesName?, authorName?, invoiceUrl? }] }. Each is tied to the book it unlocked (title/series/pen name snapshotted at purchase). amountPence is VAT-INCLUSIVE (the provider handles tax); purchases are NON-REFUNDABLE. Aggregate client-side for spend by book, series or pen name.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/entitlements/spend":{"post":{"summary":"PREFLIGHT (read-only): check whether a book/capability is entitled WITHOUT consuming - the actual charge happens inside the metered generation endpoints themselves. Returns 200 { ok } if the book is purchased and has credit; 409 { needsPackAssign, packBalance } if the account has unassigned packs; 402 { needsPack } if it needs an Author Pack (bought on the website only). Research: pass unit=chapterId and phase ('before'|'after'). You normally don't need to call this - just pass bookId on the generation call and read its fairUse/402/409/429. Pass recover:true (on the generation call, or here) to rebuild a step that was already charged but crashed leaving a stub - no extra credit is spent (valid only once that slot has been paid; real cost is still metered).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"capability":{"type":"string"},"unit":{"type":"string"},"phase":{"type":"string"},"recover":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/entitlements/checkout":{"post":{"summary":"Start a checkout. pack:'author' (default) buys Author Packs at a flat $75 each: pass quantity (no bookId) to add N packs to the account balance (assigned to books on first studio use), or bookId with quantity 1 to unlock that book directly. pack:'capacity' buys a repeatable $19 capacity bolt-on for one heavy book (bookId required). Or pass sku (author-pack, author-pack-5, capacity-bolton). -> { configured:true, checkoutUrl } where checkoutUrl is the item's page at the Polyglyph store (https://store.polyglyphanalytica.com/scrollfoundry/<sku>), carrying a signed reference to your account: open it in a browser to pay. The grant lands on your account once the store confirms the payment (read /entitlements). { configured:false, message } when payment is not available on this deployment.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"pack":{"type":"string"},"quantity":{"type":"integer"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/account/delete":{"post":{"summary":"Delete the key owner's account and its sign-in: erases everything we hold for it (the account, pen names, author profile, projects, book settings, packs, usage, API keys, and every file in the account's library and trash) except receipts, which are kept for tax with only what a tax record needs. An Author Page subscription is billed by the store: when one is active, manageUrl is where to cancel it. Needs a key made with the 'account:delete' scope (403 { needsScope } otherwise). -> { ok, subscriptionCancelled, dataPurged, signInDeleted, manageUrl? }; dataPurged is false when a part could not be erased.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/derive":{"post":{"summary":"Derive a NEW book from an existing one. Two families: REUSE THE WORK - derivation:'clone' (a full copy), 'fork' (a full copy meant to continue on a different path), 'remix' (keep the plan and premise, blank the prose to rewrite); EXTEND THE WORLD - 'sequel'/'prequel' (a fresh manuscript in the SAME series), 'spinoff' (a fresh manuscript that seeds a NEW, linked series). parentBookName is the existing book's title; newBookName (or newTitle) names the new one. The structured project, book config and book count carry over per the derivation; for clone/fork the parent's library folder is copied too, with its own records. -> { project, config, derivation, parentBookName, filesCopied }.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"parentBookName":{"type":"string"},"newBookName":{"type":"string"},"newTitle":{"type":"string"},"derivation":{"type":"string"},"seriesName":{"type":"string"},"authorId":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/book/delete":{"post":{"summary":"Delete a book: its structured project, book config and book count, and its library folder - moved to the trash, where it can be restored for 30 days (GET /library/trash, POST /library/restore). A stored manuscript record (POST /manuscripts) is kept: remove it with POST /manuscripts/delete. Pass bookName. -> { deleted, bookName, filesTrashed, removedBookIds }.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookName":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/series/delete":{"post":{"summary":"Delete an EMPTY series record. Pass seriesId or name. 409 { seriesIds } while any book, manuscript, project or config still uses it; library folders are untouched. (book/delete already prunes a series when its last book goes.) -> { deleted, seriesIds }.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"seriesId":{"type":"string"},"name":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/manuscripts/delete":{"post":{"summary":"Delete one stored manuscript record (from POST /manuscripts). Library files are untouched. -> { deleted, manuscriptId }.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"manuscriptId":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/reader-fit":{"post":{"summary":"Reader-fit appraisal (metered): how well the book serves a described ideal reader. bookTitle + readerPersona (free text) required.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"bookTitle":{"type":"string"},"subtitle":{"type":"string"},"author":{"type":"string"},"genre":{"type":"string"},"kind":{"type":"string"},"summary":{"type":"string"},"manuscriptText":{"type":"string"},"readerPersona":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/agent-pitch":{"post":{"summary":"Literary agent / publisher pitch letter (metered). bookTitle required.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"bookTitle":{"type":"string"},"subtitle":{"type":"string"},"author":{"type":"string"},"authorBio":{"type":"string"},"genre":{"type":"string"},"kind":{"type":"string"},"summary":{"type":"string"},"comps":{"type":"string"},"wordCount":{"type":"integer"},"targetType":{"type":"string"},"targetName":{"type":"string"},"marketplaceCountry":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/health":{"get":{"summary":"Dependency check: { ok, ready, deps: { text, image, library, safety: { status, detail } }, routing: { text, safety, webSearch, image, tts }, summary }. 503 when not ready. status is ok | billing | ... - run before a build.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/index":{"get":{"summary":"The server-owned shelf, rebuilt live from the library + started books: { books[], series[], assets[], fileCount }.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/projects":{"get":{"summary":"List the caller's structured book projects (summaries).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/project":{"get":{"summary":"Read one structured project: ?bookName= -> { project | null }.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Create/update a structured project (outline, chapters, metadata). bookName required. chapters[] replaces the list; a chapter sent without content keeps the text that chapter (same title) already has, and content (even an empty string) sets it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookName":{"type":"string"},"seriesName":{"type":"string"},"title":{"type":"string"},"author":{"type":"string"},"genre":{"type":"string"},"kind":{"type":"string"},"topic":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/book-config":{"get":{"summary":"Read a book's config: ?bookName= -> { config }.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Save a book's config (series, genre, kind, persona, ...). bookName required.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookName":{"type":"string"},"seriesName":{"type":"string"},"genre":{"type":"string"},"kind":{"type":"string"},"authorId":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/assets":{"get":{"summary":"List deliverable asset records: ?bookName= (optional) -> { assets[] }.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/validate":{"post":{"summary":"FREE quality check. { subject:'manuscript', chapters:[{title,content}] } or { subject:'docx'|'epub', base64 } -> { subject, ok, errors, warnings, issues[], stats }. Reports only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string"},"chapters":{"type":"array"},"base64":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/terms/status":{"get":{"summary":"Terms-of-Use gate state: { accepted, acceptedAt, acceptedVersion, termsVersion, effectiveDate, enforced }.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/pricing/localized":{"get":{"summary":"PUBLIC: prices localised to the caller's country: { country, currencyCode, authorPack, authorPack5, capacityBolton, authorPage }.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/book/page-visibility":{"post":{"summary":"Show/hide a book on the author page (showOnPage) and publisher page (showOnPublisherPage). bookId is the book record id (from /index or /manuscripts).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string"},"showOnPage":{"type":"boolean"},"showOnPublisherPage":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/authors/{id}":{"delete":{"summary":"Delete one author persona (not the default).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/notifications":{"get":{"summary":"In-app notifications: { notifications[], unread }.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/notifications/read":{"post":{"summary":"Mark notifications read: { ids? } (omit = all) -> { ok, marked }.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/notifications/prefs":{"get":{"summary":"Notification preferences: { prefs }.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Save notification preferences.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"push":{"type":"boolean"},"mutedTypes":{"type":"array"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/notifications/config":{"get":{"summary":"Push config for clients: { enabled, vapidKey, senderId }.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/notifications/token":{"post":{"summary":"Register a push device token (20-4096 chars).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"platform":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/notifications/token/delete":{"post":{"summary":"Unregister a push device token.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/skill/version":{"get":{"summary":"PUBLIC: current Cowork skill version + changelog.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/skill.zip":{"get":{"summary":"PUBLIC: the Cowork skill bundle (zip).","responses":{"200":{"description":"application/zip"}}}},"/api/v1/docs":{"get":{"summary":"PUBLIC: human-readable API docs (HTML).","responses":{"200":{"description":"text/html"}}}},"/api/v1/openapi.json":{"get":{"summary":"PUBLIC: this OpenAPI document.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/admin/suspended":{"get":{"summary":"SUPERUSER: suspended accounts.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/admin/unsuspend":{"post":{"summary":"SUPERUSER: goodwill fair-use meter reset.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string"},"email":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/admin/billing-reconcile":{"get":{"summary":"SUPERUSER: internal cost meter vs billing export.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/admin/store-health":{"get":{"summary":"SUPERUSER: datastore health + counts.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/admin/covers/backfill":{"post":{"summary":"SUPERUSER: backfill public cover slots into Storage.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/legal/{doc}":{"get":{"summary":"Fetch a legal document as { id, title, effectiveDate, markdown }. doc is 'terms' or 'privacy'. Public (no key required) so it can be shown before sign-in; render the markdown verbatim.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/library/push":{"post":{"summary":"Write a file into the key owner's library under '[author ->] series -> book'. contentBase64 is the file bytes (up to ~14 MB through this route; 30 MB is the most for one file). Allowed types: Word, EPUB, PDF, ZIP, text, Markdown, JSON, HTML, CSV, PNG, JPEG, WebP, GIF, MP3, WAV, M4A (415 otherwise); 507 when the account's library is full. Pass kind/runId/channel/sources to record it (a numbered filename like 09-cover_... is recorded by itself). For publisher accounts, pass authorName (or authorId) to file under a specific pen name / imprint; author accounts omit it. Pass supersede:true when writing a REBUILD of a deliverable - the server moves any older build of the same deliverable (matched by base name, so siblings like other chapters' research are never touched) into archive/<stamp>/ before writing the fresh one, so the live folder keeps ONE canonical copy. Response includes { archived }.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"seriesName":{"type":"string"},"bookName":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"contentBase64":{"type":"string"},"authorId":{"type":"string"},"authorName":{"type":"string"},"supersede":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/library/files":{"get":{"summary":"List every file in the key owner's library, each with its folder path, md5Checksum and modifiedTime - so a client can mirror the tree AND detect changes/deletions. Fields: id, name, path, md5Checksum, modifiedTime, size, mimeType. Use with /library/file/{id} (the id holds '/', so URL-encode it).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/library/file/{id}":{"get":{"summary":"Download one library file by id -> { id, name, mimeType, contentBase64 }.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/library/trash":{"get":{"summary":"Recently deleted: one entry per delete -> { deleted:[{ stamp, folders[], fileCount, deletedAt }], keptDays:30 }. Trash is removed after 30 days.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/library/restore":{"post":{"summary":"Put one delete back where it was. { stamp } from /library/trash -> { ok, restored }.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stamp":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/library/usage":{"get":{"summary":"How much of the library is used -> { usedBytes, quotaBytes, unlimited, maxFileBytes }.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/admin/support/files":{"get":{"summary":"SUPERUSER ONLY. List one book's files for support, ?userId=&bookName=. 403 unless the author has a live 'Let support open this book' grant for it (7 days); every call is logged on the author's Files screen.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/admin/support/file":{"get":{"summary":"SUPERUSER ONLY. One file of a shared book, ?userId=&bookName=&id= -> { id, name, mimeType, contentBase64 }. 403 without a live grant or for a file outside that book; logged before the bytes go out.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/library/export":{"get":{"summary":"Download all my books: a ZIP of every file in the library by pen name, series and book, plus books.json with each book's project (chapters included) and settings.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/library/dedupe":{"post":{"summary":"Dedupe superseded deliverables in the library, the channel-agnostic tidy. DRY-RUN by default: returns { groups:[{ base, keep, trash[], platform? }], trashedCount, applied:false, folders } describing what it WOULD trash. Pass apply:true to move the older duplicates to the trash (restorable for 30 days). Target ONE folder with { folderId }, or a book's publish/<platform>/ subfolders with { seriesName, bookName, authorName? }. Within each folder it keeps the NEWEST per deliverable base and trashes only strictly-older duplicates; research + illustration files (legitimately many) are always skipped, so a per-chapter deliverable is never destroyed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"folderId":{"type":"string"},"seriesName":{"type":"string"},"bookName":{"type":"string"},"authorName":{"type":"string"},"apply":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/preview/{id}":{"get":{"summary":"Readable-text preview of one library file by id -> { name, mimeType, kind, text, truncated, note }. Server-side extraction: .docx/.epub are unzipped to prose; text/markdown/json/etc. pass through. kind 'binary' (note 'image'|'pdf') means no inline text view - show the image or download the file. Lets any channel examine an artefact's content without downloading it.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/skill/checkin":{"post":{"summary":"Skill self-update check-in. Send { installedVersion } (the version embedded in the installed SKILL.md). The endpoint owns a 24h per-account cadence and returns { latest, updateAvailable, mustUpdate, throttled, skillUrl, companions[], minSupported, changes[] }. On updateAvailable the skill silently re-saves SKILL.md + companions from skillUrl and prints one quiet line; mustUpdate means the installed version is below minSupported.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"installedVersion":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/book/claim":{"post":{"summary":"Claim a book as work-in-progress so parallel Cowork agents don't build the same one. Server-authoritative (atomic Firestore transaction) - not a file marker, so exactly one agent wins. Send { bookKey (any stable per-book string - its library folder path or title-slug), agentId, agentLabel?, ttlSeconds? }. Returns { claimed:true, expiresAt } if yours, else { claimed:false, heldBy, heldByLabel, expiresAt } - on false, SKIP to the next book. Heartbeat to keep it; a lapsed TTL frees a crashed agent's claim.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookKey":{"type":"string"},"agentId":{"type":"string"},"agentLabel":{"type":"string"},"ttlSeconds":{"type":"number"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/book/claim/heartbeat":{"post":{"summary":"Extend your WIP claim on a book during long work -> { ok, expiresAt }. { ok:false } if you're not the current owner.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookKey":{"type":"string"},"agentId":{"type":"string"},"ttlSeconds":{"type":"number"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/book/release":{"post":{"summary":"Release your WIP claim on a book when finished or aborting -> { ok }. status is 'done' (default) or 'abandoned'.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookKey":{"type":"string"},"agentId":{"type":"string"},"status":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/book/claims":{"get":{"summary":"List the books currently claimed WIP (non-expired) for this account -> { claims:[{ bookKey, agentId, agentLabel, claimedAt, expiresAt }] }. Use to show who's building what across a multi-agent run.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/author-identities":{"get":{"summary":"Shared, claimable author pages you own or co-own -> { identities:[{ id, handle, displayName, isPenName, aka[{name,isPenName}], owners[{accountId,role,canEdit,isMe}], myRole, canEdit, bookCount, myBookCount, pendingClaims[] }], toApprove:[{ id, handle, displayName, claims[{accountId,byName,role,mode,at}] }] }. An author page aggregates books from EVERY publisher (each book carries its publisher's attribution); a publisher only ever displays the books it published for that author.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/author-identity/claim":{"post":{"summary":"Request to claim a page by handle. mode 'coown' (share) or 'takeover' (become sole editor; other owners keep attribution). The current owner approves. If you (an author) already have your own page, an approved claim MERGES the claimed page into yours.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string"},"mode":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/author-identity/claim/resolve":{"post":{"summary":"Approve or deny a pending claim on a page you can edit. Pass the identity id (or handle), the claimant accountId, and approve (boolean). Approving an author's claim who already has a page merges the two into theirs and 301-redirects the old handle.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"handle":{"type":"string"},"accountId":{"type":"string"},"approve":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/author-identity/book":{"post":{"summary":"Add a book to a page you own/co-own, attributed to your account. It appears on the author's page (always, with your name as publisher) and on your publisher page (filtered to your books). book:{ title(required), subtitle, year, coverFileId, external, buyKind:'amazon'|'url'|'universal', asin, buyUrl, visible }.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string"},"id":{"type":"string"},"book":{"type":"object"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/diag/log":{"post":{"summary":"Beacon anonymous application/error diagnostics to the server's live tail. Nothing personal is stored (payloads are scrubbed; any actor is reduced to a salted anon id). src:'web'|'android'|'api'|'server'; events:[{ level:'info'|'warn'|'error', event:'<slug>', meta:{...} }]. -> { ok, accepted }.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"src":{"type":"string"},"events":{"type":"array"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/diag/logs":{"get":{"summary":"OPERATOR ONLY (superuser key): read the recent anonymous diagnostics tail -> { total, seq, entries[{ t, level, src, event, meta, anon }] }. Filter with ?level=&src=&event=&since=&limit=.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/diag/summary":{"get":{"summary":"OPERATOR ONLY (superuser key): health roll-up of the diagnostics tail -> { total, seq, byLevel{info,warn,error}, topEvents[{event,count}] }.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/diag/prune":{"post":{"summary":"OPERATOR ONLY (superuser key): delete diagnostics older than the retention window (default 7 days; ?days= to override). The server also runs this automatically once a day, so an external cron is optional. -> { ok, retentionDays, memory, durable, cutoff }.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}