REST API

Get a token

1. On Connect AI assistant, 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.

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 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.

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.