openapi: 3.1.0
info:
  title: Shuffll API
  description: >
    The Shuffll API enables seamless automation and integration of Shuffll's
    AI-powered video creation platform into external workflows.


    **What is Shuffll?**


    Shuffll is an AI-powered platform designed to automate and streamline video
    content creation for businesses, marketers, and content creators. By
    leveraging machine learning, Shuffll enables users to generate high-quality
    videos efficiently, reducing production time and effort while maintaining
    creative control.


    With **Shuffll's API**, developers can integrate automated video generation
    into their applications, enabling seamless video content production at
    scale. Whether it's for marketing, social media, training, or corporate
    communications, Shuffll simplifies the process of creating engaging and
    professional videos.


    **Key Features**


    - **AI-Driven Video Creation** – Generate videos automatically based on
    structured input, scripts, or templates.

    - **Smart Editing & Automation** – Apply transitions, overlays, and effects
    without manual editing.

    - **Custom API Endpoints** – Programmatically generate, edit, and manage
    video content.

    - **Brand Consistency** – Ensure that videos align with predefined brand
    styles and messaging.

    - **Seamless Integrations** – Connect with third-party tools, media
    libraries, and content management systems.


    Shuffll's API empowers developers to automate video production, integrate
    AI-enhanced video workflows, and create personalized video content at
    scale—all with minimal effort.
  version: 1.2.0
  termsOfService: https://shuffll.com/terms-of-use/
  contact:
    email: info@shuffll.com
    url: https://shuffll.com
  license:
    name: MIT
    url: https://opensource.org/license/mit/
servers:
  - url: https://api.shuffll.com/api/v1
security:
  - ShuffllApiKey: []
tags:
  - name: Configuration
    description: >-
      Retrieve available options for AI voices, avatars, background music, and
      video category tags. Call these endpoints to populate field values when
      creating a project.
  - name: Organizations
    description: >-
      Manage organizations and retrieve their workspaces, branding, and
      settings.
  - name: Workspaces
    description: >-
      Manage workspaces within an organization, and list projects within a
      workspace.
  - name: Branding
    description: >-
      Read and update branding configuration (logo, colors, company info,
      pronunciations) for a workspace or organization.
  - name: Assets
    description: >-
      Upload, organize, rename, move, and delete media assets in a workspace.
      Assets can be referenced directly in project creation requests.
  - name: Templates
    description: >-
      Browse and retrieve reusable video templates. Templates define the scene
      structure and visual style of a project.
  - name: Projects
    description: Create, monitor, and manage AI-generated video projects.
  - name: Enhance
    description: >-
      Monitor the automatic post-production enhancement process (branding,
      subtitles, audio cleanup) that runs after a project is created.
  - name: Export
    description: Trigger video export and retrieve the final downloadable video URLs.
