openapi: 3.0.0
info:
  title: TikTok Profile Collections API
  description: |
    Retrieve the public collections of a TikTok user: the named folders of saved videos the user has made
    visible on their profile. Each collection includes its name, link, video count and cover image, beside
    the user's profile. A user without public collections returns an empty list and an error saying so.

    **Cross-linking**: Pass the same username to the TikTok Profile API for the full profile and to the
    TikTok Profile Videos API for the user's own posts.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: TikTok Profile Collections Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine identifier
          schema:
            type: string
            enum: ["tiktok_profile_collections"]
            default: "tiktok_profile_collections"
        - name: username
          in: query
          required: true
          description: TikTok username (with or without the @ symbol)
          schema:
            type: string
            pattern: '^@?[a-zA-Z0-9_.]{1,24}$'
        - name: next_page_token
          in: query
          required: false
          description: Token to retrieve the next page of collections, returned as pagination.next_page_token when pagination.has_more is true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        profile:
          $ref: '#/components/schemas/Profile'
        collections:
          type: array
          description: The user's public collections, empty when the user has none
          items:
            $ref: '#/components/schemas/Collection'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Error message when the user has no public collections, the username does not exist, the account is private or behind a log-in wall, or no results are found

    SearchMetadata:
      type: object
      required: [status, created_at]
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: TikTok URL for this search
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results

    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Search engine identifier
        username:
          type: string
          description: TikTok username
        next_page_token:
          type: string
          description: Pagination token used for this request

    Profile:
      type: object
      properties:
        id:
          type: string
          description: TikTok numeric user ID
        sec_uid:
          type: string
          description: TikTok secure user ID
        username:
          type: string
          description: TikTok username
        link:
          type: string
          description: URL to the profile page
        name:
          type: string
          description: Display name
        bio:
          type: string
          description: Profile bio or description
        avatar:
          type: string
          description: URL to the profile avatar image
        avatar_hd:
          type: string
          description: URL to a high-resolution version of the profile avatar image
        is_verified:
          type: boolean
          description: Whether the account is verified
        is_private:
          type: boolean
          description: Whether the account is private
        followers:
          type: integer
          description: Number of followers
        following:
          type: integer
          description: Number of accounts being followed
        hearts:
          type: integer
          description: Total hearts (likes) received across all videos
        posts:
          type: integer
          description: Total number of videos posted

    Collection:
      type: object
      required: [position, id, name, link, videos_count]
      properties:
        position:
          type: integer
          description: 1-based position of the collection in the returned page
        id:
          type: string
          description: TikTok collection ID
        name:
          type: string
          description: Collection name
        link:
          type: string
          description: URL to the collection page
        cover:
          type: string
          description: Collection cover image URL (signed by TikTok, expires after ~48 hours)
        videos_count:
          type: integer
          description: Number of videos TikTok counts in the collection

    Pagination:
      type: object
      properties:
        has_more:
          type: boolean
          description: Whether more collections are available on a following page
        next_page_token:
          type: string
          description: Token to pass back as next_page_token to retrieve the next page of collections

    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
