---
title: Moatlight documentation
description: REST API, OAuth login, MCP server and discovery files for measuring AI search visibility.
canonical: https://www.moatlight.com/docs
last-updated: 2026-11-05
---

# Moatlight documentation

> Measure whether ChatGPT and Google AI Overview name a business, and read a ranked plan of changes. REST, MCP and OAuth 2.0. Public endpoints and a sandbox need no login.

Canonical page: https://www.moatlight.com/docs

## Overview

The Moatlight API lets an AI agent or a script measure whether ChatGPT and Google AI Overview name a business, see which rivals they name instead, and read a ranked plan of changes. It is REST over JSON, with an MCP server for agents and an OpenAPI description.

Use it when a person asks about AI search visibility (GEO or AEO) for a website, wants the buyer questions AI answers with a rival, or wants to check how ready a site is for AI agents. Do not use it to write or publish content: Moatlight measures and advises only.

- Base URL: https://www.moatlight.com/api/v1
- OpenAPI: https://www.moatlight.com/openapi.json
- MCP server (Streamable HTTP): https://www.moatlight.com/mcp
- Docs MCP server: https://www.moatlight.com/mcp/docs
- Sandbox (no login, made-up data): https://www.moatlight.com/api/v1/sandbox
- Contact: ceo@moatlight.com

## Quickstart

Try the public endpoints and the sandbox first. They need no login and cost nothing.

```bash
curl https://www.moatlight.com/api/v1/product
curl https://www.moatlight.com/api/v1/pricing
curl https://www.moatlight.com/api/v1/sandbox/reports/demo
```

Then start a sandbox report. It validates the body like the real endpoint and returns a fake report.

```bash
curl -X POST https://www.moatlight.com/api/v1/sandbox/reports \
  -H 'Content-Type: application/json' \
  -d '{"website":"yourcompany.com"}'
```

## Authentication

Account and report endpoints use OAuth 2.0 (authorization code with PKCE). The user signs in and approves the scopes you ask for. Apps register themselves with Dynamic Client Registration (RFC 7591); no manual approval or API key is needed.

