TikTok for Developers Post API

openapi: 3.1.0
info:
  title: TikTok Content Posting OAuth Post 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:
  schemas:
    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'
    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
    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'
    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
    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'
    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'
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        log_id:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token