openapi: 3.0.1
info:
  title: Blotato API
  description: >-
    The Blotato API lets you upload media, publish and schedule posts to social
    platforms (Twitter/X, Instagram, LinkedIn, Facebook, TikTok, Pinterest,
    Threads, Bluesky, YouTube), generate AI videos and visuals from templates,
    and retrieve connected accounts. All requests are authenticated with a
    blotato-api-key header.
  termsOfService: https://www.blotato.com/terms
  contact:
    name: Blotato Support
    url: https://help.blotato.com
  version: '2.0'
servers:
  - url: https://backend.blotato.com/v2
    description: Blotato REST API v2
security:
  - blotatoApiKey: []
tags:
  - name: Media
    description: Upload media for use in posts.
  - name: Posts
    description: Publish, schedule, and track posts.
  - name: Visuals
    description: AI video and visual generation from templates.
  - name: Accounts
    description: User and connected social account lookup.
paths:
  /media:
    post:
      operationId: uploadMedia
      tags:
        - Media
      summary: Upload media from a URL
      description: >-
        Uploads media to Blotato by passing a publicly accessible URL or a
        base64-encoded image data URL. Returns a Blotato-hosted media URL to use
        in the mediaUrls of a post. Files up to 200MB are supported.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadMediaRequest'
      responses:
        '200':
          description: Media uploaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadMediaResponse'
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limit exceeded.
  /posts:
    post:
      operationId: publishPost
      tags:
        - Posts
      summary: Publish a post
      description: >-
        Publishes or schedules a post to a connected social account. Returns a
        postSubmissionId; poll GET /posts/{postSubmissionId} to track status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishPostRequest'
      responses:
        '201':
          description: Post submission accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishPostResponse'
        '401':
          description: Missing or invalid API key.
        '422':
          description: Validation error.
        '429':
          description: Rate limit exceeded.
        '500':
          description: Server error.
  /posts/{postSubmissionId}:
    get:
      operationId: getPostStatus
      tags:
        - Posts
      summary: Get post status
      description: Returns the publishing status for a post submission.
      parameters:
        - name: postSubmissionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Post submission status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostStatusResponse'
        '401':
          description: Missing or invalid API key.
        '404':
          description: Post submission not found.
  /users/me:
    get:
      operationId: getCurrentUser
      tags:
        - Accounts
      summary: Get current user
      description: Retrieves information about the authenticated user.
      responses:
        '200':
          description: Current user.
        '401':
          description: Missing or invalid API key.
  /users/me/accounts:
    get:
      operationId: listAccounts
      tags:
        - Accounts
      summary: List connected accounts
      description: >-
        Returns the authenticated user's connected social accounts, optionally
        filtered by platform. Provides the accountId values used when publishing.
      parameters:
        - name: platform
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Connected accounts.
        '401':
          description: Missing or invalid API key.
  /users/me/accounts/{accountId}/subaccounts:
    get:
      operationId: listSubaccounts
      tags:
        - Accounts
      summary: List subaccounts
      description: >-
        Returns subaccounts for an account (for example LinkedIn or Facebook
        pages) associated with the given accountId.
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Subaccounts.
        '401':
          description: Missing or invalid API key.
  /social/pinterest/boards:
    get:
      operationId: listPinterestBoards
      tags:
        - Accounts
      summary: List Pinterest boards
      description: Lists the Pinterest boards available for a connected account.
      responses:
        '200':
          description: Pinterest boards.
        '401':
          description: Missing or invalid API key.
  /videos/templates:
    get:
      operationId: listVisualTemplates
      tags:
        - Visuals
      summary: List visual templates
      description: >-
        Lists the available AI video and visual templates, returning the
        templateId values and the inputs each template accepts.
      responses:
        '200':
          description: Available templates.
        '401':
          description: Missing or invalid API key.
  /videos/from-templates:
    post:
      operationId: createVisual
      tags:
        - Visuals
      summary: Create a visual from a template
      description: >-
        Creates an AI video or visual creation from a template plus inputs.
        Returns a creation id and an initial status; poll
        GET /videos/creations/{id} until the creation is done.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVisualRequest'
      responses:
        '201':
          description: Visual creation queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateVisualResponse'
        '401':
          description: Missing or invalid API key.
        '422':
          description: Validation error.
  /videos/creations/{id}:
    get:
      operationId: getVisualStatus
      tags:
        - Visuals
      summary: Get visual creation status
      description: >-
        Returns the status of a visual creation. When done, the response
        includes a mediaUrl for videos or imageUrls for images and carousels.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Visual creation status.
        '401':
          description: Missing or invalid API key.
        '404':
          description: Creation not found.
components:
  securitySchemes:
    blotatoApiKey:
      type: apiKey
      in: header
      name: blotato-api-key
      description: >-
        API key generated in Blotato Settings > API. Sent in the blotato-api-key
        header on every request. Keys may include trailing '=' padding that must
        be preserved.
  schemas:
    UploadMediaRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          description: >-
            A publicly accessible media URL, or a base64-encoded image data URL,
            to upload to Blotato.
    UploadMediaResponse:
      type: object
      properties:
        url:
          type: string
          description: The Blotato-hosted media URL to reference in a post.
    PublishPostRequest:
      type: object
      required:
        - post
      properties:
        post:
          $ref: '#/components/schemas/Post'
        scheduledTime:
          type: string
          format: date-time
          description: ISO 8601 time at which to publish the post (optional).
        useNextFreeSlot:
          type: boolean
          description: Publish at the next free scheduling slot (optional).
        slot:
          $ref: '#/components/schemas/Slot'
    Post:
      type: object
      required:
        - accountId
        - content
        - target
      properties:
        accountId:
          type: string
          description: The connected account id, from GET /users/me/accounts.
        content:
          $ref: '#/components/schemas/PostContent'
        target:
          $ref: '#/components/schemas/PostTarget'
    PostContent:
      type: object
      required:
        - text
        - mediaUrls
        - platform
      properties:
        text:
          type: string
          description: The post text/caption.
        mediaUrls:
          type: array
          maxItems: 20
          items:
            type: string
          description: Hosted media URLs (for example from POST /media).
        platform:
          type: string
          description: The destination platform for this content.
          enum:
            - twitter
            - instagram
            - linkedin
            - facebook
            - tiktok
            - pinterest
            - threads
            - bluesky
            - youtube
            - other
        additionalPosts:
          type: array
          maxItems: 10
          description: Additional posts for threads/carousels.
          items:
            type: object
            required:
              - text
              - mediaUrls
            properties:
              text:
                type: string
              mediaUrls:
                type: array
                maxItems: 20
                items:
                  type: string
    PostTarget:
      type: object
      required:
        - targetType
      description: >-
        Platform-specific target. The targetType selects the platform; some
        platforms require additional fields (for example linkedin/facebook
        pageId, pinterest boardId, youtube title/privacyStatus, tiktok privacy
        and content-disclosure flags).
      properties:
        targetType:
          type: string
          enum:
            - twitter
            - instagram
            - linkedin
            - facebook
            - tiktok
            - pinterest
            - threads
            - bluesky
            - youtube
            - webhook
        pageId:
          type: string
          description: Required for linkedin and facebook page targets.
        boardId:
          type: string
          description: Required for pinterest targets.
        mediaType:
          type: string
          description: Optional content variant, for example reel or story.
        title:
          type: string
          description: Title (youtube, pinterest).
        privacyStatus:
          type: string
          description: Required for youtube targets.
        privacyLevel:
          type: string
          description: Required for tiktok targets.
        url:
          type: string
          description: Required for webhook targets.
    Slot:
      type: object
      required:
        - id
        - time
      properties:
        id:
          type: string
        time:
          type: string
    PublishPostResponse:
      type: object
      properties:
        postSubmissionId:
          type: string
          description: Identifier used to poll publishing status.
    PostStatusResponse:
      type: object
      properties:
        postSubmissionId:
          type: string
        status:
          type: string
          description: Current publishing status of the submission.
    CreateVisualRequest:
      type: object
      required:
        - templateId
        - inputs
      properties:
        templateId:
          type: string
          description: A template id from GET /videos/templates.
        inputs:
          type: object
          description: Template-specific inputs.
        prompt:
          type: string
        render:
          type: boolean
        isDraft:
          type: boolean
        title:
          type: string
        useBrandKit:
          type: boolean
    CreateVisualResponse:
      type: object
      properties:
        item:
          type: object
          properties:
            id:
              type: string
            status:
              type: string
              description: Initial creation status, for example queueing.