openapi: 3.1.0
info:
  title: TikTok Research API
  description: >-
    The TikTok Research API provides academic and institutional researchers
    access to TikTok public data. Supports querying videos, user information,
    comments, followers, following lists, liked videos, and reposted videos.
  version: v2
  contact:
    name: TikTok for Developers
    url: https://developers.tiktok.com/doc/research-api-get-started
  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: Research Videos
    description: Video search and query operations
  - name: Research Users
    description: User information for research
  - name: Research Comments
    description: Comment data operations
  - name: Research Social
    description: Social graph data
paths:
  /v2/research/video/query/:
    post:
      operationId: queryResearchVideos
      summary: Query Research Videos
      description: >-
        Queries TikTok videos using boolean operators (AND, OR, NOT) with
        filters such as keywords, region, date range, hashtags, music ID, and
        effect ID. Returns video IDs and selected metadata fields.
      tags:
        - Research Videos
      parameters:
        - name: fields
          in: query
          required: true
          schema:
            type: string
          description: Comma-separated list of fields to return
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoQueryRequest'
      responses:
        '200':
          description: Video query results returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoQueryResponse'
        '401':
          description: Unauthorized
        '400':
          description: Bad Request
  /v2/research/user/info/:
    post:
      operationId: queryResearchUserInfo
      summary: Query Research User Info
      description: >-
        Retrieves public TikTok account information by TikTok handle. Returns
        fields such as display_name, bio_description, avatar_url, is_verified,
        follower_count, following_count, likes_count, and video_count.
      tags:
        - Research Users
      parameters:
        - name: fields
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInfoRequest'
      responses:
        '200':
          description: User info returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResearchUserInfoResponse'
        '401':
          description: Unauthorized
  /v2/research/video/comment/list/:
    post:
      operationId: listVideoComments
      summary: List Video Comments
      description: >-
        Retrieves all comments on a specific TikTok video, including comment
        text, author information, create time, and like count.
      tags:
        - Research Comments
      parameters:
        - name: fields
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentListRequest'
      responses:
        '200':
          description: Comments returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentListResponse'
        '401':
          description: Unauthorized
  /v2/research/user/followers/:
    post:
      operationId: listUserFollowers
      summary: List User Followers
      description: >-
        Retrieves the list of followers for a specified TikTok user.
      tags:
        - Research Social
      parameters:
        - name: fields
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SocialListRequest'
      responses:
        '200':
          description: Followers list returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialListResponse'
        '401':
          description: Unauthorized
  /v2/research/user/following/:
    post:
      operationId: listUserFollowing
      summary: List User Following
      description: >-
        Retrieves the list of accounts that a specified TikTok user follows.
      tags:
        - Research Social
      parameters:
        - name: fields
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SocialListRequest'
      responses:
        '200':
          description: Following list returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialListResponse'
        '401':
          description: Unauthorized
  /v2/research/user/liked_videos/:
    post:
      operationId: listUserLikedVideos
      summary: List User Liked Videos
      description: >-
        Retrieves the list of videos liked by a specified TikTok user.
      tags:
        - Research Videos
      parameters:
        - name: fields
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SocialListRequest'
      responses:
        '200':
          description: Liked videos returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoQueryResponse'
        '401':
          description: Unauthorized
  /v2/research/user/pinned_videos/:
    post:
      operationId: listUserPinnedVideos
      summary: List User Pinned Videos
      description: >-
        Retrieves the list of videos pinned by a specified TikTok user.
      tags:
        - Research Videos
      parameters:
        - name: fields
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SocialListRequest'
      responses:
        '200':
          description: Pinned videos returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoQueryResponse'
        '401':
          description: Unauthorized
  /v2/research/user/reposted_videos/:
    post:
      operationId: listUserRepostedVideos
      summary: List User Reposted Videos
      description: >-
        Retrieves the list of videos reposted by a specified TikTok user.
      tags:
        - Research Videos
      parameters:
        - name: fields
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SocialListRequest'
      responses:
        '200':
          description: Reposted videos returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoQueryResponse'
        '401':
          description: Unauthorized
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token (client credentials flow for Research API)
  schemas:
    VideoQueryRequest:
      type: object
      required:
        - query
        - start_date
        - end_date
        - max_count
      properties:
        query:
          type: object
          description: Boolean query object with and/or/not operators
          properties:
            and:
              type: array
              items:
                $ref: '#/components/schemas/QueryCondition'
            or:
              type: array
              items:
                $ref: '#/components/schemas/QueryCondition'
            not:
              type: array
              items:
                $ref: '#/components/schemas/QueryCondition'
        start_date:
          type: string
          description: Start date in YYYYMMDD format
        end_date:
          type: string
          description: End date in YYYYMMDD format
        max_count:
          type: integer
          description: Maximum results per page (1-100)
          minimum: 1
          maximum: 100
        cursor:
          type: integer
          description: Pagination cursor
        search_id:
          type: string
          description: Search ID for pagination continuation
    QueryCondition:
      type: object
      properties:
        field_name:
          type: string
          enum:
            - id
            - video_description
            - create_date
            - username
            - region_code
            - hashtag_name
            - keyword
            - music_id
            - effect_id
            - video_length
        operation:
          type: string
          enum:
            - EQ
            - IN
            - GT
            - GTE
            - LT
            - LTE
        field_values:
          type: array
          items:
            type: string
    VideoQueryResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            videos:
              type: array
              items:
                $ref: '#/components/schemas/ResearchVideo'
            cursor:
              type: integer
            has_more:
              type: boolean
            search_id:
              type: string
        error:
          $ref: '#/components/schemas/Error'
    ResearchVideo:
      type: object
      properties:
        id:
          type: string
        create_time:
          type: integer
        username:
          type: string
        region_code:
          type: string
        video_description:
          type: string
        music_id:
          type: string
        like_count:
          type: integer
        comment_count:
          type: integer
        share_count:
          type: integer
        view_count:
          type: integer
        hashtag_names:
          type: array
          items:
            type: string
    UserInfoRequest:
      type: object
      required:
        - username
      properties:
        username:
          type: string
          description: TikTok handle (without @)
    ResearchUserInfoResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            display_name:
              type: string
            bio_description:
              type: string
            avatar_url:
              type: string
            is_verified:
              type: boolean
            follower_count:
              type: integer
            following_count:
              type: integer
            likes_count:
              type: integer
            video_count:
              type: integer
        error:
          $ref: '#/components/schemas/Error'
    CommentListRequest:
      type: object
      required:
        - video_id
        - max_count
      properties:
        video_id:
          type: string
          description: TikTok video ID
        max_count:
          type: integer
          minimum: 1
          maximum: 100
        cursor:
          type: integer
    CommentListResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            comments:
              type: array
              items:
                $ref: '#/components/schemas/Comment'
            cursor:
              type: integer
            has_more:
              type: boolean
        error:
          $ref: '#/components/schemas/Error'
    Comment:
      type: object
      properties:
        id:
          type: string
        video_id:
          type: string
        text:
          type: string
        like_count:
          type: integer
        reply_count:
          type: integer
        parent_comment_id:
          type: string
        create_time:
          type: integer
    SocialListRequest:
      type: object
      required:
        - username
        - max_count
      properties:
        username:
          type: string
          description: TikTok handle (without @)
        max_count:
          type: integer
          minimum: 1
          maximum: 100
        cursor:
          type: integer
    SocialListResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            user_followers:
              type: array
              items:
                $ref: '#/components/schemas/SocialUser'
            cursor:
              type: integer
            has_more:
              type: boolean
        error:
          $ref: '#/components/schemas/Error'
    SocialUser:
      type: object
      properties:
        display_name:
          type: string
        username:
          type: string
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        log_id:
          type: string