# Agent API (/docs/api/agent)

The agent API reads what the dashboard shows. It changes nothing. The [MCP server](/docs/agents) runs on it, and [`/openapi.json`](https://numbers.obelism.studio/openapi.json) describes it.

Every request carries a bearer token: an Obelism session token, or an access token from the MCP server's OAuth flow.

```
Authorization: Bearer <token>
```

| Operation           | Request                                                                                      |
| ------------------- | -------------------------------------------------------------------------------------------- |
| `listOrganizations` | `GET /api/agent/organizations`                                                               |
| `listSpaces`        | `GET /api/agent/organizations/{organizationId}/spaces`                                       |
| `getReport`         | `GET /api/agent/organizations/{organizationId}/spaces/{spaceId}/{environment}/report?range=` |
| `listEvents`        | `GET /api/agent/organizations/{organizationId}/spaces/{spaceId}/{environment}/events?range=` |

- `range` is `24h`, `7d` (the default), `30d` or `90d`.
- `getReport` answers with what the dashboard's overview shows: the totals with `previous` (the range before), the series per UTC hour or day, and the top 10 pages, sources, campaigns, countries, devices, browsers, operating systems and clicked elements.
- `listEvents` lists every event name and scope with its count, visitors and when it was last seen.

300 calls a minute per person. Errors are problem JSON with a `code` and a `hint` ([errors](/docs/api/errors)).