Create a new story version

POST /v2/versions
Bearer auth

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

application/json

Body Required

  • 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

    Minimum value is 1.

  • data object Required

    Additional properties are allowed.

    Hide data attributes Show data attributes object
    • 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 array[object]

      Array of product objects

      Hide products attributes Show products attributes object
      • name string
      • price number
    • gatedContent object

      Gated content configuration for access control

      Hide gatedContent attributes Show gatedContent attributes object
      • gatedContent boolean

        Enable/disable content gating

      • name boolean

        Show name field in the gate form

      • nameRequired boolean

        Make name field required

      • logoSRC string(uri)

        URL of the logo to display on the gate form

      • title string

        Custom message shown on the gate form

    • password string

      Password required to view the version

    • ogImage string(uri)

      Open Graph preview image URL for the version

Responses

  • 200 application/json

    Version created successfully

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

    Invalid request parameters

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

    Authentication failed or token outdated

    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

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

    Internal server error

    Hide response attributes Show response attributes object
    • error string
    • errorId string
POST /v2/versions 
curl \
 --request POST 'https://api.storydoc.com/v2/versions' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"data":{"title":"Sales Presentation for ACME Corp","company":"ACME Corporation","last_name":"Doe","first_name":"John"},"storyId":"61b1e50223b713000a41ca74","senderEmail":"sender@company.com"}'