paths:
  /auth/config/storytelling_techniques:
    get:
      summary: Get storytelling techniques
      description: >
        Retrieve all available storytelling techniques for video creation.

        Returns an array of 12 storytelling techniques with descriptions,
        explanations of why they work, and examples.


        Use these techniques when creating projects to structure your video
        narrative effectively.
      operationId: getStorytellingTechniques
      tags:
        - Configuration
      responses:
        '200':
          description: Successfully retrieved storytelling techniques.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorytellingTechniquesResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/StorytellingTechniquesResponseExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/config/tone_of_voice:
    get:
      summary: Get tone of voice options
      description: |
        Retrieve all available tone of voice options for video narration.
        Returns an array of tone options with descriptions.

        Use the `id` value as `toneOfVoice` when creating a project.
      operationId: getToneOfVoice
      tags:
        - Configuration
      responses:
        '200':
          description: Successfully retrieved tone of voice options.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToneOfVoiceResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/ToneOfVoiceResponseExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/config/video_tags:
    get:
      summary: Get video category tags
      description: >
        Retrieve all available video category tags.


        Use the `id` value as `videoTagId` when creating a project to categorize
        your video (e.g., Marketing, Explainer, Training).
      operationId: getVideoTags
      tags:
        - Configuration
      responses:
        '200':
          description: Successfully retrieved video tags.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoTagsResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/VideoTagsResponseExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/config/ai_voice_options:
    get:
      summary: Get AI voice options
      description: >
        Retrieve all available AI voice-over options and tone styles.


        Returns two arrays:

        - `aiVoiceOptions` — the list of available voices. Use the `id` value as
        `aiVoiceSettings.voiceId` when creating a project.

        - `aiVoiceTones` — tone styles that can be layered on top of a voice
        (e.g., friendly, professional, dramatic).


        Voices are provided by either OpenAI or ElevenLabs depending on the
        `voiceType` field.
      operationId: getAiVoiceOptions
      tags:
        - Configuration
      responses:
        '200':
          description: Successfully retrieved AI voice options.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiVoiceOptionsResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/AiVoiceOptionsResponseExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/config/ai_avatar_options:
    get:
      summary: Get AI avatar options
      description: >
        Retrieve all available AI avatar presenter options.


        Each avatar has a name, accent, and a preview video URL. Use the `id`
        value when configuring an AI avatar presenter for your project.
      operationId: getAiAvatarOptions
      tags:
        - Configuration
      responses:
        '200':
          description: Successfully retrieved AI avatar options.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiAvatarOptionsResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/AiAvatarOptionsResponseExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/config/music-library:
    get:
      summary: Get background music library
      description: >
        Retrieve all available background music tracks.


        Use the `relativePath` value as `customTemplate.preConfigs.bgMusic.path`
        when creating a project to set the background music.
      operationId: getMusicLibrary
      tags:
        - Configuration
      responses:
        '200':
          description: Successfully retrieved music library.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MusicLibraryResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/MusicLibraryResponseExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/organization/list:
    get:
      summary: Get organization list
      description: |
        Retrieve array of all organizations the user has access to.

        Returns metadata for each organization including:
        - Organization ID and name
        - Workspaces within each organization
        - Branding configuration (colors, logos, company info)
        - Video prompts and ideas
        - User access status and user count
      operationId: getOrganizationList
      tags:
        - Organizations
      responses:
        '200':
          description: Successfully retrieved organization list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationsResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/GetOrganizationListResponseExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/organization/{organizationId}:
    get:
      summary: Get specific organization
      description: >
        Retrieve detailed information about a specific organization including:

        - Organization ID and name

        - All workspaces with detailed metrics (asset count, project count,
        template count)

        - Complete branding configuration

        - User information
      operationId: getOrganizationById
      tags:
        - Organizations
      parameters:
        - $ref: '#/components/parameters/OrganizationIdParam'
      responses:
        '200':
          description: Successfully retrieved organization details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationDetail'
              examples:
                default_example:
                  $ref: '#/components/examples/GetOrganizationByIdResponseExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /auth/organization/{organizationId}/workspace/{workspaceId}:
    get:
      summary: Get workspace
      description: |
        Retrieve detailed information about a specific workspace including:
        - Workspace ID and name
        - Metrics (asset count, project count, template count, user count)
        - Complete branding configuration
        - Video prompts and ideas
        - Creator information
      operationId: getWorkspaceById
      tags:
        - Workspaces
      parameters:
        - $ref: '#/components/parameters/OrganizationIdParam'
        - $ref: '#/components/parameters/WorkspaceIdParam'
      responses:
        '200':
          description: Successfully retrieved workspace details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceDetail'
              examples:
                default_example:
                  $ref: '#/components/examples/GetWorkspaceByIdResponseExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      summary: Update workspace
      description: >
        Update fields on a specific workspace.


        Currently supports updating the workspace `name`.

        To update workspace branding (logo, colors, company info), use `PUT
        /auth/branding/entity`.
      operationId: updateWorkspace
      tags:
        - Workspaces
      parameters:
        - $ref: '#/components/parameters/OrganizationIdParam'
        - $ref: '#/components/parameters/WorkspaceIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkspaceRequest'
            examples:
              default_example:
                $ref: '#/components/examples/UpdateWorkspaceRequestExample'
      responses:
        '200':
          description: Workspace updated successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /auth/workspace/{workspaceId}/projects:
    get:
      summary: List workspace projects
      description: >
        Retrieve all projects in a specific workspace.


        Returns a list of project summaries including each project's ID, name,
        current status, and creation date.

        Use this endpoint to enumerate existing projects before exporting or
        checking their status.
      operationId: listWorkspaceProjects
      tags:
        - Workspaces
      parameters:
        - $ref: '#/components/parameters/WorkspaceIdParam'
      responses:
        '200':
          description: Successfully retrieved project list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsListResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/ListProjectsResponseExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /auth/branding/entity:
    get:
      summary: Get branding
      description: >
        Retrieve the branding configuration for a workspace or organization.


        Pass either `workspaceId` or `organizationId` as a query parameter to
        specify which entity's branding to retrieve.
      operationId: getBranding
      tags:
        - Branding
      parameters:
        - name: workspaceId
          in: query
          description: ID of the workspace to retrieve branding for
          schema:
            type: string
            example: 693fb82afd8d1c43077ba0fe
        - name: organizationId
          in: query
          description: >-
            ID of the organization to retrieve branding for (used when no
            workspace is specified)
          schema:
            type: string
            example: 693fb82afd8d1c43077ba0fb
      responses:
        '200':
          description: Successfully retrieved branding.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserBranding'
              examples:
                default_example:
                  $ref: '#/components/examples/GetBrandingResponseExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      summary: Update branding property
      description: >
        Update a single branding property for a workspace or organization.


        This endpoint uses a property-name/value pattern — each call updates one
        property at a time.


        **Supported `propertyName` values:**


        | `propertyName` | Type | Description |

        |---|---|---|

        | `logo` | `string` (URL) | Primary logo URL |

        | `logoW` | `string` (URL) | White/light logo URL |

        | `colors` | `object` | Brand color palette |

        | `company` | `object` | Company metadata (name, domain, etc.) |

        | `about` | `string` | About text used in AI video scripts |

        | `pronunciations` | `array` | Custom pronunciation rules for AI
        voiceover |

        | `enabled` | `boolean` | Enable or disable branding |


        For `colors`, pass an object with `colorPrimary`, `colorSecondary`, and
        `colorExtra` hex values.


        See the examples below for common update patterns.
      operationId: updateBranding
      tags:
        - Branding
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBrandingRequest'
            examples:
              update_colors:
                $ref: '#/components/examples/UpdateBrandingColorsExample'
              update_logo:
                $ref: '#/components/examples/UpdateBrandingLogoExample'
              update_company:
                $ref: '#/components/examples/UpdateBrandingCompanyExample'
      responses:
        '200':
          description: Branding updated successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /auth/workspace/{workspaceId}/assets:
    get:
      summary: List assets
      description: >
        Retrieve all assets in a workspace.


        Use the `type` query parameter to filter by asset type (e.g., `image`,
        `video`, `audio`).

        Use the `folder` query parameter to list assets within a specific folder
        path.


        The `uploadPath` field on each asset is the CDN URL you can use directly
        in `videosToAdd[].url` when creating a project.
      operationId: listAssets
      tags:
        - Assets
      parameters:
        - $ref: '#/components/parameters/WorkspaceIdParam'
        - name: type
          in: query
          description: Filter assets by type prefix (e.g., `image`, `video`, `audio`)
          schema:
            type: string
            enum:
              - image
              - video
              - audio
              - pdf
            example: video
        - name: folder
          in: query
          description: Filter assets by folder path (e.g., `/my-folder`)
          schema:
            type: string
            example: /
      responses:
        '200':
          description: Successfully retrieved assets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetsListResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/AssetsListResponseExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      summary: Upload asset
      description: >
        Upload one or more files to a workspace as assets.


        Files are uploaded as `multipart/form-data`. Each uploaded file becomes
        an asset in the workspace.


        For video files, a DASH streaming version is automatically generated.


        The returned `uploadPath` on each asset is the CDN URL that can be used
        directly in `videosToAdd[].url` when creating a project.
      operationId: uploadAsset
      tags:
        - Assets
      parameters:
        - $ref: '#/components/parameters/WorkspaceIdParam'
        - name: folder
          in: query
          description: Target folder path for the uploaded file (defaults to `/`)
          schema:
            type: string
            example: /
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: >-
                    The file to upload. Supported types — images (JPEG, PNG,
                    GIF, WebP, SVG), videos (MP4, MOV, WebM), audio (MP3, WAV,
                    OGG), and PDFs.
      responses:
        '200':
          description: Files uploaded successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadAssetsResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/UploadAssetsResponseExample'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      summary: Delete assets
      description: |
        Delete one or more assets from a workspace by their IDs.

        This action is permanent and cannot be undone.
      operationId: deleteAssets
      tags:
        - Assets
      parameters:
        - $ref: '#/components/parameters/WorkspaceIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteAssetsRequest'
            examples:
              default_example:
                $ref: '#/components/examples/DeleteAssetsRequestExample'
      responses:
        '200':
          description: Assets deleted successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/workspace/{workspaceId}/assets/folder:
    post:
      summary: Create folder
      description: >
        Create a new folder in the workspace asset library.


        Folders are used to organize assets. The folder name must be unique
        within the workspace.
      operationId: createAssetFolder
      tags:
        - Assets
      parameters:
        - $ref: '#/components/parameters/WorkspaceIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFolderRequest'
            examples:
              default_example:
                $ref: '#/components/examples/CreateFolderRequestExample'
      responses:
        '200':
          description: Folder created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/workspace/{workspaceId}/assets/move:
    put:
      summary: Move assets
      description: >
        Move one or more assets to a different folder.


        The target folder must exist. Use `POST
        /auth/workspace/{workspaceId}/assets/folder` to create a folder first if
        needed.
      operationId: moveAssets
      tags:
        - Assets
      parameters:
        - $ref: '#/components/parameters/WorkspaceIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveAssetsRequest'
            examples:
              default_example:
                $ref: '#/components/examples/MoveAssetsRequestExample'
      responses:
        '200':
          description: Assets moved successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/workspace/{workspaceId}/assets/{assetId}/file:
    put:
      summary: Rename asset
      description: |
        Rename an existing asset by updating its display name.
      operationId: renameAsset
      tags:
        - Assets
      parameters:
        - $ref: '#/components/parameters/WorkspaceIdParam'
        - $ref: '#/components/parameters/AssetIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenameAssetRequest'
            examples:
              default_example:
                $ref: '#/components/examples/RenameAssetRequestExample'
      responses:
        '200':
          description: Asset renamed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /auth/templates:
    get:
      summary: Get all templates
      description: >
        Retrieve a list of all templates you have created in your account.


        Templates are reusable video project structures that define scene order,
        types, and configurations.
      operationId: getAllTemplates
      tags:
        - Templates
      responses:
        '200':
          description: Successfully retrieved templates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplatesResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/GetAllTemplatesResponseExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/organization/{organizationId}/workspace/{workspaceId}/templates:
    get:
      summary: Get templates by organization and workspace
      description: >
        Retrieve all templates for a specific organization and workspace.


        This endpoint allows you to get templates from a particular organization
        and workspace rather than the default ones.
      operationId: getTemplatesByOrgWorkspace
      tags:
        - Templates
      parameters:
        - $ref: '#/components/parameters/OrganizationIdParam'
        - $ref: '#/components/parameters/WorkspaceIdParam'
      responses:
        '200':
          description: Successfully retrieved templates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplatesResponse'
              examples:
                default_example:
                  $ref: >-
                    #/components/examples/GetTemplatesByOrgWorkspaceResponseExample
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /auth/templates/{templateId}:
    get:
      summary: Get specific template
      description: >
        Retrieve detailed information about a specific template including:

        - Template ID, name, and description

        - All scenes with their types and order

        - Dynamic fields for each scene (headers, colors, texts, voice settings,
        etc.)

        - Scene configuration options


        Use this endpoint to understand the template structure before creating a
        project from it.
      operationId: getTemplateById
      tags:
        - Templates
      parameters:
        - $ref: '#/components/parameters/TemplateIdParam'
      responses:
        '200':
          description: >
            Successfully retrieved template details.


            **Note:** For the project creation process, you can provide initial
            values for scenes using the dynamic values through the API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateDetail'
              examples:
                default_example:
                  $ref: '#/components/examples/GetTemplateByIdResponseExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /auth/project/create:
    post:
      summary: Create project
      description: >
        Create a new AI-powered video project from a prompt, URL, or script.


        ---


        ### Prompt Types


        | `promptType` | Description |

        |---|---|

        | `Prompt` | A free-text description of the video topic (default) |

        | `Link` | A public URL — Shuffll scrapes the content and uses it as the
        basis for the script |

        | `Docs` | A Google Docs URL — Shuffll reads the document content |

        | `Slides` | A Google Slides URL — Shuffll reads the slide content |

        | `Script` | A pre-written script — AI generation is skipped, the script
        is used as-is |


        ---


        ### Scene Media — Fallback System


        For each scene, Shuffll fills in media content using the following
        priority order.

        If a source doesn't yield results, it automatically tries the next one.


        1. **Your videos** (`customTemplate.scenes[].videosToAdd`) — Videos you
        explicitly provide are always used first.

        2. **Stock footage** — Shuffll searches stock video libraries for
        footage matching the scene content.

        3. **Workspace assets** — Shuffll looks in your workspace asset library
        for relevant clips.

        4. **Image → Video animation** — A still image is generated (via
        Stability AI) and animated into a short clip.

        5. **AI video generation** — A full video clip is generated from scratch
        based on the scene script.


        You can override this default order using `videoSourcesPipeline`. For
        example, to use only workspace assets and then generate from text, set:

        ```json

        "videoSourcesPipeline": ["workspace_assets", "generate_from_text"]

        ```


        The same fallback logic applies to still images in scene overlays,
        controlled by `imagesSourcePipeline`.


        ---


        ### Missing Images (`toGenerateMissingImages`)


        Scene templates can have image slots in their dynamic values. If you
        don't fill those slots:

        - `toGenerateMissingImages: true` → Shuffll generates a contextually
        relevant image using Stability AI.

        - `toGenerateMissingImages: false` → The slot is left empty (scene
        renders without the image).


        ---


        ### AI Presenter (Avatar)


        Set `aiAvatarSettings.avatarId` to use an AI avatar presenter in the
        video. Get available avatars from `GET /auth/config/ai_avatar_options`.


        ---


        ### Webhooks


        Set `webhook` to a URL that Shuffll will call when the export completes.
        The payload sent to your URL will be:


        ```json

        {
          "type": "export",
          "payload": {
            "projectId": "...",
            "projectName": "...",
            "urls": { "uploadPath": "...", "dashPath": "..." },
            "additionalParams": { }
          }
        }

        ```


        Use `additionalParams` to embed any custom data (IDs, metadata) you want
        returned in the webhook payload.


        Set `toAutoEnhance: true` and `toAutoExport: true` to fully automate the
        pipeline: create → enhance → export → webhook, with no polling required.


        ---


        ### After creating a project


        Project creation is asynchronous. Poll `GET
        /auth/project/{projectId}/create/status` until the project is ready.

        Enhancement runs automatically. Monitor progress with `GET
        /auth/project/{projectId}/edit/status/enhance`.

        When enhancement is complete, trigger export with `POST
        /auth/project/{projectId}/edit/export`.
      operationId: createProject
      tags:
        - Projects
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
            examples:
              basic_example:
                $ref: '#/components/examples/CreateProjectRequestExample'
      responses:
        '200':
          description: Project created successfully. Returns the project ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectCreateResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/CreateProjectResponseExample'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/project/{projectId}/create/status:
    get:
      summary: Get project creation status
      description: >
        Poll this endpoint after creating a project to track AI generation
        progress.


        Returns a `status` field with one of three values:


        | `status` | Meaning |

        |---|---|

        | `STRUCTURE` | The AI is building the storyline and script |

        | `GENERATING_IMAGES` | Scene visuals and media are being generated |

        | `DONE` | Project creation is complete — enhancement will begin
        automatically |


        Keep polling until `status` is `DONE`. After that, use `GET
        /auth/project/{projectId}/edit/status/enhance` to track enhancement
        progress.
      operationId: getProjectCreateStatus
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Status retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectCreateStatusResponse'
              examples:
                done:
                  $ref: '#/components/examples/GetProjectCreateStatusDoneExample'
                in_progress:
                  $ref: >-
                    #/components/examples/GetProjectCreateStatusInProgressExample
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /auth/project/{projectId}:
    get:
      summary: Get project
      description: >
        Retrieve the full details of a specific project, including its current
        status, name, and workspace.


        Use the `status` field to determine if the project is still being
        generated:

        - `STRUCTURE` — initial structure is being built

        - `GENERATING_IMAGES` — images and media are being generated

        - `EDITING` — enhancement is running automatically

        - `DONE` — project is ready
      operationId: getProjectById
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Successfully retrieved project details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectDetail'
              examples:
                default_example:
                  $ref: '#/components/examples/GetProjectResponseExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      summary: Delete project
      description: |
        Permanently delete a project and all associated data.

        This action cannot be undone.
      operationId: deleteProject
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Project deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /auth/project/{projectId}/edit/status/enhance:
    get:
      summary: Get project enhancement status
      description: >
        Check the progress of the automatic enhancement process for a project.


        Enhancement starts automatically after a project is created. Poll this
        endpoint to track progress.


        - A `202` response means enhancement is still in progress — continue
        polling.

        - A `200` response with `isDone: true` means enhancement is complete and
        the project is ready to export.
      operationId: getEnhanceStatus
      tags:
        - Enhance
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Enhancement complete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectStatusEnhanceStatusResponse'
              examples:
                default_example:
                  $ref: >-
                    #/components/examples/ProjectStatusEnhanceStatusResponseExample
        '202':
          description: Enhancement still in progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectStatusEnhanceStatusResponse'
              examples:
                default_example:
                  $ref: >-
                    #/components/examples/ProjectStatusEnhanceStatusStillInProccessResponseExample
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /auth/project/{projectId}/edit/export:
    post:
      summary: Export project
      description: >
        Trigger the export of a completed project to a video file.


        Returns a `projectId` and `editId` that can be used to poll the export
        status.


        **Prerequisites:** The project must have completed enhancement before
        exporting.

        Check enhancement status with `GET
        /auth/project/{projectId}/edit/status/enhance`.
      operationId: exportProject
      tags:
        - Export
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Export job started successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportTriggerResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/ExportTriggerResponseExample'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /auth/project/{projectId}/edit/status/export:
    get:
      summary: Get project export status
      description: >
        Check the progress of a project export job.


        - A `202` response means the export is still being processed — continue
        polling.

        - A `200` response with `isDone: true` means the export is complete. The
        `urls` object will contain the video file URLs.


        **URLs returned on completion:**

        - `uploadPath` — direct MP4 download URL

        - `dashPath` — MPEG-DASH streaming manifest URL
      operationId: getExportStatus
      tags:
        - Export
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Export complete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectExportStatusResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/ProjectExportDoneResponse'
        '202':
          description: Export still in progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectExportStatusResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/ProjectExportStillInProcessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    StorytellingTechniquesResponse:
      description: Array of available storytelling techniques for video creation
      type: object
      properties:
        techniques:
          type: array
          description: List of storytelling techniques
          items:
            $ref: '#/components/schemas/StorytellingTechnique'
    ToneOfVoiceResponse:
      description: Array of available tone of voice options for video narration
      type: object
      properties:
        tones:
          type: array
          description: List of tone options
          items:
            $ref: '#/components/schemas/ToneOfVoice'
    VideoTagsResponse:
      description: Available video category tags
      type: object
      properties:
        tags:
          type: array
          items:
            $ref: '#/components/schemas/VideoTag'
    VideoTag:
      description: A video category tag
      type: object
      properties:
        id:
          type: string
          description: Tag identifier — use as `videoTagId` when creating a project
          example: Marketing
        title:
          type: string
          description: Display title of the tag
          example: Marketing Video
        text:
          type: string
          description: Description of the video type
          example: Describe your marketing video
    AiVoiceOptionsResponse:
      description: Available AI voice options and tone styles
      type: object
      properties:
        aiVoiceOptions:
          type: array
          description: List of available voice-over options
          items:
            $ref: '#/components/schemas/AiVoiceOption'
        aiVoiceTones:
          type: array
          description: List of tone styles that can be applied to a voice
          items:
            $ref: '#/components/schemas/AiVoiceTone'
    AiVoiceOption:
      description: An available AI voice-over option
      type: object
      properties:
        id:
          type: string
          description: >-
            Voice identifier — use as `aiVoiceSettings.voiceId` when creating a
            project
          example: alloy
        name:
          type: string
          description: Internal voice name
          example: alloy
        title:
          type: string
          description: Display title of the voice
          example: Alloy
        subtitle:
          type: string
          description: Short description of the voice character
          example: Neutral and balanced
        voiceType:
          type: string
          description: Voice provider
          enum:
            - open-ai
            - eleven-labs
          example: open-ai
        tones:
          type: array
          description: Tone IDs supported by this voice
          items:
            type: string
          example:
            - friendly
            - professional
    AiVoiceTone:
      description: A tone style applied to an AI voice
      type: object
      properties:
        id:
          type: string
          description: Tone identifier
          example: friendly
        title:
          type: string
          description: Display name of the tone
          example: Friendly
        instructions:
          type: string
          description: Style instructions passed to the voice model
          example: Speak in a warm, approachable manner
    AiAvatarOptionsResponse:
      description: Available AI avatar presenter options
      type: object
      properties:
        aiAvatarOptions:
          type: array
          items:
            $ref: '#/components/schemas/AiAvatarOption'
    AiAvatarOption:
      description: An available AI avatar presenter
      type: object
      properties:
        id:
          type: string
          description: Avatar identifier
          example: avatar_sarah_001
        name:
          type: string
          description: Avatar name
          example: Sarah
        accent:
          type: string
          description: Avatar's voice accent
          example: American English
        title:
          type: string
          description: Display title
          example: Professional Presenter
        subtitle:
          type: string
          description: Short description
          example: Confident and clear
        videoPath:
          type: string
          description: URL of the avatar preview video
          example: https://content.shuffll.com/avatars/sarah_preview.mp4
        avatarType:
          type: string
          description: Avatar rendering type
          example: realistic
    MusicLibraryResponse:
      description: Available background music tracks
      type: array
      items:
        $ref: '#/components/schemas/BgMusicTrack'
    BgMusicTrack:
      description: A background music track
      type: object
      properties:
        id:
          type: string
          description: Track identifier
          example: track_upbeat_001
        name:
          type: string
          description: Track name
          example: Upbeat Corporate
        relativePath:
          type: string
          description: >-
            Path to use as `customTemplate.preConfigs.bgMusic.path` when
            creating a project
          example: /music/upbeat-corporate.mp3
        image:
          type: string
          description: Track artwork URL
          example: https://content.shuffll.com/music/upbeat-corporate-cover.jpg
    OrganizationsResponse:
      description: Array of available organizations
      type: array
      items:
        $ref: '#/components/schemas/OrganizationSummary'
    OrganizationSummary:
      description: Organization summary with metadata and branding
      type: object
      properties:
        id:
          type: string
          description: Unique organization identifier
          example: 693fb82afd8d1c43077ba0fb
        name:
          type: string
          description: Organization name
          example: My Organization
        workspaces:
          type: array
          description: List of workspaces in this organization
          items:
            type: object
            properties:
              id:
                type: string
                description: Workspace identifier
              createdAt:
                type: string
                format: date-time
                description: Workspace creation timestamp
              isDefaultForUser:
                type: boolean
                description: Whether this is the user's default workspace
        branding:
          $ref: '#/components/schemas/UserBranding'
        createdByEmail:
          type: string
          format: email
          description: Email of organization creator
        isAllowedToUseOrganization:
          type: boolean
          description: Whether user can use this organization
        userCount:
          type: integer
          description: Number of users in organization
        isDefaultForUser:
          type: boolean
          description: Whether this is the user's default organization
    OrganizationDetail:
      description: Detailed organization information with expanded workspace details
      type: object
      properties:
        id:
          type: string
          description: Unique organization identifier
          example: 693fb82afd8d1c43077ba0fb
        name:
          type: string
          description: Organization name
          example: My Organization
        workspaces:
          type: array
          description: List of workspaces with detailed metrics
          items:
            $ref: '#/components/schemas/WorkspaceDetail'
        branding:
          $ref: '#/components/schemas/UserBranding'
        createdByEmail:
          type: string
          format: email
          description: Email of organization creator
        userCount:
          type: integer
          description: Number of users in organization
    WorkspaceDetail:
      description: Detailed workspace information with metrics and branding
      type: object
      properties:
        id:
          type: string
          description: Workspace identifier
          example: 693fb82afd8d1c43077ba0fe
        name:
          type: string
          description: Workspace name
          example: My Workspace
        assetCount:
          type: integer
          description: Number of assets in workspace
        projectCount:
          type: integer
          description: Number of projects in workspace
        templateCount:
          type: integer
          description: Number of templates in workspace
        userCount:
          type: integer
          description: Number of users in workspace
        createdByEmail:
          type: string
          format: email
          description: Email of workspace creator
        branding:
          $ref: '#/components/schemas/UserBranding'
    UpdateWorkspaceRequest:
      description: Fields that can be updated on a workspace
      type: object
      properties:
        name:
          type: string
          description: New display name for the workspace
          example: Marketing Team Workspace
    UpdateBrandingRequest:
      description: >
        Update a single branding property for a workspace or organization.

        Provide either `workspace.id` or `organization.id` to identify the
        target entity.
      type: object
      required:
        - propertyName
        - propertyValue
      properties:
        workspace:
          type: object
          description: Target workspace. Required if updating workspace branding.
          properties:
            id:
              type: string
              description: Workspace identifier
              example: 693fb82afd8d1c43077ba0fe
        organization:
          type: object
          description: >-
            Target organization. Required if updating organization branding (and
            no workspace is specified).
          properties:
            id:
              type: string
              description: Organization identifier
              example: 693fb82afd8d1c43077ba0fb
        propertyName:
          type: string
          description: The branding property to update
          enum:
            - logo
            - logoW
            - colors
            - company
            - about
            - pronunciations
            - enabled
          example: colors
        propertyValue:
          description: >
            The new value for the property. Shape depends on `propertyName`:

            - `logo` / `logoW`: `string` (URL)

            - `colors`: `{ colorPrimary: string, colorSecondary: string,
            colorExtra: string }`

            - `company`: `{ name: string, domain: string, geoLocation?: string
            }`

            - `about`: `string`

            - `pronunciations`: `array` of pronunciation objects

            - `enabled`: `boolean`
          example:
            colorPrimary: '#1a1a2e'
            colorSecondary: '#16213e'
            colorExtra: '#0f3460'
        socketIdToExclude:
          type: string
          description: Optional socket ID to exclude from real-time update notifications
    Asset:
      description: A media asset stored in a workspace
      type: object
      properties:
        _id:
          type: string
          description: Unique asset identifier
          example: 6947b539cc95ea68854bb523
        displayName:
          type: string
          description: Display name of the asset
          example: product-demo.mp4
        uploadPath:
          type: string
          description: >
            CDN URL of the asset file. Use this value as `videosToAdd[].url`
            when creating a project.
          example: https://content.shuffll.com/workspace/product-demo.mp4
        dashPath:
          type: string
          description: >-
            MPEG-DASH streaming URL (available for video assets after
            processing)
          example: https://content.shuffll.com/workspace/product-demo.mpd
        mimetype:
          type: string
          description: MIME type of the file
          example: video/mp4
        type:
          type: string
          description: Asset category, automatically determined from MIME type
          enum:
            - image
            - video
            - audio
            - pdf
            - folder
          example: video
        folder:
          type: string
          description: Folder path the asset belongs to
          example: /
        userEmail:
          type: string
          format: email
          description: Email of the user who uploaded the asset
          example: user@example.com
        createdAt:
          type: string
          format: date-time
          description: Upload timestamp
          example: '2025-12-15T07:26:34.333Z'
        aspectRatio:
          type: string
          description: Aspect ratio of the asset (for images and videos)
          example: '16:9'
        analytics:
          type: object
          description: AI-generated analysis of the asset content
          properties:
            description:
              type: string
              description: AI-generated description of the asset
            videoPrompt:
              type: string
              description: Suggested video prompt based on asset content
            directions:
              type: string
              description: Suggested usage directions
            textHeaderPosition:
              type: number
              description: Suggested text overlay position
    AssetsListResponse:
      description: List of assets in a workspace
      type: array
      items:
        $ref: '#/components/schemas/Asset'
    UploadAssetsResponse:
      description: Result of a file upload
      type: object
      properties:
        uploaded:
          type: array
          description: Array of successfully uploaded assets
          items:
            $ref: '#/components/schemas/Asset'
    DeleteAssetsRequest:
      description: Asset IDs to delete
      type: object
      required:
        - assetIds
      properties:
        assetIds:
          oneOf:
            - type: string
              description: Single asset ID
            - type: array
              items:
                type: string
              description: Array of asset IDs
          example:
            - 6947b539cc95ea68854bb523
            - 6947b539cc95ea68854bb524
    CreateFolderRequest:
      description: Name for the new folder
      type: object
      required:
        - newName
      properties:
        newName:
          type: string
          description: Folder name (must be unique in the workspace)
          example: Campaign Assets
    MoveAssetsRequest:
      description: Move assets to a different folder
      type: object
      required:
        - toFolder
        - assetIds
      properties:
        toFolder:
          type: string
          description: Target folder path to move the assets into
          example: /Campaign Assets
        assetIds:
          oneOf:
            - type: string
              description: Single asset ID
            - type: array
              items:
                type: string
              description: Array of asset IDs
          example:
            - 6947b539cc95ea68854bb523
    RenameAssetRequest:
      description: New name for the asset
      type: object
      required:
        - newName
      properties:
        newName:
          type: string
          description: New display name for the asset
          example: final-product-demo.mp4
    TemplatesResponse:
      description: Array of available templates
      type: array
      items:
        $ref: '#/components/schemas/TemplateSummary'
    TemplateSummary:
      description: Template summary information
      type: object
      properties:
        id:
          type: string
          description: Unique template identifier
          example: 6945258969368fe55125c4b9
        description:
          type: string
          description: Template description
          example: A template for new product demo videos
        name:
          type: string
          description: Template name
          example: Product Demo Template
    TemplateDetail:
      description: Detailed template information with scenes and dynamic fields
      type: object
      properties:
        id:
          type: string
          description: Unique template identifier
          example: 6945258969368fe55125c4b9
        description:
          type: string
          description: Template description
          example: This is a sample template about how useful trees are
        name:
          type: string
          description: Template name
          example: Trees for Kids - Template
        scenes:
          type: array
          description: Array of scenes in the template
          items:
            $ref: '#/components/schemas/TemplateScene'
    TemplateScene:
      description: Individual scene within a template
      type: object
      properties:
        id:
          type: string
          description: Unique scene identifier
          example: a517722a-582b-4f8c-bb8f-c8e8014cf6cc
        type:
          type: string
          description: Type of scene
          example: headline_txt
        dynamicValues:
          type: array
          description: Array of dynamic values that can be customized for this scene
          items:
            type: object
            properties:
              type:
                type: string
                description: >-
                  Type of dynamic value (e.g., color_fill, header, image, logo,
                  etc.)
                example: color_fill
              position:
                type: integer
                description: Position index for the dynamic value
                example: 201
        name:
          type: string
          description: Scene name or title
          example: Amazing Tree Discovery
        availableStagePositions:
          type: array
          description: Available stage positions for this scene
          items:
            type: object
            properties:
              id:
                type: string
                description: Stage position identifier
                example: default
              position:
                type: integer
                description: Position value
                example: 100
              x:
                type: integer
                description: X coordinate
                example: 0
              'y':
                type: integer
                description: Y coordinate
                example: 0
              height:
                type: integer
                description: Height value
                example: 0
              width:
                type: integer
                description: Width value
                example: 0
    CreateProjectRequest:
      description: >
        Request payload for creating a new video project.


        Projects must always start from a prompt. You can optionally use a
        template and customize various aspects of the video generation.
      type: object
      properties:
        prompt:
          type: string
          description: The content/topic for your video
          example: Explore Riot Games' Innovative Player Experiences
        promptType:
          type: string
          description: |
            How Shuffll should interpret the `prompt` field.
            - `Prompt` — Free-text topic description (default)
            - `Link` — A public URL; Shuffll scrapes the page content
            - `Docs` — A Google Docs URL; Shuffll reads the document
            - `Slides` — A Google Slides URL; Shuffll reads the slides
            - `Script` — A fully written script; AI script generation is skipped
          enum:
            - Prompt
            - Link
            - Docs
            - Slides
            - Script
          example: Prompt
        language:
          type: string
          description: >
            Language for the video script and voiceover.

            Use `auto` to detect the language automatically from the prompt
            text.

            Defaults to `en` when omitted.
          enum:
            - auto
            - en
            - es
            - fr
            - zh
            - iw
          example: en
        videoLength:
          type: number
          description: |
            Target video duration in minutes.
            `0.5` → ~30 sec · `1` → ~1 min · `2` → ~2 min · `3` → ~3 min
          enum:
            - 0.5
            - 1
            - 2
            - 3
          example: 2
        storyTellingTechnique:
          type: string
          description: >-
            Storytelling structure for the script. Use the `technique` value
            from `GET /auth/config/storytelling_techniques`.
          example: The Before-and-After Transformation
        toneOfVoice:
          type: string
          description: >-
            Narration tone. Use the `id` value from `GET
            /auth/config/tone_of_voice`.
          enum:
            - Natural
            - Professional
            - Informative
            - Inspirational
            - Energetic
          example: Professional
        videoTagId:
          type: string
          description: >
            Video category. Guides the AI when writing the script and selecting
            media.

            Use the `id` value from `GET /auth/config/video_tags`. Defaults to
            `explainer` if omitted.
          example: Marketing
        webhook:
          type: string
          format: uri
          description: |
            URL to POST to when the project export completes.
            See the endpoint description for the full webhook payload format.
          example: https://your-app.com/hooks/shuffll-export
        additionalParams:
          type: object
          description: >-
            Arbitrary data to embed in the webhook payload (e.g., campaign ID,
            user ID).
          example:
            campaignId: camp_123
            userId: usr_456
        toAutoEnhance:
          type: boolean
          description: |
            Automatically start enhancement after project creation completes.
            Defaults to `true` for integration API requests.
          example: true
        toAutoExport:
          type: boolean
          description: >
            Automatically start export after enhancement completes.

            Combine with `webhook` to receive the result with no polling
            required.
          example: false
        aiVoiceSettings:
          type: object
          description: >-
            AI voiceover configuration. Get available voices from `GET
            /auth/config/ai_voice_options`.
          properties:
            voiceId:
              type: string
              description: >-
                Voice identifier. Use the `id` value from `GET
                /auth/config/ai_voice_options`.
              example: alloy
            voiceType:
              type: string
              description: Voice provider. Must match the `voiceType` of the chosen voice.
              enum:
                - open-ai
                - eleven-labs
              example: open-ai
            voiceSpeed:
              type: number
              description: Playback speed multiplier (0.7–1.2). `1.0` is normal speed.
              minimum: 0.7
              maximum: 1.2
              example: 1
            voiceInstructions:
              type: string
              description: >
                Custom style instructions for the voice model (OpenAI voices
                only).

                Overrides the global tone setting for fine-grained voice
                control.
              example: Speak slowly and clearly, with a warm and encouraging tone.
        aiAvatarSettings:
          type: object
          description: >
            AI avatar presenter configuration. When set, an AI avatar appears on
            screen as the video presenter.

            Get available avatars from `GET /auth/config/ai_avatar_options`.
          properties:
            avatarId:
              type: string
              description: >-
                Avatar identifier. Use the `id` value from `GET
                /auth/config/ai_avatar_options`.
              example: avatar_sarah_001
            aiVoiceId:
              type: string
              description: >-
                Override the avatar's default voice with a specific voice ID
                from `GET /auth/config/ai_voice_options`.
              example: alloy
        videoSourcesPipeline:
          type: array
          description: >
            Override the default order in which Shuffll sources media for each
            scene.

            Sources are tried in order; the first one that yields results is
            used.


            **Default order:** `["stock_footage", "workspace_assets",
            "generate_from_image", "generate_from_text"]`


            | Value | Description |

            |---|---|

            | `stock_footage` | Search stock video libraries |

            | `workspace_assets` | Use videos from your workspace asset library
            |

            | `generate_from_image` | Generate a still image (Stability AI) then
            animate it |

            | `generate_from_text` | Generate a full video clip from scratch
            using generative AI |
          items:
            type: string
            enum:
              - stock_footage
              - workspace_assets
              - generate_from_image
              - generate_from_text
          example:
            - workspace_assets
            - stock_footage
        imagesSourcePipeline:
          type: array
          description: >
            Override the default order for sourcing still images used in scene
            overlays and graphics.


            **Default order:** `["stock_footage", "generate_from_text",
            "workspace_assets"]`


            | Value | Description |

            |---|---|

            | `stock_footage` | Search stock image libraries |

            | `generate_from_text` | Generate an image using Stability AI |

            | `workspace_assets` | Use images from your workspace asset library
            |
          items:
            type: string
            enum:
              - stock_footage
              - generate_from_text
              - workspace_assets
          example:
            - workspace_assets
            - generate_from_text
        customTemplate:
          type: object
          description: Template and scene configuration.
          properties:
            id:
              type: string
              description: >-
                Template ID from `GET /auth/templates`. Omit to use the default
                template.
            description:
              type: string
              description: >
                Custom description used as the AI system prompt when generating
                video scripts.

                Overrides the template's stored description regardless of
                `toUseTemplateDescription`.

                Use this to provide brand context, tone guidelines, or audience
                information that shapes the entire script.
              example: >-
                Shuffll helps marketing teams create professional videos in
                minutes. Tone: confident, modern, B2B-focused.
            toUseTemplateDescription:
              type: boolean
              description: >
                When `true`, the template's stored description is used as the AI
                system prompt.

                Ignored if `description` is also provided (explicit description
                always wins).
              example: true
            flexibilityOverride:
              type: string
              description: >
                Controls how strictly the AI follows the template scene
                structure.

                - `rigid` — Scene order and types are fixed exactly as in the
                template

                - `minor` — Small adaptations allowed (e.g., skipping an empty
                scene)

                - `flexible` — AI can freely reorganize or adapt scenes to fit
                the content

                Overrides the flexibility setting stored on the template.
              enum:
                - rigid
                - minor
                - flexible
              example: flexible
            assets:
              type: array
              description: >
                Media assets (images or videos) to make available for the AI to
                distribute across scenes.


                Each asset in this list is:

                1. Validated as a reachable image or video URL

                2. Analyzed by AI to generate a description and usage context

                3. Downloaded and stored in your workspace under the **"Api
                Assets"** folder

                4. Made available for the AI to intelligently assign to the most
                relevant scenes


                This is the recommended way to bring your own branded media into
                a project without pre-assigning clips to specific scenes. For
                explicit scene-level placement, use `scenes[].videosToAdd`
                instead.
              items:
                type: object
                required:
                  - url
                properties:
                  url:
                    type: string
                    format: uri
                    description: Publicly accessible URL of the image or video asset.
                    example: https://example.com/product-launch.mp4
                  type:
                    type: string
                    description: >-
                      Asset media type. If omitted, Shuffll auto-detects from
                      the URL.
                    enum:
                      - image
                      - video
                    example: video
                  description:
                    type: string
                    description: >
                      Optional human-provided description of the asset. If
                      omitted, Shuffll generates one automatically using AI.

                      Providing a description improves the accuracy of scene
                      matching.
                    example: >-
                      A 30-second product demo showing the dashboard onboarding
                      flow.
                  direction:
                    type: string
                    description: >
                      Optional guidance on how the asset should be used (e.g.,
                      which scenes it fits, what mood it conveys).
                    example: Use in the opening scene to establish product credibility.
                  textHeaderPosition:
                    type: number
                    description: >-
                      Suggested vertical position for text overlays on this
                      asset (percentage from top).
                    example: 20
            videoSourcesByOrder:
              type: array
              description: >
                Override the video media fallback pipeline when using a
                template.

                Equivalent to the top-level `videoSourcesPipeline` field — use
                one or the other, not both.

                If omitted, the pipeline configured on the template is used.
              items:
                type: string
                enum:
                  - stock_footage
                  - workspace_assets
                  - generate_from_image
                  - generate_from_text
              example:
                - workspace_assets
                - stock_footage
            imageSourcesByOrder:
              type: array
              description: >
                Override the image media fallback pipeline when using a
                template.

                Equivalent to the top-level `imagesSourcePipeline` field — use
                one or the other, not both.
              items:
                type: string
                enum:
                  - stock_footage
                  - generate_from_text
                  - workspace_assets
              example:
                - workspace_assets
                - generate_from_text
            fontsSettings:
              type: object
              description: >
                Custom font configuration for the video. Overrides the
                template's default fonts.

                Both `primary` and `secondary` must include `family` and
                `weight` if provided.
              properties:
                primary:
                  type: object
                  description: Primary font used for main headings and titles.
                  properties:
                    family:
                      type: string
                      example: Arimo
                    weight:
                      type: string
                      example: '700'
                secondary:
                  type: object
                  description: Secondary font used for subheadings and body text.
                  properties:
                    family:
                      type: string
                      example: Arimo
                    weight:
                      type: string
                      example: '400'
                remaining:
                  type:
                    - object
                    - 'null'
                  description: >-
                    Font applied to all other text elements not covered by
                    primary or secondary.
                  properties:
                    family:
                      type: string
                    weight:
                      type: string
            toUseTemplateFont:
              type: boolean
              description: |
                When `true`, use the font settings stored on the template.
                Ignored if `fontsSettings` is explicitly provided.
              example: true
            preConfigs:
              type: object
              description: Global settings applied across all scenes.
              properties:
                bgMusic:
                  type: object
                  description: Background music settings.
                  properties:
                    volume:
                      type: number
                      description: >-
                        Music volume relative to voiceover (0–1). `0.3` is a
                        common value for subtle background music.
                      minimum: 0
                      maximum: 1
                      example: 0.3
                    path:
                      type: string
                      description: >-
                        Track path from `GET /auth/config/music-library` (use
                        the `relativePath` field).
                      example: /music/upbeat-corporate.mp3
                toCleanAudio:
                  type: boolean
                  description: >
                    Automatically remove background noise from audio in
                    user-uploaded videos.

                    Recommended when your `videosToAdd` clips contain ambient
                    noise.
                  example: false
                aiGenerationStability:
                  type: number
                  description: >
                    Creativity vs. accuracy tradeoff for AI image generation
                    (0–1).

                    Lower = more creative/varied; higher = closer to the prompt.
                  minimum: 0
                  maximum: 1
                  example: 0.5
                subtitles:
                  type: object
                  description: Subtitle appearance settings.
                  properties:
                    percentOffset:
                      type: number
                      description: >-
                        Vertical position from the bottom as a percentage
                        (1–100).
                      minimum: 1
                      maximum: 100
                    textSize:
                      type: number
                      description: Font size in points (8–48).
                      minimum: 8
                      maximum: 48
                    strategy:
                      type: string
                      description: |
                        How text is revealed as it is spoken.
                        - `FULL_UTTERANCE` — Full sentence appears at once
                        - `WORD_BY_WORD` — One word at a time
                        - `KARAOKE` — Words highlight progressively
                        - `WORD_HIGHLIGHT` — Active word is highlighted
                      enum:
                        - FULL_UTTERANCE
                        - WORD_BY_WORD
                        - KARAOKE
                        - WORD_HIGHLIGHT
                    fontName:
                      type: string
                      description: Subtitle font name.
                    isBold:
                      type: boolean
                      description: Bold subtitle text.
                    primaryColour:
                      type: string
                      description: Primary text color (hex).
                      example: '#FFFFFF'
                    secondaryColour:
                      type: string
                      description: Shadow/secondary text color (hex).
                      example: '#000000'
                    outlineColour:
                      type: string
                      description: Text outline color (hex).
                      example: '#000000'
                    styles:
                      type: object
                      description: >
                        Fine-grained style overrides for normal and highlighted
                        subtitle states.

                        Used with `KARAOKE` and `WORD_HIGHLIGHT` strategies to
                        style the active word differently.
                      properties:
                        normal:
                          type: object
                          description: Style for words that are not currently being spoken.
                          properties:
                            color:
                              type: string
                              description: Text color (hex).
                              example: '#FFFFFF'
                            fontSize:
                              type: number
                              description: Font size override for normal words.
                        highlight:
                          type: object
                          description: Style for the word currently being spoken.
                          properties:
                            color:
                              type: string
                              description: Highlight text color (hex).
                              example: '#FFD700'
                            fontSize:
                              type: number
                              description: Font size override for the highlighted word.
            scenes:
              type: array
              description: >
                Per-scene overrides. Only include scenes you want to customize.

                Scenes not listed here are auto-generated using the template and
                your workspace branding.
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: >-
                      Scene ID from the template. Get scene IDs from `GET
                      /auth/templates/{templateId}`.
                  staticScript:
                    type: string
                    description: >
                      Force a fixed voiceover script for this scene, bypassing
                      AI generation.

                      To render the scene with no voiceover at all, provide a
                      single space `" "`.
                  moreDetailsAboutScene:
                    type: string
                    description: >
                      Extra guidance for the AI when writing this scene's
                      script.

                      Example: `"Open with a bold statistic about player
                      retention."`
                  toGenerateMissingImages:
                    type: boolean
                    description: >
                      When `true`, any image slots in this scene's template
                      layout that are not provided in `dynamicValues` will be
                      auto-generated using Stability AI.

                      When `false` (default), unfilled image slots are left
                      empty.
                    example: true
                  toUseSubtitles:
                    type: boolean
                    description: >-
                      Enable or disable subtitles for this scene. Overrides the
                      global subtitle setting.
                  toMakeVOAsMasterInDefault:
                    type: boolean
                    description: >-
                      Make the AI voiceover the master audio track, taking
                      priority over any video audio.
                  wordBoost:
                    type: array
                    items:
                      type: string
                    description: >
                      Words to boost in speech recognition transcription for
                      this scene.

                      Use this for product names, brand names, or uncommon terms
                      that the transcription model might mis-hear.
                    example:
                      - Shuffll
                      - MPEG-DASH
                      - Riot Games
                  customSpelling:
                    type: array
                    description: >
                      Custom spelling corrections for the subtitle transcript of
                      this scene.

                      Each entry maps a list of heard variations (`from`) to the
                      correct spelling (`to`).

                      Useful when the AI voiceover or transcription produces a
                      slightly wrong spelling of a proper noun.
                    items:
                      type: object
                      required:
                        - from
                        - to
                      properties:
                        from:
                          type: array
                          items:
                            type: string
                          description: Incorrect or alternative spellings to replace.
                          example:
                            - Shuffel
                            - Shufflle
                        to:
                          type: string
                          description: The correct spelling.
                          example: Shuffll
                  staticText:
                    type: array
                    items:
                      type: string
                    description: >
                      Fixed text values to display in this scene's text
                      elements, used when `toUseStaticText` is `true`.

                      Provided in order — each string maps to a text element in
                      the scene layout.
                    example:
                      - Your headline here
                      - Supporting detail line
                  toUseStaticText:
                    type: boolean
                    description: >
                      When `true`, use the strings in `staticText` as the
                      scene's on-screen text instead of AI-generated content.
                  punctuationsToRemove:
                    type: array
                    items:
                      type: string
                    description: >-
                      Punctuation marks to strip from the subtitle text for this
                      scene.
                    example:
                      - ','
                      - .
                      - '!'
                  dynamicValues:
                    type: array
                    description: >
                      Override specific visual elements in the scene (text,
                      colors, images, logos).

                      Get the available element types and positions from `GET
                      /auth/templates/{templateId}`.


                      Common `type` values: `header`, `topic`, `cta`, `website`,
                      `logo`, `image`, `color_fill`, `company`, `tagline`.
                    items:
                      type: object
                      properties:
                        position:
                          type: number
                          description: >-
                            Element position index (from the template
                            definition).
                        type:
                          type: string
                          description: >-
                            Element type (e.g., `header`, `logo`, `image`,
                            `color_fill`).
                        value:
                          type: string
                          description: The value to set for this element.
                    example:
                      - position: 0
                        type: header
                        value: Innovating Player Experience
                      - position: 0
                        type: logo
                        value: https://example.com/logo.png
                      - position: 0
                        type: website
                        value: https://riotgames.com
                  videosToAdd:
                    type: array
                    description: >
                      Videos to place in this scene. These bypass the media
                      fallback pipeline entirely — provided videos are always
                      used first.


                      Use `uploadPath` from `GET
                      /auth/workspace/{workspaceId}/assets` to reference a
                      workspace asset, or provide any publicly accessible URL.


                      Use `stagePositionNumber` to target a specific layout slot
                      within the scene. Available positions come from
                      `availableStagePositions` in `GET
                      /auth/templates/{templateId}`.
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                          format: uri
                          description: >
                            Public video URL. Use `uploadPath` from `GET
                            /auth/workspace/{workspaceId}/assets` to reference a
                            workspace asset.
                          example: >-
                            https://content.shuffll.com/workspace/product-demo.mp4
                        stagePositionNumber:
                          type:
                            - number
                            - 'null'
                          description: >
                            Layout slot to place this video in. Corresponds to
                            the `position` value from `availableStagePositions`
                            in the template.

                            Pass `null` to use the default (highest available)
                            position.
                          example: 100
                        isMaster:
                          type: boolean
                          description: >
                            Marks this as the primary video layer for the scene.

                            The master video drives timing and is synced with
                            voiceover and subtitles.

                            Only one video per scene can be master. If none is
                            marked, the longest video is chosen automatically.
                        isMuted:
                          type: boolean
                          description: >-
                            Mute this video's audio (voiceover will still play
                            over it).
                        toFlip:
                          type: boolean
                          description: Mirror the video horizontally.
                        toAutoTrim:
                          type:
                            - boolean
                            - 'null'
                          description: >-
                            Automatically trim the video to match the scene
                            duration.
                        toUseSubtitles:
                          type: boolean
                          description: >-
                            Use this video's own subtitles/audio instead of the
                            AI voiceover for this scene.
                        toGenerateSubtitles:
                          type: boolean
                          description: >
                            Generate subtitles by transcribing this video's
                            audio track.

                            Different from `toUseSubtitles` — this transcribes
                            the video's own speech rather than using the AI
                            voiceover.
            toReturnAnErrorIfMissingScene:
              type: boolean
              description: >
                When `true`, returns a `400` error if a scene ID in `scenes[]`
                does not exist in the template.

                When `false` (default), unrecognized scenes are silently
                skipped.
      required:
        - prompt
    ProjectCreateResponse:
      description: Response returned when a project is successfully created.
      type: object
      properties:
        projectId:
          type: string
          description: Unique identifier for the created project
          example: 6947b539cc95ea68854bb523
    ProjectCreateStatusResponse:
      description: Response from the project creation status endpoint.
      type: object
      properties:
        status:
          type: string
          description: Current creation stage of the project
          enum:
            - STRUCTURE
            - GENERATING_IMAGES
            - DONE
          example: DONE
    ProjectDetail:
      description: Detailed information about a project
      type: object
      properties:
        id:
          type: string
          description: Unique project identifier
          example: 6947b539cc95ea68854bb523
        name:
          type: string
          description: Project name
          example: Breaking the Agency Mold
        status:
          type: string
          description: Current project status
          enum:
            - STRUCTURE
            - GENERATING_IMAGES
            - EDITING
            - DONE
          example: DONE
        createdAt:
          type: string
          format: date-time
          description: Project creation timestamp
          example: '2025-12-15T07:26:34.333Z'
        workspaceId:
          type: string
          description: ID of the workspace this project belongs to
          example: 693fb82afd8d1c43077ba0fe
    ProjectSummary:
      description: Brief project summary for list views
      type: object
      properties:
        id:
          type: string
          description: Unique project identifier
          example: 6947b539cc95ea68854bb523
        name:
          type: string
          description: Project name
          example: Breaking the Agency Mold
        status:
          type: string
          description: Current project status
          enum:
            - STRUCTURE
            - GENERATING_IMAGES
            - EDITING
            - DONE
          example: DONE
        createdAt:
          type: string
          format: date-time
          description: Project creation timestamp
          example: '2025-12-15T07:26:34.333Z'
    ProjectsListResponse:
      description: List of projects in a workspace
      type: array
      items:
        $ref: '#/components/schemas/ProjectSummary'
    ProjectStatusEnhanceStatusResponse:
      description: Enhancement progress status
      type: object
      properties:
        percentages:
          $ref: '#/components/schemas/Percentages'
        isDone:
          $ref: '#/components/schemas/isDone'
    ExportTriggerResponse:
      description: Response returned when an export job is initiated
      type: object
      properties:
        projectId:
          type: string
          description: Unique identifier of the project being exported
          example: 3be6453c-03eb-4357-ae5a-984a0e574a54
        editId:
          type: string
          description: Unique identifier of the edit created for this export job
          example: 2f14374a-9c65-4ee5-94b7-fba66d893483
    ProjectExportStatusResponse:
      description: Export progress status and download URLs
      type: object
      properties:
        isDone:
          $ref: '#/components/schemas/isDone'
        urls:
          $ref: '#/components/schemas/Urls'
    ToneOfVoice:
      description: Individual tone of voice option
      type: object
      properties:
        id:
          type: string
          description: Tone identifier
          example: Natural
        description:
          type: string
          description: Description of the tone
          example: Clear and simple to understand.
    StorytellingTechnique:
      description: Individual storytelling technique with details
      type: object
      properties:
        technique:
          type: string
          description: Name of the storytelling technique
          example: The Relatable Problem
        description:
          type: string
          description: Detailed description of the technique
          example: Start by describing a problem that your audience can relate to.
        whyItWorks:
          type: string
          description: Explanation of why this technique is effective
          example: It immediately captures attention by addressing a pain point.
        example:
          type: string
          description: Example usage of the technique
          example: >-
            Ever feel like you're wasting hours on [insert task] and getting
            nowhere? That's exactly where I was a year ago.
    UserBranding:
      description: User's branding configuration for video creation
      type: object
      properties:
        company:
          type: object
          description: Company information
          properties:
            id:
              type: string
              description: Company identifier
              example: shuffll
            domain:
              type: string
              description: Company domain
              example: ''
            geoLocation:
              type:
                - string
                - 'null'
              description: Geographic location of company
            minSize:
              type:
                - integer
                - 'null'
              description: Minimum company size
            maxSize:
              type:
                - integer
                - 'null'
              description: Maximum company size
            name:
              type: string
              description: Company name
              example: ''
        isDefault:
          type: boolean
          description: Whether using default branding settings
          example: true
        enabled:
          type: boolean
          description: Whether branding is enabled
          example: true
        logo:
          type: string
          description: Path to company logo
          example: /files/platform/onboarding/logo-placeholder.svg
        logoW:
          type: string
          description: Path to white version of logo
          example: /files/platform/onboarding/logo-placeholder.svg
        colors:
          type: object
          description: Brand color palette
          properties:
            colorPrimary:
              type: string
              description: Primary brand color (hex)
              example: '#99b898'
            colorSecondary:
              type: string
              description: Secondary brand color (hex)
              example: '#feceab'
            colorExtra:
              type: string
              description: Extra/accent brand color (hex)
              example: '#ff847c'
            _id:
              type: string
              description: Internal color palette identifier
        prompts:
          type: array
          description: User's saved prompts with tags and suggestions
          items:
            type: object
            properties:
              tag:
                type: object
                properties:
                  title:
                    type: string
                    description: Prompt category title
                    example: Thought Leadership Video
                  id:
                    type: string
                    description: Prompt category ID
                    example: Thought leadership
                  text:
                    type: string
                    description: Prompt description text
                    example: Describe your Thought leadership video
              suggestions:
                type: array
                description: Suggested prompts for this category
                items:
                  type: string
                  example: Exploring Unconventional Solutions for Team Innovation
        about:
          type: string
          description: Company description used by AI when writing video scripts
          example: Acme Corp builds innovative solutions for enterprise teams.
        videoIdeas:
          type: array
          description: AI-generated video idea suggestions for the workspace
          items:
            type: object
            properties:
              shortTitle:
                type: string
              prompt:
                type: string
              designId:
                type: string
              designGroupId:
                type: string
              createdAt:
                type: string
                format: date-time
        videoIdeaStatus:
          type: string
          description: Status of the video idea generation
          example: COMPLETED
        pronunciations:
          type: array
          description: >-
            Custom pronunciation settings for brand, people, and product names
            in AI voiceovers
          items:
            type: object
    Percentages:
      description: Completion percentage
      type: number
      example: 100
    isDone:
      description: Whether the operation is complete
      type: boolean
      example: true
    Urls:
      description: Video output URLs
      type: object
      properties:
        uploadPath:
          $ref: '#/components/schemas/UploadPath'
        dashPath:
          $ref: '#/components/schemas/DashPath'
    UploadPath:
      type: string
      description: Direct MP4 download URL
      example: https://content.shuffll.com/exports/project.mp4
    DashPath:
      type: string
      description: MPEG-DASH streaming manifest URL
      example: https://content.shuffll.com/exports/project.mpd
    Error:
      type: object
      properties:
        type:
          type: string
          example: object
        title:
          type: string
          example: Validation failed
        message:
          type: string
          example: Bad Request
  securitySchemes:
    ShuffllApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >
        API key for authentication. Obtain from Account Settings > API
        Integration.

        Format: sfl-{key}.{secret}:{token}
  examples:
    StorytellingTechniquesResponseExample:
      summary: List of all storytelling techniques
      value:
        techniques:
          - technique: The Relatable Problem
            description: Start by describing a problem that your audience can relate to.
            whyItWorks: It immediately captures attention by addressing a pain point.
            example: >-
              Ever feel like you're wasting hours on [insert task] and getting
              nowhere? That's exactly where I was a year ago.
          - technique: The Before-and-After Transformation
            description: >-
              Show a contrast between 'how things were' and 'how things are
              now.'
            whyItWorks: >-
              People love transformation stories because they're inspiring and
              aspirational.
            example: >-
              A year ago, I was struggling to get leads. Fast forward to today,
              I've tripled my ROI using this one strategy.
          - technique: The Hero's Journey
            description: >-
              Use a classic storytelling arc: challenge, struggle, solution,
              success.
            whyItWorks: >-
              It positions you as a guide helping your audience become the hero
              of their own story.
            example: >-
              I used to think [wrong assumption]. Then I learned [solution], and
              it completely changed the way I do [task].
          - technique: Data-Driven Narrative
            description: >-
              Use statistics or facts to ground your story and create
              credibility.
            whyItWorks: Numbers can be persuasive and make your story feel more impactful.
            example: >-
              Did you know 80% of businesses fail because they don't [solution]?
              Here's how I avoided that and succeeded.
          - technique: The Obstacle-Reversal
            description: >-
              Start with an obstacle you faced, and explain how you flipped it
              into an opportunity.
            whyItWorks: People are drawn to stories of resilience and creativity.
            example: >-
              When my ad budget was cut in half, I thought my campaign was over.
              But then I discovered this technique, and my engagement
              skyrocketed.
          - technique: Customer Success Story
            description: Share the story of a real customer or client.
            whyItWorks: >-
              It builds trust and shows that your product or service delivers
              results.
            example: >-
              One of our clients, Sarah, was spending hours editing videos. With
              our platform, she created professional content in minutes.
          - technique: The 'What If' Scenario
            description: Paint a picture of a better future or a nightmare avoided.
            whyItWorks: >-
              It triggers imagination and emotion, making your message more
              memorable.
            example: >-
              What if you could double your sales in half the time? That's what
              our software does.
          - technique: The Open Loop
            description: >-
              Start with an intriguing question or incomplete story and finish
              it later in the video.
            whyItWorks: >-
              It keeps viewers hooked because they want to see how the story
              ends.
            example: >-
              I tried 5 strategies to grow my business, and only 1 worked. Let
              me show you why.
          - technique: Personal Vulnerability
            description: Share a personal challenge or failure.
            whyItWorks: Authenticity builds trust and connection with your audience.
            example: >-
              I almost gave up on [project/task] because I thought I wasn't good
              enough. Here's what changed everything for me.
          - technique: Lessons Learned Format
            description: Share a lesson you learned through trial and error.
            whyItWorks: People love learning from others' mistakes or insights.
            example: >-
              I wasted $10,000 on ads before I realized what I was doing wrong.
              Here are the 3 things I learned.
          - technique: The Challenge
            description: Issue a challenge to your audience.
            whyItWorks: >-
              It engages your audience and makes them feel like part of the
              story.
            example: >-
              Here's a challenge: try this strategy for 7 days and tell me if
              you don't see results.
          - technique: The 'What Happened Next' Story
            description: Start with a cliffhanger and explain the outcome.
            whyItWorks: Builds suspense and keeps viewers engaged.
            example: >-
              I posted this one video, went to bed, and woke up to 10,000 new
              followers. Here's how it happened.
    ToneOfVoiceResponseExample:
      summary: List of all tone of voice options
      value:
        tones:
          - id: Natural
            description: Clear and simple to understand.
          - id: Professional
            description: Formal and credible.
          - id: Informative
            description: Clear and educational.
          - id: Inspirational
            description: Motivates and uplifts.
          - id: Energetic
            description: Lively and exciting.
    VideoTagsResponseExample:
      summary: List of all video category tags
      value:
        tags:
          - id: Marketing
            title: Marketing Video
            text: Describe your marketing video
          - id: explainer
            title: Explainer Video
            text: Describe your explainer video
          - id: 'Training '
            title: Training Video
            text: Describe your Training video
          - id: 'Product '
            title: Product Video
            text: Describe your Product video
          - id: Thought leadership
            title: Thought Leadership Video
            text: Describe your Thought leadership video
    AiVoiceOptionsResponseExample:
      summary: List of AI voice options and tone styles
      value:
        aiVoiceOptions:
          - id: alloy
            name: alloy
            title: Alloy
            subtitle: Neutral and balanced
            voiceType: open-ai
            tones:
              - friendly
              - professional
              - calm
          - id: nova
            name: nova
            title: Nova
            subtitle: Warm and engaging
            voiceType: open-ai
            tones:
              - friendly
              - excited
              - empathy
          - id: EXAVITQu4vr4xnSDxMaL
            name: bella
            title: Bella
            subtitle: Expressive and versatile
            voiceType: eleven-labs
            tones:
              - professional
              - dramatic
              - energetic
        aiVoiceTones:
          - id: friendly
            title: Friendly
            instructions: Speak in a warm, approachable manner
          - id: professional
            title: Professional
            instructions: Maintain a clear, authoritative tone
          - id: excited
            title: Excited
            instructions: Speak with high energy and enthusiasm
          - id: calm
            title: Calm
            instructions: Speak slowly and soothingly
    AiAvatarOptionsResponseExample:
      summary: List of available AI avatar presenters
      value:
        aiAvatarOptions:
          - id: avatar_sarah_001
            name: Sarah
            accent: American English
            title: Professional Presenter
            subtitle: Confident and clear
            videoPath: https://content.shuffll.com/avatars/sarah_preview.mp4
            avatarType: realistic
          - id: avatar_james_002
            name: James
            accent: British English
            title: Executive Speaker
            subtitle: Authoritative and polished
            videoPath: https://content.shuffll.com/avatars/james_preview.mp4
            avatarType: realistic
    MusicLibraryResponseExample:
      summary: List of available background music tracks
      value:
        - id: track_upbeat_001
          name: Upbeat Corporate
          relativePath: /music/upbeat-corporate.mp3
          image: https://content.shuffll.com/music/upbeat-corporate-cover.jpg
        - id: track_ambient_002
          name: Ambient Focus
          relativePath: /music/ambient-focus.mp3
          image: https://content.shuffll.com/music/ambient-focus-cover.jpg
        - id: track_cinematic_003
          name: Cinematic Inspire
          relativePath: /music/cinematic-inspire.mp3
          image: https://content.shuffll.com/music/cinematic-inspire-cover.jpg
    UpdateWorkspaceRequestExample:
      summary: Rename a workspace
      value:
        name: Marketing Team Workspace
    GetBrandingResponseExample:
      summary: Branding configuration for a workspace
      value:
        isDefault: false
        enabled: true
        company:
          id: acme-corp
          name: Acme Corp
          domain: acme.com
          minSize: null
          maxSize: null
          geoLocation: null
        logo: https://content.shuffll.com/branding/acme-logo.png
        logoW: https://content.shuffll.com/branding/acme-logo-white.png
        colors:
          colorPrimary: '#1a1a2e'
          colorSecondary: '#16213e'
          colorExtra: '#0f3460'
        about: Acme Corp builds innovative solutions for enterprise teams.
        pronunciations: []
    UpdateBrandingColorsExample:
      summary: Update brand colors
      value:
        workspace:
          id: 693fb82afd8d1c43077ba0fe
        propertyName: colors
        propertyValue:
          colorPrimary: '#1a1a2e'
          colorSecondary: '#16213e'
          colorExtra: '#0f3460'
    UpdateBrandingLogoExample:
      summary: Update primary logo
      value:
        workspace:
          id: 693fb82afd8d1c43077ba0fe
        propertyName: logo
        propertyValue: https://content.shuffll.com/branding/acme-logo.png
    UpdateBrandingCompanyExample:
      summary: Update company information
      value:
        workspace:
          id: 693fb82afd8d1c43077ba0fe
        propertyName: company
        propertyValue:
          name: Acme Corp
          domain: acme.com
          geoLocation: New York, USA
    AssetsListResponseExample:
      summary: List of workspace assets
      value:
        - _id: 6947b539cc95ea68854bb523
          displayName: product-demo.mp4
          uploadPath: https://content.shuffll.com/workspace/product-demo.mp4
          dashPath: https://content.shuffll.com/workspace/product-demo.mpd
          mimetype: video/mp4
          type: video
          folder: /
          userEmail: user@example.com
          createdAt: '2025-12-15T07:26:34.333Z'
          aspectRatio: '16:9'
        - _id: 6947b539cc95ea68854bb524
          displayName: company-logo.png
          uploadPath: https://content.shuffll.com/workspace/company-logo.png
          mimetype: image/png
          type: image
          folder: /
          userEmail: user@example.com
          createdAt: '2025-12-10T10:00:00.000Z'
    UploadAssetsResponseExample:
      summary: Successfully uploaded file
      value:
        uploaded:
          - _id: 6947b539cc95ea68854bb525
            displayName: new-video.mp4
            uploadPath: https://content.shuffll.com/workspace/new-video.mp4
            mimetype: video/mp4
            type: video
            folder: /
            userEmail: user@example.com
            createdAt: '2026-02-23T09:00:00.000Z'
    DeleteAssetsRequestExample:
      summary: Delete multiple assets
      value:
        assetIds:
          - 6947b539cc95ea68854bb523
          - 6947b539cc95ea68854bb524
    CreateFolderRequestExample:
      summary: Create a new folder
      value:
        newName: Campaign Assets
    MoveAssetsRequestExample:
      summary: Move assets into a folder
      value:
        toFolder: /Campaign Assets
        assetIds:
          - 6947b539cc95ea68854bb523
    RenameAssetRequestExample:
      summary: Rename an asset
      value:
        newName: final-product-demo.mp4
    GetOrganizationListResponseExample:
      summary: List of all organizations with full details
      value:
        - id: 693fb82afd8d1c43077ba0fb
          name: My Organization
          workspaces:
            - id: 693fb82afd8d1c43077ba0fe
              createdAt: '2025-12-15T07:26:34.333Z'
              isDefaultForUser: true
          branding:
            isDefault: true
            enabled: true
            company:
              id: shuffll
              domain: ''
              name: ''
              minSize: null
              maxSize: null
              geoLocation: null
            logo: /files/platform/onboarding/logo-placeholder.svg
            logoW: /files/platform/onboarding/logo-placeholder.svg
            colors:
              colorPrimary: '#99b898'
              colorSecondary: '#feceab'
              colorExtra: '#ff847c'
              _id: 693fb7e6fd8d1c43077ba0eb
            prompts:
              - tag:
                  title: Thought Leadership Video
                  id: Thought leadership
                  text: Describe your Thought leadership video
                suggestions:
                  - Exploring Unconventional Solutions for Team Innovation
                  - >-
                    Embracing Sustainable Practices in Everyday Business
                    Operations
            videoIdeas:
              - shortTitle: Future Trends
                prompt: Anticipating Future Industry Shifts
                designId: 66589deee3146a3394628496
                designGroupId: 66681ba732c4c63a053f2274
                createdAt: '2025-12-18T20:22:42.399Z'
            videoIdeaStatus: COMPLETED
            pronunciations: []
          createdByEmail: info@shuffll.com
          isAllowedToUseOrganization: true
          userCount: 1
          isDefaultForUser: true
    GetOrganizationByIdResponseExample:
      summary: Detailed organization information with expanded workspace metrics
      value:
        id: 693fb82afd8d1c43077ba0fb
        name: My Organization
        workspaces:
          - id: 693fb82afd8d1c43077ba0fe
            name: My Workspace
            assetCount: 4
            projectCount: 3
            userCount: 1
            templateCount: 1
            createdByEmail: info@shuffll.com
            branding:
              isDefault: true
              enabled: true
              company:
                id: shuffll
                domain: ''
                name: ''
                minSize: null
                maxSize: null
                geoLocation: null
              logo: /files/platform/onboarding/logo-placeholder.svg
              logoW: /files/platform/onboarding/logo-placeholder.svg
              colors:
                colorPrimary: '#99b898'
                colorSecondary: '#feceab'
                colorExtra: '#ff847c'
        branding:
          isDefault: true
          enabled: true
          company:
            id: shuffll
            domain: ''
            name: ''
          logo: /files/platform/onboarding/logo-placeholder.svg
          logoW: /files/platform/onboarding/logo-placeholder.svg
          colors:
            colorPrimary: '#99b898'
            colorSecondary: '#feceab'
            colorExtra: '#ff847c'
          pronunciations: []
        createdByEmail: info@shuffll.com
        userCount: 1
    GetWorkspaceByIdResponseExample:
      summary: Detailed workspace information with metrics and branding
      value:
        id: 693fb82afd8d1c43077ba0fe
        name: My Workspace
        assetCount: 4
        projectCount: 3
        userCount: 1
        templateCount: 1
        createdByEmail: info@shuffll.com
        branding:
          isDefault: true
          enabled: true
          company:
            id: shuffll
            domain: ''
            name: ''
            minSize: null
            maxSize: null
            geoLocation: null
          logo: /files/platform/onboarding/logo-placeholder.svg
          logoW: /files/platform/onboarding/logo-placeholder.svg
          colors:
            colorPrimary: '#99b898'
            colorSecondary: '#feceab'
            colorExtra: '#ff847c'
          pronunciations: []
    ListProjectsResponseExample:
      summary: List of projects in a workspace
      value:
        - id: 6947b539cc95ea68854bb523
          name: Breaking the Agency Mold
          status: DONE
          createdAt: '2025-12-15T07:26:34.333Z'
        - id: 6947b539cc95ea68854bb524
          name: Product Launch Q1 2026
          status: EDITING
          createdAt: '2026-01-10T14:10:00.000Z'
        - id: 6947b539cc95ea68854bb525
          name: Customer Success Stories
          status: GENERATING_IMAGES
          createdAt: '2026-02-01T09:00:00.000Z'
    GetAllTemplatesResponseExample:
      summary: List of templates for default organization and workspace
      value:
        - id: 6945258969368fe55125c4b9
          description: This is a sample template about how useful trees are
          name: Trees for Kids - Template
    GetTemplatesByOrgWorkspaceResponseExample:
      summary: List of templates for specific organization and workspace
      value:
        - id: 6945258969368fe55125c4b9
          description: This is a sample template about how useful trees are
          name: Trees for Kids - Template
    GetTemplateByIdResponseExample:
      summary: Detailed template information with all scenes
      value:
        id: 6945258969368fe55125c4b9
        description: This is a sample template about how useful trees are
        name: Trees for Kids - Template
        scenes:
          - id: a517722a-582b-4f8c-bb8f-c8e8014cf6cc
            type: headline_txt
            dynamicValues:
              - type: color_fill
                position: 201
              - type: color_fill
                position: 0
              - type: color_fill
                position: 100
              - type: color_fill
                position: 102
              - type: header
                position: 0
            name: Amazing Tree Discovery
            availableStagePositions:
              - id: default
                position: 100
                x: 0
                'y': 0
                height: 0
                width: 0
          - id: 08865dcb-d8f3-4dfd-964d-76304fbbfa9d
            type: img_and_headline_txt
            dynamicValues:
              - type: image
                position: 0
              - type: color_fill
                position: 201
              - type: color_fill
                position: 0
              - type: color_fill
                position: 100
              - type: color_fill
                position: 102
              - type: header
                position: 0
            name: Tree Parts Explorer
            availableStagePositions:
              - id: default
                position: 100
                x: 0
                'y': 0
                height: 0
                width: 0
          - id: 00566c97-a41a-45fe-a66c-36a868621297
            type: cta_txt
            dynamicValues:
              - type: logo
                position: 0
              - type: color_fill
                position: 208
              - type: color_fill
                position: 100
              - type: color_fill
                position: 102
              - type: website
                position: 0
              - type: cta
                position: 0
            name: Nature Explorer Call
            availableStagePositions:
              - id: default
                position: 100
                x: 0
                'y': 0
                height: 0
                width: 0
    CreateProjectRequestExample:
      summary: Full-featured project creation with template, assets, and webhook
      value:
        prompt: Breaking the Agency Mold - Building Long-Term Partnerships with Data
        promptType: Prompt
        language: en
        videoLength: 2
        toneOfVoice: Professional
        videoTagId: Marketing
        storyTellingTechnique: The Before-and-After Transformation
        toAutoEnhance: true
        toAutoExport: true
        webhook: https://your-app.com/hooks/shuffll-export
        additionalParams:
          campaignId: camp_123
        aiVoiceSettings:
          voiceId: alloy
          voiceType: open-ai
          voiceSpeed: 1
        customTemplate:
          id: 67682e831de738f85b0d0fc9
          description: >-
            Agency-focused video brand. Tone: confident, data-driven, B2B.
            Audience: marketing directors.
          flexibilityOverride: flexible
          toUseTemplateFont: true
          assets:
            - url: https://example.com/product-demo.mp4
              type: video
              description: 60-second product walkthrough showing the analytics dashboard.
              direction: Use in a middle scene to demonstrate product value.
            - url: https://example.com/team-photo.jpg
              type: image
              description: Company team photo, outdoor setting.
          videoSourcesByOrder:
            - workspace_assets
            - stock_footage
            - generate_from_image
          preConfigs:
            bgMusic:
              volume: 0.35
              path: /music/upbeat-corporate.mp3
            toCleanAudio: false
            subtitles:
              strategy: WORD_HIGHLIGHT
              textSize: 18
              percentOffset: 40
              fontName: Arimo
              isBold: true
              primaryColour: '#FFFFFF'
              outlineColour: '#000000'
              styles:
                normal:
                  color: '#FFFFFF'
                highlight:
                  color: '#FFD700'
          scenes:
            - id: a517722a-582b-4f8c-bb8f-c8e8014cf6cc
              staticScript: >-
                Data-driven agencies don't just win clients — they keep them for
                years.
              dynamicValues:
                - position: 0
                  type: header
                  value: Breaking the Agency Mold
                - position: 0
                  type: logo
                  value: https://example.com/logo.png
              wordBoost:
                - Shuffll
                - ROI
              customSpelling:
                - from:
                    - Shuffel
                    - Shufflle
                  to: Shuffll
            - id: 08865dcb-d8f3-4dfd-964d-76304fbbfa9d
              moreDetailsAboutScene: >-
                Focus on the before/after contrast — struggling agency vs.
                data-driven success.
              toGenerateMissingImages: true
              videosToAdd:
                - url: https://content.shuffll.com/workspace/agency-intro.mp4
                  isMaster: true
                  stagePositionNumber: 100
                  isMuted: false
                  toAutoTrim: true
    CreateProjectResponseExample:
      summary: Project created successfully
      value:
        projectId: 6947b539cc95ea68854bb523
    GetProjectCreateStatusDoneExample:
      summary: Creation complete
      value:
        status: DONE
    GetProjectCreateStatusInProgressExample:
      summary: Creation in progress
      value:
        status: GENERATING_IMAGES
    GetProjectResponseExample:
      summary: Full project details
      value:
        id: 6947b539cc95ea68854bb523
        name: Breaking the Agency Mold
        status: DONE
        createdAt: '2025-12-15T07:26:34.333Z'
        workspaceId: 693fb82afd8d1c43077ba0fe
    ProjectStatusEnhanceStatusResponseExample:
      summary: Enhancement complete
      value:
        percentages: 100
        isDone: true
    ProjectStatusEnhanceStatusStillInProccessResponseExample:
      summary: Enhancement in progress
      value:
        percentages: 50
        isDone: false
    ExportTriggerResponseExample:
      summary: Export job started
      value:
        projectId: 3be6453c-03eb-4357-ae5a-984a0e574a54
        editId: 2f14374a-9c65-4ee5-94b7-fba66d893483
    ProjectExportDoneResponse:
      summary: Export complete — video URLs available
      value:
        isDone: true
        urls:
          uploadPath: https://content.shuffll.com/exports/project.mp4
          dashPath: https://content.shuffll.com/exports/project.mpd
    ProjectExportStillInProcessResponse:
      summary: Export still in progress
      value:
        isDone: false
        urls: {}
  parameters:
    OrganizationIdParam:
      name: organizationId
      in: path
      description: Unique identifier for the organization
      required: true
      schema:
        type: string
        example: 693fb82afd8d1c43077ba0fb
    WorkspaceIdParam:
      name: workspaceId
      in: path
      description: Unique identifier for the workspace
      required: true
      schema:
        type: string
        example: 693fb82afd8d1c43077ba0fe
    TemplateIdParam:
      name: templateId
      in: path
      description: Unique identifier for the template
      required: true
      schema:
        type: string
        example: 67682e831de738f85b0d0fc9
    AssetIdParam:
      name: assetId
      in: path
      description: Unique identifier for the asset
      required: true
      schema:
        type: string
        example: 6947b539cc95ea68854bb523
    ProjectId:
      name: projectId
      in: path
      description: Unique identifier for the project
      required: true
      schema:
        type: string
        format: uuid
        example: dad4bce8-f5cb-4078-a211-995864315e39
  responses:
    BadRequest:
      description: Bad request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
