# Starcovery > Starcovery helps you find and hire real Instagram and TikTok creators from a plain-language brief, on the web or from your agents. No cut-down tier: web, MCP, REST, and CLI call same endpoints for search, campaigns, and credits. Agent has same capabilities as signed-in human. ## Start here (agents) - Agentic signup skill (auth.md protocol): https://www.starcovery.com/agents - Unsigned search (no credential, 50/UTC-day per IP): https://www.starcovery.com/api/search?q=coffee - Pre-claim agent tokens have no free grant: searches spend prepaid balance only (402 when empty) - Claimed / session free grant (when prepaid balance is empty): 100/UTC-day - CLI unsigned search: starcovery search "coffee" - 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 free grant 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; 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 + MCP; x-payment-info on search): https://www.starcovery.com/openapi.json CLI: settle externally (link-cli / mppx SPT), then: starcovery search "coffee" --payment 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, keys, MCP; MPP on search): https://www.starcovery.com/openapi.json ## Product surfaces - Marketing home: https://www.starcovery.com/ - Web: https://www.starcovery.com/app - MCP (OAuth, Bearer, or last-resort ?api_key=): https://www.starcovery.com/api/mcp - AI creator search hub: https://www.starcovery.com/guides/ai-creator-search - MCP how-to: https://www.starcovery.com/guides/mcp - CLI quickstart: https://www.starcovery.com/guides/cli - REST search: https://www.starcovery.com/api/search - Campaigns (credential required; goal, generate, augment, operate; public reads are free; setting private costs 1 credit): 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/app/settings/api-keys after sign-in - Human checkout / auto-reload UI: https://www.starcovery.com/app/settings/billing - Modash alternative: https://www.starcovery.com/vs/modash - HypeAuditor alternative: https://www.starcovery.com/vs/hypeauditor # 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 path capped at 50 searches per UTC day per IP (plus small per-minute burst). Cap hit: 429 with authUrl pointing here. Registering gives identity but no free searches: pre-claim tokens share same API scopes and unlock campaigns, and can use machine payment when that rail is enabled, and searches spend prepaid balance only. Free grant unlocks at claim: 100 searches per UTC day, plus 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, campaigns, billing state, keys, and MCP; Machine Payments x-payment-info only on GET /api/search): 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 Or do HTTP dance below (same protocol). ## 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.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. Registering with service_auth returns 400 service_auth_not_enabled; identity_assertion returns 400 issuer_not_enabled (service trusts no ID-JAG issuers). Both terminal: fall back to anonymous. ## Step 3. Register anonymously POST https://www.starcovery.com/agent/identity Content-Type: application/json { "type": "anonymous" } Optional referral code (double-sided credits for referrer and referee): { "type": "anonymous", "ref": "YOURCODE" } CLI: starcovery auth register --ref YOURCODE (or STARCOVERY_REF). Invalid codes do not fail registration; response may include referral object. 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 6-digit user_code, verification_uri, expires_in, and interval. Starcovery emails one-time link to address supplied, reaching human even with no direct channel. That link is half you never see: verification_uri is plain claim page, opens only for emailed link. user_code is other half and travels only through you. Neither channel alone finishes ceremony; mailbox proves human identity. Tell person in one message: open link emailed to them (verification_uri is https://www.starcovery.com/claim; emailed link opens that page), then enter 6-digit code: . They set password on that page, enter code, account is theirs. Disposable, reserved, or undeliverable addresses (e.g. .invalid) return undeliverable_email before initiation; if claim returns mail_send_failed, ask for 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 user_code window closes, call claim endpoint again with same claim_token and email for fresh code. New code and link replace previous pair; previous pair stops working immediately. ## 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. 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), 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 campaign ## Credits and pricing Each identified search spends one credit from prepaid balance when non-empty. Empty balance: pre-claim token has no free grant, returns 402 immediately; after claim (or with session / Settings API key) grant is 100 searches per UTC day, then 402 the same way. Recovery from 402: prepaid credit pack. Unsigned callers stay on 50/day IP grant, never reach credit ledger. ## 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 free grant: 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/app/settings/billing" } While free grant or 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/app/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.