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_requiredand an estimate. It runs only when you repeat it withconfirm: true. - Rate limit: 60 requests a minute per key. Over the limit you get
429with aRetry-Afterheader. - 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_businessesfreeadd_businessneeds confirmestimate_scanfreerun_ai_scanneeds confirmrun_maps_scanneeds confirmget_scanfreecompare_scansfreerun_auditneeds confirmget_auditfreeget_fix_kitneeds confirmcreate_prospect_batchneeds confirmget_prospect_batchfreeget_usagefree
claude mcp add --transport http rankbyai https://rankbyai.live/api/mcp \ --header "Authorization: Bearer rbai_live_YOUR_KEY"
{
"mcpServers": {
"rankbyai": {
"url": "https://rankbyai.live/api/mcp",
"headers": {
"Authorization": "Bearer rbai_live_YOUR_KEY"
}
}
}
}{
"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"
}
}
}
}curl https://rankbyai.live/api/v1/businesses \ -H "Authorization: Bearer rbai_live_YOUR_KEY"
REST reference
/api/v1/businessesList tracked businesses
| limit | integer · query | Default: 50. |
| offset | integer · query | Default: 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.
/api/v1/businessesAdd 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`.
| name * | string | |
| city | string | |
| country | "US" | "GB" | "CA" | "AU" | "IE" | "NZ" | Default: "US". |
| lat | number | |
| lng | number | |
| address | string | |
| website | string (uri) | |
| phone | string | |
| primary_category | string | |
| confirm | boolean | Without 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.
/api/v1/businesses/{id}Get a business and its recent scans
| id * | string (uuid) · path | Id 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.
/api/v1/scansEstimate 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).
| business_id * | string (uuid) | |
| kind * | "ai" | "maps" | |
| keyword * | string | The service people search for, e.g. "dentist". `prompt` is accepted as an alias. |
| prompt_template | string | AI scans only. Must contain {service} and {neighbourhood} or {city}. |
| grid_size * | 1 | 3 | 5 | 7 | 9 | |
| radius_miles | number | Default: 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". |
| confirm | boolean | Without 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.
/api/v1/scans/compareCompare two finished scans of the same business
| a * | string (uuid) · query | The earlier scan. |
| b * | string (uuid) · query | The 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.
/api/v1/scans/{id}Scan status, summary and cost
| id * | string (uuid) · path | Id 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.
/api/v1/scans/{id}/pointsEvery grid point, with the AI answers for AI scans
| id * | string (uuid) · path | Id 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.
/api/v1/auditsEstimate or run a Local AI Audit
| business_id * | string (uuid) | |
| service * | string | The main service, e.g. "dentist". |
| months | integer | Months to close the review gap. Default: 3. |
| funding | "byok" | "credits" | byok = your own API keys; credits = included scans. Default: "byok". |
| confirm | boolean | Without 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.
/api/v1/audits/{id}Audit score, findings with evidence, and checks that could not run
| id * | string (uuid) · path | Id 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.
/api/v1/audits/{id}/fix-kitThe 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`.
| id * | string (uuid) · path | Id of the audit. |
| confirm | boolean · 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.
/api/v1/prospectsEstimate 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.
| niche * | string | |
| city * | string | |
| country | "US" | "GB" | "CA" | "AU" | "IE" | "NZ" | Default: "US". |
| max_reports | integer | Default: 10. |
| funding | "byok" | "credits" | byok = your own API keys; credits = included scans. Default: "byok". |
| confirm | boolean | Without 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.
/api/v1/prospects/{id}Batch progress and the reports that are ready
| id * | string (uuid) · path | Id 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.
/api/v1/usageThis 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.