Quickstart
Run an unsigned search, register an identity, and create a campaign.
This page runs an unsigned search, registers an identity, and creates a campaign.
Search before signing up
Search accepts a plain-language brief. No credential is required for the first call.
curl:
curl "https://www.starcovery.com/api/search?q=slow+morning+coffee"CLI:
npx starcovery search "slow morning coffee"Unsigned search is free and needs no account and no credit pack. An unsigned caller gets 100 uses per rolling 24 hours per IP. An identified caller gets 200 uses per rolling 24 hours, then spends prepaid credits. A search is one use, and a thread turn is one use plus one for each search it runs.
Get a credential
Both credentials are self-serve.
- Agent access token: run
npx starcovery auth register, or callPOST /agent/identity. - Settings API key: after sign-in, open Settings > API Keys.
Test against the live API
The live test call is the unsigned GET /api/search above. Test calls use the same host as production calls. API versioning covers the versioning and rate-limit headers.
Narrow the shortlist
The q parameter contains the brief. Three optional filters narrow it:
| Filter | Values |
|---|---|
platform | ig, tt |
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 followers; nano+, micro+, mid+, and macro+ mean that tier's lower bound and above, and micro-, mid-, and macro- mean 1,000 up to that tier's upper bound |
country | au, br, ca, de, fr, gb, in, jp, kr, us |
curl "https://www.starcovery.com/api/search?q=slow+morning+coffee&platform=ig&tier=nano&country=us"A value outside these sets returns 400 invalid_query with a message that names the parameter. An undeclared parameter is ignored. Full details: Search.
Register an identity
Agents and humans can register without another person in the loop. Short path:
npx starcovery auth registerThis follows the auth.md protocol, exchanges a service-signed assertion for an access token, saves the credential to ~/.config/starcovery/config.json, and installs the host skill. The same protocol works over plain HTTP. See Authentication.
Send the token as Authorization: Bearer <access_token> or as x-api-key on every API call.
Start a campaign
Create a campaign with a goal, generate matches, then add or remove matches as needed.
curl -X POST "https://www.starcovery.com/api/campaigns" \
-H "x-api-key: <access_token>" \
-H "content-type: application/json" \
-d '{"name": "Coffee", "goal": "quiet morning coffee creators who film at home"}'See Campaigns and the API reference.