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:

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.

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

For AI agents, see Agents and MCP.