Create a new story version

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://docs.storydoc.com/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json
{
  "Storydoc API MCP server": {
    "url": "https://docs.storydoc.com/mcp"
  }
}

Close
POST /v2/versions

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

    • _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.

      Hide _optionalContent attribute Show _optionalContent attribute object
      • * boolean Additional properties
    • 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, or the story uses variables above the account's plan (code: VARIABLES_PLAN_REQUIRED)

    Hide response attributes Show response attributes object
    • error string
    • code string

      VARIABLES_PLAN_REQUIRED when the story uses variables above the account's plan; absent for authentication failures.

    • requiredPlan string

      With VARIABLES_PLAN_REQUIRED: the lowest plan that covers every blocked variable.

      Values are pro or team.

    • variables array[object]

      With VARIABLES_PLAN_REQUIRED: the blocked variables and the plan each needs.

      Hide variables attributes Show variables attributes object
      • name string
      • requiredPlan 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 '{
  "storyId": "61b1e50223b713000a41ca74",
  "senderEmail": "sender@company.com",
  "data": {
    "title": "Sales Presentation for ACME Corp",
    "company": "ACME Corporation",
    "first_name": "John",
    "last_name": "Doe"
  }
}'
Request examples
Basic personalized version with just the required fields
{
  "storyId": "61b1e50223b713000a41ca74",
  "senderEmail": "sender@company.com",
  "data": {
    "title": "Sales Presentation for ACME Corp",
    "company": "ACME Corporation",
    "first_name": "John",
    "last_name": "Doe"
  }
}
Automatically fetch and apply company logos based on domain
{
  "storyId": "61b1e50223b713000a41ca74",
  "senderEmail": "sender@company.com",
  "data": {
    "title": "Partnership Proposal",
    "company": "ACME Corporation",
    "first_name": "John",
    "last_name": "Doe",
    "partner_logo": {
      "theme": "dark",
      "domain": "microsoft.com"
    }
  }
}
Version that automatically expires after 30 days
{
  "storyId": "61b1e50223b713000a41ca74",
  "senderEmail": "sender@company.com",
  "daysToExpire": 30,
  "data": {
    "title": "Sales Presentation for ACME Corp",
    "company": "ACME Corporation",
    "first_name": "John",
    "last_name": "Doe"
  }
}
Secure version requiring password access
{
  "storyId": "61b1e50223b713000a41ca74",
  "senderEmail": "sender@company.com",
  "data": {
    "title": "Sales Presentation for ACME Corp",
    "company": "ACME Corporation",
    "first_name": "John",
    "last_name": "Doe",
    "password": "SecurePass123"
  }
}
Collect visitor information before showing content
{
  "storyId": "61b1e50223b713000a41ca74",
  "senderEmail": "sender@company.com",
  "data": {
    "title": "Product Demo - Lead Generation",
    "company": "ACME Corporation",
    "offer": "Free 30-day trial included",
    "gatedContent": {
      "gatedContent": true,
      "name": true,
      "nameRequired": true,
      "logo": true,
      "logoSRC": "https://www.storydoc.com/assets/images/branding/og-storydoc.gif",
      "title": "Get instant access to our product demo"
    }
  }
}
Version with product catalogs, pricing tables, or team rosters
{
  "storyId": "61b1e50223b713000a41ca74",
  "senderEmail": "sender@company.com",
  "data": {
    "title": "2025 Product Catalog",
    "company": "ACME Corporation",
    "launch_date": "January 2025",
    "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"
      }
    ],
    "team_contacts": [
      {
        "name": "Sarah Johnson",
        "role": "Sales Director",
        "email": "sarah@acme.com"
      },
      {
        "name": "Mike Chen",
        "role": "Product Manager",
        "email": "mike@acme.com"
      }
    ]
  }
}
Set a custom preview thumbnail image for the version
{
  "storyId": "61b1e50223b713000a41ca74",
  "senderEmail": "sender@company.com",
  "data": {
    "title": "Visual Impact Report",
    "company": "ACME Corporation",
    "tagline": "Results that speak for themselves",
    "highlight": "300% ROI in 6 months",
    "ogImage": "https://www.storydoc.com/assets/images/branding/og-storydoc.gif"
  }
}
Comprehensive example combining all features: expiration, password protection, gated content, arrays, and custom preview
{
  "storyId": "61b1e50223b713000a41ca74",
  "senderEmail": "sender@company.com",
  "daysToExpire": 30,
  "data": {
    "title": "Enterprise Sales Proposal - Q1 2025",
    "company": "ACME Corporation",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@acme.com",
    "phone": "+1-555-0123",
    "date": "January 15, 2025",
    "password": "SecureProposal2025",
    "ogImage": "https://www.storydoc.com/assets/images/branding/og-storydoc.gif",
    "logo1": {
      "domain": "acme.com",
      "theme": "dark"
    },
    "products": [
      {
        "name": "Enterprise Suite",
        "price": 15000,
        "features": "Unlimited users, 24/7 support",
        "discount": "20%"
      },
      {
        "name": "Professional Plan",
        "price": 3000,
        "features": "50 users, Business hours support",
        "discount": "10%"
      },
      {
        "name": "Starter Package",
        "price": 500,
        "features": "10 users, Email support",
        "discount": "5%"
      }
    ],
    "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"
      }
    ],
    "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": {
      "gatedContent": true,
      "name": true,
      "nameRequired": true,
      "logo": true,
      "logoSRC": "https://www.storydoc.com/assets/images/branding/og-storydoc.gif",
      "title": "Get instant access to your personalized enterprise proposal"
    },
    "custom_field_1": "Premium Support Included",
    "custom_field_2": "ROI Calculator Available",
    "custom_field_3": "Free 30-day Trial"
  }
}
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",
  "code": "VARIABLES_PLAN_REQUIRED",
  "requiredPlan": "pro",
  "variables": [
    {
      "name": "deal_value",
      "requiredPlan": "pro"
    }
  ]
}
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"
}