Request examples
Basic personalized version with just the required fields 
{
  "data": {
    "title": "Sales Presentation for ACME Corp",
    "company": "ACME Corporation",
    "last_name": "Doe",
    "first_name": "John"
  },
  "storyId": "61b1e50223b713000a41ca74",
  "senderEmail": "sender@company.com"
}
Automatically fetch and apply company logos based on domain 
{
  "data": {
    "title": "Partnership Proposal",
    "company": "ACME Corporation",
    "last_name": "Doe",
    "first_name": "John",
    "partner_logo": {
      "theme": "dark",
      "domain": "microsoft.com"
    }
  },
  "storyId": "61b1e50223b713000a41ca74",
  "senderEmail": "sender@company.com"
}
Version that automatically expires after 30 days 
{
  "data": {
    "title": "Sales Presentation for ACME Corp",
    "company": "ACME Corporation",
    "last_name": "Doe",
    "first_name": "John"
  },
  "storyId": "61b1e50223b713000a41ca74",
  "senderEmail": "sender@company.com",
  "daysToExpire": 30
}
Secure version requiring password access 
{
  "data": {
    "title": "Sales Presentation for ACME Corp",
    "company": "ACME Corporation",
    "password": "SecurePass123",
    "last_name": "Doe",
    "first_name": "John"
  },
  "storyId": "61b1e50223b713000a41ca74",
  "senderEmail": "sender@company.com"
}
Collect visitor information before showing content 
{
  "data": {
    "offer": "Free 30-day trial included",
    "title": "Product Demo - Lead Generation",
    "company": "ACME Corporation",
    "gatedContent": {
      "logo": true,
      "name": true,
      "title": "Get instant access to our product demo",
      "logoSRC": "https://www.storydoc.com/assets/images/branding/og-storydoc.gif",
      "gatedContent": true,
      "nameRequired": true
    }
  },
  "storyId": "61b1e50223b713000a41ca74",
  "senderEmail": "sender@company.com"
}
Version with product catalogs, pricing tables, or team rosters 
{
  "data": {
    "title": "2025 Product Catalog",
    "company": "ACME Corporation",
    "products": [
      {
        "name": "Enterprise Suite",
        "price": 15000,
        "custom_field1": "24/7 Support"
      },
      {
        "name": "Professional Plan",
        "price": 3000,
        "custom_field1": "Business Hours Support"
      },
      {
        "name": "Starter Package",
        "price": 500,
        "custom_field1": "Email Support"
      }
    ],
    "launch_date": "January 2025",
    "team_contacts": [
      {
        "name": "Sarah Johnson",
        "role": "Sales Director",
        "email": "sarah@acme.com"
      },
      {
        "name": "Mike Chen",
        "role": "Product Manager",
        "email": "mike@acme.com"
      }
    ]
  },
  "storyId": "61b1e50223b713000a41ca74",
  "senderEmail": "sender@company.com"
}
Set a custom preview thumbnail image for the version 
{
  "data": {
    "title": "Visual Impact Report",
    "company": "ACME Corporation",
    "ogImage": "https://www.storydoc.com/assets/images/branding/og-storydoc.gif",
    "tagline": "Results that speak for themselves",
    "highlight": "300% ROI in 6 months"
  },
  "storyId": "61b1e50223b713000a41ca74",
  "senderEmail": "sender@company.com"
}
Comprehensive example combining all features: expiration, password protection, gated content, arrays, and custom preview 
{
  "data": {
    "date": "January 15, 2025",
    "email": "john.doe@acme.com",
    "logo1": {
      "theme": "dark",
      "domain": "acme.com"
    },
    "phone": "+1-555-0123",
    "title": "Enterprise Sales Proposal - Q1 2025",
    "company": "ACME Corporation",
    "ogImage": "https://www.storydoc.com/assets/images/branding/og-storydoc.gif",
    "password": "SecureProposal2025",
    "products": [
      {
        "name": "Enterprise Suite",
        "price": 15000,
        "discount": "20%",
        "features": "Unlimited users, 24/7 support"
      },
      {
        "name": "Professional Plan",
        "price": 3000,
        "discount": "10%",
        "features": "50 users, Business hours support"
      },
      {
        "name": "Starter Package",
        "price": 500,
        "discount": "5%",
        "features": "10 users, Email support"
      }
    ],
    "last_name": "Doe",
    "first_name": "John",
    "milestones": [
      {
        "phase": "Discovery",
        "timeline": "Week 1-2",
        "deliverable": "Requirements document"
      },
      {
        "phase": "Implementation",
        "timeline": "Week 3-6",
        "deliverable": "System deployment"
      },
      {
        "phase": "Training",
        "timeline": "Week 7-8",
        "deliverable": "User certification"
      }
    ],
    "gatedContent": {
      "logo": true,
      "name": true,
      "title": "Get instant access to your personalized enterprise proposal",
      "logoSRC": "https://www.storydoc.com/assets/images/branding/og-storydoc.gif",
      "gatedContent": true,
      "nameRequired": true
    },
    "team_contacts": [
      {
        "name": "Sarah Johnson",
        "role": "Sales Director",
        "email": "sarah@acme.com",
        "phone": "+1-555-0124"
      },
      {
        "name": "Mike Chen",
        "role": "Product Manager",
        "email": "mike@acme.com",
        "phone": "+1-555-0125"
      }
    ],
    "custom_field_1": "Premium Support Included",
    "custom_field_2": "ROI Calculator Available",
    "custom_field_3": "Free 30-day Trial"
  },
  "storyId": "61b1e50223b713000a41ca74",
  "senderEmail": "sender@company.com",
  "daysToExpire": 30
}
Response examples (200) 
{
  "url": "https://www.storydoc.com/5d7d8922e00d9265/2e91b144-092f-456b-8f2e-0bae9f7f3355",
  "shortUrl": "https://view.storydoc.com/4GdDGt",
  "editorUrl": "https://app.storydoc.com/pages/editor/61b1e50223b713000a41ca74/61b1f40a3a86b7a96d0d8ccc",
  "versionUrl": "https://app.storydoc.com/pages/editor/61b1e50223b713000a41ca74/versions/61b1f40a3a86b7a96d0d8ccc",
  "versionId": "61b1f40a3a86b7a96d0d8ccc"
}
Response examples (400)
The required title field is missing from the data object 
{
  "error": "Missing data.title in request body."
}
The sender email is not registered in the organization 
{
  "error": "senderEmail email@domain.com not found in this organization"
}
The specified story ID does not exist 
{
  "error": "Story 67c8451e37c1f5065165c08b3 not found."
}
The story exists but has not been published yet 
{
  "error": "Story status is not Live, click Share to set it to Live, https://editor.storydoc.com/pages/editor/6776560c218435d60586da69"
}
Response examples (403) 
{
  "error": "Access denied"
}
Response examples (429) 
# Headers
x-rate-limit-counter: 42
x-rate-limit-maximum: 42

# Payload
{
  "error": "Too many requests"
}
Response examples (500) 
{
  "error": "Error occured",
  "errorId": "550e8400-e29b-41d4-a716-446655440000"
}