rankbyai.liveAI VISIBILITY, PAID ONCERankbyAI
Developers

API and MCP documentation

Last updated 17 November 2026

Everything in the app is available over a REST API and an MCP server: AI visibility grids, Google Maps grids, audits, Fix Kits and prospect reports. Your scripts or your AI agent can run them and read the results.

The basics

  • Base URL: https://rankbyai.live/api/v1. JSON in, JSON out.
  • Authentication: an API key you create in the app under API & MCP, sent as Authorization: Bearer rbai_live_…. A key is shown once and stored as a hash. Up to 5 keys per workspace.
  • You see the cost first: every request that calls a vendor answers with confirm_required and an estimate. It runs only when you repeat it with confirm: true.
  • Rate limit: 60 requests a minute per key. Over the limit you get 429 with a Retry-After header.
  • Paying for scans: funding: "byok" uses your own API keys at cost; funding: "credits" uses included scans.
  • OpenAPI 3.1: /api/v1/openapi.json.

AI answers vary between runs, places and time; API results can differ from what people see in the consumer apps. Lifetime access is needed to run scans; see pricing.

MCP server

The MCP server is at https://rankbyai.live/api/mcp (Streamable HTTP) and uses the same API key. Tools marked “needs confirm” return the estimate when called without confirm: true and do nothing else, so an agent has to show you the cost before it can spend anything.

  • list_businessesfree
  • add_businessneeds confirm
  • estimate_scanfree
  • run_ai_scanneeds confirm
  • run_maps_scanneeds confirm
  • get_scanfree
  • compare_scansfree
  • run_auditneeds confirm
  • get_auditfree
  • get_fix_kitneeds confirm
  • create_prospect_batchneeds confirm
  • get_prospect_batchfree
  • get_usagefree
Claude CodeRun in a terminal
claude mcp add --transport http rankbyai https://rankbyai.live/api/mcp \
  --header "Authorization: Bearer rbai_live_YOUR_KEY"
Cursor~/.cursor/mcp.json (or .cursor/mcp.json in a project)
{
  "mcpServers": {
    "rankbyai": {
      "url": "https://rankbyai.live/api/mcp",
      "headers": {
        "Authorization": "Bearer rbai_live_YOUR_KEY"
      }
    }
  }
}
Claude DesktopSettings → Developer → Edit Config (claude_desktop_config.json), then restart Claude
{
  "mcpServers": {
    "rankbyai": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://rankbyai.live/api/mcp",
        "--header",
        "Authorization:${RANKBYAI_AUTH}"
      ],
      "env": {
        "RANKBYAI_AUTH": "Bearer rbai_live_YOUR_KEY"
      }
    }
  }
}
REST (curl)Any terminal
curl https://rankbyai.live/api/v1/businesses \
  -H "Authorization: Bearer rbai_live_YOUR_KEY"

REST reference

GET/api/v1/businesses

List tracked businesses

Parameters
limitinteger · queryDefault: 50.
offsetinteger · queryDefault: 0.

Responses: 200 Businesses, newest first. · 400 The request is not valid. · 401 Missing or invalid API key. · 403 The workspace has no lifetime access. · 404 Not found in this workspace. · 429 More than 60 requests in a minute for this key.

POST/api/v1/businesses

Add a business

With `lat` and `lng` the business is stored as given, at no cost. With `name` and `city` it is looked up on Google Maps: one paid lookup on your DataForSEO key, which needs `confirm: true`.

JSON body
name *string
citystring
country"US" | "GB" | "CA" | "AU" | "IE" | "NZ"Default: "US".
latnumber
lngnumber
addressstring
websitestring (uri)
phonestring
primary_categorystring
confirmbooleanWithout it the response is the estimate only. Send true to run and be charged. Default: false.

Responses: 200 Either the estimate (confirm_required) or a business that already existed. · 201 Business created. · 400 The request is not valid. · 401 Missing or invalid API key. · 403 The workspace has no lifetime access. · 404 Not found in this workspace. · 429 More than 60 requests in a minute for this key.

GET/api/v1/businesses/{id}

Get a business and its recent scans

Parameters
id *string (uuid) · pathId of the business.

Responses: 200 The business. · 400 The request is not valid. · 401 Missing or invalid API key. · 403 The workspace has no lifetime access. · 404 Not found in this workspace. · 429 More than 60 requests in a minute for this key.

POST/api/v1/scans

Estimate or run a scan

`kind: ai` asks the AI engines who they recommend at each grid point (grid 1, 3 or 5). `kind: maps` reads the Google Maps rank at each point (grid 3, 5, 7 or 9).

