KOLens · Schema

DiscoveryPlanCreate

Issue #163 — the preferred field is now ``platform`` (one of ``tiktok / instagram / x / douyin``). ``data_source`` is retained for backward compat with pre-#163 callers (CLI, Cowork plugin) but emits a deprecation warning server-side and is resolved to a platform via ``discovery_platform_resolver``.

InfluencerTikTokInstagramAnalyticsArtificial Intelligence

Properties

Name Type Description
name string
keyword string
platform string User-facing platform. One of tiktok / instagram / x / douyin. The backend resolves this to an internal data_source for pipeline dispatch.
interval_hours integer
max_videos_per_run integer
region object ISO-3166 alpha-2 country code (e.g. 'US', 'JP', 'SG'). Copied onto every job the scheduler spawns from this plan; the TikTok scrape then browses as if from that country. Omit / empty = the global (US)
filters object
target_list_id object
status string draft (saved, NOT scheduled) | active (scheduler picks up) | disabled (paused). Defaults to draft — creating a plan no longer auto-schedules it; the user opts in by hitting Activate on the detail page
data_source object DEPRECATED — pass ``platform`` instead. Accepted only for backward compat with pre-#163 callers.
View JSON Schema on GitHub

JSON Schema

kolens-ai-discovery-plan-create-schema.json Raw ↑
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/kolens-ai/json-schema/kolens-ai-discovery-plan-create-schema.json",
  "title": "DiscoveryPlanCreate",
  "description": "Issue #163 — the preferred field is now ``platform`` (one of\n``tiktok / instagram / x / douyin``). ``data_source`` is retained\nfor backward compat with pre-#163 callers (CLI, Cowork plugin) but\nemits a deprecation warning server-side and is resolved to a\nplatform via ``discovery_platform_resolver``.",
  "x-generated": "2026-11-14",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/kolens-ai-openapi.json#/components/schemas/DiscoveryPlanCreate",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "title": "Name"
    },
    "keyword": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "title": "Keyword"
    },
    "platform": {
      "type": "string",
      "title": "Platform",
      "description": "User-facing platform. One of tiktok / instagram / x / douyin. The backend resolves this to an internal data_source for pipeline dispatch.",
      "default": "tiktok"
    },
    "interval_hours": {
      "type": "integer",
      "maximum": 720.0,
      "minimum": 1.0,
      "title": "Interval Hours",
      "default": 24
    },
    "max_videos_per_run": {
      "type": "integer",
      "maximum": 2000.0,
      "minimum": 1.0,
      "title": "Max Videos Per Run",
      "default": 100
    },
    "region": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Region",
      "description": "ISO-3166 alpha-2 country code (e.g. 'US', 'JP', 'SG'). Copied onto every job the scheduler spawns from this plan; the TikTok scrape then browses as if from that country. Omit / empty = the global (US) default."
    },
    "filters": {
      "anyOf": [
        {
          "$ref": "#/$defs/DiscoveryFilters"
        },
        {
          "type": "null"
        }
      ]
    },
    "target_list_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Target List Id"
    },
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "active",
        "disabled"
      ],
      "title": "Status",
      "description": "draft (saved, NOT scheduled) | active (scheduler picks up) | disabled (paused). Defaults to draft — creating a plan no longer auto-schedules it; the user opts in by hitting Activate on the detail page once they've verified the keyword + filters.",
      "default": "draft"
    },
    "data_source": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Data Source",
      "description": "DEPRECATED — pass ``platform`` instead. Accepted only for backward compat with pre-#163 callers."
    }
  },
  "type": "object",
  "required": [
    "name",
    "keyword"
  ],
  "$defs": {
    "DiscoveryFilters": {
      "properties": {
        "min_followers": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Min Followers"
        },
        "max_followers": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Max Followers"
        },
        "min_avg_views": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Min Avg Views"
        },
        "min_engagement_rate": {
          "anyOf": [
            {
              "type": "number",
              "maximum": 100.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Min Engagement Rate"
        },
        "require_email": {
          "type": "boolean",
          "title": "Require Email",
          "default": false
        },
        "roles_in": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Roles In",
          "description": "Only auto-add authors whose dominant role is in this list. Allowed values: KOL, Seller, Customer, Passenger."
        }
      },
      "type": "object",
      "title": "DiscoveryFilters",
      "description": "Filters applied to scraped KOLs before auto-adding to target_list."
    }
  }
}

Work with this as data

Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for schemas

4 MCP tools reach this
  • find_json_schemasBrowse and filter every JSON Schema in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/kolens-ai-discovery-plan-create"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.