openapi: 3.0.0
info:
  title: TikTok Hashtag API
  description: |
    The TikTok Hashtag API returns the details of a TikTok hashtag: its id, name, description, images and
    its total video and view counts, as a single `hashtag` object. The hashtag is looked up by name, with
    or without the leading "#".

    **Cross-linking**: Hashtag names appear in the `hashtags` of videos returned by the TikTok Search,
    TikTok Profile Videos and TikTok Video APIs. Pass one as the `hashtag` parameter to look it up.
    Pass the hashtag's `name` as the `q` parameter of the TikTok Search API to search videos for it.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: TikTok Hashtag
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine identifier
          schema:
            type: string
            enum: ["tiktok_hashtag"]
            default: "tiktok_hashtag"
        - name: hashtag
          in: query
          required: true
          description: The hashtag to look up, with or without the leading "#" (e.g., "football" or "#football"), made of letters, numbers, underscores and emoji, up to 70 characters not counting the leading "#", and matched regardless of letter case
          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, or TikTok answered but returned nothing usable. The body is a bare
            {"error": ...} rather than a search response, and the search is not billed.
            A hashtag that does not exist or is restricted is not this case: it is a 200 with a not-found error.
          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'
        hashtag:
          $ref: '#/components/schemas/Hashtag'
        error:
          type: string
          description: Error message when the hashtag was not found
    Hashtag:
      type: object
      required: [id, name, title, link, videos, views]
      properties:
        id:
          type: string
          description: TikTok's numeric identifier of the hashtag
        name:
          type: string
          description: The hashtag TikTok matched, without the leading "#", whose letter case can differ from the request
        title:
          type: string
          description: Hashtag as TikTok displays it (e.g., "#football")
        link:
          type: string
          description: URL of the TikTok hashtag page
        description:
          type: string
          description: Description TikTok shows on the hashtag page
        thumbnail:
          type: string
          description: URL of the hashtag's icon image
        cover:
          type: string
          description: URL of the hashtag's cover image
        videos:
          type: integer
          description: Total number of videos tagged with the hashtag
        views:
          type: integer
          description: Total number of views across videos tagged with the hashtag
        is_commerce:
          type: boolean
          description: Whether TikTok marks the hashtag as a commerce hashtag
    SearchMetadata:
      type: object
      required: [id, 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
        hashtag:
          type: string
          description: The hashtag looked up, without the leading "#"
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong