CartViral Carousels API

openapi: 3.2.0
info:
  title: CartViral Carousels API
  version: 1.0.0
  description: 'AI product videos for e-commerce: import products, generate TikTok, Reels and Shorts clips, get download links, and work with the CartViral Earn creator marketplace. Same operations as the MCP server at https://app.cartviral.com/mcp. Docs: https://cartviral.com/api'
  contact:
    name: CartViral
    email: support@cartviral.com
    url: https://cartviral.com
servers:
- url: https://app.cartviral.com/api/v1
security:
- bearer: []
- oauth:
  - mcp
tags:
- name: Carousels
paths:
  /carousels:
    post:
      operationId: generateCarousel
      summary: Queue a carousel of a product
      description: 'Queue a multi-slide carousel (Instagram and TikTok slides) for one catalog product, built only from its real facts: 3 credits per set, a few minutes to render. format picks the content idea (e.g. a save-this cheat sheet or a myth vs fact), style picks the visual look; leave either out and CartViral rotates to a format/style combo it hasn''t tried recently for this account. Credits are charged from the account; a failed set refunds automatically. Poll list_carousels for download links.'
      x-openai-isConsequential: true
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Invalid input or the action could not be done; body has an error message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid credentials
        '429':
          description: 'Rate limit: 120 calls per minute per key'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                product_id:
                  type: string
                  description: Product id from list_products
                format:
                  type: string
                  enum:
                  - cheat_sheet
                  - myth_vs_fact
                  - this_or_that
                  - vs_usual_way
                  - before_after
                  - listicle
                  - how_to_routine
                  - gift_guide
                  - behind_the_scenes
                  - customer_story
                  - origin_story
                  - unpopular_opinion
                  description: Optional carousel format id; omit to let CartViral pick one
                style:
                  type: string
                  enum:
                  - editorial
                  - cinematic
                  - comic
                  - social
                  description: Optional visual style id; omit to let CartViral pick one
              required:
              - product_id
      tags:
      - Carousels
    get:
      operationId: listCarousels
      summary: Carousels with render status and download links
      description: Recent carousels of the account's catalog, newest first, with render status, the hook and caption CartViral wrote and, when done, a zip download link and each slide's Instagram/TikTok image links.
      x-openai-isConsequential: false
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 12
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Invalid input or the action could not be done; body has an error message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid credentials
        '429':
          description: 'Rate limit: 120 calls per minute per key'
      tags:
      - Carousels
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: API key from Account → AI agents (cv_live_...), or an OAuth access token
    oauth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.cartviral.com/oauth/authorize
          tokenUrl: https://app.cartviral.com/oauth/token
          refreshUrl: https://app.cartviral.com/oauth/token
          scopes:
            mcp: Use your CartViral account