# Generate a new story from a prompt

**POST /v2/stories/generate**

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


## Servers
- Production API server: https://api.storydoc.com (Production API server)


## Authentication methods
- Bearer auth


## Parameters



### Body: application/json (object)

- **prompt** (string)
  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))
  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`.


## Responses
### 200
Story generated and published successfully

#### Body: application/json (object)
- **url** (string(uri))
  Public live URL of the generated story.
- **shortUrl** (string(uri))
  Shortened share URL for the live link.
- **pageId** (string)
  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)
  ID of the generated live link. Use it as the path parameter for `POST /v2/versions/{versionId}` to update its data.
- **editorUrl** (string(uri))
  Deep link to edit the generated version in the Storydoc editor.
- **versionUrl** (string(uri))
  Deep link to the version detail page in the Storydoc platform.

### 400
Invalid request body or unsupported presentation type

#### Body: application/json (object)
- **error** (string)


### 403
Missing or invalid authorization token

#### Body: application/json (object)
- **error** (string)


### 404
Account not found for the authenticated organization

#### Body: application/json (object)
- **error** (string)


### 429
Rate limit exceeded
#### Headers
- **x-rate-limit-counter** (integer)
  Current request count
- **x-rate-limit-maximum** (integer)
  Maximum allowed requests per minute

#### Body: application/json (object)
- **error** (string)


### 500
Generation pipeline failed

#### Body: application/json (object)
- **error** (string)

- **errorId** (string)



[Powered by Bump.sh](https://bump.sh)