---
title: "Create a new story version"
method: POST
path: "/v2/versions"
tags: ["versions"]
---

# Create a new story version

`POST /v2/versions`

## Request

- Base URL: `https://api.storydoc.com`
- URL: `https://api.storydoc.com/v2/versions`
- Auth: HTTP bearer

Creates a personalized version of an existing story template with custom data. Each version gets a unique URL and can be tracked independently.

## Request body

- CreateVersionRequest
  - `storyId` string, required: The ID of the story template. Extract this from your Storydoc editor URL: https://editor.storydoc.com/pages/editor/{storyId}
  - `senderEmail` string, email, required: Email of the sender (must exist in organization)
  - `daysToExpire` integer: Number of days until version expires. Omit for permanent/public version
  - `data` VersionData, required
    - `title` string, required: Title of the version (required)
    - `first_name` string
    - `last_name` string
    - `company` string
    - `email` string, email
    - `phone` string
    - `date` string: Date in any format
    - `products` object[]: Array of product objects
      - `name` string
      - `price` number
    - `gatedContent` GatedContent: Gated content configuration for access control
      - `gatedContent` boolean: Enable/disable content gating
      - `name` boolean: Show name field in the gate form
      - `nameRequired` boolean: Make name field required
      - `logo` boolean: Show logo on the gate form
      - `logoSRC` string, uri: URL of the logo to display on the gate form
      - `title` string: Custom message shown on the gate form
    - `_optionalContent` object: Show or hide content the author marked optional in the editor, by entity id: `false` hides it, `true` shows it, ids left out show. Only entities listed with `toggleable: true` in `optionalContent` are accepted (400 otherwise): the story's (GET /v2/stories/{storyId}?include=optionalContent) when creating, the version's own (GET /v2/versions/{versionId}?include=optionalContent) when updating. On POST /v2/versions/{versionId} only the ids sent change, the version's other choices are kept, and ids sent back with their current value are not checked. Hidden content is not shown to viewers but is still in the page's source, so do not rely on it to keep confidential content from a recipient.
    - `password` string: Password required to view the version
    - `ogImage` string, uri: Open Graph preview image URL for the version
    - `logo` LogoVariable: Logo configuration object
      - `domain` string, required: Domain to fetch logo from
      - `theme` 'dark' | 'light': Logo theme preference

## Response `200`

Version created successfully

- VersionResponse
  - `url` string, uri: Public URL for the version
  - `shortUrl` string, uri: Shortened URL for the version
  - `editorUrl` string, uri: URL to edit the version in Storydoc editor
  - `versionUrl` string, uri: URL to view version details in Storydoc platform
  - `versionId` string: Unique identifier for the version (only in create response)

## Other responses

- `400`: Invalid request parameters
- `403`: Authentication failed or token outdated, or the story uses variables above the account's plan (`code: VARIABLES_PLAN_REQUIRED`)
- `429`: Rate limit exceeded
- `500`: Internal server error

---

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