- Protected resource metadata (RFC 9728): https://www.moatlight.com/.well-known/oauth-protected-resource
- Authorization server metadata (RFC 8414): https://www.moatlight.com/.well-known/oauth-authorization-server
- Registration endpoint: https://www.moatlight.com/api/auth/oauth2/register
- Authorization endpoint: https://www.moatlight.com/api/auth/oauth2/authorize
- Token endpoint: https://www.moatlight.com/api/auth/oauth2/token
- Agent identity (no browser redirect: you name the person's email, they type a code): POST https://www.moatlight.com/agent/identity
- Step-by-step guide for agents: https://www.moatlight.com/auth.md

Send the token as Authorization: Bearer <access_token>. Access tokens last one hour; ask for the offline_access scope to get a refresh token. Without a valid token the API answers 401 with a WWW-Authenticate header that points to the metadata above.

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://www.moatlight.com/.well-known/oauth-protected-resource"
Content-Type: application/json

{"error":{"code":"unauthorized","message":"This endpoint needs a bearer access token.","hint":"..."}}
```

### Scopes

| Scope | What it allows |
| --- | --- |
| account:read | Read your plan, limits and whether you hold the Early Access pass. |
| reports:read | Read your reports: status, visibility numbers, competitors and the ranked plan. |
| reports:write | Start a report for a website and confirm its setup. Uses your free report allowance. |
| agent-readiness:read | Read the stored agent readiness scan of a report (Early Access pass). |
| agent-readiness:scan | Run an agent readiness scan for a report (Early Access pass). |

## Plans and access

The API follows the user's plan. GET /api/v1/me returns it. A payment needs a person in a browser; an agent cannot pay, so a gated call answers 402 with a link to the pricing page.

|  | Free | Early Access pass |
| --- | --- | --- |
| Price | US$0, no card | US$10 one-time, no subscription (Dodo Payments is the seller of record) |
| Websites | 1 | 1 |
| Reports | 1 per 30 days | 1 per 30 days |
| Visibility reports and ranked plan | Yes | Yes |
| Agent readiness scan (API and tab) | No (402) | Yes, for 90 days |
| Refund | n/a | 14 days, full |

## Report lifecycle

A report is a short job. Each step is one call; the report's stage tells you what to do next.

| Stage | What to do |
| --- | --- |
| analyzing | Poll GET /api/v1/reports/{id} every few seconds until stage is needs_confirmation. |
| analysis_failed | Call POST /api/v1/reports again with the same website to retry. |
| needs_confirmation | Review profile and questions, then call POST /api/v1/reports/{id}/start. |
| running | Poll GET /api/v1/reports/{id} until stage is finished (about two minutes). |
| finished | Read the result with GET /api/v1/reports/{id} and GET /api/v1/reports/{id}/actions. |
| failed | See run_error. If run_failure is 'limit', the free allowance is used; otherwise start again. |

```bash
# 1. start (scope reports:write)
curl -X POST https://www.moatlight.com/api/v1/reports -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"website":"yourcompany.com"}'

# 2. poll until stage = needs_confirmation
curl https://www.moatlight.com/api/v1/reports/$ID -H "Authorization: Bearer $TOKEN"

# 3. confirm the proposed setup and run (about two minutes)
curl -X POST https://www.moatlight.com/api/v1/reports/$ID/start -H "Authorization: Bearer $TOKEN"

# 4. read the result and the plan
curl https://www.moatlight.com/api/v1/reports/$ID/actions -H "Authorization: Bearer $TOKEN"
```

Show the user the proposed profile and questions before step 3. Do not invent facts about the business.

## Endpoints

| Method and path | Scope | What it does |
| --- | --- | --- |
| GET /api/v1/product | none | What Moatlight does and when to use it |
| GET /api/v1/pricing | none | Plans and prices |
| GET /api/v1/faq | none | Frequently asked questions |
| GET /api/v1/sample-report | none | A finished sample report on made-up data |
| GET /api/v1/me | account:read | The signed-in user, plan and limits |
| GET /api/v1/reports | reports:read | List the user's reports |
| POST /api/v1/reports | reports:write | Start a report for a website |
| GET /api/v1/reports/{reportId} | reports:read | Read one report: stage, setup to confirm, or results |
| POST /api/v1/reports/{reportId}/start | reports:write | Confirm the setup and run the report |
| GET /api/v1/reports/{reportId}/actions | reports:read | The ranked plan of changes and the questions you lost |
| GET /api/v1/reports/{reportId}/agent-readiness | agent-readiness:read | Stored agent readiness scan (Early Access pass) |
| POST /api/v1/reports/{reportId}/agent-readiness/scan | agent-readiness:scan | Run an agent readiness scan (Early Access pass) |

Request and response schemas, parameters and error codes for every endpoint are in the OpenAPI document at https://www.moatlight.com/openapi.json. The sandbox mirrors the report endpoints under https://www.moatlight.com/api/v1/sandbox.

### Example: read a finished report

```json
{
  "id": "…",
  "website": "yourcompany.com",
  "stage": "finished",
  "summary": {
    "answers": 50,
    "named": 18,
    "share_of_voice": {
      "k": 18,
      "n": 112,
      "brands": 11
    },
    "rank": {
      "place": 4,
      "of": 11
    },
    "per_engine": [
      {
        "engine": "ChatGPT",
        "answers": 25,
        "named": 7
      }
    ],
    "top_brands": [
      {
        "name": "Rival Co",
        "appeared": 34,
        "own": false
      }
    ],
    "lost_questions": 6
  }
}
```

For a finished report: up to three ranked moves (reason, exact edit, page, effort) and, for each buyer question AI answered with a rival, who won and why.

## MCP server

Agents can use Moatlight as tools over the Model Context Protocol (Streamable HTTP). https://www.moatlight.com/mcp exposes the same operations as the REST API as tools; the docs server at https://www.moatlight.com/mcp/docs lets an agent search these docs.

- Moatlight: https://www.moatlight.com/mcp (server card: https://www.moatlight.com/mcp/server-card)
- Moatlight docs: https://www.moatlight.com/mcp/docs (server card: https://www.moatlight.com/mcp/docs/server-card)

Listing tools needs no login. Calling a tool that reads or writes an account sends the client through the OAuth login above (the server answers 401 with a WWW-Authenticate header). Public tools work without it.

```json
{
  "mcpServers": {
    "moatlight": {
      "url": "https://www.moatlight.com/mcp"
    }
  }
}
```

Tool names: get_product, get_pricing, list_faq, get_sample_report, get_account, list_reports, create_report, get_report, start_report, get_report_actions, get_agent_readiness, scan_agent_readiness.

## Ask endpoint (NLWeb) and agent card (A2A)

POST https://www.moatlight.com/ask answers questions about Moatlight from these docs, the FAQ and the pricing, using the NLWeb protocol (v0.55). Send {"query":{"text":"how much does it cost"}}. Add "prefer":{"streaming":true} for server-sent events (start, result, complete).

```bash
curl -X POST https://www.moatlight.com/ask -H 'Content-Type: application/json' \
  -d '{"query":{"text":"does the free plan need a card"}}'
```

The A2A agent card is at https://www.moatlight.com/.well-known/agent-card.json and its endpoint at https://www.moatlight.com/a2a. It answers questions about Moatlight; starting reports needs the OAuth-protected API.

## Errors

Every error is JSON with a code, a message and a hint. Branch on the code, not the message.

```json
{
  "error": {
    "code": "needs_early_access_pass",
    "message": "Agent readiness is part of the Early Access pass.",
    "hint": "A person must buy the pass in a browser: https://www.moatlight.com/pricing",
    "docs": "https://www.moatlight.com/docs#errors",
    "upgrade_url": "https://www.moatlight.com/pricing"
  }
}
```

| HTTP | Code | Meaning |
| --- | --- | --- |
| 400 | invalid_request, invalid_website, invalid_locale | The body is malformed or the website cannot be used. |
| 401 | unauthorized, invalid_token | No valid bearer token. Follow the WWW-Authenticate header. |
| 402 | needs_early_access_pass | The call needs the pass. Send the user to upgrade_url. |
| 403 | insufficient_scope, domain_cap | The token lacks a scope, or the free plan covers one website. |
| 404 | not_found, no_scan | No such item for this account. |
| 409 | domain_locked, not_ready, not_finished, setup_closed | The call does not fit the report's stage or the 30-day limit (see unlock_at). |
| 422 | site_unreachable, profile_invalid | The website could not be read, or the setup needs the dashboard. |
| 429 | rate_limited | Too many requests. Wait for Retry-After seconds. |
| 503 | unavailable | The feature is off right now. |

## Limits and good manners

- Free plan: 1 website and 1 report every 30 days. A report uses real AI queries, so start one only when the user asks.
- Writes are limited per user per hour (20 report starts, 10 scans). Reads are not metered, but poll no faster than every 5 seconds.
- Agent readiness scans reuse results under 24 hours old. Use force only after a fix is deployed.
- Moatlight reads public pages only and respects robots.txt.
- Do not promise traffic, leads or dates from a report. It shows counts of answers.

## Discovery files

| What | Where |
| --- | --- |
| llms.txt | https://www.moatlight.com/llms.txt |
| Agent view of the home page | https://www.moatlight.com/?mode=agent |
| OpenAPI | https://www.moatlight.com/openapi.json |
| API catalog (RFC 9727) | https://www.moatlight.com/.well-known/api-catalog |
| ARD catalog | https://www.moatlight.com/.well-known/ard.json |
| AI catalog | https://www.moatlight.com/.well-known/ai-catalog.json |
| Agent skills | https://www.moatlight.com/.well-known/agent-skills/index.json |
| A2A agent card | https://www.moatlight.com/.well-known/agent-card.json |
| MCP server cards | https://www.moatlight.com/mcp/server-card |
| OAuth metadata | https://www.moatlight.com/.well-known/oauth-protected-resource |
| Auth guide | https://www.moatlight.com/auth.md |
| Web Bot Auth keys | https://www.moatlight.com/.well-known/http-message-signatures-directory |