--- title: "Generate a new story from a prompt" method: POST path: "/v2/stories/generate" tags: ["stories"] --- # Generate a new story from a prompt `POST /v2/stories/generate` ## Request - Base URL: `https://api.storydoc.com` - URL: `https://api.storydoc.com/v2/stories/generate` - Auth: HTTP bearer Generates a brand-new presentation from a natural-language prompt using AI. The endpoint runs a 3-step pipeline (outline → slide layouts → per-slide content), optionally derives a brand color palette and fonts from the supplied `website`, persists the page in **Live** status, and creates its live link. The response includes the live URL, short URL, editor URL, and the `pageId` / `versionId` you can pass to other v2 endpoints (e.g. use `pageId` as `storyId` in `POST /v2/versions` to create personalized variants of the generated story). ## Rate Limit 150 requests per minute per organization. Every response includes `x-rate-limit-counter` and `x-rate-limit-maximum` headers. ## Latency Generation is synchronous and typically takes 30–90 seconds depending on slide count and brand pipeline. Use a long-running HTTP client and set a generous read timeout (≥ 180s). ## Request body - GenerateStoryRequest - `prompt` string, required: Natural-language description of the presentation you want to generate. The more concrete the prompt (topic, audience, structure, tone, key points), the better the output. Cannot be empty or whitespace-only. - `senderEmail` string, email, required: Email of the user that owns the generated story (becomes the story creator and the sender on the live link). Must belong to a user in the authenticated organization, otherwise the request is rejected with 400. - `company` string: Optional company name to use as the subject of the presentation. If omitted and `website` is provided, the name is inferred from Brandfetch. - `website` string: Optional company website used to derive brand colors, fonts, and logo for the generated story's design system. Accepts a bare domain (`acme.com`) or a full URL (`https://acme.com/about`); the hostname is extracted automatically. If the brand pipeline fails or returns unusable data, the story falls back to scaffold defaults (the request still succeeds). - `presentation type` 'Agency pitch deck' | 'Annual report' | 'Brand guidelines' | 'Brand proposal' | 'Brochure' | 'Business Plan' | 'Business report' | 'Case study one-pager' | 'Company presentation' | 'Construction proposal' | 'Customer onboarding meeting' | 'E-book' | 'ESG report' | 'Event proposal' | 'Film pitch deck' | 'Gaming pitch deck' | 'General presentation' | 'HR recruitment' | 'Invest pitch deck' | 'Investor report' | 'Marketing case study' | 'Marketing plan' | 'Marketing proposal' | 'Music event sponsorship proposal' | 'NGO report' | 'New employee onboarding' | 'One pager' | 'Partnership proposal' | 'Pre-interview deck' | 'Product launch' | 'Product newsletter' | 'Product pitch deck' | 'Product roadmap' | 'Project proposal' | 'Quarterly Business Review' | 'Quarterly report' | 'Real estate listing' | 'Research report' | 'Restaurant proposal deck' | 'Sales deck' | 'Sales kickoff meeting' | 'Sales proposal' | 'Service pitch deck' | 'Sports sponsorship' | 'Startup pitch deck' | 'Student case study' | 'Student report' | 'Video case study' | 'Webinar' | 'White paper' | 'Workshop proposal': Optional classification that selects an AI template tuned for that document class. Must be one of the supported subtypes (see enum). Defaults to `General presentation` when omitted. Unsupported values return 400 with the full allowed list under `allowedPresentationTypes`. ## Response `200` Story generated and published successfully - GenerateStoryResponse - `url` string, uri, required: Public live URL of the generated story. - `shortUrl` string, uri, required: Shortened share URL for the live link. - `pageId` string, required: ID of the underlying story (page). Use this as `storyId` in subsequent `POST /v2/versions` calls to create personalized variants of the generated story. - `versionId` string, required: ID of the generated live link. Use it as the path parameter for `POST /v2/versions/{versionId}` to update its data. - `editorUrl` string, uri, required: Deep link to edit the generated version in the Storydoc editor. - `versionUrl` string, uri, required: Deep link to the version detail page in the Storydoc platform. ## Other responses - `400`: Invalid request body or unsupported presentation type - `403`: Missing or invalid authorization token - `404`: Account not found for the authenticated organization - `429`: Rate limit exceeded - `500`: Generation pipeline failed --- [API](https://skmtc.dev/storydoc/apis/storydoc-api-v2.md) - [All operations](https://skmtc.dev/storydoc/apis/storydoc-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/storydoc/apis/storydoc-api-v2/revisions/366e7d124e9e?raw)