Developers · API reference

MazeRank API

A read-only REST API for your AI visibility data. All endpoints are GET, return JSON wrapped in { "data": … }, and accept CORS requests.

Base URL

https://clever-curlew-385.convex.site/api/v1

Authentication

Create a key in the app under Account → API & MCP. Keys start with lr_, are shown once and stored hashed. Send the key as a bearer token or in X-Api-Key.

Bearer

curl https://clever-curlew-385.convex.site/api/v1/sites \
  -H "Authorization: Bearer lr_YOUR_KEY"

Header

curl https://clever-curlew-385.convex.site/api/v1/sites \
  -H "X-Api-Key: lr_YOUR_KEY"

An account key reads the websites you own; for agencies that's every client. Keys are read-only and can be revoked at any time. Up to 20 active keys per account.

Scopes

Each key has one or more scopes. Each endpoint and MCP tool needs exactly one.

sitesratesenginescompetitorsanswersalertsreports

Rate limits

120 requests per minute per key, shared between REST and MCP. Successful responses include X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit you get 429 with Retry-After: 60.

Errors

Errors return { "error": "code" }.

Status	error	Meaning
401	missing_api_key	No key, or the key doesn't start with lr_.
401	invalid_api_key	Key not found or revoked.
403	missing_scope	The key lacks the scope; the response includes "scope".
404	site_not_found	Unknown site id, or not readable by this key.
404	not_found	Unknown path.
429	rate_limited	Over the per-minute limit. Retry-After: 60.

List sites

GET/api/v1/sitesscope: sites

Websites this key can read. Agency keys see every client.

Request

curl "https://clever-curlew-385.convex.site/api/v1/sites" \
  -H "Authorization: Bearer $LR_KEY"

Response · 200

{
  "data": [{
    "id": "k57f3x2c9q8w1e6r4t0y",
    "name": "Dental Studio Lisboa",
    "website": "https://dentalstudio.pt",
    "city": "Lisboa", "country": "PT",
    "languages": ["pt", "en"],
    "plan": "spark",
    "agencyClient": true,
    "brandId": null, "location": null
  }]
}

Get site

GET/api/v1/sites/{id}scope: sites

One website, same shape as an item in List sites.

path · string

Site id from GET /sites.

Request

curl "https://clever-curlew-385.convex.site/api/v1/sites/SITE_ID" \
  -H "Authorization: Bearer $LR_KEY"

Response · 200

{ "data": { "id": "k57f3x2c9q8w1e6r4t0y", "name": "Dental Studio Lisboa", … } }

Mention rates

GET/api/v1/sites/{id}/mention-ratesscope: rates

Mention rate is the percentage of AI answers that name the business. Returns the last 7 days and one row per completed weekly run.

id	path · string	Site id from GET /sites.
weeks	query · integer	Weeks of history. Default 12, max 52.

Request

curl "https://clever-curlew-385.convex.site/api/v1/sites/SITE_ID/mention-rates?weeks=12" \
  -H "Authorization: Bearer $LR_KEY"

Response · 200

{
  "data": {
    "current": { "mentionRate": 42.0, "answers": 312, "window": "last 7 days" },
    "weekly": [
      { "week": "2026-09-28", "mentionRate": 38.4, "answers": 296 },
      { "week": "2026-10-05", "mentionRate": 40.2, "answers": 301 }
    ]
  }
}

Engines

GET/api/v1/sites/{id}/enginesscope: engines

Mention rate per AI engine over the last 7 days, highest first. Engine ids: chatgpt, google_aio, google_ai_mode, gemini, perplexity, claude.

path · string

Site id from GET /sites.

Request

curl "https://clever-curlew-385.convex.site/api/v1/sites/SITE_ID/engines" \
  -H "Authorization: Bearer $LR_KEY"

Response · 200

{
  "data": [
    { "engine": "perplexity", "label": "Perplexity", "mentionRate": 55.0, "answers": 52 },
    { "engine": "chatgpt", "label": "ChatGPT", "mentionRate": 41.2, "answers": 52 }
  ]
}

Competitors

GET/api/v1/sites/{id}/competitorsscope: competitors

Businesses AI names most often for this site's questions over the last 7 days, compared with the site itself.

id	path · string	Site id from GET /sites.
limit	query · integer	Default 20, max 50.

Request

curl "https://clever-curlew-385.convex.site/api/v1/sites/SITE_ID/competitors?limit=20" \
  -H "Authorization: Bearer $LR_KEY"

Response · 200

{
  "data": {
    "you": { "name": "Dental Studio Lisboa", "mentionRate": 42.0 },
    "tracked": ["Clínica Sorriso"],
    "competitors": [
      { "name": "Clínica Sorriso", "mentionRate": 51.3 },
      { "name": "OralMed", "mentionRate": 33.0 }
    ]
  }
}

