# REST API

For developers: the same operations as the MCP server, over plain HTTP with a personal access token.

## Get a token

1. On [Connect AI assistant](/settings/api-tokens), create a personal access token. Tick **Allow writes** only if your code needs to change things.
2. Send it with every request as `Authorization: Bearer <token>`.

A token acts as you, across every team you are in, and lasts a year. Keep it in an environment variable or your CI's secrets, not in your code.

## Find the endpoints

Every endpoint is under `/api/v1` on your Copilot SEO address. `GET /api/v1` lists them all.

```sh
curl -fsS https://your-copilot-seo-address/api/v1 \
  -H "Authorization: Bearer $COPILOT_SEO_TOKEN" \
  -H 'Accept: application/json'
```

The endpoints match the MCP server's tools one for one, with the same inputs, outputs and rules. The [agent guide](/agents.md) lists each tool next to its endpoint.

With your token, `GET /api/v1/guide` returns the full agent guide as Markdown, with the rules for reading the data and each routine step by step. Each handbook article is Markdown too, at `/help/{article}.md`: send the token and it includes the parts only signed-in customers see.

## Rules

- A site, action or experiment in a team you are not in comes back as a 404, the same as one that does not exist.
- A token without Allow writes cannot change anything.
- Each user can make 120 requests a minute.
- The figures follow the same rules as the app: about two days behind, CTR as a fraction, position averaged. See [Why the numbers differ from Search Console](/help/numbers-vs-search-console).

## Marking releases from CI

To annotate releases from a deploy pipeline, a site's release marker token is simpler. It can only add annotations to that one site, so it is safer to keep in CI. See [Annotations](/help/annotations).