Creator River Creators API

openapi: 3.2.0
info:
  title: Creatorriver Com Creators API
  version: '1'
  description: 'Operations tagged creators across 2 of this provider''s published API definitions: creatorriver-com-openapi.json, creatorriver-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://www.creatorriver.com/api/v1
security:
- apiKey: []
tags:
- name: Creators
paths:
  /searches:
    post:
      operationId: search_creators
      summary: Find creators by description and filters
      description: 'Searches the creator database by meaning: describe the creators you want in plain words (niche, content, audience), and optionally narrow by platform, niche, creator country, audience country, language, size, engagement rate and how recently they posted. To find creators like ones the user already knows, pass their handles or profile links as exampleCreators. Free, but each call counts against the daily search limit (see get_account). Results show each creator’s name but no handle or profile link. Pass campaignId to rank against that campaign’s brief and record the search in it.'
      tags:
      - Creators
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  minLength: 1
                  maxLength: 1000
                  description: 'The creators you want, in plain words: niche, what their content is like, who watches it'
                exampleCreators:
                  description: 'Creators to find more like: @handles or profile links, e.g. @mkbhd or https://www.tiktok.com/@khaby.lame. The query still says what they should share. Ones not found are listed in warnings'
                  maxItems: 10
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 300
                platforms:
                  description: Only creators on these platforms
                  type: array
                  items:
                    type: string
                    enum:
                    - youtube
                    - instagram
                    - tiktok
                niches:
                  description: Only creators whose main content is one of these niches. Creators who cover many topics are filed under none, so leave this out for broad lifestyle searches
                  type: array
                  items:
                    type: string
                    enum:
                    - music
                    - gaming
                    - tech
                    - beauty
                    - food
                    - sports
                    - fitness
                    - travel
                    - pets
                    - fashion
                    - health
                    - education
                    - comedy
                    - cars
                    - parenting
                markets:
                  description: 'Only creators based in these countries: two-letter codes, e.g. us, gb, jp'
                  type: array
                  items:
                    type: string
                    minLength: 1
                audienceCountries:
                  description: 'Only creators whose largest audience is in these countries: two-letter codes, e.g. us, gb, th'
                  type: array
                  items:
                    type: string
                    minLength: 1
                languages:
                  description: 'Only creators posting in these languages: two-letter codes, e.g. en, es, ja'
                  type: array
                  items:
                    type: string
                    minLength: 1
                lastPostWithinDays:
                  description: 'Only creators whose latest post is at most this many days old: 7, 14, 30, 90 or 180'
                  type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
                minFollowers:
                  description: At least this many followers
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                maxFollowers:
                  description: At most this many followers
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                minAvgViews:
                  description: At least this many average views per post
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                maxAvgViews:
                  description: At most this many average views per post
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                minEngagementRate:
                  description: 'At least this engagement rate, as a fraction: 0.02 for 2%'
                  type: number
                  minimum: 0
                  maximum: 1
                maxEngagementRate:
                  description: 'At most this engagement rate, as a fraction: 0.1 for 10%'
                  type: number
                  minimum: 0
                  maximum: 1
                campaignId:
                  description: Rank for this campaign and record the search in it
                  type: string
                  minLength: 1
                limit:
                  description: How many to return, 1-100 (default 20)
                  type: integer
                  minimum: 1
                  maximum: 100
              required:
              - query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {}
                required:
                - data
        4XX:
          description: Failure; `error.code` says what to do
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Failure; `error.code` says what to do
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://www.creatorriver.com/api/v1
  /creators/browse:
    get:
      operationId: browse_creators
      summary: List the biggest creators matching filters
      description: Lists the creators that match the filters, most followed first, with no description to match, as the dashboard’s Discover list does before a search. Free, does not count against the daily search limit and is not kept as a search. Use it for asks like the biggest beauty creators in the US; use search_creators when the user describes what the content should be about. Results show names but no handles.
      tags:
      - Creators
      parameters:
      - name: platforms
        in: query
        required: false
        description: Only creators on these platforms
        schema:
          description: Only creators on these platforms
          type: array
          items:
            type: string
            enum:
            - youtube
            - instagram
            - tiktok
        style: form
        explode: false
      - name: niches
        in: query
        required: false
        description: Only creators whose main content is one of these niches. Creators who cover many topics are filed under none, so leave this out for broad lifestyle searches
        schema:
          description: Only creators whose main content is one of these niches. Creators who cover many topics are filed under none, so leave this out for broad lifestyle searches
          type: array
          items:
            type: string
            enum:
            - music
            - gaming
            - tech
            - beauty
            - food
            - sports
            - fitness
            - travel
            - pets
            - fashion
            - health
            - education
            - comedy
            - cars
            - parenting
        style: form
        explode: false
      - name: markets
        in: query
        required: false
        description: 'Only creators based in these countries: two-letter codes, e.g. us, gb, jp'
        schema:
          description: 'Only creators based in these countries: two-letter codes, e.g. us, gb, jp'
          type: array
          items:
            type: string
            minLength: 1
        style: form
        explode: false
      - name: audienceCountries
        in: query
        required: false
        description: 'Only creators whose largest audience is in these countries: two-letter codes, e.g. us, gb, th'
        schema:
          description: 'Only creators whose largest audience is in these countries: two-letter codes, e.g. us, gb, th'
          type: array
          items:
            type: string
            minLength: 1
        style: form
        explode: false
      - name: languages
        in: query
        required: false
        description: 'Only creators posting in these languages: two-letter codes, e.g. en, es, ja'
        schema:
          description: 'Only creators posting in these languages: two-letter codes, e.g. en, es, ja'
          type: array
          items:
            type: string
            minLength: 1
        style: form
        explode: false
      - name: lastPostWithinDays
        in: query
        required: false
        description: 'Only creators whose latest post is at most this many days old: 7, 14, 30, 90 or 180'
        schema:
          description: 'Only creators whose latest post is at most this many days old: 7, 14, 30, 90 or 180'
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
      - name: minFollowers
        in: query
        required: false
        description: At least this many followers
        schema:
          description: At least this many followers
          type: integer
          minimum: 0
          maximum: 9007199254740991
      - name: maxFollowers
        in: query
        required: false
        description: At most this many followers
        schema:
          description: At most this many followers
          type: integer
          minimum: 0
          maximum: 9007199254740991
      - name: minAvgViews
        in: query
        required: false
        description: At least this many average views per post
        schema:
          description: At least this many average views per post
          type: integer
          minimum: 0
          maximum: 9007199254740991
      - name: maxAvgViews
        in: query
        required: false
        description: At most this many average views per post
        schema:
          description: At most this many average views per post
          type: integer
          minimum: 0
          maximum: 9007199254740991
      - name: minEngagementRate
        in: query
        required: false
        description: 'At least this engagement rate, as a fraction: 0.02 for 2%'
        schema:
          description: 'At least this engagement rate, as a fraction: 0.02 for 2%'
          type: number
          minimum: 0
          maximum: 1
      - name: maxEngagementRate
        in: query
        required: false
        description: 'At most this engagement rate, as a fraction: 0.1 for 10%'
        schema:
          description: 'At most this engagement rate, as a fraction: 0.1 for 10%'
          type: number
          minimum: 0
          maximum: 1
      - name: limit
        in: query
        required: false
        description: How many to return, 1-100 (default 20)
        schema:
          description: How many to return, 1-100 (default 20)
          type: integer
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {}
                required:
                - data
        4XX:
          description: Failure; `error.code` says what to do
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Failure; `error.code` says what to do
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://www.creatorriver.com/api/v1
  /creators/lookup:
    get:
      operationId: find_creator
      summary: Find a creator by handle or profile link
      description: Looks up a creator the user names by @handle or profile link, on every platform where that exact handle is in Creator River, and returns their creatorId for get_creator, add_creator or reveal_contact. Free. An empty list means Creator River does not have them.
      tags:
      - Creators
      parameters:
      - name: reference
        in: query
        required: true
        description: An @handle or a profile link, e.g. @mkbhd or https://www.youtube.com/@mkbhd
        schema:
          type: string
          minLength: 1
          maxLength: 300
          description: An @handle or a profile link, e.g. @mkbhd or https://www.youtube.com/@mkbhd
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {}
                required:
                - data
        4XX:
          description: Failure; `error.code` says what to do
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Failure; `error.code` says what to do
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://www.creatorriver.com/api/v1
  /creators/{creatorId}/similar:
    post:
      operationId: find_similar_creators
      summary: Find creators like one you already have
      description: 'Finds creators whose content is closest to one creator’s, on the same platform: pass the creatorId of a search result, no handle or unlock needed. Free, but each call counts against the daily search limit (see get_account). With campaignId, creators already in that campaign or excluded from it are left out. Results show names but no handles, as search_creators does, each with a matchScore from 0 to 1; the search is kept, so list_searches and get_search can read it again.'
      tags:
      - Creators
      parameters:
      - name: creatorId
        in: path
        required: true
        description: The creator to find more like, from search_creators or another result
        schema:
          type: string
          minLength: 1
          description: The creator to find more like, from search_creators or another result
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                campaignId:
                  description: Leave out creators this campaign already has or excluded
                  type: string
                  minLength: 1
                markets:
                  description: 'Only creators based in these countries: two-letter codes, e.g. us, gb, jp'
                  type: array
                  items:
                    type: string
                    minLength: 1
                languages:
                  description: 'Only creators posting in these languages: two-letter codes, e.g. en, es, ja'
                  type: array
                  items:
                    type: string
                    minLength: 1
                minFollowers:
                  description: At least this many followers
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                maxFollowers:
                  description: At most this many followers
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                minAvgViews:
                  description: At least this many average views per post
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                maxAvgViews:
                  description: At most this many average views per post
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                limit:
                  description: How many to return, 1-100 (default 20)
                  type: integer
                  minimum: 1
                  maximum: 100
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {}
                required:
                - data
        4XX:
          description: Failure; `error.code` says what to do
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Failure; `error.code` says what to do
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://www.creatorriver.com/api/v1
  /creators/{creatorId}:
    get:
      operationId: get_creator
      summary: Show a creator’s profile
      description: 'Returns a creator’s profile: platform, country, language, followers, views, engagement, topics, audience, recent content, estimated price and whether an email is available. Free. Until you unlock the creator, the handle, profile link and recent video titles and links are hidden. Pass campaignId to also see where the creator stands in that campaign.'
      tags:
      - Creators
      parameters:
      - name: creatorId
        in: path
        required: true
        description: Creator id, from search_creators results
        schema:
          type: string
          minLength: 1
          description: Creator id, from search_creators results
      - name: campaignId
        in: query
        required: false
        description: Also show this campaign’s progress with the creator
        schema:
          description: Also show this campaign’s progress with the creator
          type: string
          minLength: 1
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {}
                required:
                - data
        4XX:
          description: Failure; `error.code` says what to do
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Failure; `error.code` says what to do
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://www.creatorriver.com/api/v1
  /creators/{creatorId}/unlock:
    post:
      operationId: unlock_creator
      summary: Unlock a creator’s handle and profile link
      description: Unlocks the creator and returns the full profile with handle, profile link and recent video titles and links. Costs 0.5 credits the first time for each creator; unlocking again is free. It does not reveal the email address; use reveal_contact for that.
      tags:
      - Creators
      parameters:
      - name: creatorId
        in: path
        required: true
        description: Creator id, from search_creators results
        schema:
          type: string
          minLength: 1
          description: Creator id, from search_creators results
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {}
                required:
                - data
        4XX:
          description: Failure; `error.code` says what to do
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Failure; `error.code` says what to do
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://www.creatorriver.com/api/v1
  /creators/{creatorId}/save:
    post:
      operationId: save_creator
      summary: Save a creator to the account’s saved list
      description: Saves a creator to the account’s saved list, which is the user’s own bookmarks outside any campaign (the dashboard’s Saved page). Saving unlocks the creator, which costs 0.5 credits the first time for each creator; saving again is free. Pass searchId to remember where they were found.
      tags:
      - Creators
      parameters:
      - name: creatorId
        in: path
        required: true
        description: Creator id, from search_creators results
        schema:
          type: string
          minLength: 1
          description: Creator id, from search_creators results
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                searchId:
                  description: The search the creator was found in
                  type: string
                  minLength: 1
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {}
                required:
                - data
        4XX:
          description: Failure; `error.code` says what to do
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Failure; `error.code` says what to do
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: unsave_creator
      summary: Remove a creator from the saved list
      description: Removes a creator from the account’s saved list. Free; the creator stays unlocked and in any campaign.
      tags:
      - Creators
      parameters:
      - name: creatorId
        in: path
        required: true
        description: Creator id, from search_creators results
        schema:
          type: string
          minLength: 1
          description: Creator id, from search_creators results
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {}
                required:
                - data
        4XX:
          description: Failure; `error.code` says what to do
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Failure; `error.code` says what to do
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://www.creatorriver.com/api/v1
  /creators/saved:
    get:
      operationId: list_saved_creators
      summary: List saved creators
      description: Lists the creators on the account’s saved list, most recently saved first. Free.
      tags:
      - Creators
      parameters:
      - name: page
        in: query
        required: false
        description: Page number, from 1
        schema:
          description: Page number, from 1
          type: integer
          minimum: 1
          maximum: 9007199254740991
      - name: limit
        in: query
        required: false
        description: How many to return, 1-100 (default 20)
        schema:
          description: How many to return, 1-100 (default 20)
          type: integer
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {}
                required:
                - data
        4XX:
          description: Failure; `error.code` says what to do
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Failure; `error.code` says what to do
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://www.creatorriver.com/api/v1
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - unauthorized
              - not_found
              - invalid_input
              - insufficient_credits
              - rate_limited
              - conflict
              - internal
            message:
              type: string
            details:
              type: object
            requestId:
              type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: An API key from https://www.creatorriver.com/settings/apikeys
x-refined-from:
- creatorriver-com-openapi.json
- creatorriver-com-openapi.yml