STstorydoc
stories

Generate a new story from a prompt

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).

post/v2/stories/generate

Request

  • Base URL
    https://api.storydoc.com
  • Auth
    HTTP bearer

Request body

promptstring 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.

senderEmailstring 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.

companystring

Optional company name to use as the subject of the presentation. If omitted and website is provided, the name is inferred from Brandfetch.

websitestring

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.

Example request

{
  "prompt": "A 6-slide sales deck pitching our analytics product to enterprise marketing teams. Highlight ROI, ease of integration, and customer success stories.",
  "senderEmail": "sender@company.com",
  "company": "ACME Corporation",
  "website": "acme.com",
  "presentation type": "Sales deck"
}

Response

Story generated and published successfully

urlstring uri required

Public live URL of the generated story.

shortUrlstring uri required

Shortened share URL for the live link.

pageIdstring 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.

versionIdstring required

ID of the generated live link. Use it as the path parameter for POST /v2/versions/{versionId} to update its data.

editorUrlstring uri required

Deep link to edit the generated version in the Storydoc editor.

versionUrlstring uri required

Deep link to the version detail page in the Storydoc platform.

Example response

{
  "url": "https://www.storydoc.com/5d7d8922e00d9265/2e91b144-092f-456b-8f2e-0bae9f7f3355",
  "shortUrl": "https://view.storydoc.com/4GdDGt",
  "pageId": "672a1c50223b713000a41ca74",
  "versionId": "672a1f40a3a86b7a96d0d8ccc",
  "editorUrl": "https://app.storydoc.com/pages/editor/672a1c50223b713000a41ca74/672a1f40a3a86b7a96d0d8ccc",
  "versionUrl": "https://app.storydoc.com/pages/editor/672a1c50223b713000a41ca74/versions/672a1f40a3a86b7a96d0d8ccc"
}

Changes

No recorded changes to this operation across all 1 revision of this API.