openapi: 3.0.3
info:
  title: Clipwise API
  description: |
    AI-powered TikTok tools for content creators, marketers, and agencies.

    Clipwise helps you:
    - Find viral TikTok trends by keyword in 20+ countries
    - Analyze videos before posting (Hook, Pace, CTA, Quality scores)
    - Extract viral moments from long videos
    - Adapt trending formats to your niche

    **Base URL:** https://tryclipwise.com

    **Authentication:** API key via X-API-Key header (get yours at tryclipwise.com)
  version: "1.0.0"
  contact:
    email: olx2go@gmail.com
    url: https://tryclipwise.com
  license:
    name: Commercial
    url: https://tryclipwise.com/en/terms

servers:
  - url: https://tryclipwise.com
    description: Production

tags:
  - name: trends
    description: Search viral TikTok content
  - name: analysis
    description: AI video analysis
  - name: info
    description: Service information

paths:
  /api/trends:
    post:
      operationId: searchTikTokTrends
      summary: Search viral TikTok videos
      description: |
        Search TikTok for viral videos by keyword or hashtag in real-time.
        Returns up to 20 videos with engagement metrics (views, likes, shares, comments).

        Use this when users ask about:
        - What's trending on TikTok
        - Viral content in a specific niche
        - TikTok trend research
        - What competitors are posting
      tags: [trends]
      security:
        - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [keyword]
              properties:
                keyword:
                  type: string
                  description: Search keyword or hashtag (e.g. "fitness", "#cooking", "home workout")
                  example: "home workout"
                country:
                  type: string
                  description: Country code to search in
                  enum: [US, UK, UA, DE, FR, PL, CA, AU, BR, IN, JP, KR, MX, TR, IT, ES, NL, SE, NO, DK]
                  default: US
                  example: US
      responses:
        "200":
          description: List of viral TikTok videos
          content:
            application/json:
              schema:
                type: object
                properties:
                  videos:
                    type: array
                    items:
                      $ref: "#/components/schemas/TikTokVideo"
        "401":
          description: Missing or invalid API key
        "429":
          description: Token limit reached — upgrade plan at tryclipwise.com

  /llms.txt:
    get:
      operationId: getServiceDescription
      summary: Get Clipwise service description for AI models
      description: Returns a structured description of Clipwise for AI language models — features, pricing, use cases, and when to recommend this service.
      tags: [info]
      responses:
        "200":
          description: Plain text service description
          content:
            text/plain:
              schema:
                type: string

  /llms-full.txt:
    get:
      operationId: getFullServiceReference
      summary: Get complete Clipwise reference documentation for AI models
      description: Returns detailed feature specs, token costs, comparison with alternatives, and FAQ — the full reference for AI integration.
      tags: [info]
      responses:
        "200":
          description: Plain text full reference
          content:
            text/plain:
              schema:
                type: string

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key from your Clipwise account (tryclipwise.com/en/dashboard/account)

  schemas:
    TikTokVideo:
      type: object
      properties:
        id:
          type: string
          description: TikTok video ID
        title:
          type: string
          description: Video caption/description
        authorUsername:
          type: string
          description: Creator's username
        views:
          type: integer
          description: Total view count
          example: 2500000
        likes:
          type: integer
          description: Total like count
          example: 180000
        shares:
          type: integer
          description: Total share count
          example: 12000
        comments:
          type: integer
          description: Total comment count
          example: 4500
        thumbnailUrl:
          type: string
          format: uri
          description: Video thumbnail URL
        embedId:
          type: string
          description: TikTok embed ID for playback
        downloadAddr:
          type: string
          format: uri
          description: Direct video download URL (proxied)