# 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: <access_token>

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 <credential>
    x-api-key: <access_token>

OpenAPI discovery (REST + MCP; x-payment-info on search): 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, keys, MCP; MPP on search): https://www.starcovery.com/openapi.json

## Product surfaces

- Web home: https://www.starcovery.com/
- Web search: https://www.starcovery.com/app?q=<term>
- Catalog profile: https://www.starcovery.com/♥/{handle}
- Share URL: https://starcovery.me/{handle} (308 to www `/♥/{handle}`; not a content origin)
- 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