openapi: 3.1.0
info:
  title: TikTok Content Posting API
  description: >-
    The TikTok Content Posting API allows third-party platforms to publish
    videos directly to a user's TikTok account. Supports direct post and
    file-upload flows, including video initiation, chunk upload, and publish
    status polling.
  version: v2
  contact:
    name: TikTok for Developers
    url: https://developers.tiktok.com/
  termsOfService: https://developers.tiktok.com/doc/tiktok-api-terms-of-service
servers:
  - url: https://open.tiktokapis.com
    description: TikTok Open API Production
security:
  - BearerAuth: []
tags:
  - name: Post
    description: Video publishing operations
paths:
  /v2/post/publish/video/init/:
    post:
      operationId: initVideoPublish
      summary: Init Video Upload
      description: >-
        Initiates a video upload or direct post to a user's TikTok account.
        Declare the video source type (FILE_UPLOAD or PULL_FROM_URL), chunk
        count, file size, and publish metadata. Returns an upload_url and
        publish_id.
      tags:
        - Post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoInitRequest'
      responses:
        '200':
          description: Upload initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoInitResponse'
        '401':
          description: Unauthorized
        '400':
          description: Bad Request
  /v2/post/publish/status/fetch/:
    post:
      operationId: getPublishStatus
      summary: Get Publish Status
      description: >-
        Polls the status of a video publish job using the publish_id returned
        from the init endpoint. Status transitions from PROCESSING to
        PUBLISH_COMPLETE.
      tags:
        - Post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishStatusRequest'
      responses:
        '200':
          description: Publish status returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishStatusResponse'
        '401':
          description: Unauthorized
  /v2/post/publish/inbox/video/init/:
    post:
      operationId: initInboxVideoUpload
      summary: Init Inbox Video Upload
      description: >-
        Initiates a video upload to a user's TikTok inbox as a draft. The user
        can review and publish from the TikTok app.
      tags:
        - Post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxVideoInitRequest'
      responses:
        '200':
          description: Inbox upload initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoInitResponse'
        '401':
          description: Unauthorized
  /v2/post/publish/creator_info/query/:
    post:
      operationId: queryCreatorInfo
      summary: Query Creator Info
      description: >-
        Retrieves the authenticated creator's content posting settings including
        allowed privacy levels, duet and stitch permissions, and comment
        settings.
      tags:
        - Post
      responses:
        '200':
          description: Creator info returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatorInfoResponse'
        '401':
          description: Unauthorized
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token
  schemas:
    VideoInitRequest:
      type: object
      required:
        - source_info
        - post_info
      properties:
        source_info:
          type: object
          properties:
            source:
              type: string
              enum:
                - FILE_UPLOAD
                - PULL_FROM_URL
              description: Source type for the video
            video_url:
              type: string
              description: URL of the video (required when source is PULL_FROM_URL)
            chunk_size:
              type: integer
              description: Size of each upload chunk in bytes
            total_chunk_count:
              type: integer
              description: Total number of chunks
        post_info:
          $ref: '#/components/schemas/PostInfo'
    InboxVideoInitRequest:
      type: object
      required:
        - source_info
      properties:
        source_info:
          type: object
          properties:
            source:
              type: string
              enum:
                - FILE_UPLOAD
                - PULL_FROM_URL
            video_url:
              type: string
            chunk_size:
              type: integer
            total_chunk_count:
              type: integer
    PostInfo:
      type: object
      properties:
        title:
          type: string
          description: Caption/title for the post (max 2200 chars)
        privacy_level:
          type: string
          enum:
            - PUBLIC_TO_EVERYONE
            - MUTUAL_FOLLOW_FRIENDS
            - FOLLOWER_OF_CREATOR
            - SELF_ONLY
          description: Privacy level for the video
        disable_duet:
          type: boolean
          description: Whether to disable duet for this post
        disable_comment:
          type: boolean
          description: Whether to disable comments
        disable_stitch:
          type: boolean
          description: Whether to disable stitch
        video_cover_timestamp_ms:
          type: integer
          description: Timestamp in milliseconds for video cover
    VideoInitResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            publish_id:
              type: string
              description: Unique identifier for this publish job
            upload_url:
              type: string
              description: URL to upload video chunks to
        error:
          $ref: '#/components/schemas/Error'
    PublishStatusRequest:
      type: object
      required:
        - publish_id
      properties:
        publish_id:
          type: string
          description: The publish_id returned from the init endpoint
    PublishStatusResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            status:
              type: string
              enum:
                - PROCESSING_UPLOAD
                - PROCESSING_DOWNLOAD
                - SENDING_TO_USER_INBOX
                - FAILED
                - PUBLISH_COMPLETE
              description: Current status of the publish job
            publish_id:
              type: string
            uploaded_bytes:
              type: integer
              description: Bytes uploaded so far
        error:
          $ref: '#/components/schemas/Error'
    CreatorInfoResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            creator_avatar_url:
              type: string
            creator_username:
              type: string
            creator_nickname:
              type: string
            privacy_level_options:
              type: array
              items:
                type: string
            comment_disabled:
              type: boolean
            duet_disabled:
              type: boolean
            stitch_disabled:
              type: boolean
            max_video_post_duration_sec:
              type: integer
        error:
          $ref: '#/components/schemas/Error'
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        log_id:
          type: string