creatordb-app AI Search API

openapi: 3.2.0
info:
  version: 1.0.0
  title: CreatorDB Headless API V3 AI Search API
  description: '# CreatorDB Headless API V3'
  contact:
    name: CreatorDB
    url: https://www.creatordb.app
    email: support@creatordb.app
  license:
    url: http://www.apache.org/licenses/LICENSE-2.0.html
    name: Apache 2.0
servers:
- url: https://apiv3.creatordb.app
  description: Production Environment (CreatorDB Headless API V3)
security:
- ApiKeyAuth: []
tags:
- name: AI Search
paths:
  /nls:
    post:
      tags:
      - AI Search
      summary: Natural Language Search
      description: Search for creators across YouTube, Instagram, and TikTok using natural language descriptions. The AI determines the appropriate platform from your query and converts it into structured search filters. Results are delivered via Server-Sent Events (SSE) streaming.
      operationId: getNLS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Natural language search parameters.
              properties:
                description:
                  type: string
                  description: A natural language description of the creators you are looking for.
                  minLength: 1
                  maxLength: 1000
                  example: Find US-based YouTube beauty creators that own makeup brands and have more than 15 million subscribers
              required:
              - description
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X POST \"https://apiv3.creatordb.app/nls\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"api-key: <YOUR_API_KEY_HERE>\" \\\n  -d '{\n    \"description\": \"Find US-based YouTube beauty creators that own makeup brands and have more than 15 million subscribers\"\n  }'\n"
      - lang: python
        label: Python
        source: "import requests\n\nurl = \"https://apiv3.creatordb.app/nls\"\n\npayload = { \"description\": \"Find US-based YouTube beauty creators that own makeup brands and have more than 15 million subscribers\" }\nheaders = {\n    \"api-key\": \"<YOUR_API_KEY_HERE>\",\n    \"Content-Type\": \"application/json\"\n}\n\nresponse = requests.post(url, json=payload, headers=headers, stream=True)\n\nfor line in response.iter_lines(decode_unicode=True):\n    print(line)\n"
      responses:
        '200':
          description: 'NLS results are delivered via Server-Sent Events (SSE). The stream emits multiple `event: progress` messages with status updates (e.g., `{"message":"Loading..."}`, `{"message":"Analyzing intent..."}`, `{"message":"Query ready..."}`), followed by a final `event: result` containing the response object shown below. Connect using an SSE-capable client or `stream=True` in your HTTP library.'
          content:
            text/event-stream:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      creatorList:
                        type: array
                        description: Matching creators. Present when the query returns results.
                        items:
                          type: object
                          properties:
                            displayName:
                              type: string
                              description: The creator display name.
                            uniqueId:
                              type: string
                              description: The creator handle.
                            channelId:
                              type: string
                              description: YouTube channel ID.
                            avatarUrl:
                              type: string
                              description: Profile picture URL.
                            totalSubscribers:
                              type: integer
                              description: YouTube subscriber count.
                            totalFollowers:
                              type: integer
                              description: Instagram or Tiktok follower count.
                      platform:
                        type: string
                        description: The platform detected from the query.
                        enum:
                        - youtube
                        - instagram
                        - tiktok
                      message:
                        type: string
                        description: Explanation when the query is too broad (suggestion response).
                      suggestion:
                        type: array
                        items:
                          type: string
                        description: Refined query suggestions when the original query is too broad.
                  creditsUsed:
                    type: number
                    description: Credits consumed for this request (dynamic, based on token usage).
                    examples:
                    - 3.04
                  creditsAvailable:
                    type: number
                    description: Number of API credits remaining. Equals planCreditsAvailable plus purchasedCreditsAvailable.
                    examples:
                    - 2627.89
                  planCreditsAvailable:
                    type: number
                    description: Remaining plan credits after this request, in credits.
                    examples:
                    - 900
                  purchasedCreditsAvailable:
                    type: number
                    description: Remaining purchased credits after this request, in credits.
                    examples:
                    - 75
                  keyCreditsAvailable:
                    type: number
                    description: Remaining credits this API key may still spend before reaching its spend limit, in credits. Present only when the key has a spend limit.
                    examples:
                    - 4975
                  traceId:
                    type: string
                    description: Unique trace ID for each request.
                    examples:
                    - 6ddf6c22a7a84b83e9a98f70a06e6235
                  timestamp:
                    type: integer
                    description: Time the response was generated, represented as a Unix timestamp in milliseconds.
                    examples:
                    - 1774586488186
                  errorCode:
                    type: string
                    description: Error code returned if the request fails. Empty if the request is successful.
                    examples:
                    - ''
                  errorDescription:
                    type: string
                    description: Description of the error. Empty if the request is successful.
                    examples:
                    - ''
                  success:
                    type: boolean
                    description: '`true` if the request is successful.'
                    examples:
                    - true
                required:
                - data
                - traceId
                - timestamp
                - errorCode
                - errorDescription
                - success
                - creditsUsed
                - creditsAvailable
                - planCreditsAvailable
                - purchasedCreditsAvailable
              examples:
                default:
                  summary: SSE stream with progress events and final result
                  value:
                  - event: progress
                    data:
                      message: Loading...
                  - event: progress
                    data:
                      message: Query validated...
                  - event: progress
                    data:
                      message: Analyzing intent...
                  - event: progress
                    data:
                      message: Processing request...
                  - event: progress
                    data:
                      message: Identifying filters...
                  - event: progress
                    data:
                      message: Working on it...
                  - event: progress
                    data:
                      message: Getting the right filters...
                  - event: progress
                    data:
                      message: Analysis complete...
                  - event: progress
                    data:
                      message: Putting it all together...
                  - event: progress
                    data:
                      message: Building query...
                  - event: progress
                    data:
                      message: Query ready...
                  - event: result
                    data:
                      creatorList:
                      - displayName: YouTube
                        uniqueId: '@youtube'
                        channelId: UCBR8-60-B28hp2BmDPdntcQ
                        avatarUrl: https://yt3.googleusercontent.com/3s6evpqAiDU9tQR4sC2siJippbH2RWVPnwHgyl4V0th2iuQz0VDQZbUhQBGmsxLYo-mjG6TqZQ=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 45000000
                      - displayName: 5-Minute Crafts DIY
                        uniqueId: '@5minutecraftsdiy'
                        channelId: UC2etEuPIfohP4P53wM0KImA
                        avatarUrl: https://yt3.googleusercontent.com/dpw85Qj9vAdE4iX_yr0wUcoZkuBZqPBrlovIkePsgOzmywZdQeJpUQARG1to6mEEeqmUQlMtR-o=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 20100000
                      - displayName: 5-Minute Crafts FAMILY
                        uniqueId: '@5minutecraftsfamily'
                        channelId: UC63mNFJR8EAb8wAIJwoCmTA
                        avatarUrl: https://yt3.googleusercontent.com/jPrniMECPSuIG45SMTj4VlCxtYqQ4E4RqnZIPxJPPhm_mb1ZHV2X0MFwCh3X6R_3lLvIooVxbNE=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 15800000
                      - displayName: Kids Diana Show
                        uniqueId: '@kidsdianashow'
                        channelId: UCk8GzjMOrta8yxDcKfylJYw
                        avatarUrl: https://yt3.googleusercontent.com/G88LBGqFoBWMos0glZEdCvQ7uEMPnhBYsPRMOFX5b5z6tuqWaD6ZcscslaKu0zLO37v8sMUA=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 138000000
                      - displayName: Maria Clara & JP
                        uniqueId: '@mariaclaraejp'
                        channelId: UCKe6w0exI94U-RzqAyoY1VA
                        avatarUrl: https://yt3.googleusercontent.com/ytc/AIdro_n8EDt3qdYql9Dt6WAZDlb_7Af8wIukpc3h3cAbCptHNUg=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 50200000
                      - displayName: Mr DegrEE
                        uniqueId: '@mrdegreeofficial'
                        channelId: UCeYTfGpNCmVhlxjQxBDrGPA
                        avatarUrl: https://yt3.googleusercontent.com/ytc/AIdro_k8LXkXtQX2Skbr0NZ2jzNO-_j-Bu2T80hWwDUs3eL2ZCg=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 40400000
                      - displayName: SMOL
                        uniqueId: '@smol_official'
                        channelId: UCBBZ7No0AzEJ3qiatjSa-mg
                        avatarUrl: https://yt3.googleusercontent.com/QSq4dqpufwELLxjadoLE8CghxJ12tfu4vGUM8t2YiwztzAyYtPvSKN59nH_lEd02vPQfnQ3L2Q=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 27200000
                      - displayName: Fabiosa Best Lifehacks
                        uniqueId: '@fabiosabestlifehacks'
                        channelId: UCF5Rp2ghzXsX6vwYqa7aepg
                        avatarUrl: https://yt3.googleusercontent.com/g9YIHarU8-wUSH5lnFRNg9e9RBT9EHv21rlP7r10lHwmpALsDzt-jiSkVzBxTUyDBQjK3Hz1hA=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 25900000
                      - displayName: James Charles
                        uniqueId: '@jamescharles'
                        channelId: UCucot-Zp428OwkyRm2I7v2Q
                        avatarUrl: https://yt3.googleusercontent.com/6WC8rRE_1ME7Sza7y-Z75g_wGahOKlyRevH2hOE9DNMrHM37ZYCmNGBnJpJWqhUpy0-c05xQcjk=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 23900000
                      - displayName: Troom Troom
                        uniqueId: '@troomtroom'
                        channelId: UCWwqHwqLSrdWMgp5DZG5Dzg
                        avatarUrl: https://yt3.googleusercontent.com/KxkUWubksdvmkXC6dKk_JuJF40McZgmDYWcclmNJHAuhDnZGpVA9-sdW75q9MTCZ-NE2z3yBfY0=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 23800000
                      - displayName: Marusya Outdoors
                        uniqueId: '@marusya_outdoors'
                        channelId: UCRR3vpGoVKF3q_vZI7mCfjQ
                        avatarUrl: https://yt3.googleusercontent.com/JNVo_OhRKlrCe4lTIehltRomjHGhAwADSeliVky8KSpwqfeaZ2Y7QCCUiOPVIfFt6XLzCwNE=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 20600000
                      - displayName: Dr Ryan
                        uniqueId: '@itsdrryan'
                        channelId: UC26FEMwAAjj8jfNbuVdFMBQ
                        avatarUrl: https://yt3.googleusercontent.com/8XsSINxf0myiTvCb-KByq8eLOQMDg7en6Mxdap1YlbddXyvyBypr5lCaSi98KJhSOCwD9z5gxQ=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 20000000
                      - displayName: VICE
                        uniqueId: '@vice'
                        channelId: UCn8zNIfYAQNdrFRrr8oibKw
                        avatarUrl: https://yt3.googleusercontent.com/9AgWUnohXk3gFYvmvAZemlr1q6yd7NxHozeEqrPpJhYf9Crjrvqml0ulZ4PL4v38I4XDoLEhaw=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 19100000
                      - displayName: Crafty Panda
                        uniqueId: '@craftypanda'
                        channelId: UC03RvJoIhm_fMwlUpm9ZvFw
                        avatarUrl: https://yt3.googleusercontent.com/ytc/AIdro_kI-gjxVAiZh-LDX0ayqKKSQL-qIxrCG7qi3Q2IQNeTamk=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 19000000
                      - displayName: Ray William Johnson
                        uniqueId: '@raywilliamjohnson'
                        channelId: UCGt7X90Au6BV8rf49BiM6Dg
                        avatarUrl: https://yt3.googleusercontent.com/y_myu5CoUFndBkJ5sZFCiSoi-rM6UY-x-Wog6C7nl_6pgXt9M0Z-YPfVCHSvIYS5PlyRidhE=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 18700000
                      - displayName: JULIA GISELLA
                        uniqueId: '@juliagisella'
                        channelId: UCCPsBYxLUykj5xbgOGTRzKQ
                        avatarUrl: https://yt3.googleusercontent.com/2n0OZs6fyMF6lvszolH4Pe5s-4koRhrWR7R2julWoeKwnAsLgUTS_6COm0CnGzuf5vIhLvepsNw=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 18100000
                      - displayName: Jennifer Lopez
                        uniqueId: '@jenniferlopez'
                        channelId: UCr8RjWUQ_9KYcIPmWiqBroQ
                        avatarUrl: https://yt3.googleusercontent.com/u0IEPhk-hqU3pbeBNAPf5EQRwQs2mnT1-3rRQaGt3pXhf6lhQgFk3j6LQfupRNV0iYIU4BeIQJw=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 17500000
                      - displayName: Vogue
                        uniqueId: '@vogue'
                        channelId: UCRXiA3h1no_PFkb1JCP0yMA
                        avatarUrl: https://yt3.googleusercontent.com/pjWEB6VpO5GmzI7aGg6pAjkNSdLf75LKoUXmmj2HAs1Fq1V1zlcevvR4hf7J9VtV7fYxaYJHS8g=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 16200000
                      - displayName: MrBeast
                        uniqueId: '@mrbeast'
                        channelId: UCX6OQ3DkcsbYNE6H8uQQuVA
                        avatarUrl: https://yt3.googleusercontent.com/nxYrc_1_2f77DoBadyxMTmv7ZpRZapHR5jbuYe7PlPd5cIRJxtNNEYyOC0ZsxaDyJJzXrnJiuDE=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 473000000
                      - displayName: Alan's Universe
                        uniqueId: '@alanchikinchow'
                        channelId: UC5gxP-2QqIh_09djvlm9Xcg
                        avatarUrl: https://yt3.googleusercontent.com/QYrADJNN_BMJSYm0LkqAs13ehWHjtxITE7kSBPsEIB_I_VFeDvujpH4aJfHfJO3FsFMsYa6Oig=s900-c-k-c0x00ffffff-no-rj
                        totalSubscribers: 100000000
                      platform: youtube
                    traceId: 6ddf6c22a7a84b83e9a98f70a06e6235
                    timestamp: 1774586488186
                    creditsAvailable: 2627.89
                    creditsUsed: 3.04
                    errorCode: ''
                    errorDescription: ''
                    success: true
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                type: object
                title: ValidationErrorResponse
                properties:
                  success:
                    const: false
                  error:
                    type: string
                  message:
                    type: string
                  timestamp:
                    type: integer
                required:
                - success
                - error
                - message
                - timestamp
              examples:
                missing description:
                  summary: Missing description field
                  value:
                    success: false
                    error: VALIDATION_ERROR
                    message: 'Missing required field: ''description''.'
                    timestamp: 1770099403116
                description too long:
                  summary: Description exceeds 1000 characters
                  value:
                    success: false
                    error: VALIDATION_ERROR
                    message: The 'description' field must be between 1 and 1000 characters.
                    timestamp: 1770099403116
        '429':
          description: Exceeded quota or rate limit.
          content:
            application/json:
              schema:
                type: object
                title: QuotaErrorResponse
                properties:
                  success:
                    const: false
                  error:
                    type: string
                  message:
                    type: string
                  remainingPlanCredit:
                    type: number
                required:
                - success
                - error
                - message
                - remainingPlanCredit
              examples:
                rate limit:
                  summary: Rate limit exceeded
                  value:
                    success: false
                    error: RATE_LIMIT_EXCEEDED
                    message: Too many requests. Please try again later.
                quota exceeded:
                  summary: Credit quota exceeded
                  value:
                    success: false
                    error: QUOTA_EXCEEDED
                    message: Not enough credits to complete this request.
      security:
      - ApiKeyAuth: []
      servers:
      - url: https://apiv3.creatordb.app
        description: Production Environment (CreatorDB Headless API V3)
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: The valid CreatorDB API key for authentication.
      name: api-key
      in: header