# Starcovery > Starcovery helps you find and hire real Instagram and TikTok creators from a plain-language brief, on the web or from your agents. Web, MCP, REST, and CLI call the same endpoints for search, shortlist enrichment, campaigns, and credits. An agent has the same API capabilities as a signed-in human. Search, campaign generate, and enrich wait up to 300 seconds. There is no job id; the request stays open until the result. Do not use Starcovery to generate synthetic creator video, to search a YouTube-only catalog, or when you need a human sales demo before the first shortlist. ## Start here (agents) - Documentation (guides + API reference, Markdown-friendly): https://www.starcovery.com/docs - Agentic signup skill (auth.md protocol): https://www.starcovery.com/agents - Host skill (Agent Skills SKILL.md): https://www.starcovery.com/agents/skill - Unsigned search (no credential): https://www.starcovery.com/api/search?q=coffee - Unsigned callers get 10 searches per rolling 24 hours per IP (402 when that grant is used) - Identified callers get 20 searches per rolling 24 hours, then prepaid extra credits (402 when extra is empty) - Pre-claim agent tokens spend prepaid only (402 when empty) - CLI unsigned search: starcovery search "coffee" - CLI shortlist enrich: starcovery search "coffee" --enrich - CLI agentic signup: starcovery auth register - CLI is starcovery npm package: npx starcovery or bunx starcovery runs with no install ## Machine payments (MPP) Protocol: https://mpp.dev/ (Stripe fiat SPT rail) After the prepaid balance is exhausted, identified search answers HTTP 402 with WWW-Authenticate: Payment ... (Machine Payments Protocol). One payment buys 10 credits for $0.50. Dry-run (no charge, no Checkout session; returns a live 402 + WWW-Authenticate: Payment challenge): GET https://www.starcovery.com/api/search?q=coffee&force_payment=1 x-api-key: Payment credential while entitlement remains routes through paywall (never silent 200 settlement). Invalid credentials get challenge or diagnostic; settled credential replays with Payment-Receipt. Paid retry (identity must ride x-api-key; Authorization is for Payment): GET https://www.starcovery.com/api/search?q=coffee Authorization: Payment x-api-key: OpenAPI discovery (REST): https://www.starcovery.com/openapi.json CLI: pay checkoutUrl, then retry: starcovery search "coffee" Full paid-rail notes: https://www.starcovery.com/agents ## Discovery (RFC 9728 / auth.md) - Protected resource metadata: https://www.starcovery.com/.well-known/oauth-protected-resource - Authorization server metadata (agent_auth block): https://www.starcovery.com/.well-known/oauth-authorization-server - OpenAPI (search, campaigns, billing state, and keys): https://www.starcovery.com/openapi.json ## Product surfaces - Web home: https://www.starcovery.com/ - Web search: https://www.starcovery.com/app?q= - Creator page: https://www.starcovery.com/tt/@{handle} or https://www.starcovery.com/ig/@{handle}; a claimed handle at https://www.starcovery.com/@{handle} - MCP (OAuth, Bearer, or last-resort ?api_key=): https://www.starcovery.com/api/mcp - AI creator search hub: https://www.starcovery.com/docs/guides/ai-creator-search - MCP how-to: https://www.starcovery.com/docs/guides/mcp - CLI quickstart: https://www.starcovery.com/docs/guides/cli - REST search: https://www.starcovery.com/api/search - REST shortlist enrich (ticketed NDJSON, up to 300 seconds): https://www.starcovery.com/api/search/enrich - Campaigns (credential required; name, goal, generate, augment, operate; ordinary public reads are free for identified callers; setting private costs 1 credit; contract, creator posting date, campaign details declassifying date, and disclosure are accepted, and one that fails the terms check returns 400 invalid_campaign_terms with the reason in message): https://www.starcovery.com/api/campaigns - Billing state (credential required): https://www.starcovery.com/api/billing/state - API keys (session or human key; agent tokens 403): https://www.starcovery.com/api/keys ## Optional - Humans mint API keys at https://www.starcovery.com/home?settings=api-keys after sign-in - Human checkout UI: https://www.starcovery.com/home?settings=billing - Modash alternative: https://www.starcovery.com/vs/modash - HypeAuditor alternative: https://www.starcovery.com/vs/hypeauditor - What Starcovery isn't: https://www.starcovery.com/isnt # auth.md Starcovery is creator search API for Instagram and TikTok: describe kind of creator in natural language, get ranked shortlist back with profile data and sample videos. Service supports agentic registration (open auth.md protocol). Get working credential with no human involved, spend immediately, hand ownership to person later if needed. Humans reading this: same path works for any agent you point here. ## Search without signing up Search before registering. No credential: GET https://www.starcovery.com/api/search?q=slow+morning+coffee Unsigned landing search works without a credential. Registering gives identity: pre-claim tokens share same API scopes and unlock campaigns, and can use machine payment when that rail is enabled, and searches use 20 identified searches per rolling 24 hours then prepaid extra credits. Pre-claim tokens skip the daily grant and spend prepaid only. Claim adds human ownership, sign-in, billing, and credit-pack access. CLI equivalent with no credential (CLI is starcovery npm package; npx starcovery and bunx starcovery both run with no install): starcovery search "slow morning coffee" OpenAPI 3.1 discovery (REST paths for search, shortlist enrich, campaigns, billing state, and keys; MCP discovery is separate): GET https://www.starcovery.com/openapi.json Protocol overview: https://mpp.dev/ ## Agentic signup (preferred for agents) Follow steps in order to get identity. Short path: starcovery auth register That command saves the credential and runs bunx skills when bun is on PATH, otherwise npx -y skills. Or do HTTP dance below (same protocol). The install step is required either way. ## Step 1. Discover On 401 from gated endpoint (campaigns, MCP, keys, billing), read WWW-Authenticate header. It carries resource_metadata pointing at Protected Resource Metadata document. Also fetch well-known URLs directly: GET https://www.starcovery.com/.well-known/oauth-protected-resource GET https://www.starcovery.com/.well-known/oauth-authorization-server Second carries agent_auth block. agent_auth.skill is this document. agent_auth.agent_skill is the host SKILL.md at https://www.starcovery.com/agents/skill. agent_auth.identity_endpoint and agent_auth.claim_endpoint are the registration and claim URLs below. identity_types_supported lists which registration methods service accepts. ## Step 2. Pick a method Service accepts one identity type: anonymous. identity_types_supported lists it alone. Other type values return 400 invalid_request. ## Step 3. Register anonymously POST https://www.starcovery.com/agent/identity Content-Type: application/json { "type": "anonymous" } Response: registration_id, service-signed identity_assertion with its assertion_expires, pre_claim_scopes, and claim materials (claim_url, claim_token, claim_token_expires, post_claim_scopes). No email, no human, no consent screen: no user identity to assert yet. Registration reservations capped at 100 per UTC day (failed create after reserve still burns slot). Cap hit: 429 with error rate_limited. claim_token returned once. Hold it as long as human may want ownership of this identity. ## Step 4. Claim ceremony (optional) Run only when human wants to own account. Ask service to start ceremony: POST https://www.starcovery.com/agent/identity/claim Content-Type: application/json { "claim_token": "...", "email": "person@their-inbox.com" } Response: claim_attempt block with verification_uri, expires_in, and interval. Starcovery emails a one-time link to the address supplied. That link carries a one-time token. Clicking it is the claim. verification_uri is the plain claim page; the emailed URL opens that page with the token. The mailbox proves human identity. Tell the person: open the link emailed to them (verification_uri is https://www.starcovery.com/claim; the emailed link opens that page). They confirm the claim on that page, then sign in with Google using that email address. The account is theirs. Disposable, reserved, or undeliverable addresses (e.g. .invalid) return undeliverable_email before initiation; if claim returns mail_send_failed, ask for a deliverable inbox and retry. Poll token endpoint until it stops answering authorization_pending: POST https://www.starcovery.com/oauth2/token Content-Type: application/x-www-form-urlencoded grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=... Honor interval. Success: post-claim access_token and fresh identity_assertion returned; pre-claim access tokens revoked at that moment, drop them and use new one. If the claim link window closes, call the claim endpoint again with the same claim_token and email for a fresh link. The new link replaces the previous one immediately. Claim initiation per registration is capped at 3 per rolling 24 hours. Cap hit: 429 with error rate_limited. Honor Retry-After. ## Step 5. Exchange the assertion for an access token POST https://www.starcovery.com/oauth2/token Content-Type: application/x-www-form-urlencoded grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=... Response: bearer access_token with expires_in. Re-run with same identity_assertion when access token expires. No refresh token: assertion is long-lived half. Each exchange retires previous token; hold exactly one and re-fetch when it lapses rather than minting pool. ## Step 6. Install the global skill Default after a credential exists. CLI short path already does this. HTTP agents run the same installer: If bun is on PATH: bunx skills add https://www.starcovery.com --global --yes --skill starcovery --agent cursor --agent claude-code --agent codex Otherwise: npx -y skills add https://www.starcovery.com --global --yes --skill starcovery --agent cursor --agent claude-code --agent codex If bunx, npx, or skills fails, registration still stands. Warn and continue. Never write a token into the skill. Never write project .cursor/skills by hand. Claude Desktop has no skills CLI agent id. Download https://www.starcovery.com/agents/skill.zip and upload at Customize > Skills with code execution on. MCP connector is separate: https://www.starcovery.com/api/mcp ## Step 7. Call the API GET https://www.starcovery.com/api/search?q=space+and+astronomy+explainers Authorization: Bearer Query rides q. Optional filters: platform (ig, tt), tier (nano, micro, mid, macro, mega; plus forms nano+, micro+, mid+, macro+ mean that follower count and above), and country (us, gb, ca, au, de, fr, br, jp, kr, in). Anything else answered 400 with issues named. Header x-api-key accepted as well with same token. MCP (access token or API key required; no unsigned MCP): https://www.starcovery.com/api/mcp Authorization: Bearer Browser MCP hosts supporting OAuth (Claude Desktop custom connectors) discover authorization_code via WWW-Authenticate challenge on bare call; sign in when prompted. Prefer that over pasting key. Fallback when host cannot set Authorization (exposes key in logs and Referer; last resort only): https://www.starcovery.com/api/mcp?api_key= CLI with a saved credential from Step 5 (or starcovery auth register): starcovery search "space and astronomy explainers" starcovery campaigns ## Credits and pricing Each identified search uses the 20-search rolling 24h grant first, then one prepaid extra credit. Pre-claim tokens spend prepaid only (402 when extra credits are empty); claim the identity before buying a prepaid credit pack. Unsigned callers get 10 searches per rolling 24 hours, never reach the extra-credit ledger, and must wait for the window or sign in after an unsigned_daily 402. ## Paying for credits yourself That 402 also carries WWW-Authenticate challenge in Payment scheme: Stripe Machine Payments Protocol, fiat, over Shared Payment Token. Settle yourself, no human needed. One payment buys 10 credits for $0.50 (Stripe card floor $0.50, so single search cannot be charged alone); unspent credits stay on balance for next call. Sample 402 shape (live header bytes vary per challenge; parse Payment scheme, do not hard-code token). Dry-run without spending prepaid or creating Checkout: GET https://www.starcovery.com/api/search?q=coffee&force_payment=1 x-api-key: HTTP/1.1 402 Payment Required WWW-Authenticate: Payment Content-Type: application/json { "error": "out_of_credits", "packsUrl": "https://www.starcovery.com/home?settings=billing" } While prepaid balance remains, Authorization: Payment routes through paywall (never silent 200). Invalid credentials get challenge or diagnostic; settled credential replays with Payment-Receipt. Retry the same request with the credential: GET https://www.starcovery.com/api/search?q=... Authorization: Payment x-api-key: Send identity as x-api-key on retry, not as bearer token. Payment credential needs Authorization header; MPP clients overwrite that header when attaching it, destroying a bearer token there. Payment request without identifiable caller answers 401 identity_required, nothing charged: credits live on account, must know whose balance payment funds. Credential also bound to challenged identity: redeeming under different account, or sending one so damaged caller cannot be read, answers 403 credential_caller_mismatch, nothing charged. Recover: repeat search with identity and no payment credential to get fresh challenge. Paid response: search result plus Payment-Receipt header. Keep receipt as proof payment settled. Two receipted failures exist, neither needs second payment. 503 search_failed: credits bought are on balance, only search broke; retry without payment credential. 503 credit_pending: charge succeeded, credit grant still landing through Stripe webhook; wait, then retry without payment credential. Plain 402 after credit_pending carries no receipt: grant still in flight, not lost; keep waiting. 402 carrying Payment-Receipt means earlier payment settled and its 10 credits are already spent; fresh payment needed. Larger packs with bonus credits on same $0.05 rate are available to human account owners on the web (Step 4). Ladder at https://www.starcovery.com/home?settings=billing. ## Scopes Registration returns pre_claim_scopes and post_claim_scopes; on this service they are same set. Claiming does not widen API access; it gives human the account (sign-in, credit packs, billing) while credential, credits, and history carry over. User id never changes.