{"openapi":"3.1.0","info":{"title":"Penreel.ai API","version":"1.0.0","description":"REST API exposing the actions of the Penreel.ai product. Authenticate with a Kavaro API key as a bearer token."},"servers":[{"url":"https://kavaro.ai"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","description":"A Kavaro API key (user- or organization-scoped)."}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/api/rest/actions/create_story":{"post":{"operationId":"create_story","summary":"New story","description":"Create a new story in the chosen mode from a premise. Starts at the storyline stage.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["stories:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"title":{"type":"string","description":"Working title for the story"},"mode":{"type":"string","enum":["novel","short_story","screenplay","cartoon","childrens"],"description":"The story mode (shapes writing + visuals)"},"premise":{"description":"A sentence, paragraph or fuller idea to start from","type":"string"}},"required":["title","mode"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/update_story":{"post":{"operationId":"update_story","summary":"Update story","description":"Edit a story's title, premise, logline, synopsis or style. Records a revision so it can be reverted.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["stories:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"storyId":{"type":"string"},"title":{"type":"string"},"premise":{"type":"string"},"logline":{"type":"string"},"synopsis":{"type":"string"},"styleConfig":{"description":"Visual/video style overrides (locked or steered)"}},"required":["storyId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/delete_story":{"post":{"operationId":"delete_story","summary":"Delete story","description":"Permanently delete a story and all its chapters, sections and assets.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["stories:delete"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"storyId":{"type":"string"}},"required":["storyId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/create_chapter":{"post":{"operationId":"create_chapter","summary":"Add chapter","description":"Add a chapter to a story, optionally after a given chapter. Provide a brief describing what happens.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["chapters:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"storyId":{"type":"string"},"title":{"type":"string"},"brief":{"type":"string"},"afterChapterId":{"description":"Place the new chapter after this one; omit to append at the end","type":"string"},"involvedCharacterIds":{"type":"array","items":{"type":"string"}}},"required":["storyId","title"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/update_chapter":{"post":{"operationId":"update_chapter","summary":"Update chapter","description":"Edit a chapter's title, brief, status or involved characters. Records a revision.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["chapters:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"chapterId":{"type":"string"},"title":{"type":"string"},"brief":{"type":"string"},"status":{"type":"string","enum":["planned","drafting","drafted","approved","postponed"]},"involvedCharacterIds":{"type":"array","items":{"type":"string"}}},"required":["chapterId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/delete_chapter":{"post":{"operationId":"delete_chapter","summary":"Delete chapter","description":"Delete a chapter and its sections.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["chapters:delete"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"chapterId":{"type":"string"}},"required":["chapterId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/reorder_chapter":{"post":{"operationId":"reorder_chapter","summary":"Reorder chapter","description":"Move a chapter to a new position (after another chapter, or to the start when omitted).","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["chapters:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"chapterId":{"type":"string"},"afterChapterId":{"type":"string"}},"required":["chapterId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/create_section":{"post":{"operationId":"create_section","summary":"Add section","description":"Add a section (scene/beat/panel/page) to a chapter, optionally after a given section.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["sections:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"chapterId":{"type":"string"},"type":{"description":"Section type; defaults to the mode's section type","type":"string"},"title":{"type":"string"},"content":{"type":"string"},"afterSectionId":{"type":"string"}},"required":["chapterId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/update_section":{"post":{"operationId":"update_section","summary":"Update section","description":"Edit a section's title, type or content. Records a revision.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["sections:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"sectionId":{"type":"string"},"title":{"type":"string"},"type":{"type":"string"},"content":{"type":"string"}},"required":["sectionId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/delete_section":{"post":{"operationId":"delete_section","summary":"Delete section","description":"Delete a section.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["sections:delete"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"sectionId":{"type":"string"}},"required":["sectionId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/reorder_section":{"post":{"operationId":"reorder_section","summary":"Reorder section","description":"Move a section to a new position within its chapter.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["sections:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"sectionId":{"type":"string"},"afterSectionId":{"type":"string"}},"required":["sectionId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/create_character":{"post":{"operationId":"create_character","summary":"New character","description":"Create a character in the shared library. Provide a name and optionally a short sketch or profile fields.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["characters:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string"},"shortSketch":{"type":"string"},"profile":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Partial map of profile field id → text. Known fields: identity, background, personality, motivations, relationships, definingHighlights, physicalDescription, arc."}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/update_character":{"post":{"operationId":"update_character","summary":"Update character","description":"Edit a character's name, sketch, profile fields or visual signature. Records a per-field revision.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["characters:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"characterId":{"type":"string"},"name":{"type":"string"},"shortSketch":{"type":"string"},"profile":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Partial map of profile field id → text. Known fields: identity, background, personality, motivations, relationships, definingHighlights, physicalDescription, arc."},"visualSignature":{}},"required":["characterId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/delete_character":{"post":{"operationId":"delete_character","summary":"Delete character","description":"Delete a character from the library and remove them from every story.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["characters:delete"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"characterId":{"type":"string"}},"required":["characterId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/cast_character":{"post":{"operationId":"cast_character","summary":"Add to story","description":"Cast a library character into a story, optionally with a story-specific role.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["characters:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"storyId":{"type":"string"},"characterId":{"type":"string"},"storyRole":{"type":"string"}},"required":["storyId","characterId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/uncast_character":{"post":{"operationId":"uncast_character","summary":"Remove from story","description":"Remove a character from a story (keeps them in the library).","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["characters:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"storyId":{"type":"string"},"characterId":{"type":"string"}},"required":["storyId","characterId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/set_relationship":{"post":{"operationId":"set_relationship","summary":"Set relationship","description":"Record or update a relationship from one character to another (nature + history), optionally story-specific.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["characters:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"characterId":{"type":"string"},"relatedCharacterId":{"type":"string"},"nature":{"type":"string","description":"e.g. 'sister', 'rival', 'mentor'"},"history":{"type":"string"},"storyId":{"type":"string"}},"required":["characterId","relatedCharacterId","nature"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/delete_relationship":{"post":{"operationId":"delete_relationship","summary":"Remove relationship","description":"Delete a character relationship.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["characters:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"relationshipId":{"type":"string"}},"required":["relationshipId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/revert_element":{"post":{"operationId":"revert_element","summary":"Revert","description":"Revert an element (story / chapter / section / character) to an earlier version captured in its history. Restoring is itself recorded, so a revert can be undone.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["stories:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"revisionId":{"type":"string","description":"The AuthoringRevision id to restore"}},"required":["revisionId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/propose_storyline":{"post":{"operationId":"propose_storyline","summary":"Propose storyline","description":"Stage 1. Propose a logline, a short synopsis and a light starting cast for the story from its premise. Cheap scaffolding the author iterates on before anything expensive happens.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["stories:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"storyId":{"type":"string"}},"required":["storyId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/approve_storyline":{"post":{"operationId":"approve_storyline","summary":"Approve storyline","description":"Lock the storyline & cast and advance the story to the chapter-plan stage.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["stories:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"storyId":{"type":"string"}},"required":["storyId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/propose_chapter_plan":{"post":{"operationId":"propose_chapter_plan","summary":"Propose chapter plan","description":"Stage 2. Propose an ordered chapter plan — each chapter a brief (what happens, which characters, what it accomplishes), not prose. Only available before drafting has begun; replaces the current planned chapters.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["chapters:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"storyId":{"type":"string"}},"required":["storyId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/approve_chapter_plan":{"post":{"operationId":"approve_chapter_plan","summary":"Approve chapter plan","description":"Lock the chapter plan and advance the story to the drafting stage.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["chapters:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"storyId":{"type":"string"}},"required":["storyId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/draft_chapter":{"post":{"operationId":"draft_chapter","summary":"Draft chapter","description":"Stage 3. Write full prose for one chapter from its approved brief, broken into sections. Marks it drafted.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["sections:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"chapterId":{"type":"string"}},"required":["chapterId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/approve_chapter":{"post":{"operationId":"approve_chapter","summary":"Approve chapter","description":"Lock a drafted chapter as approved.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["chapters:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"chapterId":{"type":"string"}},"required":["chapterId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/postpone_chapter":{"post":{"operationId":"postpone_chapter","summary":"Postpone chapter","description":"Skip this chapter for now and come back to it later.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["chapters:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"chapterId":{"type":"string"}},"required":["chapterId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/reopen_stage":{"post":{"operationId":"reopen_stage","summary":"Step back","description":"Step the story back to an earlier stage (storyline or chapter_plan) to revise it. Non-destructive.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["stories:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"storyId":{"type":"string"},"stage":{"type":"string","enum":["storyline","chapter_plan","drafting"]}},"required":["storyId","stage"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/revise_element":{"post":{"operationId":"revise_element","summary":"Apply comment","description":"Apply the author's plain-language comment to a single element (a section's prose, a chapter's brief, the synopsis, or a character profile field), revising only that element and leaving the rest untouched.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["stories:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"model":{"type":"string","enum":["AuthoringStory","AuthoringChapter","AuthoringSection","AuthoringCharacter"]},"entityId":{"type":"string"},"field":{"description":"For AuthoringStory (logline|synopsis) or AuthoringCharacter (profile field id)","type":"string"},"comment":{"type":"string","description":"The author's feedback to apply"}},"required":["model","entityId","comment"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/regenerate_element":{"post":{"operationId":"regenerate_element","summary":"Regenerate","description":"Produce a fresh, different take on a single element. The prior version is kept in history so it can be restored.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["stories:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"model":{"type":"string","enum":["AuthoringStory","AuthoringChapter","AuthoringSection","AuthoringCharacter"]},"entityId":{"type":"string"},"field":{"type":"string"},"instructions":{"description":"Optional steer for the new take","type":"string"}},"required":["model","entityId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/regenerate_alternatives":{"post":{"operationId":"regenerate_alternatives","summary":"Suggest alternatives","description":"Produce several distinct alternative takes on a single element WITHOUT changing it — the author reviews them and picks one (which is then applied as an edit). Use for 'give me options' rather than an in-place rewrite.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["stories:view"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"model":{"type":"string","enum":["AuthoringStory","AuthoringChapter","AuthoringSection","AuthoringCharacter"]},"entityId":{"type":"string"},"field":{"type":"string"},"instructions":{"type":"string"},"count":{"type":"integer","minimum":2,"maximum":5}},"required":["model","entityId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/invent_character":{"post":{"operationId":"invent_character","summary":"Invent character","description":"Invent a character from a one-line prompt — fleshing out the full structured profile. Optionally cast into a story.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["characters:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"prompt":{"type":"string","description":"A one-line idea, e.g. 'a retired lighthouse keeper with a secret'"},"storyId":{"description":"If given, cast the new character into this story","type":"string"}},"required":["prompt"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/expand_character_field":{"post":{"operationId":"expand_character_field","summary":"Expand field","description":"Deepen one field of a character's profile (identity, background, personality, motivations, …).","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["characters:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"characterId":{"type":"string"},"field":{"type":"string","description":"The profile field id to expand"}},"required":["characterId","field"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/extract_characters":{"post":{"operationId":"extract_characters","summary":"Extract characters","description":"Scan a story's drafted chapters and propose characters that appear but aren't yet in the cast, creating and casting them.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["characters:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"storyId":{"type":"string"}},"required":["storyId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/suggest_characters":{"post":{"operationId":"suggest_characters","summary":"Suggest characters","description":"Suggest new characters that would strengthen the story (returns ideas; does not create them).","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["characters:view"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"storyId":{"type":"string"}},"required":["storyId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/consistency_check":{"post":{"operationId":"consistency_check","summary":"Consistency check","description":"Check a story's drafted prose against its characters' established profiles and flag contradictions. Read-only.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["stories:view"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"storyId":{"type":"string"}},"required":["storyId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/generate_character_reference_set":{"post":{"operationId":"generate_character_reference_set","summary":"Generate reference set","description":"Generate a clean visual reference set for a character (full-body turnaround, no background) in the story's style — the mechanism that keeps the character looking consistent everywhere. Produces variations to pick from.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["media:generate"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"characterId":{"type":"string"},"storyId":{"description":"Use this story's visual style","type":"string"},"n":{"type":"integer","minimum":1,"maximum":4},"stylePrompt":{"description":"Optional extra style steer","type":"string"}},"required":["characterId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/generate_scene_illustration":{"post":{"operationId":"generate_scene_illustration","summary":"Illustrate scene","description":"Generate artwork for a chapter, section, panel or page using the relevant characters and the story's style.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["media:generate"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"storyId":{"type":"string"},"chapterId":{"type":"string"},"sectionId":{"type":"string"},"prompt":{"description":"Optional explicit description; otherwise derived from the content","type":"string"},"n":{"type":"integer","minimum":1,"maximum":4}},"required":["storyId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/generate_cover_art":{"post":{"operationId":"generate_cover_art","summary":"Generate cover","description":"Generate cover art for the story in its style and mode, featuring characters or a key scene.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["media:generate"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"storyId":{"type":"string"},"prompt":{"type":"string"},"n":{"type":"integer","minimum":1,"maximum":4}},"required":["storyId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/generate_variations":{"post":{"operationId":"generate_variations","summary":"More variations","description":"Generate more variations of an existing image asset, grouped with it so the author can pick a favourite.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["media:generate"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"assetId":{"type":"string"},"n":{"type":"integer","minimum":1,"maximum":4}},"required":["assetId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/lock_canonical":{"post":{"operationId":"lock_canonical","summary":"Set as canonical","description":"Lock an image as the canonical choice: a character's reference set, the story's cover, or the locked style. Unsets any sibling in the same variation group.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["media:generate"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"assetId":{"type":"string"}},"required":["assetId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/generate_chapter_video":{"post":{"operationId":"generate_chapter_video","summary":"Make chapter video","description":"Turn a whole chapter into a video clip in the story's style. Runs in the background — the clip appears when ready and the author is notified.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["media:generate"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"chapterId":{"type":"string"}},"required":["chapterId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/generate_section_video":{"post":{"operationId":"generate_section_video","summary":"Make scene video","description":"Turn a single section (scene/panel/page) into a video clip in the story's style. Runs in the background.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["media:generate"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"sectionId":{"type":"string"}},"required":["sectionId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/reroll_video":{"post":{"operationId":"reroll_video","summary":"Re-roll video","description":"Re-generate a video asset that was already created (e.g. you didn't like the result). Runs in the background.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["media:generate"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"assetId":{"type":"string"}},"required":["assetId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}}}}