{ "openapi": "3.0.1", "info": { "title": "Storydoc API V2", "description": "# Overview\nThe Storydoc API V2 provides capabilities for automating Storydoc version creation and management. Create personalized versions of your Storydoc templates with custom data, password protection, and gated content.\n\n## Key Features\n- **Version Management**: Create and update personalized versions of your Storydoc templates\n- **Dynamic Variables**: Support for text, numbers, links, dates, arrays, and logo variables\n- **Access Control**: Password protection and gated content forms\n\n## Rate Limits\n**Version Endpoints**: 150 requests per minute per IP address\n\n**Rate Limit Headers**: Every response includes the following headers to help you monitor usage:\n- `x-rate-limit-counter`: Current number of requests made\n- `x-rate-limit-maximum`: Maximum allowed requests per minute\n\n**Rate Limit Exceeded**: When the limit is exceeded, you'll receive a 429 status code with the error message \"Too many requests\". Wait for the rate limit window to reset before making additional requests.", "contact": { "email": "support@storydoc.com" }, "version": "2.1.0" }, "tags": [ { "name": "versions", "description": "Manage story versions" }, { "name": "account", "description": "Account/Organization information" }, { "name": "stories", "description": "Manage and retrieve stories" }, { "name": "analytics", "description": "Query engagement analytics" } ], "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api.storydoc.com", "description": "Production API server" } ], "paths": { "/v2/versions": { "post": { "tags": ["versions"], "summary": "Create a new story version", "description": "Creates a personalized version of an existing story template with custom data. Each version gets a unique URL and can be tracked independently.", "operationId": "createStoryVersion", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVersionRequest" }, "examples": { "simple": { "summary": "1. Simple Version", "description": "Basic personalized version with just the required fields", "value": { "storyId": "61b1e50223b713000a41ca74", "senderEmail": "sender@company.com", "data": { "title": "Sales Presentation for ACME Corp", "company": "ACME Corporation", "first_name": "John", "last_name": "Doe" } } }, "withAutomatedLogo": { "summary": "2. Automated Logo Generation", "description": "Automatically fetch and apply company logos based on domain", "value": { "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" } } } }, "withExpiry": { "summary": "3. Time-Limited Version", "description": "Version that automatically expires after 30 days", "value": { "storyId": "61b1e50223b713000a41ca74", "senderEmail": "sender@company.com", "daysToExpire": 30, "data": { "title": "Sales Presentation for ACME Corp", "company": "ACME Corporation", "first_name": "John", "last_name": "Doe" } } }, "withPassword": { "summary": "4. Password Protected", "description": "Secure version requiring password access", "value": { "storyId": "61b1e50223b713000a41ca74", "senderEmail": "sender@company.com", "data": { "title": "Sales Presentation for ACME Corp", "company": "ACME Corporation", "first_name": "John", "last_name": "Doe", "password": "SecurePass123" } } }, "withGatedContent": { "summary": "5. Lead Capture Form", "description": "Collect visitor information before showing content", "value": { "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" } } } }, "withArrayOfObjects": { "summary": "6. Dynamic Data Lists", "description": "Version with product catalogs, pricing tables, or team rosters", "value": { "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"} ] } } }, "withPreviewImage": { "summary": "7. Set Thumbnail", "description": "Set a custom preview thumbnail image for the version", "value": { "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" } } }, "completeExample": { "summary": "8. Complete Example", "description": "Comprehensive example combining all features: expiration, password protection, gated content, arrays, and custom preview", "value": { "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" } } } } } } }, "responses": { "200": { "description": "Version created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" }, "examples": { "missingTitle": { "summary": "Missing data.title", "description": "The required title field is missing from the data object", "value": { "error": "Missing data.title in request body." } }, "senderNotFound": { "summary": "Sender email not found", "description": "The sender email is not registered in the organization", "value": { "error": "senderEmail email@domain.com not found in this organization" } }, "storyNotFound": { "summary": "Story not found", "description": "The specified story ID does not exist", "value": { "error": "Story 67c8451e37c1f5065165c08b3 not found." } }, "storyNotLive": { "summary": "Story not published", "description": "The story exists but has not been published yet", "value": { "error": "Story status is not Live, click Share to set it to Live, https://editor.storydoc.com/pages/editor/6776560c218435d60586da69" } } } } } }, "403": { "description": "Authentication failed or token outdated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "x-rate-limit-counter": { "description": "Current request count", "schema": { "type": "integer" } }, "x-rate-limit-maximum": { "description": "Maximum allowed requests", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v2/versions/{versionId}": { "post": { "tags": ["versions"], "summary": "Update an existing version", "description": "Updates the data in an existing version. Use the force parameter to override versions that have been manually edited.", "operationId": "updateStoryVersion", "parameters": [ { "name": "versionId", "in": "path", "required": true, "description": "The ID of the version to update", "schema": { "type": "string", "example": "61b1f40a3a86b7a96d0d8ccc" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVersionRequest" }, "example": { "senderEmail": "sender@company.com", "data": { "title": "Updated Sales Presentation", "company": "ACME Corporation", "first_name": "John", "last_name": "Doe" } } } } }, "responses": { "200": { "description": "Version updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionResponse" } } } }, "400": { "description": "Invalid request or version not editable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" }, "examples": { "missingTitle": { "summary": "Missing data.title", "description": "The required title field is missing from the data object", "value": { "error": "Missing data.title in request body." } }, "senderNotFound": { "summary": "Sender email not found", "description": "The sender email is not registered in the organization", "value": { "error": "senderEmail email@domain.com not found in this organization" } }, "versionNotEditable": { "summary": "Version not editable", "description": "The version has been manually edited and cannot be updated without force flag", "value": { "error": "The version has been edited. Use force=true to override the changes." } } } } } }, "403": { "description": "Authentication failed or token outdated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "404": { "description": "Version not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "x-rate-limit-counter": { "description": "Current request count", "schema": { "type": "integer" } }, "x-rate-limit-maximum": { "description": "Maximum allowed requests", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v2/account": { "get": { "tags": ["account"], "summary": "Get account details", "description": "Retrieves basic information about the authenticated account/organization", "operationId": "getAccount", "responses": { "200": { "description": "Account details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponse" }, "example": { "orgId": "60d5eca77a2d1a001c4d9f7e", "title": "ACME Corporation" } } } }, "403": { "description": "Authentication failed or missing token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "example": { "error": "Missing authorization token" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" }, "example": { "error": "Account not found." } } } }, "429": { "description": "Rate limit exceeded", "headers": { "x-rate-limit-counter": { "description": "Current request count", "schema": { "type": "integer" } }, "x-rate-limit-maximum": { "description": "Maximum allowed requests", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v2/stories/{storyId}": { "get": { "tags": ["stories"], "summary": "Get story details", "description": "Retrieves detailed information about a specific story including its settings and dynamic variables", "operationId": "getStory", "parameters": [ { "name": "storyId", "in": "path", "required": true, "description": "The ID of the story to retrieve", "schema": { "type": "string", "example": "61b1e50223b713000a41ca74" } } ], "responses": { "200": { "description": "Story details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoryResponse" }, "example": { "id": "61b1e50223b713000a41ca74", "status": "Live", "previewUrl": "https://view.storydoc.com/preview/abc123", "createdAt": "2024-01-15T10:30:00.000Z", "title": "Sales Presentation Template", "dynamicVariables": { "first_name": { "type": "input", "name": "first_name", "title": "Prospect's first name", "default": "", "tip": "Prospect's first name", "validation": { "required": true, "errorMessage": "Required" }, "mapping": "FirstName" }, "company": { "type": "input", "name": "company", "title": "Company name", "default": "", "tip": "Enter the company name", "validation": { "required": false }, "mapping": "CompanyName" } } } } } }, "400": { "description": "Missing or invalid storyId parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" }, "example": { "error": "Missing storyId" } } } }, "403": { "description": "Authentication failed or missing token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "example": { "error": "Access denied" } } } }, "404": { "description": "Story not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" }, "example": { "error": "Story not found" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "x-rate-limit-counter": { "description": "Current request count", "schema": { "type": "integer" } }, "x-rate-limit-maximum": { "description": "Maximum allowed requests", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v2/stories": { "get": { "tags": ["stories"], "summary": "List all stories", "description": "Retrieves a list of all stories in the organization with optional status filtering", "operationId": "getStories", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter stories by status", "schema": { "type": "string", "enum": ["Draft", "Live", "Archived"], "example": "Live" } } ], "responses": { "200": { "description": "Stories retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoryResponse" } }, "example": [ { "id": "61b1e50223b713000a41ca74", "status": "Live", "previewUrl": "https://view.storydoc.com/preview/abc123", "createdAt": "2024-01-15T10:30:00.000Z", "title": "Sales Presentation Template", "dynamicVariables": { "first_name": { "type": "input", "name": "first_name", "title": "Prospect's first name", "default": "", "tip": "Prospect's first name", "validation": { "required": true, "errorMessage": "Required" }, "mapping": "FirstName" }, "company": { "type": "input", "name": "company", "title": "Company name", "default": "", "tip": "Enter the company name", "validation": { "required": false }, "mapping": "CompanyName" } } }, { "id": "61b1e50223b713000a41ca75", "status": "Draft", "previewUrl": null, "createdAt": "2024-01-20T14:45:00.000Z", "title": "Product Demo Template", "dynamicVariables": { "product_name": { "type": "input", "name": "product_name", "title": "Product Name", "default": "", "tip": "Enter the product name", "validation": { "required": true, "errorMessage": "Product name is required" }, "mapping": "ProductName" }, "features": { "type": "array", "name": "features", "title": "Product Features", "default": [], "tip": "List of product features", "validation": { "required": false }, "mapping": "Features" } } } ] } } }, "403": { "description": "Authentication failed or missing token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "example": { "error": "Access denied" } } } }, "404": { "description": "No stories found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" }, "example": { "error": "Stories not found" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "x-rate-limit-counter": { "description": "Current request count", "schema": { "type": "integer" } }, "x-rate-limit-maximum": { "description": "Maximum allowed requests", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v2/stories/generate": { "post": { "tags": ["stories"], "summary": "Generate a new story from a prompt", "description": "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.\n\nThe 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).\n\n## Rate Limit\n150 requests per minute per organization. Every response includes `x-rate-limit-counter` and `x-rate-limit-maximum` headers.\n\n## Latency\nGeneration 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).", "operationId": "generateStory", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateStoryRequest" }, "examples": { "minimal": { "summary": "1. Minimal request", "description": "Only the required fields — the generator picks a default presentation type and skips the brand pipeline.", "value": { "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" } }, "withBrand": { "summary": "2. With brand context", "description": "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).", "value": { "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" } }, "withPresentationType": { "summary": "3. With a specific presentation type", "description": "`presentation type` selects an AI template tuned for that document class. Must be one of the supported classifications — see the enum on `GenerateStoryRequest`.", "value": { "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" } } } } } }, "responses": { "200": { "description": "Story generated and published successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateStoryResponse" }, "example": { "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" } } } }, "400": { "description": "Invalid request body or unsupported presentation type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" }, "examples": { "missingPrompt": { "summary": "Missing or empty prompt", "value": { "error": "Missing or empty \"prompt\" in request body" } }, "invalidSender": { "summary": "Missing or invalid senderEmail", "value": { "error": "Missing or invalid \"senderEmail\" in request body" } }, "senderNotInOrg": { "summary": "Sender email not in organization", "value": { "error": "senderEmail \"sender@company.com\" not found in this organization" } }, "invalidPresentationType": { "summary": "Unsupported presentation type", "description": "When the supplied `presentation type` is not in the allowed list, the response body includes the full list under `allowedPresentationTypes`.", "value": { "error": "Invalid \"presentation type\". Must be one of the supported classifications.", "allowedPresentationTypes": [ "Agency pitch deck", "Sales deck", "Quarterly Business Review", "..." ] } }, "invalidTokenOrgId": { "summary": "Token missing orgId", "value": { "error": "Invalid token: missing orgId" } } } } } }, "403": { "description": "Missing or invalid authorization token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "examples": { "missingToken": { "summary": "Missing token", "value": { "error": "Missing authorization token" } }, "invalidToken": { "summary": "Invalid or expired token", "value": { "error": "Access denied" } } } } } }, "404": { "description": "Account not found for the authenticated organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" }, "example": { "error": "Account not found" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "x-rate-limit-counter": { "description": "Current request count", "schema": { "type": "integer" } }, "x-rate-limit-maximum": { "description": "Maximum allowed requests per minute", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Generation pipeline failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" }, "example": { "error": "Failed to generate story", "errorId": "a1b2c3d4e5f60718" } } } } } } }, "/v2/analytics/events": { "get": { "tags": ["analytics"], "summary": "Query analytics events", "description": "Returns paginated raw engagement events (views and clicks) for the authenticated organization, filtered by date range and optional storyId / versionId / userEmail.\n\n## Plan\nThis endpoint is available on the **Team** plan only.\n\n## Date Range\nBoth `dateFrom` and `dateTo` are required ISO 8601 strings. The `dateTo` boundary is inclusive (events on the supplied day are returned). The maximum range is 92 days (3 months).\n\n## Pagination\nResults are paginated with a fixed page size of 1000. Pages are 1-indexed. Use the `pagination.hasMore` flag to determine whether to request the next page.\n\n## Filtering by user\nPass `userEmail` to restrict results to events on versions created by that user. The email is resolved to a user in the authenticated organization before querying.", "operationId": "getAnalyticsEvents", "parameters": [ { "name": "dateFrom", "in": "query", "required": true, "description": "Inclusive start of the date range (ISO 8601, UTC)", "schema": { "type": "string", "format": "date-time", "example": "2026-01-01T00:00:00Z" } }, { "name": "dateTo", "in": "query", "required": true, "description": "Inclusive end of the date range (ISO 8601, UTC). Must be at most 92 days after dateFrom.", "schema": { "type": "string", "format": "date-time", "example": "2026-03-31T23:59:59Z" } }, { "name": "storyId", "in": "query", "required": false, "description": "Restrict events to a single story", "schema": { "type": "string", "example": "61b1e50223b713000a41ca74" } }, { "name": "versionId", "in": "query", "required": false, "description": "Restrict events to a single version", "schema": { "type": "string", "example": "65a1e50223b713000a41ca99" } }, { "name": "userEmail", "in": "query", "required": false, "description": "Restrict events to versions created by the user with this email. Must match a user in the authenticated organization.", "schema": { "type": "string", "format": "email", "example": "sender@company.com" } }, { "name": "page", "in": "query", "required": false, "description": "1-indexed page number. Defaults to 1.", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 } } ], "responses": { "200": { "description": "Events retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsEventsResponse" } } } }, "400": { "description": "Invalid request (missing/invalid params, range > 3 months, invalid token, etc.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" }, "examples": { "missingDates": { "summary": "Missing required dates", "value": { "error": "dateFrom and dateTo are required (ISO 8601, e.g. 2026-01-01 or 2026-01-01T00:00:00Z)" } }, "rangeTooLarge": { "summary": "Date range exceeds 3 months", "value": { "error": "Date range cannot exceed 3 months" } }, "invalidEmail": { "summary": "Invalid userEmail", "value": { "error": "userEmail must be a valid email address" } }, "tokenRevoked": { "summary": "API token revoked", "value": { "error": "Token has been revoked" } } } } } }, "403": { "description": "Authentication failed, missing token, or account is not on the Team plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "examples": { "missingToken": { "summary": "Missing or invalid token", "value": { "error": "Access denied" } }, "notTeamPlan": { "summary": "Account is not on the Team plan", "value": { "error": "Analytics API is available on the Team plan only" } } } } } }, "404": { "description": "userEmail does not match any user in the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" }, "example": { "error": "userEmail sender@company.com not found in this organization" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "x-rate-limit-counter": { "description": "Current request count", "schema": { "type": "integer" } }, "x-rate-limit-maximum": { "description": "Maximum allowed requests per minute", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT Bearer token authentication in the Authorization header using the format: `Bearer `.\n\n**Note:** Applicable for Storydoc subscription plans that have API access.\n\n**Getting Your API Key:**\n1. Log into your Storydoc account\n2. Navigate to the [Integrations page](https://editor.storydoc.com/pages/profile/integrations?tab=automations)\n3. Go to the \"Automations\" tab\n4. Copy your API key from the displayed token\n\nIf you encounter authentication errors, you may need to regenerate your token from the integrations page." } }, "schemas": { "CreateVersionRequest": { "type": "object", "required": ["storyId", "senderEmail", "data"], "properties": { "storyId": { "type": "string", "description": "The ID of the story template. Extract this from your Storydoc editor URL: https://editor.storydoc.com/pages/editor/{storyId}", "example": "61b1e50223b713000a41ca74" }, "senderEmail": { "type": "string", "format": "email", "description": "Email of the sender (must exist in organization)", "example": "john.doe@company.com" }, "daysToExpire": { "type": "integer", "description": "Number of days until version expires. Omit for permanent/public version", "minimum": 1, "example": 30 }, "data": { "$ref": "#/components/schemas/VersionData" } } }, "UpdateVersionRequest": { "type": "object", "required": ["senderEmail", "data"], "properties": { "senderEmail": { "type": "string", "format": "email", "description": "Email of the sender (must exist in organization)", "example": "john.doe@company.com" }, "force": { "type": "boolean", "description": "Force update even if version has been manually edited", "default": false, "example": false }, "data": { "$ref": "#/components/schemas/VersionData" } } }, "VersionData": { "type": "object", "required": ["title"], "properties": { "title": { "type": "string", "description": "Title of the version (required)", "example": "Sales Proposal - ACME Corporation" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "company": { "type": "string", "example": "ACME Corporation" }, "email": { "type": "string", "format": "email", "example": "john.doe@acme.com" }, "phone": { "type": "string", "example": "+1-555-0123" }, "date": { "type": "string", "description": "Date in any format", "example": "January 15, 2025" }, "products": { "type": "array", "description": "Array of product objects", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Enterprise Suite" }, "price": { "type": "number", "example": 15000 } } } }, "gatedContent": { "$ref": "#/components/schemas/GatedContent" }, "password": { "type": "string", "description": "Password required to view the version", "example": "SecurePass123" }, "ogImage": { "type": "string", "format": "uri", "description": "Open Graph preview image URL for the version", "example": "https://www.storydoc.com/assets/images/branding/og-storydoc.gif" }, "logo": { "$ref": "#/components/schemas/LogoVariable", "description": "Logo configuration for automatic logo fetching", "example": { "theme": "dark", "domain": "microsoft.com" } } }, "additionalProperties": true, "example": { "title": "Sales Presentation", "company": "ACME Corp", "custom_field_1": "Any value", "custom_field_2": 12345, "logo": { "domain": "acme.com", "theme": "dark" }, "partner_logo": { "domain": "microsoft.com", "theme": "light" } } }, "GatedContent": { "type": "object", "description": "Gated content configuration for access control", "properties": { "gatedContent": { "type": "boolean", "description": "Enable/disable content gating", "example": true }, "name": { "type": "boolean", "description": "Show name field in the gate form", "example": true }, "nameRequired": { "type": "boolean", "description": "Make name field required", "example": true }, "logo": { "type": "boolean", "description": "Show logo on the gate form", "example": true }, "logoSRC": { "type": "string", "format": "uri", "description": "URL of the logo to display on the gate form", "example": "https://www.storydoc.com/assets/images/branding/og-storydoc.gif" }, "title": { "type": "string", "description": "Custom message shown on the gate form", "example": "Please fill in the information below to view your proposal." } } }, "LogoVariable": { "type": "object", "description": "Logo configuration object", "required": ["domain"], "properties": { "domain": { "type": "string", "description": "Domain to fetch logo from", "example": "acme.com" }, "theme": { "type": "string", "description": "Logo theme preference", "enum": ["dark", "light"], "default": "dark", "example": "dark" } } }, "VersionResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Public URL for the version", "example": "https://www.storydoc.com/5d7d8922e00d9265/2e91b144-092f-456b-8f2e-0bae9f7f3355" }, "shortUrl": { "type": "string", "format": "uri", "description": "Shortened URL for the version", "example": "https://view.storydoc.com/4GdDGt" }, "editorUrl": { "type": "string", "format": "uri", "description": "URL to edit the version in Storydoc editor", "example": "https://app.storydoc.com/pages/editor/61b1e50223b713000a41ca74/61b1f40a3a86b7a96d0d8ccc" }, "versionUrl": { "type": "string", "format": "uri", "description": "URL to view version details in Storydoc platform", "example": "https://app.storydoc.com/pages/editor/61b1e50223b713000a41ca74/versions/61b1f40a3a86b7a96d0d8ccc" }, "versionId": { "type": "string", "description": "Unique identifier for the version (only in create response)", "example": "61b1f40a3a86b7a96d0d8ccc" } } }, "AccountResponse": { "type": "object", "properties": { "orgId": { "type": "string", "description": "Unique identifier for the organization/account", "example": "60d5eca77a2d1a001c4d9f7e" }, "title": { "type": "string", "description": "Name of the organization/account", "example": "ACME Corporation" } }, "required": ["orgId", "title"] }, "StoryResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the story", "example": "61b1e50223b713000a41ca74" }, "status": { "type": "string", "description": "Current status of the story", "enum": ["Draft", "Live", "Archived"], "example": "Live" }, "previewUrl": { "type": "string", "format": "uri", "nullable": true, "description": "Preview URL for the story (null if not published)", "example": "https://view.storydoc.com/preview/abc123" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the story was created", "example": "2024-01-15T10:30:00.000Z" }, "title": { "type": "string", "description": "Title of the story", "example": "Sales Presentation Template" }, "dynamicVariables": { "type": "object", "description": "Dynamic variables configuration for the story", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of the variable", "example": "input" }, "name": { "type": "string", "description": "Variable name", "example": "first_name" }, "title": { "type": "string", "description": "Display title for the variable", "example": "Prospect's first name" }, "default": { "type": "string", "description": "Default value", "example": "" }, "tip": { "type": "string", "description": "Tooltip or help text", "example": "Prospect's first name" }, "validation": { "type": "object", "properties": { "required": { "type": "boolean", "example": true }, "errorMessage": { "type": "string", "example": "Required" } } }, "mapping": { "type": "string", "description": "Field mapping", "example": "FirstName" } } }, "example": { "first_name": { "type": "input", "name": "first_name", "title": "Prospect's first name", "default": "", "tip": "Prospect's first name", "validation": { "required": true, "errorMessage": "Required" }, "mapping": "FirstName" }, "company": { "type": "input", "name": "company", "title": "Company name", "default": "", "tip": "Enter the company name", "validation": { "required": false }, "mapping": "CompanyName" } } } }, "required": ["id", "status", "title"] }, "GenerateStoryRequest": { "type": "object", "required": ["prompt", "senderEmail"], "properties": { "prompt": { "type": "string", "description": "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.", "example": "A 6-slide sales deck pitching our analytics product to enterprise marketing teams. Highlight ROI, ease of integration, and customer success stories." }, "senderEmail": { "type": "string", "format": "email", "description": "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.", "example": "sender@company.com" }, "company": { "type": "string", "description": "Optional company name to use as the subject of the presentation. If omitted and `website` is provided, the name is inferred from Brandfetch.", "example": "ACME Corporation" }, "website": { "type": "string", "description": "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).", "example": "acme.com" }, "presentation type": { "type": "string", "description": "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`.", "default": "General presentation", "enum": [ "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", "Workshop proposal" ], "example": "Sales deck" } } }, "GenerateStoryResponse": { "type": "object", "required": ["url", "shortUrl", "pageId", "versionId", "editorUrl", "versionUrl"], "properties": { "url": { "type": "string", "format": "uri", "description": "Public live URL of the generated story.", "example": "https://www.storydoc.com/5d7d8922e00d9265/2e91b144-092f-456b-8f2e-0bae9f7f3355" }, "shortUrl": { "type": "string", "format": "uri", "description": "Shortened share URL for the live link.", "example": "https://view.storydoc.com/4GdDGt" }, "pageId": { "type": "string", "description": "ID of the underlying story (page). Use this as `storyId` in subsequent `POST /v2/versions` calls to create personalized variants of the generated story.", "example": "672a1c50223b713000a41ca74" }, "versionId": { "type": "string", "description": "ID of the generated live link. Use it as the path parameter for `POST /v2/versions/{versionId}` to update its data.", "example": "672a1f40a3a86b7a96d0d8ccc" }, "editorUrl": { "type": "string", "format": "uri", "description": "Deep link to edit the generated version in the Storydoc editor.", "example": "https://app.storydoc.com/pages/editor/672a1c50223b713000a41ca74/672a1f40a3a86b7a96d0d8ccc" }, "versionUrl": { "type": "string", "format": "uri", "description": "Deep link to the version detail page in the Storydoc platform.", "example": "https://app.storydoc.com/pages/editor/672a1c50223b713000a41ca74/versions/672a1f40a3a86b7a96d0d8ccc" } } }, "AnalyticsEventRow": { "type": "object", "properties": { "sessionId": { "type": "string", "nullable": true, "example": "1c2f0c2c-9b7e-4f4a-9f8e-3a3a3a3a3a3a" }, "eventId": { "type": "string", "nullable": true, "example": "evt_8a1c0a16d2b14e9c" }, "visitorId": { "type": "string", "nullable": true, "example": "vis_aa11bb22cc33dd44" }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-04-15T14:32:11.000Z" }, "storyId": { "type": "string", "example": "61b1e50223b713000a41ca74" }, "storyTitle": { "type": "string", "nullable": true, "example": "Sales Presentation Template" }, "versionId": { "type": "string", "example": "65a1e50223b713000a41ca99" }, "versionTitle": { "type": "string", "nullable": true, "example": "ACME Corp - Q2 Pitch" }, "versionCreatedAt": { "type": "string", "nullable": true, "format": "date-time", "example": "2026-04-10T09:15:00.000Z" }, "prospectName": { "type": "string", "nullable": true, "example": "Jane Cooper" }, "prospectEmail": { "type": "string", "nullable": true, "format": "email", "example": "jane.cooper@acme.com" }, "prospectPosition": { "type": "string", "nullable": true, "example": "VP Marketing" }, "eventName": { "type": "string", "nullable": true, "description": "Specific action (e.g. view_slide_3, click_cta)", "example": "view_slide_3" }, "eventCategory": { "type": "string", "nullable": true, "description": "Always 'view' or 'click'", "example": "view" }, "deviceType": { "type": "string", "nullable": true, "example": "desktop" }, "deviceTypeName": { "type": "string", "nullable": true, "example": "Mac" }, "eventUrl": { "type": "string", "nullable": true, "format": "uri", "example": "https://view.storydoc.com/abc123" }, "locationCity": { "type": "string", "nullable": true, "example": "New York" }, "locationLatitude": { "type": "number", "nullable": true, "format": "float", "example": 40.7128 }, "locationLongitude": { "type": "number", "nullable": true, "format": "float", "example": -74.0060 } }, "required": ["timestamp", "storyId", "versionId"] }, "AnalyticsEventsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsEventRow" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "pageSize": { "type": "integer", "example": 1000 }, "total": { "type": "integer", "example": 12453 }, "totalPages": { "type": "integer", "example": 13 }, "hasMore": { "type": "boolean", "example": true } }, "required": ["page", "pageSize", "total", "totalPages", "hasMore"] } }, "required": ["data", "pagination"], "example": { "data": [ { "sessionId": "1c2f0c2c-9b7e-4f4a-9f8e-3a3a3a3a3a3a", "eventId": "evt_8a1c0a16d2b14e9c", "visitorId": "vis_aa11bb22cc33dd44", "timestamp": "2026-04-15T14:32:11.000Z", "storyId": "61b1e50223b713000a41ca74", "storyTitle": "Sales Presentation Template", "versionId": "65a1e50223b713000a41ca99", "versionTitle": "ACME Corp - Q2 Pitch", "versionCreatedAt": "2026-04-10T09:15:00.000Z", "prospectName": "Jane Cooper", "prospectEmail": "jane.cooper@acme.com", "prospectPosition": "VP Marketing", "eventName": "view_slide_3", "eventCategory": "view", "deviceType": "desktop", "deviceTypeName": "Mac", "eventUrl": "https://view.storydoc.com/abc123", "locationCity": "New York", "locationLatitude": 40.7128, "locationLongitude": -74.0060 } ], "pagination": { "page": 1, "pageSize": 1000, "total": 12453, "totalPages": 13, "hasMore": true } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "errorId": { "type": "string", "description": "Unique error identifier for support" } }, "example": { "error": "Error message varies by status code" } }, "Error400": { "type": "object", "properties": { "error": { "type": "string", "example": "Missing data.title in request body." } } }, "Error403": { "type": "object", "properties": { "error": { "type": "string", "example": "Access denied" } } }, "Error404": { "type": "object", "properties": { "error": { "type": "string", "example": "Version not found" } } }, "Error429": { "type": "object", "properties": { "error": { "type": "string", "example": "Too many requests" } } }, "Error500": { "type": "object", "properties": { "error": { "type": "string", "example": "Error occured" }, "errorId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } } } } } }