Starcovery

Search Instagram and TikTok creators with a natural-language brief. Returns ranked creators with fit score, follower count, platform, recent videos, and a shortlist enrichment ticket when available. Contact addresses stay empty until reveal_contact. Holds the call open until the result, up to 800 seconds. Each search is one use. Unsigned callers get 100 uses per rolling 24 hours per IP. Identified callers get 200 uses per rolling 24 hours, then prepaid credits. Pre-claim agent tokens skip the daily grant and use prepaid credits only. Pass creators, query.q, and ticket to enrich_creators for niche, evidence, and signal analysis.

{
  "type": "object",
  "properties": {
    "country": {
      "type": "string",
      "enum": [
        "us",
        "gb",
        "ca",
        "au",
        "de",
        "fr",
        "br",
        "jp",
        "kr",
        "in"
      ],
      "description": "ISO 3166-1 alpha-2 country code, e.g. us"
    },
    "platform": {
      "type": "string",
      "enum": [
        "ig",
        "tt"
      ],
      "description": "Filter to Instagram (ig) or TikTok (tt)"
    },
    "q": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Natural-language brief: audience, brand vibe, or campaign goal"
    },
    "tier": {
      "type": "string",
      "enum": [
        "nano",
        "micro",
        "mid",
        "macro",
        "mega",
        "nano+",
        "micro+",
        "mid+",
        "macro+",
        "micro-",
        "mid-",
        "macro-"
      ],
      "description": "Follower tier: nano 1,000 to 9,999, micro 10,000 to 49,999, mid 50,000 to 249,999, macro 250,000 to 999,999, mega 1,000,000 or more, nano+ 1,000 or more, micro+ 10,000 or more, mid+ 50,000 or more, macro+ 250,000 or more, micro- 1,000 to 49,999, mid- 1,000 to 249,999, macro- 1,000 to 999,999. A plus tier means that follower count and above, and a minus tier means that tier and every smaller one."
    }
  },
  "required": [
    "q"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

{
  "type": "object",
  "properties": {
    "creators": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "averageViews": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "Mean views of the creator's 6 newest posts with a stored video, counting the posts that have views. Null when none of them has views."
          },
          "bio": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "country": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "emails": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            },
            "description": "Contact addresses for this organization after Reveal contact. Empty until then.",
            "default": []
          },
          "engagementOnViews": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0
              },
              {
                "type": "null"
              }
            ],
            "description": "Mean of likes plus comments per view over the same posts as averageViews. Null when none of them has views."
          },
          "externalUrl": {
            "anyOf": [
              {
                "type": "string",
                "format": "uri"
              },
              {
                "type": "null"
              }
            ]
          },
          "fitScore": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "followerCount": {
            "type": "integer",
            "allOf": [
              {
                "minimum": -2147483648,
                "maximum": 2147483647
              }
            ],
            "minimum": 1000
          },
          "hasContact": {
            "type": "boolean",
            "description": "True when a contact address exists. The address is omitted until this organization reveals it.",
            "default": false
          },
          "id": {
            "type": "string",
            "minLength": 1
          },
          "isVerified": {
            "type": "boolean"
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "platform": {
            "type": "string",
            "enum": [
              "ig",
              "tt"
            ]
          },
          "profileImageUrl": {
            "anyOf": [
              {
                "type": "string",
                "format": "uri"
              },
              {
                "type": "null"
              }
            ]
          },
          "tier": {
            "type": "string",
            "enum": [
              "nano",
              "micro",
              "mid",
              "macro",
              "mega"
            ]
          },
          "username": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "videos": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "bunnyStreamId": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "caption": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Video caption, truncated to the first 500 characters."
                },
                "commentCount": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                },
                "id": {
                  "type": "string",
                  "minLength": 1
                },
                "isAd": {
                  "type": "boolean"
                },
                "isSponsored": {
                  "type": "boolean"
                },
                "likeCount": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                },
                "playCount": {
                  "anyOf": [
                    {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "playUrl": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "uri"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Signed video URL. It expires within 24 hours. Search again for a new URL."
                },
                "postedAt": {
                  "type": "string",
                  "format": "date-time",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}[Tt](?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:[Zz]|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$"
                },
                "score": {
                  "type": "number"
                },
                "thumbnailUrl": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "uri"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Signed thumbnail URL. It expires within 24 hours. Search again for a new URL."
                },
                "webUrl": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "required": [
                "bunnyStreamId",
                "caption",
                "commentCount",
                "id",
                "isAd",
                "isSponsored",
                "likeCount",
                "playCount",
                "playUrl",
                "postedAt",
                "score",
                "thumbnailUrl",
                "webUrl"
              ],
              "additionalProperties": true
            }
          }
        },
        "required": [
          "averageViews",
          "bio",
          "country",
          "engagementOnViews",
          "fitScore",
          "followerCount",
          "id",
          "isVerified",
          "name",
          "platform",
          "profileImageUrl",
          "tier",
          "username",
          "videos"
        ],
        "additionalProperties": true
      }
    },
    "query": {
      "type": "object",
      "properties": {
        "country": {
          "type": "string",
          "enum": [
            "us",
            "gb",
            "ca",
            "au",
            "de",
            "fr",
            "br",
            "jp",
            "kr",
            "in"
          ],
          "description": "ISO 3166-1 alpha-2 country code, e.g. us"
        },
        "platform": {
          "type": "string",
          "enum": [
            "ig",
            "tt"
          ],
          "description": "Filter to Instagram (ig) or TikTok (tt)"
        },
        "q": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "description": "Natural-language brief: audience, brand vibe, or campaign goal"
        },
        "tier": {
          "type": "string",
          "enum": [
            "nano",
            "micro",
            "mid",
            "macro",
            "mega",
            "nano+",
            "micro+",
            "mid+",
            "macro+",
            "micro-",
            "mid-",
            "macro-"
          ],
          "description": "Follower tier: nano 1,000 to 9,999, micro 10,000 to 49,999, mid 50,000 to 249,999, macro 250,000 to 999,999, mega 1,000,000 or more, nano+ 1,000 or more, micro+ 10,000 or more, mid+ 50,000 or more, macro+ 250,000 or more, micro- 1,000 to 49,999, mid- 1,000 to 249,999, macro- 1,000 to 999,999. A plus tier means that follower count and above, and a minus tier means that tier and every smaller one."
        }
      },
      "required": [
        "q"
      ],
      "additionalProperties": true
    },
    "ticket": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Single-use shortlist enrichment ticket for POST /api/search/enrich, bound to the search caller. Null when the shortlist is empty or holds more than 100 creators, or when an unsigned caller has no client IP. Absent on the first NDJSON line of a streamed search."
    }
  },
  "required": [
    "creators",
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

Run shortlist AI enrichment (niche, celebrity, evidence, signal) for creators from search_creators. Pass the same creators array, query string (search query.q), and ticket. Returns one analysis object per creatorId. The ticket is single-use and bound to the search caller, and enrichment spends no credits. Holds the call open until the result, up to 800 seconds.

{
  "type": "object",
  "properties": {
    "creators": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "averageViews": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "Mean views of the creator's 6 newest posts with a stored video, counting the posts that have views. Null when none of them has views."
          },
          "bio": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "country": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "emails": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            },
            "description": "Contact addresses for this organization after Reveal contact. Empty until then.",
            "default": []
          },
          "engagementOnViews": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0
              },
              {
                "type": "null"
              }
            ],
            "description": "Mean of likes plus comments per view over the same posts as averageViews. Null when none of them has views."
          },
          "externalUrl": {
            "anyOf": [
              {
                "type": "string",
                "format": "uri"
              },
              {
                "type": "null"
              }
            ]
          },
          "fitScore": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "followerCount": {
            "type": "integer",
            "allOf": [
              {
                "minimum": -2147483648,
                "maximum": 2147483647
              }
            ],
            "minimum": 1000
          },
          "hasContact": {
            "type": "boolean",
            "description": "True when a contact address exists. The address is omitted until this organization reveals it.",
            "default": false
          },
          "id": {
            "type": "string",
            "minLength": 1
          },
          "isVerified": {
            "type": "boolean"
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "platform": {
            "type": "string",
            "enum": [
              "ig",
              "tt"
            ]
          },
          "profileImageUrl": {
            "anyOf": [
              {
                "type": "string",
                "format": "uri"
              },
              {
                "type": "null"
              }
            ]
          },
          "tier": {
            "type": "string",
            "enum": [
              "nano",
              "micro",
              "mid",
              "macro",
              "mega"
            ]
          },
          "username": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "videos": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "bunnyStreamId": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "caption": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Video caption, truncated to the first 500 characters."
                },
                "commentCount": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                },
                "id": {
                  "type": "string",
                  "minLength": 1
                },
                "isAd": {
                  "type": "boolean"
                },
                "isSponsored": {
                  "type": "boolean"
                },
                "likeCount": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                },
                "playCount": {
                  "anyOf": [
                    {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "playUrl": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "uri"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Signed video URL. It expires within 24 hours. Search again for a new URL."
                },
                "postedAt": {
                  "type": "string",
                  "format": "date-time",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}[Tt](?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:[Zz]|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$"
                },
                "score": {
                  "type": "number"
                },
                "thumbnailUrl": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "uri"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Signed thumbnail URL. It expires within 24 hours. Search again for a new URL."
                },
                "webUrl": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "required": [
                "bunnyStreamId",
                "caption",
                "commentCount",
                "id",
                "isAd",
                "isSponsored",
                "likeCount",
                "playCount",
                "playUrl",
                "postedAt",
                "score",
                "thumbnailUrl",
                "webUrl"
              ],
              "additionalProperties": true
            }
          }
        },
        "required": [
          "bio",
          "country",
          "fitScore",
          "followerCount",
          "id",
          "isVerified",
          "name",
          "platform",
          "profileImageUrl",
          "tier",
          "username",
          "videos"
        ],
        "additionalProperties": true
      },
      "description": "The creators array exactly as returned by search_creators, unmodified; the ticket is bound to it",
      "minItems": 1,
      "maxItems": 100
    },
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "The query.q string returned by search_creators"
    },
    "ticket": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32768,
      "description": "The single-use enrichment ticket returned by search_creators, bound to the same caller, query, and creators"
    }
  },
  "required": [
    "creators",
    "query",
    "ticket"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": {
    "type": "object",
    "properties": {
      "celebrity": {
        "type": "boolean"
      },
      "evidence": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "lines": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "metric": {
                      "type": "string",
                      "description": "Primary evidence metric or claim"
                    },
                    "tag": {
                      "type": "string",
                      "description": "Short supporting tag"
                    },
                    "tone": {
                      "type": "string",
                      "enum": [
                        "fit",
                        "growth",
                        "trust"
                      ]
                    }
                  },
                  "required": [
                    "metric",
                    "tag",
                    "tone"
                  ],
                  "additionalProperties": true
                },
                "minItems": 1,
                "maxItems": 3
              }
            },
            "required": [
              "lines"
            ],
            "additionalProperties": true
          },
          {
            "type": "null"
          }
        ]
      },
      "niche": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      },
      "signal": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "headline": {
                "type": "string",
                "description": "One-line signal detail; empty when kind is none"
              },
              "kind": {
                "type": "string",
                "enum": [
                  "competitor_collab",
                  "hidden_pick",
                  "none",
                  "rising"
                ]
              },
              "short": {
                "type": "string",
                "description": "Two or three word cell label; empty when kind is none"
              }
            },
            "required": [
              "headline",
              "kind",
              "short"
            ],
            "additionalProperties": true
          },
          {
            "type": "null"
          }
        ]
      }
    },
    "required": [
      "celebrity",
      "evidence",
      "niche",
      "signal"
    ],
    "additionalProperties": true
  }
}

Reveal a creator contact address. Costs 1 prepaid credit the first time this organization reveals that profile. Later calls return the address without charging. Needs a credential.

{
  "type": "object",
  "properties": {
    "profileId": {
      "type": "string",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
      "format": "uuid",
      "description": "Creator profile id from search_creators"
    }
  },
  "required": [
    "profileId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

{
  "type": "object",
  "properties": {
    "bio": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "emails": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "email"
      },
      "minItems": 1
    }
  },
  "required": [
    "bio",
    "emails"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

List the caller's campaigns with goal, status, visibility, match counts, and nextStep: the step the web app shows next, with its id, label, actor (you for the organization, starcovery, creators, or one creator by name), and line, the sentence that says what the step waits on. nextStep is null once no step is left: the campaign is done or archived, or no creator was reached or accepted. Needs a credential.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Get one campaign and its matched creators. Ordinary public campaigns are free to read for any identified caller. A private campaign reads as not found for a caller outside the organization. Contract, creator posting date, campaign details declassifying date, and disclosure are present for members of the organization and may be null on open and summary reads. For members of the organization, people lists each person on the campaign once, with their profiles, their answer to the proposal, their funding (requested or funded), and their signed hire with the payout amount, paidAt (null while the payout is pending), and posts, each live post Starcovery recorded with its link, viewCount, and engagementCount (likes plus comments); people also lists a hire that matches no creator on the campaign, and is null for other callers. Count hires and payouts from people. For members of the organization, nextStep names the step the web app shows next, as list_campaigns does; it is null for other callers and once no step is left. currentSteps lists every step under way in campaign order in the same shape, because a step before nextStep can still wait, such as proposals Starcovery has not sent; read currentSteps, not nextStep or status, to tell whether a step is finished. It is null for other callers and empty once no step is left. Needs a credential.

{
  "type": "object",
  "properties": {
    "campaignId": {
      "type": "string",
      "minLength": 1,
      "description": "Campaign id from list_campaigns"
    }
  },
  "required": [
    "campaignId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

Create a campaign with a goal (what to advertise or attain). A campaign is public and free by default; setting visibility "private" costs 1 credit. Contract (deliverable, compensationCents, and platforms, the platforms one payment covers), creator posting date, campaign details declassifying date (embargoUntil), disclosure, and marketInformation are accepted. Optional creators adds them as manual matches in the same call, as add_campaign_matches does, and the result carries matches with the added and present counts; a creator id outside the catalog fails the call before anything is created or charged. Needs a credential.

{
  "type": "object",
  "properties": {
    "contract": {
      "type": "object",
      "properties": {
        "compensationCents": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "creatorPostingDate": {
          "type": "string",
          "format": "date-time",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}[Tt](?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:[Zz]|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$",
          "description": "Creator posting date as an ISO 8601 timestamp. Omit when unset."
        },
        "deliverable": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        },
        "platforms": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "ig",
              "tt"
            ]
          },
          "minItems": 1,
          "maxItems": 2,
          "description": "Platforms the creator posts on for the one payment: ig for Instagram, tt for TikTok. A creator posts on each one they run."
        }
      },
      "required": [
        "compensationCents",
        "deliverable",
        "platforms"
      ],
      "additionalProperties": true,
      "description": "Compensation in USD cents, the paid deliverable, the platforms the creator posts on, and optional creator posting date."
    },
    "disclosure": {
      "type": "object",
      "properties": {
        "statement": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4000
        }
      },
      "required": [
        "statement"
      ],
      "additionalProperties": true,
      "description": "Paid partnership disclosure. Required before send."
    },
    "embargoUntil": {
      "type": "string",
      "format": "date-time",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}[Tt](?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:[Zz]|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$",
      "description": "Campaign details declassifying date as an ISO 8601 timestamp. It needs a contract in the same request. Omit when unset."
    },
    "goal": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Campaign goal: audience, brand vibe, or objective. Used as the generate search brief."
    },
    "idempotencyKey": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Client-generated key. A valid repeat with the same key answers with the campaign the first call created, even when its other fields differ."
    },
    "marketInformation": {
      "type": "object",
      "properties": {
        "releaseDelayMonths": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 18
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "releaseDelayMonths"
      ],
      "additionalProperties": true,
      "description": "When the campaign's name and pay per creator may join the going rate, the list of campaigns and the typical pay other organizations and creators see, which sets the platform fee: releaseDelayMonths 0 to 18 holds them back that many months after the first funding request for a fee of that many percent of the creator pool, and a releaseDelayMonths of null keeps them out for a 20 percent fee. A campaign joins no earlier than its declassifying date."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Campaign name"
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "public"
      ],
      "description": "Defaults to public. Private costs 1 credit."
    },
    "creators": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fitScore": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              {
                "type": "null"
              }
            ],
            "description": "Fit score from search_creators, 0 to 1, or null when unknown"
          },
          "followerCount": {
            "type": "integer",
            "allOf": [
              {
                "minimum": -2147483648,
                "maximum": 2147483647
              }
            ],
            "minimum": 1000,
            "description": "Follower count at snapshot time, at least 1000"
          },
          "name": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 200
              },
              {
                "type": "null"
              }
            ],
            "description": "Creator display name, or null"
          },
          "platform": {
            "type": "string",
            "enum": [
              "ig",
              "tt"
            ],
            "description": "ig for Instagram or tt for TikTok"
          },
          "profileId": {
            "type": "string",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
            "format": "uuid",
            "description": "Creator profile id from search_creators"
          },
          "profileImageUrl": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2048
              },
              {
                "type": "null"
              }
            ],
            "description": "Portrait URL from search_creators, or null"
          },
          "username": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 100
              },
              {
                "type": "null"
              }
            ],
            "description": "Creator handle from search_creators, or null"
          }
        },
        "required": [
          "fitScore",
          "followerCount",
          "name",
          "platform",
          "profileId",
          "profileImageUrl",
          "username"
        ],
        "additionalProperties": true
      },
      "description": "Creators to add to the new campaign, as search_creators or get_list returns them",
      "minItems": 1,
      "maxItems": 100
    }
  },
  "required": [
    "goal",
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

Update campaign fields: name, goal, visibility, or status (draft, archived, or active; Starcovery sets active when the team sends the proposals, and active reopens an archived campaign whose proposals were sent). A campaign that is active or holds a delivery cannot return to draft, a campaign with an open send or funding request cannot be archived, and a campaign that is not archived or was never sent cannot be set active; each change returns a tool error naming the reason. Changing visibility to private costs 1 credit; already-private updates do not. Contract (deliverable, compensationCents, and platforms, the platforms one payment covers), creator posting date, campaign details declassifying date (embargoUntil), disclosure, and marketInformation are accepted. Null marketInformation clears it. After the campaign's first funding request, a changed or cleared marketInformation returns a tool error naming the reason. After Starcovery sends the proposals, a changed or cleared contract returns a tool error naming the reason; omit contract to change the other fields. Needs a credential.

{
  "type": "object",
  "properties": {
    "goal": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Campaign goal, also the brief for generate_campaign_matches"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Campaign name"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "archived",
        "draft"
      ],
      "description": "draft, archived, or active. Starcovery sets active when the team sends the proposals; active reopens an archived campaign whose proposals were sent."
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "public"
      ],
      "description": "Public is free. Private costs 1 credit."
    },
    "contract": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "compensationCents": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "creatorPostingDate": {
              "type": "string",
              "format": "date-time",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}[Tt](?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:[Zz]|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$",
              "description": "Creator posting date as an ISO 8601 timestamp. Omit when unset."
            },
            "deliverable": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2000
            },
            "platforms": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "ig",
                  "tt"
                ]
              },
              "minItems": 1,
              "maxItems": 2,
              "description": "Platforms the creator posts on for the one payment: ig for Instagram, tt for TikTok. A creator posts on each one they run."
            }
          },
          "required": [
            "compensationCents",
            "deliverable",
            "platforms"
          ],
          "additionalProperties": true,
          "description": "Compensation in USD cents, the paid deliverable, the platforms the creator posts on, and optional creator posting date."
        },
        {
          "type": "null"
        }
      ],
      "description": "Null clears stored contract metadata. A stored declassifying date needs a contract, so clear embargoUntil in the same patch."
    },
    "disclosure": {
      "type": "object",
      "properties": {
        "statement": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4000
        }
      },
      "required": [
        "statement"
      ],
      "additionalProperties": true,
      "description": "Paid partnership disclosure. Required before send."
    },
    "embargoUntil": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}[Tt](?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:[Zz]|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$",
          "description": "Campaign details declassifying date as an ISO 8601 timestamp."
        },
        {
          "type": "null"
        }
      ],
      "description": "Campaign details declassifying date as an ISO 8601 timestamp. Null clears it."
    },
    "marketInformation": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "releaseDelayMonths": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 18
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "releaseDelayMonths"
          ],
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ],
      "description": "When the campaign's name and pay per creator may join the going rate, the list of campaigns and the typical pay other organizations and creators see, which sets the platform fee: releaseDelayMonths 0 to 18 holds them back that many months after the first funding request for a fee of that many percent of the creator pool, and a releaseDelayMonths of null keeps them out for a 20 percent fee. A campaign joins no earlier than its declassifying date. Null clears the answer. After the first funding request, a change or a clear is refused."
    },
    "campaignId": {
      "type": "string",
      "minLength": 1,
      "description": "Campaign id from list_campaigns"
    }
  },
  "required": [
    "campaignId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

Delete a campaign and its matches. A funded campaign, a campaign with a signed hire, or a campaign with a proposal delivery returns a tool error naming the reason. Needs a credential.

{
  "type": "object",
  "properties": {
    "campaignId": {
      "type": "string",
      "minLength": 1,
      "description": "Campaign id from list_campaigns"
    }
  },
  "required": [
    "campaignId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

Generate creator matches from the campaign goal. Runs one creator search (same daily grant and prepaid credits as search_creators; pre-claim agent tokens spend prepaid credits only) and saves matches; idempotent on (campaign, profileId). Optional filters narrow the search. Holds the call open until the result, up to 800 seconds. While a send request is open, once the campaign is sent, or while it is archived, it returns a tool error naming the reason before any search runs. Needs a credential.

{
  "type": "object",
  "properties": {
    "country": {
      "type": "string",
      "enum": [
        "us",
        "gb",
        "ca",
        "au",
        "de",
        "fr",
        "br",
        "jp",
        "kr",
        "in"
      ],
      "description": "ISO 3166-1 alpha-2 country code"
    },
    "platform": {
      "type": "string",
      "enum": [
        "ig",
        "tt"
      ],
      "description": "Instagram (ig) or TikTok (tt)"
    },
    "tier": {
      "type": "string",
      "enum": [
        "nano",
        "micro",
        "mid",
        "macro",
        "mega",
        "nano+",
        "micro+",
        "mid+",
        "macro+",
        "micro-",
        "mid-",
        "macro-"
      ],
      "description": "Follower tier: nano 1,000 to 9,999, micro 10,000 to 49,999, mid 50,000 to 249,999, macro 250,000 to 999,999, mega 1,000,000 or more, nano+ 1,000 or more, micro+ 10,000 or more, mid+ 50,000 or more, macro+ 250,000 or more, micro- 1,000 to 49,999, mid- 1,000 to 249,999, macro- 1,000 to 999,999. A plus tier means that follower count and above, and a minus tier means that tier and every smaller one."
    },
    "campaignId": {
      "type": "string",
      "minLength": 1,
      "description": "Campaign id from list_campaigns"
    }
  },
  "required": [
    "campaignId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

Add a creator as a manual match to a campaign. Idempotent on (campaign, profileId). Stores the platform, handle, name, picture, and follower count of the catalog profile and keeps only profileId and fitScore from the input; a profileId with no catalog profile returns not_found. While a send request is open, once the campaign is sent, or while it is archived, it returns a tool error naming the reason. Needs a credential.

{
  "type": "object",
  "properties": {
    "fitScore": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        {
          "type": "null"
        }
      ],
      "description": "Fit score from search_creators, 0 to 1, or null when unknown"
    },
    "followerCount": {
      "type": "integer",
      "allOf": [
        {
          "minimum": -2147483648,
          "maximum": 2147483647
        }
      ],
      "minimum": 1000,
      "description": "Follower count at snapshot time, at least 1000"
    },
    "name": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ],
      "description": "Creator display name, or null"
    },
    "platform": {
      "type": "string",
      "enum": [
        "ig",
        "tt"
      ],
      "description": "ig for Instagram or tt for TikTok"
    },
    "profileId": {
      "type": "string",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
      "format": "uuid",
      "description": "Creator profile id from search_creators"
    },
    "profileImageUrl": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 2048
        },
        {
          "type": "null"
        }
      ],
      "description": "Portrait URL from search_creators, or null"
    },
    "username": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 100
        },
        {
          "type": "null"
        }
      ],
      "description": "Creator handle from search_creators, or null"
    },
    "campaignId": {
      "type": "string",
      "minLength": 1,
      "description": "Campaign id from list_campaigns"
    }
  },
  "required": [
    "fitScore",
    "followerCount",
    "name",
    "platform",
    "profileId",
    "profileImageUrl",
    "username",
    "campaignId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

Add several creators as manual matches to a campaign in one call. Idempotent on (campaign, profileId). Stores the platform, handle, name, picture, and follower count of each catalog profile, keeps only profileId and fitScore from the input, and drops a profileId with no catalog profile. Returns added, the count of new matches, and present, the count already on the campaign, with addedCreators and presentCreators, the same counts per person, so a person with two matched profiles counts once. A campaign outside the caller's organization returns not_found. While a send request is open, once the campaign is sent, or while it is archived, it returns a tool error naming the reason. Needs a credential.

{
  "type": "object",
  "properties": {
    "campaignId": {
      "type": "string",
      "minLength": 1,
      "description": "Campaign id from list_campaigns"
    },
    "creators": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fitScore": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              {
                "type": "null"
              }
            ],
            "description": "Fit score from search_creators, 0 to 1, or null when unknown"
          },
          "followerCount": {
            "type": "integer",
            "allOf": [
              {
                "minimum": -2147483648,
                "maximum": 2147483647
              }
            ],
            "minimum": 1000,
            "description": "Follower count at snapshot time, at least 1000"
          },
          "name": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 200
              },
              {
                "type": "null"
              }
            ],
            "description": "Creator display name, or null"
          },
          "platform": {
            "type": "string",
            "enum": [
              "ig",
              "tt"
            ],
            "description": "ig for Instagram or tt for TikTok"
          },
          "profileId": {
            "type": "string",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
            "format": "uuid",
            "description": "Creator profile id from search_creators"
          },
          "profileImageUrl": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2048
              },
              {
                "type": "null"
              }
            ],
            "description": "Portrait URL from search_creators, or null"
          },
          "username": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 100
              },
              {
                "type": "null"
              }
            ],
            "description": "Creator handle from search_creators, or null"
          }
        },
        "required": [
          "fitScore",
          "followerCount",
          "name",
          "platform",
          "profileId",
          "profileImageUrl",
          "username"
        ],
        "additionalProperties": true
      },
      "description": "The creators to add to the campaign, as search_creators or get_list returns them",
      "minItems": 1,
      "maxItems": 100
    }
  },
  "required": [
    "campaignId",
    "creators"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

Remove one matched creator from a campaign by match id. A match that already has a proposal delivery, or any match while a send request is open, once the campaign is sent, or while it is archived, returns a tool error naming the reason. Needs a credential.

{
  "type": "object",
  "properties": {
    "campaignId": {
      "type": "string",
      "minLength": 1,
      "description": "Campaign id from list_campaigns"
    },
    "matchId": {
      "type": "string",
      "minLength": 1,
      "description": "Match id from get_campaign"
    }
  },
  "required": [
    "campaignId",
    "matchId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

List the files attached to a campaign of the caller's organization, with id, filename, content type, byte size, and upload time. Returns no file contents. A campaign outside the caller's organization returns not_found. Needs a credential.

{
  "type": "object",
  "properties": {
    "campaignId": {
      "type": "string",
      "minLength": 1,
      "description": "Campaign id from list_campaigns"
    }
  },
  "required": [
    "campaignId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

Delete one file attached to a campaign of the caller's organization. Irreversible. An attachment or a campaign outside the caller's organization returns not_found. Needs a credential.

{
  "type": "object",
  "properties": {
    "attachmentId": {
      "type": "string",
      "minLength": 1,
      "description": "Attachment id from list_campaign_attachments"
    },
    "campaignId": {
      "type": "string",
      "minLength": 1,
      "description": "Campaign id from list_campaigns"
    }
  },
  "required": [
    "attachmentId",
    "campaignId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

Export a campaign as CSV (Rank, Handle, Name, Platform, Followers, Fit, Source). Same access as get_campaign. Needs a credential.

{
  "type": "object",
  "properties": {
    "campaignId": {
      "type": "string",
      "minLength": 1,
      "description": "Campaign id from list_campaigns"
    }
  },
  "required": [
    "campaignId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

Request a proposal send for a draft campaign the caller's organization owns. Starcovery Proposals runs concierge: this call records one open send request and notifies the Starcovery team, who send the proposals from the staff queue. Nothing is mailed by this call. Needs a saved contract whose creator posting date, when set, is today or a later day in UTC, a captured disclosure, and at least one match. Returns a tool error naming the reason when the campaign is not the caller's, a step is missing, a request is already open, or the campaign is already sent. Returns the request row. Needs a credential.

{
  "type": "object",
  "properties": {
    "campaignId": {
      "type": "string",
      "minLength": 1,
      "description": "Campaign id from list_campaigns"
    }
  },
  "required": [
    "campaignId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

{
  "type": "object",
  "properties": {
    "request": {
      "type": "object",
      "properties": {
        "amountCents": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "Null for a send request."
        },
        "campaignId": {
          "type": "string"
        },
        "createdAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}[Tt](?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:[Zz]|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$"
            },
            {
              "type": "string",
              "format": "date-time",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}[Tt](?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:[Zz]|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$"
            }
          ]
        },
        "id": {
          "type": "string"
        },
        "kind": {
          "type": "string",
          "enum": [
            "fund",
            "send"
          ]
        },
        "requestedBy": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "resolvedAt": {
          "anyOf": [
            {
              "anyOf": [
                {
                  "type": "string",
                  "format": "date-time",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}[Tt](?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:[Zz]|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$"
                },
                {
                  "type": "string",
                  "format": "date-time",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}[Tt](?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:[Zz]|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$"
                }
              ]
            },
            {
              "type": "null"
            }
          ],
          "description": "Null while the request is open. Set when staff send the campaign."
        }
      },
      "required": [
        "amountCents",
        "campaignId",
        "createdAt",
        "id",
        "kind",
        "requestedBy",
        "resolvedAt"
      ],
      "additionalProperties": true
    }
  },
  "required": [
    "request"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

Request campaign funding for a campaign the caller's organization owns. Starcovery Payouts runs concierge: this call records one open funding request for the accepted creators not yet funded, per person, with the quoted total (compensation per creator times those people, plus the platform fee that the market information answer sets), and notifies the Starcovery team, who invoice the organization. No money moves by this call. Only organization owners and admins may call it. Needs a saved contract, an answered market information question, and at least one creator who accepted and is not yet funded. Returns a tool error naming the reason when the campaign is not the caller's, it is archived, a step is missing, or a request is already open; reopen an archived campaign with update_campaign status active first. The reason creators_changed means a creator accepted while the request was prepared, and the caller repeats the same call. Returns the request row with amountCents set to the quoted total. Needs a credential.

{
  "type": "object",
  "properties": {
    "campaignId": {
      "type": "string",
      "minLength": 1,
      "description": "Campaign id from list_campaigns"
    }
  },
  "required": [
    "campaignId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

{
  "type": "object",
  "properties": {
    "request": {
      "type": "object",
      "properties": {
        "amountCents": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "Quoted total in whole cents."
        },
        "campaignId": {
          "type": "string"
        },
        "createdAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}[Tt](?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:[Zz]|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$"
            },
            {
              "type": "string",
              "format": "date-time",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}[Tt](?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:[Zz]|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$"
            }
          ]
        },
        "id": {
          "type": "string"
        },
        "kind": {
          "type": "string",
          "enum": [
            "fund",
            "send"
          ]
        },
        "requestedBy": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "resolvedAt": {
          "anyOf": [
            {
              "anyOf": [
                {
                  "type": "string",
                  "format": "date-time",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}[Tt](?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:[Zz]|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$"
                },
                {
                  "type": "string",
                  "format": "date-time",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}[Tt](?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:[Zz]|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$"
                }
              ]
            },
            {
              "type": "null"
            }
          ],
          "description": "Null while the request is open. Set when staff record the reserve."
        }
      },
      "required": [
        "amountCents",
        "campaignId",
        "createdAt",
        "id",
        "kind",
        "requestedBy",
        "resolvedAt"
      ],
      "additionalProperties": true
    }
  },
  "required": [
    "request"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

Show the current credential, the bound user and organization, and whether the next search draws from the user daily grant or the organization balance. Needs a credential.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "billing": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "balance": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "cardOnFile": {
              "type": "boolean"
            },
            "lastPack": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "25",
                    "100",
                    "500",
                    "2000"
                  ],
                  "description": "Prepaid credit pack, named by its price in US dollars. Credits are $0.05 each, and larger packs add bonus credits."
                },
                {
                  "type": "null"
                }
              ]
            },
            "dailySearches": {
              "type": "null"
            },
            "freeGrant": {
              "type": "string",
              "enum": [
                "none"
              ]
            }
          },
          "required": [
            "balance",
            "cardOnFile",
            "lastPack",
            "dailySearches",
            "freeGrant"
          ],
          "additionalProperties": true
        },
        {
          "type": "object",
          "properties": {
            "balance": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "cardOnFile": {
              "type": "boolean"
            },
            "lastPack": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "25",
                    "100",
                    "500",
                    "2000"
                  ],
                  "description": "Prepaid credit pack, named by its price in US dollars. Credits are $0.05 each, and larger packs add bonus credits."
                },
                {
                  "type": "null"
                }
              ]
            },
            "dailySearches": {
              "type": "object",
              "properties": {
                "limit": {
                  "type": "integer",
                  "maximum": 9007199254740991,
                  "exclusiveMinimum": 0
                },
                "remaining": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                },
                "resetAt": {
                  "type": "integer",
                  "maximum": 9007199254740991,
                  "exclusiveMinimum": 0
                }
              },
              "required": [
                "limit",
                "remaining",
                "resetAt"
              ],
              "additionalProperties": true
            },
            "freeGrant": {
              "type": "string",
              "enum": [
                "identified_daily"
              ]
            }
          },
          "required": [
            "balance",
            "cardOnFile",
            "lastPack",
            "dailySearches",
            "freeGrant"
          ],
          "additionalProperties": true
        }
      ]
    },
    "credential": {
      "type": "object",
      "properties": {
        "id": {
          "anyOf": [
            {
              "type": "string",
              "minLength": 1
            },
            {
              "type": "null"
            }
          ]
        },
        "kind": {
          "type": "string",
          "enum": [
            "api_key",
            "oauth",
            "session"
          ]
        },
        "name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "prefix": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "id",
        "kind",
        "name",
        "prefix"
      ],
      "additionalProperties": true
    },
    "nextSearchCreditSource": {
      "type": "string",
      "enum": [
        "user_free_grant",
        "organization_balance"
      ]
    },
    "organizationId": {
      "type": "string",
      "minLength": 1
    },
    "searchCreditOrder": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "user_free_grant",
          "organization_balance"
        ]
      }
    },
    "userId": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "billing",
    "credential",
    "nextSearchCreditSource",
    "organizationId",
    "searchCreditOrder",
    "userId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

