{"paths":{"/api/billing/state":{"get":{"description":"Prepaid balance and auto-reload flags for identified account. Checkout and auto-reload mutations are browser-session only (not documented here).","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingState"}}},"description":"Billing state"},"401":{"description":"unauthorized: missing identity; WWW-Authenticate points at protected-resource metadata"},"429":{"description":"Rate limited"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{"SessionCookie":[]}],"summary":"Read billing state"}},"/api/campaigns":{"get":{"description":"Caller's campaigns: goal, status, visibility, match counts.","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"campaigns":{"items":{"$ref":"#/components/schemas/CampaignSummary"},"type":"array"}},"required":["campaigns"],"type":"object"}}},"description":"Campaign summaries"},"401":{"description":"unauthorized: missing identity; WWW-Authenticate points at protected-resource metadata"},"429":{"description":"Rate limited"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{"SessionCookie":[]}],"summary":"List campaigns"},"post":{"description":"Create campaign with goal. Visibility omitted defaults public and free (#397). Setting visibility private costs 1 credit (402 out-of-credits when exhausted; no Payment challenge).","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignCreate"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"campaign":{"$ref":"#/components/schemas/CampaignRow"}},"required":["campaign"],"type":"object"}}},"description":"Created campaign"},"400":{"description":"invalid_body"},"401":{"description":"unauthorized: missing identity; WWW-Authenticate points at protected-resource metadata"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutOfCredits"}}},"description":"out_of_credits when creating as private"},"429":{"description":"Rate limited"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{"SessionCookie":[]}],"summary":"Create campaign"}},"/api/campaigns/{id}":{"delete":{"description":"Delete caller-owned campaign.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"unauthorized: missing identity; WWW-Authenticate points at protected-resource metadata"},"404":{"description":"not_found"},"429":{"description":"Rate limited"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{"SessionCookie":[]}],"summary":"Delete campaign"},"get":{"description":"Fetch campaign and matches (JSON; CSV under /export). Own and public campaigns are free to read for any identified caller; private non-owned reads as 404. Anonymous callers get 401. Public reads do not spend credits (#397).","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignBody"}}},"description":"Campaign row plus matches"},"401":{"description":"unauthorized: missing identity; WWW-Authenticate points at protected-resource metadata"},"404":{"description":"not_found"},"429":{"description":"Rate limited"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{"SessionCookie":[]}],"summary":"Get campaign with matches"},"patch":{"description":"Update campaign fields: name, goal, visibility, or status (draft → active → archived operates the campaign). Changing visibility to private costs 1 credit on a public→private transition; already-private updates do not. Exhausted balance returns 402 out-of-credits (no Payment challenge).","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignPatch"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"campaign":{"$ref":"#/components/schemas/CampaignRow"}},"required":["campaign"],"type":"object"}}},"description":"Updated campaign"},"400":{"description":"invalid_body"},"401":{"description":"unauthorized: missing identity; WWW-Authenticate points at protected-resource metadata"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutOfCredits"}}},"description":"out_of_credits when setting private"},"404":{"description":"not_found"},"429":{"description":"Rate limited"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{"SessionCookie":[]}],"summary":"Update campaign"}},"/api/campaigns/{id}/export":{"get":{"description":"Download campaign as CSV attachment. Export is a full-body open: same free public access as GET /api/campaigns/{id}.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"text/csv":{"schema":{"type":"string"}}},"description":"CSV attachment"},"401":{"description":"unauthorized: missing identity; WWW-Authenticate points at protected-resource metadata"},"404":{"description":"not_found"},"429":{"description":"Rate limited"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{"SessionCookie":[]}],"summary":"Export campaign CSV"}},"/api/campaigns/{id}/generate":{"post":{"description":"Generate creator matches from stored campaign goal (owner only). Runs one creator search through same gates and credit spend as GET /api/search; saves shortlist as matches (idempotent on campaign + profileId). Optional body filters narrow search; query always comes from goal. 402 is out-of-credits without Payment challenge (machine settlement rail is on /api/search).","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"country":{"enum":["us","gb","ca","au","de","fr","br","jp","kr","in"],"type":"string"},"platform":{"enum":["ig","tt"],"type":"string"},"tier":{"enum":["nano","micro","mid","macro","mega"],"type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CampaignBody"},{"properties":{"generated":{"description":"How many searched creators landed or refreshed as matches.","type":"integer"}},"required":["generated"],"type":"object"}]}}},"description":"Campaign body plus generated count"},"400":{"description":"invalid_body"},"401":{"description":"unauthorized: missing identity; WWW-Authenticate points at protected-resource metadata"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutOfCredits"}}},"description":"out_of_credits"},"404":{"description":"not_found"},"429":{"description":"Rate limited"},"503":{"description":"Search unconfigured in this environment"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{"SessionCookie":[]}],"summary":"Generate campaign matches"}},"/api/campaigns/{id}/matches":{"post":{"description":"Add grounded creator snapshot as manual match (same fields as search results).","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedCreator"}}},"required":true},"responses":{"204":{"description":"Added"},"400":{"description":"invalid_body"},"401":{"description":"unauthorized: missing identity; WWW-Authenticate points at protected-resource metadata"},"404":{"description":"not_found"},"429":{"description":"Rate limited"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{"SessionCookie":[]}],"summary":"Add campaign match"}},"/api/campaigns/{id}/matches/{matchId}":{"delete":{"description":"Remove matched creator from campaign.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"matchId","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Removed"},"401":{"description":"unauthorized: missing identity; WWW-Authenticate points at protected-resource metadata"},"404":{"description":"not_found"},"429":{"description":"Rate limited"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{"SessionCookie":[]}],"summary":"Remove campaign match"}},"/api/keys":{"get":{"description":"List product API keys. Agent access tokens (names starting with agent:) receive 403; humans mint keys after claim via session or human-minted key.","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"keys":{"items":{"$ref":"#/components/schemas/ApiKeySummary"},"type":"array"}},"required":["keys"],"type":"object"}}},"description":"API key summaries"},"401":{"description":"unauthorized: missing identity; WWW-Authenticate points at protected-resource metadata"},"403":{"description":"forbidden: agent access token cannot manage keys"},"429":{"description":"Rate limited"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{"SessionCookie":[]}],"summary":"List API keys"},"post":{"description":"Mint product API key. Plaintext secret returned once. Agent access tokens receive 403.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyName"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"key":{"$ref":"#/components/schemas/ApiKeyCreated"}},"required":["key"],"type":"object"}}},"description":"Created key with plaintext secret"},"400":{"description":"invalid_body"},"401":{"description":"unauthorized: missing identity; WWW-Authenticate points at protected-resource metadata"},"403":{"description":"forbidden: agent access token cannot manage keys"},"429":{"description":"Rate limited"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{"SessionCookie":[]}],"summary":"Create API key"}},"/api/keys/{id}":{"delete":{"description":"Revoke product API key by id. Agent access tokens receive 403.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Revoked"},"401":{"description":"unauthorized: missing identity; WWW-Authenticate points at protected-resource metadata"},"403":{"description":"forbidden: agent access token cannot manage keys"},"404":{"description":"not_found"},"429":{"description":"Rate limited"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{"SessionCookie":[]}],"summary":"Revoke API key"}},"/api/mcp":{"post":{"description":"MCP Streamable HTTP endpoint (mcp-handler at /api/mcp). Auth: OAuth authorization_code (browser connectors), Authorization: Bearer, x-api-key, or last-resort ?api_key= (no anonymous, no session cookie). Tools: search_creators, list_campaigns, get_campaign, create_campaign, update_campaign, delete_campaign, generate_campaign_matches, add_campaign_match, remove_campaign_match, export_campaign, get_credits, list_api_keys, create_api_key, revoke_api_key. Agent access tokens cannot use list_api_keys, create_api_key, or revoke_api_key. Prefer auth.md for agent signup; path is protocol transport, not JSON CRUD API.","responses":{"200":{"description":"MCP JSON-RPC / streamable HTTP response"},"401":{"description":"unauthorized: missing or invalid credential; WWW-Authenticate challenge"},"429":{"description":"Rate limited"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{"ApiKeyQuery":[]}],"summary":"MCP Streamable HTTP"}},"/api/search":{"get":{"description":"Natural-language Instagram/TikTok creator search. Unsigned callers get 50 free searches per UTC day per IP; pre-claim agent tokens have no free grant, spend prepaid only; claimed/session/Settings-key callers spend prepaid or 100 free searches per UTC day on empty balance. Past free credits, caller gets HTTP 402 (out_of_credits) with WWW-Authenticate: Payment. Paid retries must send identity as x-api-key and settled credential as Authorization: Payment (not Bearer). Dry-run: ?force_payment=1 returns non-charging 402 challenge. Payment credential with remaining entitlement routes through paywall (never silent 200). Rejected Payment credentials return application/problem+json, not OutOfCredits JSON.","parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string"}},{"in":"query","name":"platform","required":false,"schema":{"enum":["ig","tt"],"type":"string"}},{"in":"query","name":"tier","required":false,"schema":{"enum":["nano","micro","mid","macro","mega"],"type":"string"}},{"in":"query","name":"country","required":false,"schema":{"enum":["us","gb","ca","au","de","fr","br","jp","kr","in"],"type":"string"}},{"description":"Identity for identified search; required on MPP paid retries alongside Authorization: Payment.","in":"header","name":"x-api-key","required":false,"schema":{"type":"string"}},{"description":"MPP Payment credential after settling a 402 challenge. Must be paired with x-api-key.","in":"header","name":"Authorization","required":false,"schema":{"type":"string"}},{"description":"Docs dry-run: when set to 1 with an identified caller, returns a non-charging 402 Payment challenge.","in":"query","name":"force_payment","required":false,"schema":{"enum":["1"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"}}},"description":"Ranked creator shortlist"},"400":{"description":"Invalid query"},"401":{"description":"identity_required on Payment without x-api-key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutOfCredits"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/MppPaymentProblem"}}},"description":"Two 402 bodies: application/json OutOfCredits on credit exhaustion (WWW-Authenticate: Payment); application/problem+json on rejected Payment credential (MPP diagnostic + retry challenge)."},"429":{"description":"Rate limited"}},"summary":"Search creators","x-payment-info":{"offers":[{"amount":"50","currency":"usd","description":"10 search credits (machine bundle at $0.50)","intent":"charge","method":"stripe"}]}}}},"info":{"description":"Starcovery helps you find and hire real Instagram and TikTok creators from a plain-language brief, on the web or from your agents. REST and MCP API. Search accepts unsigned callers. Campaigns, billing state, and keys accept browser session, x-api-key, or Bearer. MCP accepts OAuth, x-api-key, Bearer, or last-resort ?api_key= (no session). Machine Payments Protocol (x-payment-info) on GET /api/search when provisioned. Signup and claim at auth.md.","title":"Starcovery","version":"1.0.0"},"openapi":"3.1.0","x-service-info":{"categories":["search","creators","instagram","tiktok"],"docs":{"apiReference":"https://www.starcovery.com/agents","homepage":"https://www.starcovery.com","llms":"https://www.starcovery.com/agents"}},"components":{"schemas":{"ApiKeyCreated":{"additionalProperties":false,"properties":{"id":{"type":"string"},"key":{"description":"Plaintext secret; returned only on create","type":"string"},"name":{"type":["string","null"]}},"required":["id","key","name"],"type":"object"},"ApiKeyName":{"additionalProperties":false,"properties":{"name":{"description":"Key label; must not start with agent:","maxLength":64,"minLength":1,"type":"string"}},"required":["name"],"type":"object"},"ApiKeySummary":{"additionalProperties":false,"properties":{"createdAt":{"format":"date-time","type":"string"},"id":{"type":"string"},"lastRequest":{"format":"date-time","type":["string","null"]},"name":{"type":["string","null"]},"start":{"description":"Key prefix for display","type":["string","null"]}},"required":["createdAt","id","lastRequest","name","start"],"type":"object"},"BillingState":{"additionalProperties":false,"properties":{"autoReload":{"type":"boolean"},"balance":{"type":"number"},"cardOnFile":{"type":"boolean"},"lastPack":{"enum":["25","100","500","2000",null],"type":["string","null"]},"reloadFailed":{"type":"boolean"}},"required":["autoReload","balance","cardOnFile","lastPack","reloadFailed"],"type":"object"},"CampaignBody":{"additionalProperties":false,"properties":{"campaign":{"$ref":"#/components/schemas/CampaignRow"},"matches":{"items":{"$ref":"#/components/schemas/CampaignMatch"},"type":"array"},"owned":{"description":"True if caller owns campaign.","type":"boolean"}},"required":["campaign","matches","owned"],"type":"object"},"CampaignCreate":{"additionalProperties":false,"properties":{"goal":{"maxLength":200,"minLength":1,"type":"string"},"name":{"maxLength":100,"minLength":1,"type":"string"},"visibility":{"description":"Omitted: defaults public (#397). Setting private costs 1 credit.","enum":["private","public"],"type":"string"}},"required":["goal","name"],"type":"object"},"CampaignMatch":{"additionalProperties":false,"properties":{"addedAt":{"format":"date-time","type":"string"},"campaignId":{"type":"string"},"fitScore":{"type":["number","null"]},"followerCount":{"maximum":2147483647,"minimum":1000,"type":"integer"},"handle":{"type":"string"},"id":{"type":"string"},"name":{"type":["string","null"]},"platform":{"enum":["ig","tt"],"type":"string"},"profileId":{"type":"string"},"profileImageUrl":{"type":["string","null"]},"source":{"enum":["generated","manual"],"type":"string"}},"required":["addedAt","campaignId","fitScore","followerCount","handle","id","name","platform","profileId","profileImageUrl","source"],"type":"object"},"CampaignPatch":{"additionalProperties":false,"minProperties":1,"properties":{"goal":{"maxLength":200,"minLength":1,"type":"string"},"name":{"maxLength":100,"minLength":1,"type":"string"},"status":{"enum":["active","archived","draft"],"type":"string"},"visibility":{"description":"Setting private costs 1 credit on a public→private transition; already-private updates do not.","enum":["private","public"],"type":"string"}},"type":"object"},"CampaignRow":{"additionalProperties":false,"properties":{"createdAt":{"format":"date-time","type":"string"},"createdBy":{"enum":["agent","human"],"type":"string"},"goal":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"status":{"enum":["active","archived","draft"],"type":"string"},"updatedAt":{"format":"date-time","type":"string"},"userId":{"type":"string"},"visibility":{"enum":["private","public"],"type":"string"}},"required":["createdAt","createdBy","goal","id","name","status","updatedAt","userId","visibility"],"type":"object"},"CampaignSummary":{"additionalProperties":false,"properties":{"goal":{"type":"string"},"id":{"type":"string"},"matchCount":{"type":"integer"},"name":{"type":"string"},"status":{"enum":["active","archived","draft"],"type":"string"},"updatedAt":{"format":"date-time","type":"string"},"visibility":{"enum":["private","public"],"type":"string"}},"required":["goal","id","matchCount","name","status","updatedAt","visibility"],"type":"object"},"Creator":{"additionalProperties":false,"properties":{"bio":{"type":["string","null"]},"country":{"type":["string","null"]},"fitScore":{"type":"number"},"followerCount":{"maximum":2147483647,"minimum":1000,"type":"integer"},"id":{"type":"string"},"isVerified":{"type":"boolean"},"name":{"type":["string","null"]},"platform":{"enum":["ig","tt"],"type":"string"},"profileImageUrl":{"type":["string","null"]},"tier":{"enum":["nano","micro","mid","macro","mega"],"type":"string"},"username":{"type":["string","null"]},"videos":{"items":{"$ref":"#/components/schemas/CreatorVideo"},"type":"array"}},"required":["bio","country","fitScore","followerCount","id","isVerified","name","platform","profileImageUrl","tier","username","videos"],"type":"object"},"CreatorVideo":{"additionalProperties":false,"properties":{"bunnyStreamId":{"type":["string","null"]},"caption":{"type":["string","null"]},"commentCount":{"type":"integer"},"durationMs":{"type":"integer"},"id":{"type":"string"},"isAd":{"type":"boolean"},"isSponsored":{"type":"boolean"},"likeCount":{"type":"integer"},"playCount":{"type":["integer","null"]},"playUrl":{"type":["string","null"]},"postedAt":{"type":"string"},"score":{"type":"number"},"thumbnailUrl":{"type":["string","null"]},"webUrl":{"type":"string"}},"required":["bunnyStreamId","caption","commentCount","durationMs","id","isAd","isSponsored","likeCount","playCount","playUrl","postedAt","score","thumbnailUrl","webUrl"],"type":"object"},"MppPaymentProblem":{"additionalProperties":true,"properties":{"detail":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}},"type":"object"},"OutOfCredits":{"additionalProperties":false,"properties":{"authUrl":{"format":"uri","type":"string"},"error":{"const":"out_of_credits","type":"string"},"freeGrant":{"description":"Which free grant ran out (omitted on force_payment dry-run challenges).","enum":["identified_daily","none"],"type":"string"},"machinePayment":{"description":"MPP posture for this deployment. available=false on Vercel preview.","oneOf":[{"additionalProperties":false,"properties":{"available":{"const":true,"type":"boolean"},"challengeHeader":{"type":["string","null"]},"dryRun":{"type":"string"},"retry":{"type":"string"}},"required":["available","challengeHeader","dryRun","retry"],"type":"object"},{"additionalProperties":false,"properties":{"available":{"const":false,"type":"boolean"},"hint":{"type":"string"}},"required":["available","hint"],"type":"object"}]},"packsUrl":{"format":"uri","type":"string"}},"required":["authUrl","error","machinePayment","packsUrl"],"type":"object"},"SavedCreator":{"additionalProperties":false,"properties":{"fitScore":{"maximum":1,"minimum":-1,"type":["number","null"]},"followerCount":{"maximum":2147483647,"minimum":1000,"type":"integer"},"name":{"maxLength":200,"type":["string","null"]},"platform":{"enum":["ig","tt"],"type":"string"},"profileId":{"maxLength":64,"minLength":1,"type":"string"},"profileImageUrl":{"maxLength":2048,"type":["string","null"]},"username":{"maxLength":100,"type":["string","null"]}},"required":["fitScore","followerCount","name","platform","profileId","profileImageUrl","username"],"type":"object"},"SearchParams":{"additionalProperties":false,"properties":{"country":{"enum":["us","gb","ca","au","de","fr","br","jp","kr","in"],"type":"string"},"platform":{"enum":["ig","tt"],"type":"string"},"q":{"maxLength":200,"minLength":1,"type":"string"},"tier":{"enum":["nano","micro","mid","macro","mega"],"type":"string"}},"required":["q"],"type":"object"},"SearchResult":{"additionalProperties":false,"properties":{"creators":{"items":{"$ref":"#/components/schemas/Creator"},"type":"array"},"query":{"$ref":"#/components/schemas/SearchParams"},"ticket":{"description":"Short-lived web-UI enrichment ticket (Excel view). Null when unavailable; absent on MPP paid retries. Not part of the agent contract.","type":["string","null"]}},"required":["creators","query"],"type":"object"}},"securitySchemes":{"ApiKeyHeader":{"description":"Product API key or agent access token","in":"header","name":"x-api-key","type":"apiKey"},"ApiKeyQuery":{"description":"MCP last-resort fallback: product API key or access token in ?api_key=. Exposes key in logs, Referer, history. Use only when host cannot send Bearer or x-api-key. Prefer OAuth authorization_code for browser connectors.","in":"query","name":"api_key","type":"apiKey"},"BearerAuth":{"bearerFormat":"access token","description":"Bearer access token (agent registration), product API key, or MCP OAuth access token","scheme":"bearer","type":"http"},"SessionCookie":{"description":"Browser better-auth session cookie (REST only; MCP rejects sessions). Name is better-auth.session_token, or __Secure-better-auth.session_token on HTTPS.","in":"cookie","name":"better-auth.session_token","type":"apiKey"}}},"servers":[{"url":"https://www.starcovery.com"}]}