JSON body
business_id *string (uuid)
kind *"ai" | "maps"
keyword *stringThe service people search for, e.g. "dentist". `prompt` is accepted as an alias.
prompt_templatestringAI scans only. Must contain {service} and {neighbourhood} or {city}.
grid_size *1 | 3 | 5 | 7 | 9
radius_milesnumberDefault: 2.
engines"openai" | "perplexity" | "gemini"[]AI scans. Default: every engine you have a key for.
mode"standard" | "priority" | "live"Maps scans: queue speed. Default: "priority".
funding"byok" | "credits"byok = your own API keys; credits = included scans. Default: "byok".
confirmbooleanWithout it the response is the estimate only. Send true to run and be charged. Default: false.

Responses: 200 Estimate only: nothing ran. Repeat the request with confirm: true. · 202 The scan was started. · 400 The request is not valid. · 401 Missing or invalid API key. · 403 The workspace has no lifetime access. · 404 Not found in this workspace. · 429 More than 60 requests in a minute for this key.

GET/api/v1/scans/compare

Compare two finished scans of the same business

Parameters
a *string (uuid) · queryThe earlier scan.
b *string (uuid) · queryThe later scan.

Responses: 200 Per-point and headline changes. · 400 The request is not valid. · 401 Missing or invalid API key. · 403 The workspace has no lifetime access. · 404 Not found in this workspace. · 409 A scan has not finished. · 429 More than 60 requests in a minute for this key.

GET/api/v1/scans/{id}

Scan status, summary and cost

Parameters
id *string (uuid) · pathId of the scan.

Responses: 200 The scan. · 400 The request is not valid. · 401 Missing or invalid API key. · 403 The workspace has no lifetime access. · 404 Not found in this workspace. · 429 More than 60 requests in a minute for this key.

GET/api/v1/scans/{id}/points

Every grid point, with the AI answers for AI scans

Parameters
id *string (uuid) · pathId of the scan.

Responses: 200 Points (and samples for AI scans). · 400 The request is not valid. · 401 Missing or invalid API key. · 403 The workspace has no lifetime access. · 404 Not found in this workspace. · 429 More than 60 requests in a minute for this key.

POST/api/v1/audits

Estimate or run a Local AI Audit

JSON body
business_id *string (uuid)
service *stringThe main service, e.g. "dentist".
monthsintegerMonths to close the review gap. Default: 3.
funding"byok" | "credits"byok = your own API keys; credits = included scans. Default: "byok".
confirmbooleanWithout it the response is the estimate only. Send true to run and be charged. Default: false.

Responses: 200 Estimate only: nothing ran. Repeat the request with confirm: true. · 202 The audit was started. · 400 The request is not valid. · 401 Missing or invalid API key. · 403 The workspace has no lifetime access. · 404 Not found in this workspace. · 429 More than 60 requests in a minute for this key.

GET/api/v1/audits/{id}

Audit score, findings with evidence, and checks that could not run

Parameters
id *string (uuid) · pathId of the audit.

Responses: 200 The audit. · 400 The request is not valid. · 401 Missing or invalid API key. · 403 The workspace has no lifetime access. · 404 Not found in this workspace. · 429 More than 60 requests in a minute for this key.

GET/api/v1/audits/{id}/fix-kit

The audit's Fix Kit

Returns the stored Fix Kit. The first request builds it with one model call; on your own keys that needs `?confirm=true`.

Parameters
id *string (uuid) · pathId of the audit.
confirmboolean · query

Responses: 200 The Fix Kit, or the estimate when it has not been built yet. · 400 The request is not valid. · 401 Missing or invalid API key. · 403 The workspace has no lifetime access. · 404 Not found in this workspace. · 409 The audit has not finished. · 429 More than 60 requests in a minute for this key.

POST/api/v1/prospects

Estimate or start a prospect batch

Finds businesses for a niche and a city and builds a report for the first `max_reports` that are outside the Google Maps top 3. 2 credits per report, or your own keys.

JSON body
niche *string
city *string
country"US" | "GB" | "CA" | "AU" | "IE" | "NZ"Default: "US".
max_reportsintegerDefault: 10.
funding"byok" | "credits"byok = your own API keys; credits = included scans. Default: "byok".
confirmbooleanWithout it the response is the estimate only. Send true to run and be charged. Default: false.

Responses: 200 Estimate only: nothing ran. Repeat the request with confirm: true. · 202 The batch was started. · 400 The request is not valid. · 401 Missing or invalid API key. · 403 The workspace has no lifetime access. · 404 Not found in this workspace. · 429 More than 60 requests in a minute for this key.

GET/api/v1/prospects/{id}

Batch progress and the reports that are ready

Parameters
id *string (uuid) · pathId of the batch.

Responses: 200 The batch. · 400 The request is not valid. · 401 Missing or invalid API key. · 403 The workspace has no lifetime access. · 404 Not found in this workspace. · 429 More than 60 requests in a minute for this key.

GET/api/v1/usage

This month's spend on your own keys per provider, and included-scan credits left

Responses: 200 Usage. · 400 The request is not valid. · 401 Missing or invalid API key. · 403 The workspace has no lifetime access. · 404 Not found in this workspace. · 429 More than 60 requests in a minute for this key.