# REST API

> The atrby REST API at /api/v1 authenticates with a bearer key, offers read and write scopes, and returns JSON for stats, revenue, vitals, funnels, goals and alerts.

Canonical: https://atrby.site/docs/api
Last updated: 2026-10-21

Read stats and revenue, and create goals, alerts and payments, with one key.

## Authentication

Create a key under Settings → API keys and MCP. We show it once; store it as a secret. Send it on every request:

```
Authorization: Bearer atr_live_…
```

| Key scope | Allows |
| --- | --- |
| Read | All GET endpoints. |
| Read and write | Also POST goals, alerts and payments. |

A key sees every site in its workspace and nothing else. Owners and admins can create and revoke keys; revoking works right away. API calls are free and never count toward pageviews.

## Requests

Base URL `https://app.atrby.site/api/v1`. Most endpoints take:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `site` | string | Required | Site domain (acme.io) or id (st_…). |
| `range` | string | Optional | `today`, `24h`, `7d`, `30d` or `90d`. Default `30d`. |

```bash
curl "https://app.atrby.site/api/v1/revenue?site=acme.io&range=30d" \
  -H "Authorization: Bearer $ATRBY_API_KEY"
```

## Endpoints

| Endpoint | Returns |
| --- | --- |
| GET /sites | `sites`: id, domain, name, timezone, verified_at. |
| GET /stats | `kpis` and `previous` (visitors, sessions, pageviews, revenue, payments, bounceRate, conversionRate), `series`, and `breakdowns` by page, entry_page, channel, referrer, utm_campaign, country, device, browser and ai, top 10 each. |
| GET /revenue | `kpis` (revenue, gross, payments, refunds, attributed, newCustomers, avgOrder), `previous`, `sources` (channel, source, customers, revenue) and `series`. |
| GET /vitals | `metrics` (p75 and good/poor share), `byDevice`, `pages` (top 20) and `trend`. |
| GET /funnel | `steps` and `byChannel`. Optional `steps` parameter: a JSON array of 2 to 8 `{kind, match}`, kind one of any, page, event, revenue. Default: any page, /pricing, paid. |
| POST /goals | `{site, name, kind: "page" | "event", match}`. Page matches start with / and may end in *. |
| POST /alerts | `{site, kind, threshold_pct?, recipient}`. kind: revenue_drop, traffic_spike or tracking_stopped; threshold 10 to 500, default 30; recipient must be a workspace member. |
| POST /payments | The [Payment API](https://atrby.site/docs/payment-api). |

## Errors and limits

| Status | Meaning |
| --- | --- |
| 400 | Invalid body or parameters. The response has `error` and, for bodies, `issues`. |
| 401 | Missing, malformed or revoked key. |
| 403 | A read key used on a write endpoint. |
| 404 | Unknown endpoint, or a site that isn't in this key's workspace. |
| 429 | Over 120 requests a minute for this key. Wait for `Retry-After` seconds. |

> **OpenAPI.** The full spec is `openapi/atrby.openapi.yaml` in the atrby repository.

## Related
- [MCP](https://atrby.site/docs/mcp)
- [CLI](https://atrby.site/docs/cli)
- [Payment API](https://atrby.site/docs/payment-api)