Skip to main content
An API key identifies your account on every call. Send it as a bearer token. Your account holds one balance, and every key on it spends from that balance.

Create a key

Sign up at stophy.dev/signup with GitHub or Google, then create an API key. Save it as STOPHY_API_KEY in your server’s secret store. Keep it out of code you commit and out of browser code. A new account starts with $2. See Pricing. The CLI makes its own key when you run stophy login. Each computer gets its own key, and logging in again replaces it. Browser sign-in over MCP needs no API key.

Sign up from an agent

An agent can request an API key for you. You only approve it.
  1. The agent calls POST /v1/signup. The call needs no API key and is free. The answer holds a claimUrl and a secret code.
  2. You open claimUrl, sign in with GitHub or Google and approve.
  3. The agent calls POST /v1/signup/poll with the code every few seconds. It gets 202 with status: "waiting" until you approve, then 200 with the apiKey, once.
This is the response shape from the API reference, with placeholders for the values. The link and the code work for 24 hours. A code that is unknown, expired or already collected answers 404 with code notFound. Sign up again. Each IP address can start 5 signups a day, then the answer is 429 with code rateLimited. The full steps are in the Agent quickstart. Over MCP, the stophy_signup tool does the same.

Check a key and its expiry

GET /v1/limits shows a key’s rate limit and when it stops working. This real response is cut to those fields.
keyExpiresAt is null when the key does not expire, as for a key an agent collected. When a key has an expiry, keyExpiresAt is that time, and after it the key answers 401 with code unauthorized. A key that is wrong, revoked or expired gets the same answer.

Revoke a key

DELETE /v1/key revokes the key you call it with. It is free, and the key stops working at once. It needs an API key, not a signed-in session.
The answer is { "success": true }. stophy logout revokes the CLI’s key the same way. To replace a key, create the new one, update your app, then revoke the old one. Every call counts against the key that made it. Filter GET /v1/logs and GET /v1/usage/history by apiKeyId to see one key’s calls.

Calls without an API key

Search, scrape, map and parse work without an API key, up to 10 calls a minute and 50 calls a day per IP address, with no paging. Scrape with a parser works when the parser is marked keyless: true in the parser list. Everything else answers 401 with code apiKeyRequired, and so does a keyless call that uses a field below. The answer carries a signupUrl for a person and a signup call for an agent. On search, scrapeOptions also needs an API key. Without one, that call answers 400 with code invalidRequest. GET /v1/keyless/eligibility needs no API key. It tells you whether your IP address can still make calls without an API key.
Over the limit, a keyless call answers 429 with code freeLimit, a signupUrl and retryAfterSeconds. See Rate limits.