# API and MCP developer guide

> Connect to the AEOmeter MCP server and REST API: endpoints, OAuth authentication, rate limits, the error format, and the versioning and deprecation policy.

AEOmeter has a remote MCP server for AI assistants and a REST API for scripts. Both use the same handlers as the web app, so anything you see in the dashboard you can read or change programmatically.

## Endpoints

| Surface | URL | Description |
| --- | --- | --- |
| MCP server | `https://aeometer.com/mcp` | Streamable HTTP. Server card at [/.well-known/mcp/server-card.json](https://aeometer.com/.well-known/mcp/server-card.json). |
| REST API | `https://aeometer.com/api/v1` | OpenAPI spec at [/openapi.json](https://aeometer.com/openapi.json), reference at [/docs](https://aeometer.com/docs). |
| Agent skill | [/skill.md](https://aeometer.com/skill.md) | Instructions an agent can load before using AEOmeter for a user. |
| API catalog | [/.well-known/api-catalog](https://aeometer.com/.well-known/api-catalog) | RFC 9727 index linking the specs, docs and health endpoint. |
| Health | [/health](https://aeometer.com/health) | Returns `{"status":"ok"}` when the service is up. |

## Authentication

The MCP server uses OAuth 2.1 with client ID metadata documents. An unauthenticated request gets a 401 whose `WWW-Authenticate` header points to the [protected resource metadata](https://aeometer.com/.well-known/oauth-protected-resource/mcp); MCP clients follow it to the [authorization server metadata](https://aeometer.com/.well-known/oauth-authorization-server), open the sign-in page, and ask the user to approve the `mcp:tools` scope. Access tokens last five minutes and refresh automatically.

The REST API accepts a signed-in website session or a bearer token. Accounts are free to create at [sign up](https://aeometer.com/sign-up); the free plan needs no card.

## Rate limits

The REST API and the MCP endpoint allow **120 requests per minute** per credential, or per client address when there is none. Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the window resets). Over the limit you get HTTP 429 with a `Retry-After` header; wait that many seconds before retrying.

## Errors

Every 4xx and 5xx response from the API has the same JSON body. Branch on `code`, show `message` to people, and read `data` for validation details.

```json
{
  "defined": false,
  "code": "NOT_FOUND",
  "status": 404,
  "message": "Not found."
}
```

Common codes: `BAD_REQUEST` (400, invalid input), `UNAUTHORIZED` (401), `FORBIDDEN` (403, including plan limits), `NOT_FOUND` (404), `TOO_MANY_REQUESTS` (429) and `INTERNAL_SERVER_ERROR` (500). MCP tool failures return a tool result with `isError: true` and the same message.

## Versioning and deprecation

- The API version is in the path: `/api/v1`. The MCP server reports its version in `serverInfo`.
- Within a version, changes are additive only: new endpoints, new optional inputs, new response fields. Clients should ignore fields they do not recognize.
- Breaking changes ship under a new path version. The previous version keeps working for at least 90 days after the new one is announced.
- Deprecated endpoints respond with `Deprecation` and `Sunset` headers and a `Link` to migration notes, and every deprecation is listed in the [changelog](https://aeometer.com/changelog).

## When to use AEOmeter from an agent

Use it when a user asks whether ChatGPT, Claude, Perplexity or Google AI Overviews mention their brand, how they compare with competitors, or which pages AI answers cite. Start with `list_organizations` and `list_projects`, read results with `list_observations`, and queue fresh checks with `create_run`. Checks run in the user's Chrome through the AEOmeter extension, so a new run can take minutes and needs that browser open. The [MCP feature page](https://aeometer.com/features/mcp) shows example questions.

---

- Web page: https://aeometer.com/help/api
- Start tracking your brand: https://aeometer.com/sign-up
- All pages for AI agents: https://aeometer.com/llms.txt