POST /v2/stories/generate
Bearer auth

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

application/json

Body Required

  • 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 string

    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.

    Values are 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, or Workshop proposal. Default value is General presentation.

Responses

  • 200 application/json

    Story generated and published successfully

    Hide response attributes Show response attributes object
    • 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.
  • 400 application/json

    Invalid request body or unsupported presentation type

    Hide response attribute Show response attribute object
    • error string
  • 403 application/json

    Missing or invalid authorization token

    Hide response attribute Show response attribute object
    • error string
  • 404 application/json

    Account not found for the authenticated organization

    Hide response attribute Show response attribute object
    • error string
  • 429 application/json

    Rate limit exceeded

    Hide headers attributes Show headers attributes
    • x-rate-limit-counter integer

      Current request count

    • x-rate-limit-maximum integer

      Maximum allowed requests per minute

    Hide response attribute Show response attribute object
    • error string
  • 500 application/json

    Generation pipeline failed

    Hide response attributes Show response attributes object
    • error string
    • errorId string
POST /v2/stories/generate 
curl \
 --request POST 'https://api.storydoc.com/v2/stories/generate' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"prompt":"A sales deck pitching our analytics product to enterprise marketing teams. Highlight ROI, ease of integration, and customer success stories.","senderEmail":"sender@company.com"}'
Request examples
Only the required fields — the generator picks a default presentation type and skips the brand pipeline. 
{
  "prompt": "A sales deck pitching our analytics product to enterprise marketing teams. Highlight ROI, ease of integration, and customer success stories.",
  "senderEmail": "sender@company.com"
}
Supplying `company` and `website` lets the generator fetch brand colors, fonts, and logo via Brandfetch + website scrape and apply them to the story's design system. If the brand pipeline fails or returns unusable data, the story falls back to scaffold defaults (no error). 
{
  "prompt": "A pitch deck for our seed round: founding team, the problem, our unique solution, traction, and the ask.",
  "senderEmail": "sender@company.com",
  "company": "ACME Corporation",
  "website": "acme.com"
}
`presentation type` selects an AI template tuned for that document class. Must be one of the supported classifications — see the enum on `GenerateStoryRequest`. 
{
  "prompt": "Quarterly business review for our key enterprise account: revenue trends, product adoption, support metrics, and roadmap for next quarter.",
  "senderEmail": "sender@company.com",
  "company": "ACME Corporation",
  "website": "https://acme.com",
  "presentation type": "Quarterly Business Review"
}
Response examples (200) 
{
  "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"
}
Response examples (400) 
{
  "error": "Missing or empty \"prompt\" in request body"
}
{
  "error": "Missing or invalid \"senderEmail\" in request body"
}
{
  "error": "senderEmail \"sender@company.com\" not found in this organization"
}
When the supplied `presentation type` is not in the allowed list, the response body includes the full list under `allowedPresentationTypes`. 
{
  "error": "Invalid \"presentation type\". Must be one of the supported classifications.",
  "allowedPresentationTypes": [
    "Agency pitch deck",
    "Sales deck",
    "Quarterly Business Review",
    "..."
  ]
}
{
  "error": "Invalid token: missing orgId"
}
Response examples (403) 
{
  "error": "Missing authorization token"
}
{
  "error": "Access denied"
}
Response examples (404) 
{
  "error": "Account not found"
}
Response examples (429) 
# Headers
x-rate-limit-counter: 42
x-rate-limit-maximum: 42

# Payload
{
  "error": "Too many requests"
}
Response examples (500) 
{
  "error": "Failed to generate story",
  "errorId": "a1b2c3d4e5f60718"
}