Answers

GET/api/v1/sites/{id}/answersscope: answers

Recent individual AI answers, newest first. answer is truncated to 4,000 characters.

id	path · string	Site id from GET /sites.
limit	query · integer	Default 50, max 200.
engine	query · string	Filter by engine id, e.g. chatgpt.

Request

curl "https://clever-curlew-385.convex.site/api/v1/sites/SITE_ID/answers?limit=20&engine=chatgpt" \
  -H "Authorization: Bearer $LR_KEY"

Response · 200

{
  "data": [{
    "id": "j97…", "date": "2026-10-12",
    "question": "best dentist in Lisbon for implants",
    "language": "en", "city": "Lisboa", "engine": "chatgpt",
    "mentioned": true, "rank": 2, "sentiment": "positive",
    "competitors": ["Clínica Sorriso"],
    "citations": ["https://www.example.com/top-dentists-lisbon"],
    "ownSiteCited": false,
    "answer": "Here are some well-reviewed options…"
  }]
}

Alerts

GET/api/v1/sites/{id}/alertsscope: alerts

Alerts, newest first: mention-rate drops, competitors overtaking and wrong facts in AI answers. Up to 50.

path · string

Site id from GET /sites.

Request

curl "https://clever-curlew-385.convex.site/api/v1/sites/SITE_ID/alerts" \
  -H "Authorization: Bearer $LR_KEY"

Response · 200

{
  "data": [{
    "id": "m12…", "type": "drop", "status": "open", "engine": "chatgpt",
    "createdAt": "2026-10-12T07:04:11.000Z",
    "text": "ChatGPT mentions dropped from 48% to 31%.",
    "quote": null
  }]
}

Reports

GET/api/v1/sites/{id}/reportsscope: reports

Latest monthly PDF and the shareable weekly report link. URLs are null until a report exists.

path · string

Site id from GET /sites.

Request

curl "https://clever-curlew-385.convex.site/api/v1/sites/SITE_ID/reports" \
  -H "Authorization: Bearer $LR_KEY"

Response · 200

{
  "data": {
    "monthlyPdf": { "month": "2026-09", "generatedAt": "2026-10-01T06:00:00.000Z" },
    "pdfUrl": "…/report.pdf?t=…",
    "weeklyReportUrl": "https://mazerank.com/r/…",
    "lastWeeklyEmailFor": "2026-10-12"
  }
}

MCP server

The same data is available to AI agents over the Model Context Protocol. The server uses streamable HTTP in stateless JSON mode: POST JSON-RPC messages (single or batched), get JSON back. Protocol 2025-06-18; 2025-03-26 is also accepted. Auth, keys and rate limits are the same as REST. See MazeRank Agents for an overview.

Endpoint

https://clever-curlew-385.convex.site/mcp

Call a tool

curl https://clever-curlew-385.convex.site/mcp \
  -H "Authorization: Bearer $LR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_engines","arguments":{"site_id":"SITE_ID"}}}'

Response

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "isError": false,
    "content": [{ "type": "text", "text": "{\"data\":[…]}" }],
    "structuredContent": { "data": [ … ] }
  }
}

Supported methods: initialize, ping, tools/list, tools/call. Auth failures return HTTP 401 with JSON-RPC error code -32001.

Tools

All tools are annotated readOnlyHint: true. tools/list only returns tools the key has scopes for. Tool results match the REST responses.

Tool	Scope	Arguments
list_sites	sites	—
get_mention_rates	rates	site_id, weeks?
get_engines	engines	site_id
get_competitors	competitors	site_id, limit?
get_answers	answers	site_id, limit?, engine?
get_alerts	alerts	site_id
get_reports	reports	site_id

Client setup

Cursor

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "mazerank": {
      "url": "https://clever-curlew-385.convex.site/mcp",
      "headers": { "Authorization": "Bearer lr_YOUR_KEY" }
    }
  }
}

Claude Code

claude mcp add --transport http mazerank \
  https://clever-curlew-385.convex.site/mcp \
  --header "Authorization: Bearer lr_YOUR_KEY"

Claude Desktop (via mcp-remote)

// claude_desktop_config.json
{
  "mcpServers": {
    "mazerank": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://clever-curlew-385.convex.site/mcp",
               "--header", "Authorization:Bearer ${LR_KEY}"],
      "env": { "LR_KEY": "lr_YOUR_KEY" }
    }
  }
}

OpenAI Responses API

// OpenAI Responses API (ChatGPT models)
const res = await openai.responses.create({
  model: "gpt-5",
  tools: [{
    type: "mcp",
    server_label: "mazerank",
    server_url: "https://clever-curlew-385.convex.site/mcp",
    headers: { Authorization: "Bearer " + process.env.LR_KEY },
    require_approval: "never",
  }],
  input: "Which competitors beat us in AI answers this week?",
});