# The sirefs REST API

Every number in the dashboard and every next step as JSON, with a workspace API key. Read projects, prompts, competitors, sources, the audit and the answers; add prompts, track competitors and run the audit from your own scripts.

Last updated: 2026-10-22. HTML version: https://sirefs.com/docs/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](https://sirefs.com/docs/mcp); 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](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](https://sirefs.com/docs/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.