---
title: API and tokens
description: The UsherStats REST API, API tokens and their scopes, errors, and where the full reference lives.
nav: API & tokens
---
# API and tokens

Everything you can do in the dashboard you can do through the API: read analytics, manage sites and their keys, set
bot protection rules, goals and experiments, manage your team and tokens, and export data. The dashboard itself is
built on the same API.

## Basics

- Base address: `https://api.usherstats.com`, with every route under `/v1/`.
- JSON in and out.
- The full reference is the OpenAPI 3.1 description at `GET /v1/openapi.json`, generated from the routes the API
  serves, so it is never out of date. Load it into any OpenAPI tool to browse it or to generate a client.

## Tokens

Programs use API tokens; people use the dashboard. Send a token as a bearer token:

```sh
curl -s https://api.usherstats.com/v1/me -H "Authorization: Bearer us_live_…"
```

- A token **belongs to one workspace** and can do whatever its scopes allow there, including everything an account
  can when it holds `account:admin`.
- **Scopes** have the form `module:action`: `analytics:read`, `sites:read`, `sites:write`, `bot:read`, `bot:write`,
  `search:read`, `search:write`, `members:read`, `members:write`, `tokens:read`, `tokens:write`, `billing:read`,
  `billing:write`, `export:read`, and `account:admin` for everything.
- A token can be **limited to some sites**, and can **expire**.
- A token is **shown once**, when it is created, and stored only as a hash. Lists show its first characters so you
  can tell tokens apart, and when it was last used.
- Give each program its own token with the fewest scopes it needs, and revoke it when the program is retired.

Create tokens in the dashboard under **Settings → API tokens**, or through the API; see [API tokens](api/tokens.md).

## Errors

Every error is `application/problem+json`, with a `title` that says what went wrong and what to do, and the HTTP
status that fits: `400` for a request the API cannot accept (naming the field), `401` without a valid token, `403`
when the token lacks the scope or the site, `404` for something that does not exist in your workspace, and `429` when
you are sending too fast (wait the number of seconds in `Retry-After`).

## Reference pages

- [Accounts and sign-in](api/auth.md)
- [API tokens](api/tokens.md)
- [Sites, hostnames and keys](api/sites.md)
- [Workspace and members](api/members.md)

For AI agents, see [Agents and MCP](agents-and-mcp.md).