CreatorSearchInput

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/upriver-ai/json-schema/upriver-ai-creator-search-input-schema.json",
  "title": "CreatorSearchInput",
  "description": "Input payload for creator discovery.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/upriver-ai-openapi.json#/components/schemas/CreatorSearchInput",
  "properties": {
    "creator_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Creator Url",
      "description": "Known social media URL for the creator."
    },
    "name_or_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Name Or Handle",
      "description": "Resolve a specific creator by handle or display name. Matches exactly, by prefix, and by fuzzy substring (e.g. 'beast' finds 'MrBeast'). For discovery, use the category/follower/platform filters instead."
    },
    "creator_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Creator Name",
      "description": "Deprecated. Use `name_or_handle`.",
      "deprecated": true
    },
    "query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Query",
      "description": "Deprecated. Use `name_or_handle` for creator resolution.",
      "deprecated": true
    },
    "limit": {
      "type": "integer",
      "maximum": 50.0,
      "minimum": 1.0,
      "title": "Limit",
      "description": "Maximum number of creators to return, from 1 to 50.",
      "default": 10
    },
    "platforms": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Platforms",
      "description": "Optional platform filter. Supported platforms: instagram, podcast, spotify, substack, tiktok, twitch, x, youtube (the alias `twitter` is accepted for `x`). Any other value returns a 400 error."
    },
    "category_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Category Ids",
      "description": "Optional category filter using taxonomy IDs (e.g. technology, tech_news_lifestyle)."
    },
    "categories": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Categories",
      "description": "Free-text category keywords to filter results by content category."
    },
    "min_followers": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Min Followers",
      "description": "Optional approximate minimum based on recently observed follower counts."
    },
    "max_followers": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Max Followers",
      "description": "Optional approximate maximum based on recently observed follower counts."
    },
    "follower_bucket": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Follower Bucket",
      "description": "Approximate audience-size filter using recently observed follower counts."
    },
    "cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Cursor",
      "description": "Opaque cursor from a previous response for pagination."
    },
    "creator_country": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Creator Country",
      "description": "Filter by where creators are based, as one or more ISO 3166-1 alpha-2 country codes (e.g. US). Location coverage varies by platform, and not every creator has a known location."
    },
    "audience_country": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Audience Country",
      "description": "Filter by where a creator's audience is located, as one or more ISO 3166-1 alpha-2 country codes. Matches creators whose known audience includes any of these countries, or who are themselves based in them."
    },
    "creator_language": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Creator Language",
      "description": "Optional creator language filter."
    },
    "has_email": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Has Email",
      "description": "Filter by whether the creator has at least one public contact email available. `true` returns only creators with a contact email; `false` returns only those without; omit to include both."
    },
    "include": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Include",
      "description": "Optional response expansions, equivalent to the `include` query parameter (the two are merged). In broad/filter-only search only `email` is supported; other expansions require an exact `creator_url`."
    },
    "content_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Content Query",
      "description": "Describe the kind of content or creator you're looking for in plain language, and results are ranked by how well each creator's content matches — going beyond name and handle matching. Combine with the category, platform, follower, country, and language filters to narrow the field. When set, this drives ranking and any name/handle 'query' is not applied."
    }
  },
  "type": "object"
}