# REST API (/api)

The REST API is at `https://api.annoty.app`. Every endpoint is in the sidebar, generated from the [OpenAPI spec](https://api.annoty.app/openapi.json), which you can also load into your own tools.

## Authenticate [#authenticate]

Create an API key in the dashboard under **Settings → API keys** and send it as a bearer token:

```bash
curl https://api.annoty.app/v1/projects \
  -H "Authorization: Bearer annoty_…"
```

`x-api-key: annoty_…` works too. While your organization has no subscription or trial, every request except `GET /v1/organization` fails with 402 `SUBSCRIPTION_REQUIRED`.

## Errors [#errors]

Errors always look like `{ "error": { "code", "message", "details", "requestId" } }`. Branch on `code`; `message` may change.

## Pagination [#pagination]

List endpoints take `limit` and `cursor` and return `{ data, nextCursor }`. Pass `nextCursor` as `cursor` to get the next page; it's `null` on the last one.

## Rate limits [#rate-limits]

300 requests per minute per key, 100 while your organization is on its trial. Over that you get 429 with `Retry-After`.
