API overview
Read and manage your Peersheep workspace from your own code, scripts or AI assistant.
The Peersheep API gives you the same data you see in the app: your competitors, the pages you watch, the changes Peersheep detects and your dashboard numbers. With a read-and-write key you can also add competitors and pages, trigger crawls and manage alerts.
There are two ways in:
- REST API at
https://api.peersheep.com/v1, for scripts, dashboards and integrations. - MCP server at
https://api.peersheep.com/mcp, for AI assistants like Claude and Cursor. See MCP server.
Both use the same API keys and are available on every plan, including Free.
Create an API key
Open the API settings
Go to Settings → API. Only workspace owners can create and revoke keys; other members can see which keys exist.
Name the key and choose its access
Give the key a name that says where it's used, such as Claude or Internal dashboard, and pick its access:
| Access | What it can do |
|---|---|
| Read only | View competitors, pages, snapshots, alerts, evidence and stats |
| Read and write | Everything above, plus add and remove competitors and pages, trigger crawls, and mark, archive and rate alerts |
Start with Read only unless you need to make changes.
Copy the key
Click Create key. The full key, starting with ps_live_, is shown once. Store it in a password manager or your app's secrets.
A workspace can have up to 10 active keys. Each key belongs to one workspace, so it only ever sees that workspace's data.
Treat API keys like passwords. Don't commit them to code or paste them into client-side JavaScript. If a key leaks, revoke it under Settings → API. It stops working immediately.
Authentication
Send the key as a bearer token on every request:
curl https://api.peersheep.com/v1/me \
-H "Authorization: Bearer ps_live_..."GET /v1/me is a good first call. It returns the workspace the key belongs to, its plan and limits, and the key's access level.
API keys only work on https://api.peersheep.com/v1 and the MCP server. They can't be used to change billing, team members or other API keys; those stay in the app.
Requests and responses
- Request and response bodies are JSON. Send
Content-Type: application/jsonwithPOSTandPATCHrequests. - Timestamps are UTC.
- Every response includes an
X-Peersheep-Api-Version: 1header.
Plan limits
The API follows the same limits as the app. Adding a competitor or page past your plan's limit returns 402 with a message saying which limit you've hit. See Plans and limits.
Errors
Errors return an HTTP status code and a JSON body with a readable message and, for most errors, a code:
{ "message": "Competitor not found", "code": "NOT_FOUND" }| Status | Meaning |
|---|---|
400 | The request body is invalid. code is VALIDATION_ERROR and the message names the field, for example url: Invalid URL. |
401 | The API key is missing, invalid or revoked. |
402 | You've reached a plan limit. |
403 | The key is read only and the request would make a change, or the endpoint isn't available with API keys. |
404 | The resource doesn't exist, or belongs to a different workspace. |
409 | It already exists, for example a competitor with the same domain. |
Next steps
- Endpoints: every endpoint, with parameters and examples.
- MCP server: connect Claude, Cursor or VS Code.