{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/upriver-ai/json-schema/upriver-ai-creator-similar-input-schema.json",
  "title": "CreatorSimilarInput",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/upriver-ai-openapi.json#/components/schemas/CreatorSimilarInput",
  "oneOf": [
    {
      "properties": {
        "creator_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Creator Id",
          "description": "Optional Upriver creator ID whose eligible channel cluster supplies the similarity anchor. Each returned creator may qualify through one coherent channel expression; every channel in either creator's cluster does not need to match. Provide exactly one of `creator_id` or `channel_url`. Reuse the `creator_id` returned by `/v1/creators` or `/v1/creators/search`."
        },
        "limit": {
          "type": "integer",
          "maximum": 50.0,
          "minimum": 1.0,
          "title": "Limit",
          "description": "Maximum number of similar creators to return, from 1 to 50.",
          "default": 10
        },
        "platforms": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array",
              "maxItems": 3
            },
            {
              "type": "null"
            }
          ],
          "title": "Platforms",
          "description": "Optional platform filter. Supported values are instagram, tiktok, and youtube. A matching result must have an eligible channel on at least one requested platform."
        },
        "category_ids": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array",
              "maxItems": 20
            },
            {
              "type": "null"
            }
          ],
          "title": "Category Ids",
          "description": "Optional category filter using exact taxonomy IDs. A matching channel may satisfy any supplied category."
        },
        "min_followers": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Min Followers",
          "description": "Optional minimum follower/subscriber count filter."
        },
        "max_followers": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Max Followers",
          "description": "Optional maximum follower/subscriber count filter."
        },
        "creator_country": {
          "anyOf": [
            {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              ],
              "maxLength": 20
            },
            {
              "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."
        },
        "exclude_creator_ids": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array",
              "maxItems": 100
            },
            {
              "type": "null"
            }
          ],
          "title": "Exclude Creator Ids",
          "description": "Optional creator IDs to exclude from similar results."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "creator_id"
      ],
      "title": "By creator ID",
      "description": "Input payload for canonical creator-peer discovery."
    },
    {
      "properties": {
        "channel_url": {
          "anyOf": [
            {
              "type": "string",
              "minLength": 1,
              "format": "uri"
            },
            {
              "type": "null"
            }
          ],
          "title": "Channel Url",
          "description": "Optional known Instagram, TikTok, or YouTube profile URL used as a channel-specific similarity anchor. Provide exactly one of `creator_id` or `channel_url`."
        },
        "limit": {
          "type": "integer",
          "maximum": 50.0,
          "minimum": 1.0,
          "title": "Limit",
          "description": "Maximum number of similar creators to return, from 1 to 50.",
          "default": 10
        },
        "platforms": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array",
              "maxItems": 3
            },
            {
              "type": "null"
            }
          ],
          "title": "Platforms",
          "description": "Optional platform filter. Supported values are instagram, tiktok, and youtube. A matching result must have an eligible channel on at least one requested platform."
        },
        "category_ids": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array",
              "maxItems": 20
            },
            {
              "type": "null"
            }
          ],
          "title": "Category Ids",
          "description": "Optional category filter using exact taxonomy IDs. A matching channel may satisfy any supplied category."
        },
        "min_followers": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Min Followers",
          "description": "Optional minimum follower/subscriber count filter."
        },
        "max_followers": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Max Followers",
          "description": "Optional maximum follower/subscriber count filter."
        },
        "creator_country": {
          "anyOf": [
            {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              ],
              "maxLength": 20
            },
            {
              "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."
        },
        "exclude_creator_ids": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array",
              "maxItems": 100
            },
            {
              "type": "null"
            }
          ],
          "title": "Exclude Creator Ids",
          "description": "Optional creator IDs to exclude from similar results."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "channel_url"
      ],
      "title": "By channel URL",
      "description": "Input payload for canonical creator-peer discovery."
    }
  ]
}