Read the prepaid credit balance, the identified daily search grant status, the last pack, and whether a card is on file. Does not start checkout or change payment settings. Needs a credential.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List API keys for the active organization (id, name, prefix, timestamps). An owner or admin sees every key; a member sees only the keys they minted. Never returns plaintext keys. Needs a credential other than an agent access token or an OAuth access token.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Mint a new API key. Returns the plaintext key once; store it immediately. Needs a credential other than an agent access token or an OAuth access token.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Key label; must not start with agent:"
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

Revoke an API key by id. An owner or admin revokes any key of the organization; a member revokes only a key they minted, and another key returns not_found. Irreversible. Needs a credential other than an agent access token or an OAuth access token.

{
  "type": "object",
  "properties": {
    "keyId": {
      "type": "string",
      "minLength": 1,
      "description": "API key id from list_api_keys"
    }
  },
  "required": [
    "keyId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

Run the next turn of a search thread and return the settled brief, its filters, the operations the turn ran, the reply, and the creators of the thread result set with a shortlist enrichment ticket. Omit threadId to open a new thread; the threadId in the result is the durable handle for the next turn. A pasted website address is read into a brief; anything else refines the brief, or answers a question about the organization's campaigns, Lists, credits, or API keys from read tools without changing them. Sends notifications/progress when the caller passes a progressToken. MCP cannot stream a tool result, so the call is blocking and waits until the turn ends, up to 800 seconds. Each turn costs 1 use plus 1 for each search and each exclusion it runs, from the same daily grant as search_creators and then 1 prepaid credit each. A refinement returns the set it built; the first brief runs one search for its creators, billed like search_creators. The thread stores the set, so reading it again with GET /api/threads/{threadId}/results is free. When the allowance runs out, exhausted is set and creators is empty; a turn that finds it spent runs nothing. Needs a credential.

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "The turn text: what to search for, what to change in the running search, or a website address to read into a brief"
    },
    "threadId": {
      "type": "string",
      "minLength": 1,
      "description": "Thread id from a previous call. Omit to open a new thread"
    }
  },
  "required": [
    "message"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

Keep the creators that appear in both lists, in the order of the left list. Nothing is stored. Map a search_creators result to the saved creator shape first: profileId is the creator id, and fitScore, followerCount, name, platform, profileImageUrl, and username carry over. Needs a credential.

{
  "type": "object",
  "properties": {
    "left": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fitScore": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              {
                "type": "null"
              }
            ],
            "description": "Fit score from search_creators, 0 to 1, or null when unknown"
          },
          "followerCount": {
            "type": "integer",
            "allOf": [
              {
                "minimum": -2147483648,
                "maximum": 2147483647
              }
            ],
            "minimum": 1000,
            "description": "Follower count at snapshot time, at least 1000"
          },
          "name": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 200
              },
              {
                "type": "null"
              }
            ],
            "description": "Creator display name, or null"
          },
          "platform": {
            "type": "string",
            "enum": [
              "ig",
              "tt"
            ],
            "description": "ig for Instagram or tt for TikTok"
          },
          "profileId": {
            "type": "string",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
            "format": "uuid",
            "description": "Creator profile id from search_creators"
          },
          "profileImageUrl": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2048
              },
              {
                "type": "null"
              }
            ],
            "description": "Portrait URL from search_creators, or null"
          },
          "username": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 100
              },
              {
                "type": "null"
              }
            ],
            "description": "Creator handle from search_creators, or null"
          }
        },
        "required": [
          "fitScore",
          "followerCount",
          "name",
          "platform",
          "profileId",
          "profileImageUrl",
          "username"
        ],
        "additionalProperties": true
      },
      "description": "First creator list; the result keeps this order",
      "minItems": 1
    },
    "right": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fitScore": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              {
                "type": "null"
              }
            ],
            "description": "Fit score from search_creators, 0 to 1, or null when unknown"
          },
          "followerCount": {
            "type": "integer",
            "allOf": [
              {
                "minimum": -2147483648,
                "maximum": 2147483647
              }
            ],
            "minimum": 1000,
            "description": "Follower count at snapshot time, at least 1000"
          },
          "name": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 200
              },
              {
                "type": "null"
              }
            ],
            "description": "Creator display name, or null"
          },
          "platform": {
            "type": "string",
            "enum": [
              "ig",
              "tt"
            ],
            "description": "ig for Instagram or tt for TikTok"
          },
          "profileId": {
            "type": "string",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
            "format": "uuid",
            "description": "Creator profile id from search_creators"
          },
          "profileImageUrl": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2048
              },
              {
                "type": "null"
              }
            ],
            "description": "Portrait URL from search_creators, or null"
          },
          "username": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 100
              },
              {
                "type": "null"
              }
            ],
            "description": "Creator handle from search_creators, or null"
          }
        },
        "required": [
          "fitScore",
          "followerCount",
          "name",
          "platform",
          "profileId",
          "profileImageUrl",
          "username"
        ],
        "additionalProperties": true
      },
      "description": "Second creator list",
      "minItems": 1
    }
  },
  "required": [
    "left",
    "right"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

Save a set of creators as a List for the organization, with the brief and filters of the search that produced it. The List takes the name in name, or a name cut from the brief when name is omitted, with a number from 2 appended when another List of the organization holds that name. Map a search_creators result to the saved creator shape first: profileId is the creator id, and fitScore, followerCount, name, platform, profileImageUrl, and username carry over. The List stores the platform, handle, name, picture, and follower count of each catalog profile, keeps only profileId and fitScore from the input, and drops a profileId with no catalog profile. Returns the saved List summary. Needs a credential.

{
  "type": "object",
  "properties": {
    "country": {
      "type": "string",
      "enum": [
        "us",
        "gb",
        "ca",
        "au",
        "de",
        "fr",
        "br",
        "jp",
        "kr",
        "in"
      ],
      "description": "ISO 3166-1 alpha-2 country code, e.g. us"
    },
    "platform": {
      "type": "string",
      "enum": [
        "ig",
        "tt"
      ],
      "description": "Filter to Instagram (ig) or TikTok (tt)"
    },
    "q": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Natural-language brief: audience, brand vibe, or campaign goal"
    },
    "tier": {
      "type": "string",
      "enum": [
        "nano",
        "micro",
        "mid",
        "macro",
        "mega",
        "nano+",
        "micro+",
        "mid+",
        "macro+",
        "micro-",
        "mid-",
        "macro-"
      ],
      "description": "Follower tier: nano 1,000 to 9,999, micro 10,000 to 49,999, mid 50,000 to 249,999, macro 250,000 to 999,999, mega 1,000,000 or more, nano+ 1,000 or more, micro+ 10,000 or more, mid+ 50,000 or more, macro+ 250,000 or more, micro- 1,000 to 49,999, mid- 1,000 to 249,999, macro- 1,000 to 999,999. A plus tier means that follower count and above, and a minus tier means that tier and every smaller one."
    },
    "creators": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fitScore": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              {
                "type": "null"
              }
            ],
            "description": "Fit score from search_creators, 0 to 1, or null when unknown"
          },
          "followerCount": {
            "type": "integer",
            "allOf": [
              {
                "minimum": -2147483648,
                "maximum": 2147483647
              }
            ],
            "minimum": 1000,
            "description": "Follower count at snapshot time, at least 1000"
          },
          "name": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 200
              },
              {
                "type": "null"
              }
            ],
            "description": "Creator display name, or null"
          },
          "platform": {
            "type": "string",
            "enum": [
              "ig",
              "tt"
            ],
            "description": "ig for Instagram or tt for TikTok"
          },
          "profileId": {
            "type": "string",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
            "format": "uuid",
            "description": "Creator profile id from search_creators"
          },
          "profileImageUrl": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2048
              },
              {
                "type": "null"
              }
            ],
            "description": "Portrait URL from search_creators, or null"
          },
          "username": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 100
              },
              {
                "type": "null"
              }
            ],
            "description": "Creator handle from search_creators, or null"
          }
        },
        "required": [
          "fitScore",
          "followerCount",
          "name",
          "platform",
          "profileId",
          "profileImageUrl",
          "username"
        ],
        "additionalProperties": true
      },
      "description": "The creators to keep on the List",
      "minItems": 1,
      "maxItems": 100
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "List name. Omit to name the List after the brief in q"
    }
  },
  "required": [
    "q",
    "creators"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

List the organization's saved Lists with brief, filters, creatorCount (each person once), itemCount (each saved profile), and last update. Needs a credential.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Get one List of the caller's organization with its brief, filters, and saved creators, best fit first. The creators carry the saved creator shape that add_campaign_matches, create_campaign, and intersect_lists take. A List outside the caller's organization returns not_found. Needs a credential.

{
  "type": "object",
  "properties": {
    "listId": {
      "type": "string",
      "minLength": 1,
      "description": "List id from list_lists"
    }
  },
  "required": [
    "listId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}

Delete one List of the caller's organization and its saved creators. Campaigns keep the creators added from it. Irreversible. A List outside the caller's organization returns not_found. Needs a credential.

{
  "type": "object",
  "properties": {
    "listId": {
      "type": "string",
      "minLength": 1,
      "description": "List id from list_lists"
    }
  },
  "required": [
    "listId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true
}