The sirefs REST API
The REST API gives your scripts, spreadsheets and internal tools what the dashboard shows: the same functions, the same numbers, every rate with its sample size and interval. It is the same implementation as the MCP server; the MCP tools are these routes, named for an assistant.
Authentication
Create a key under Settings, API in the app (owners and admins; Pro and Agency). Send it as a bearer token:
curl https://api.sirefs.com/v1/projects \
-H "Authorization: Bearer sir_..."
A key stands for the whole workspace and never expires. Revoke it in Settings when a tool is retired. An OAuth access token from an assistant connection works the same way, for an hour.
Routes
All routes live under https://api.sirefs.com/v1. {project} is a project's slug or id (from GET /projects). Periods are days back from today, UTC, 28 by default.
| Method and path | What it returns |
|---|---|
GET /projects |
The workspace's projects with their visibility over 28 days. |
GET /projects/{project}/overview?days= |
Visibility, citation rate, recommendation rate, rank, sentiment and share of voice for the brand and each competitor, in total and per engine. |
GET /projects/{project}/prompts?days= |
The prompts with market, topic, status and the brand's visibility per engine. |
GET /projects/{project}/trend?days=90&entity=brand |
Visibility over time per engine, daily to 35 days and weekly beyond. |
GET /projects/{project}/competitors?days= |
Tracked brands head to head, and the untracked brands the engines name most. |
GET /projects/{project}/sources?days= |
The domains and pages the engines cite: your own, competitors', third parties. |
GET /projects/{project}/threads?days=90 |
Forum and community threads the engines cite. |
GET /projects/{project}/next-steps?days= |
What to do, ranked by impact, with evidence and dashboard links. |
GET /projects/{project}/audit |
The latest GEO audit at your plan's level. |
GET /projects/{project}/answers?engine=&prompt_id=&mentioned=&limit=20&skip=0 |
Collected answers, newest first, without their text. |
GET /projects/{project}/answers/{answer_id} |
One answer in full with its highlights and citations. |
GET /projects/{project}/alerts?limit=20 |
Significant changes and newly named competitors. |
POST /projects/{project}/prompts |
Add prompts: {"prompts": [{"text": "...", "market": "us-en", "topic": "..."}]}. Duplicates are skipped; the rest count against the plan and get their first answers within minutes. |
PATCH /projects/{project}/prompts/{prompt_id} |
{"active": false} pauses a prompt, true resumes it within the plan. |
POST /projects/{project}/competitors |
Start tracking a brand: {"name": "...", "aliases": [], "domains": []}. Stored answers are re-matched for free. |
POST /projects/{project}/not-competitors |
Mark a brand as not a competitor: {"name": "..."}. It's never suggested, alerted on or listed in next steps; a tracked competitor of that name stops being tracked. |
POST /projects/{project}/audit |
Run the GEO audit now, at most once an hour per project. |
The interactive reference with every field is at https://api.sirefs.com/docs, under the v1 tag.
Errors
Errors are HTTP status codes with a JSON body.
| Status | Meaning |
|---|---|
| 401 | No token, or an unknown, expired or revoked one. |
| 402 | The plan doesn't allow it: {"detail": {"code": "plan_limit", "limit": "prompts", "allowed": 60, "message": "..."}}. The body says what to do. |
| 403 | The token may only read. |
| 404 | No such project, prompt or answer in the workspace. |
| 422 | A bad argument; the body names it. |
| 429 | The audit ran less than an hour ago, or more than 120 requests in a minute. Retry-After says how long. |
Reading the numbers
Every rate comes as {"k": 12, "n": 40, "rate": 0.3, "low": 0.18, "high": 0.45}: the count, the sample, the rate and its 95% Wilson interval. Treat rates on fewer than 20 answers as rough, and compare intervals rather than point values when you decide whether something changed. Each answer carries its method (ui, serp or api); trends never mix methods. See reading the numbers.
Limits
- 120 requests a minute per key or connection.
- Nothing you call asks an AI engine on your behalf. Reads cost nothing against your plan; adding prompts uses the plan's prompt allowance, as in the app.
- The API is included in Pro and Agency.