API & MCP · Ranking by BobWork

Authentication

Create a key in Ranking → API & MCP. It starts with rk_live_ and is shown once. Send it on every request:

Authorization: Bearer rk_live_YOUR_KEY

Base URL: https://ranking.bobwork.ai/api/v1. Requests and responses are JSON. x-api-key: rk_live_… works too. Keys can be revoked any time; you can hold 10 active keys.

Pricing

No plan and no subscription. Calls are paid from the same credit as the app, at the same per-check prices. Results we already fetched in the last 7 days (keyword, domain and backlink research), project reads and page audits are free. Every response carries cost_usd (what this call cost) and balance_usd (what you have left).

Call	Typical cost
Google SERP, top 100 with AI Overview	$0.027
AI answer — Google AI Overview or AI Mode	$0.006
AI answer — Perplexity	$0.011
AI answer — Claude	$0.02
AI answer — ChatGPT or Gemini	$0.048–0.051
AI visibility, 1 prompt × 6 engines	≈ $0.14
Keyword ideas / domain overview / backlinks	$0.018–0.07
Page audit, project reads, cached research	Free

Top up from $1 in Billing — an account needs one top-up before its first call. When credit reaches zero, paid calls return 402 until you top up — nothing is charged to a card automatically.

MCP setup

The MCP server is https://ranking.bobwork.ai/api/mcp (Streamable HTTP). It exposes every endpoint below as a tool, billed the same way. In Claude Code:

claude mcp add --transport http ranking https://ranking.bobwork.ai/api/mcp \
  --header "Authorization: Bearer rk_live_YOUR_KEY"

Claude Desktop, Cursor and other clients that read an mcpServers config:

{
  "mcpServers": {
    "ranking": {
      "type": "http",
      "url": "https://ranking.bobwork.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer rk_live_YOUR_KEY"
      }
    }
  }
}

For a client that cannot send headers, put the key in the URL: https://ranking.bobwork.ai/api/mcp?key=rk_live_…. That URL is then a secret — don’t paste it anywhere public.

Try asking your assistant: “Use Ranking to check whether ChatGPT and Perplexity recommend us for best CRM for small agencies, and which pages they cite.”

Errors and limits

Errors look like {"error": {"code": "insufficient_credit", "message": "…", "top_up_url": "…"}}.

Status	Code	Meaning
400	`bad_request`	A field is missing or invalid; the message names it.
401	`unauthorized`	Missing, malformed or revoked key.
402	`payment_required`	This account hasn’t topped up yet. Top up at least $1 to start.
402	`insufficient_credit`	Your credit is used up. Top up from $1.
404	`not_found`	Unknown endpoint or a project that isn’t yours.
429	`rate_limited`	More than 60 requests per minute on one key.
502	`upstream_error`	The search engine or AI engine failed. Retry; Google AI Overviews fail now and then.

Calls run live and take 2–25 seconds (AI answers are the slow ones). ai/visibility collects at most 12 answers per call to stay inside the 60-second limit. Location codes: 2840 United States, 2826 United Kingdom, 2036 Australia, 2124 Canada, 2702 Singapore, 2458 Malaysia, 2356 India, 2484 Mexico, 2276 Germany.

Endpoints

GET `/api/v1/account`

Your credit balance, active keys and API spend this month.

Cost: Free
MCP tool: account_balance

Request

curl https://ranking.bobwork.ai/api/v1/account \
  -H "Authorization: Bearer $RANKING_KEY"

Response

{
  "email": "you@company.com",
  "active_keys": 2,
  "month": {
    "calls": 184,
    "spent_usd": 3.41
  },
  "active": true,
  "top_up": "https://ranking.bobwork.ai/app/billing",
  "cost_usd": 0,
  "balance_usd": 21.37
}

POST `/api/v1/serp`

Live Google search for one keyword, top 100: where your domain ranks, SERP features, and whether the AI Overview cites you. Pass competitors to get their positions too.

Cost: ≈ $0.006 (depth 10) – $0.027 (depth 100)
MCP tool: check_serp

Request

curl https://ranking.bobwork.ai/api/v1/serp \
  -H "Authorization: Bearer $RANKING_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword": "whatsapp crm", "domain": "example.com", "brand": "Example", "competitors": ["rival.com"], "location_code": 2840, "device": "desktop", "depth": 100}'

Response

{
  "keyword": "whatsapp crm",
  "domain": "example.com",
  "position": 7,
  "url": "https://example.com/whatsapp-crm",
  "serp_features": [
    "ai_overview",
    "people_also_ask",
    "video"
  ],
  "ai_overview": {
    "present": true,
    "cited": true,
    "mentioned": true,
    "rank": 3,
    "sources": [
      {
        "domain": "rival.com",
        "url": "https://rival.com/blog/best-whatsapp-crm"
      }
    ]
  },
  "competitors": {
    "rival.com": 2
  },
  "results": [
    {
      "rank": 1,
      "domain": "hubspot.com",
      "url": "…",
      "title": "…"
    }
  ],
  "cost_usd": 0.0244,
  "balance_usd": 21.34
}

POST `/api/v1/ai/answer`

Ask one AI engine one question with web search on. Returns the full answer and its sources, and whether your brand was named, in which order among brands, and whether your site was cited. Engines: chatgpt, perplexity, gemini, claude, aio (Google AI Overview), aimode (Google AI Mode).

Cost: $0.006 (aio, aimode) · ≈ $0.011 (perplexity) · ≈ $0.02 (claude) · ≈ $0.05 (chatgpt, gemini)
MCP tool: ai_answer

Request

curl https://ranking.bobwork.ai/api/v1/ai/answer \
  -H "Authorization: Bearer $RANKING_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is the best WhatsApp CRM for a small team?", "engine": "perplexity", "brand": "Example", "domain": "example.com", "competitors": [{"domain": "rival.com", "name": "Rival"}]}'

Response

{
  "prompt": "What is the best WhatsApp CRM for a small team?",
  "engine": "perplexity",
  "model": "sonar",
  "answer_shown": true,
  "answer": "For small teams, …",
  "sources": [
    {
      "url": "https://…",
      "domain": "g2.com",
      "title": "…"
    }
  ],
  "mentioned": true,
  "linked": false,
  "rank": 2,
  "sentiment": "positive",
  "brands": [
    {
      "name": "Rival",
      "domain": "rival.com",
      "rank": 1,
      "linked": true,
      "you": false,
      "competitor": true
    },
    {
      "name": "Example",
      "domain": "example.com",
      "rank": 2,
      "linked": false,
      "you": true,
      "competitor": false
    }
  ],
  "cost_usd": 0.0088,
  "balance_usd": 21.33
}

POST `/api/v1/ai/visibility`

Up to 12 prompt × engine answers in one call (e.g. 2 prompts × 6 engines), summarised: visibility (share of answers that name you) with a 95% Wilson interval, citation rate, share of voice against your competitors, per-engine breakdown. All engines run when engines is omitted.

Cost: Sum of the answers · ≈ $0.14 for 1 prompt × 6 engines
MCP tool: ai_visibility

Request

curl https://ranking.bobwork.ai/api/v1/ai/visibility \
  -H "Authorization: Bearer $RANKING_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompts": ["Best WhatsApp shared inbox for a support team?"], "engines": ["chatgpt", "perplexity", "gemini", "claude", "aio", "aimode"], "brand": "Example", "domain": "example.com", "competitors": [{"domain": "rival.com", "name": "Rival"}]}'

Response

{
  "summary": {
    "answers": 6,
    "named": 2,
    "cited": 1,
    "visibility": 0.333,
    "visibility_ci95": [
      0.097,
      0.7
    ],
    "citation_rate": 0.167,
    "share_of_voice": [
      {
        "name": "Rival",
        "mentions": 5,
        "share": 0.714
      },
      {
        "name": "Example",
        "mentions": 2,
        "share": 0.286
      }
    ],
    "by_engine": [
      {
        "engine": "chatgpt",
        "answers": 1,
        "named": 1,
        "cited": 0
      }
    ]
  },
  "results": [
    "…one ai/answer object per prompt × engine…"
  ],
  "cost_usd": 0.118,
  "balance_usd": 21.2
}

POST `/api/v1/keywords/ideas`

Keyword ideas for a seed with volume, difficulty (0–100), CPC, intent, SERP features and a 12-month trend. limit ≤ 300.

Cost: ≈ $0.07 · free when cached (7 days)
MCP tool: keyword_ideas

Request

curl https://ranking.bobwork.ai/api/v1/keywords/ideas \
  -H "Authorization: Bearer $RANKING_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seed": "whatsapp chatbot", "limit": 50, "location_code": 2840}'

Response

{
  "seed": "whatsapp chatbot",
  "count": 50,
  "items": [
    {
      "keyword": "whatsapp chatbot",
      "volume": 5400,
      "difficulty": 41,
      "cpc": 12.3,
      "intent": "commercial",
      "serp_features": [
        "ai_overview",
        "video"
      ],
      "trend": [
        {
          "month": "2025-11",
          "volume": 4400
        }
      ]
    }
  ],
  "cost_usd": 0.0634
}

POST `/api/v1/keywords/metrics`

Volume, difficulty, CPC, intent and trend for up to 100 keywords you already have.

Cost: ≈ $0.02 · free when cached (7 days)
MCP tool: keyword_metrics

Request

curl https://ranking.bobwork.ai/api/v1/keywords/metrics \
  -H "Authorization: Bearer $RANKING_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["whatsapp crm", "whatsapp api pricing"], "location_code": 2840}'

Response

{
  "items": [
    {
      "keyword": "whatsapp crm",
      "volume": 320,
      "difficulty": 7,
      "cpc": 18.5,
      "intent": "commercial"
    }
  ],
  "cost_usd": 0.0169
}

POST `/api/v1/domain/overview`

Organic overview of any domain: ranking keywords, estimated monthly traffic and its value in USD, position distribution, new / up / down / lost keywords.

Cost: ≈ $0.018 · free when cached (7 days)
MCP tool: domain_overview

Request

curl https://ranking.bobwork.ai/api/v1/domain/overview \
  -H "Authorization: Bearer $RANKING_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "rival.com", "location_code": 2840}'

Response

{
  "domain": "rival.com",
  "keywords": 2115,
  "traffic": 1419,
  "traffic_value_usd": 5693,
  "positions": {
    "1": 30,
    "2-3": 49,
    "4-10": 460,
    "11-20": 380,
    "21-50": 600,
    "51-100": 596
  },
  "movement": {
    "new": 1156,
    "up": 200,
    "down": 310,
    "lost": 1446
  },
  "cost_usd": 0.017
}

POST `/api/v1/domain/keywords`

Keywords a domain ranks for, by traffic, with position and ranking URL. limit ≤ 1000.

Cost: ≈ $0.018 per 100 rows · free when cached (7 days)
MCP tool: domain_keywords

Request

curl https://ranking.bobwork.ai/api/v1/domain/keywords \
  -H "Authorization: Bearer $RANKING_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "rival.com", "limit": 100}'

Response

{
  "domain": "rival.com",
  "total": 2115,
  "items": [
    {
      "keyword": "…",
      "volume": 1900,
      "difficulty": 12,
      "position": 3,
      "url": "https://rival.com/…",
      "traffic": 210
    }
  ],
  "cost_usd": 0.0174
}

POST `/api/v1/domain/competitors`

Domains that compete with a domain on Google, ranked by shared keywords.

Cost: ≈ $0.018 · free when cached (7 days)
MCP tool: domain_competitors

Request

curl https://ranking.bobwork.ai/api/v1/domain/competitors \
  -H "Authorization: Bearer $RANKING_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "limit": 40}'

Response

{
  "domain": "example.com",
  "items": [
    {
      "domain": "rival.com",
      "shared_keywords": 312,
      "avg_position": 18.4,
      "keywords": 2115,
      "traffic": 1419
    }
  ],
  "cost_usd": 0.0174
}

POST `/api/v1/backlinks/summary`

Backlink profile: strength (0–100), backlinks, referring domains, referring IPs, spam score, broken backlinks.

Cost: ≈ $0.037 · free when cached (7 days)
MCP tool: backlinks_summary

Request

curl https://ranking.bobwork.ai/api/v1/backlinks/summary \
  -H "Authorization: Bearer $RANKING_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "rival.com"}'

Response

{
  "domain": "rival.com",
  "strength": 36,
  "backlinks": 52286,
  "referring_domains": 4510,
  "referring_domains_nofollow": 2133,
  "referring_ips": 2911,
  "spam_score": 10,
  "broken_backlinks": 512,
  "first_seen": "2019-01-20 14:41:21 +00:00",
  "cost_usd": 0.033
}

POST `/api/v1/backlinks/referring-domains`

Strongest referring domains linking to a domain. limit ≤ 1000.

Cost: ≈ $0.037 per 100 · free when cached (7 days)
MCP tool: referring_domains

Request

curl https://ranking.bobwork.ai/api/v1/backlinks/referring-domains \
  -H "Authorization: Bearer $RANKING_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "limit": 100}'

Response

{
  "domain": "example.com",
  "total": 349,
  "items": [
    {
      "domain": "blog.partner.com",
      "strength": 48,
      "backlinks": 12,
      "dofollow": 12,
      "first_seen": "2024-03-02",
      "spam_score": 2
    }
  ],
  "cost_usd": 0.0324
}

POST `/api/v1/page/audit`

Fetch one page the way AI crawlers do (no JavaScript): on-page facts, AI-readiness signals — which AI crawlers robots.txt lets in, answer-first question headings, structured data, canonical host — and, with a keyword, an on-page score.

Cost: Free
MCP tool: audit_page

Request

curl https://ranking.bobwork.ai/api/v1/page/audit \
  -H "Authorization: Bearer $RANKING_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/pricing", "keyword": "crm pricing"}'

Response

{
  "url": "https://example.com/pricing",
  "status": 200,
  "response_ms": 370,
  "page": {
    "title": "Pricing — Example",
    "h1": [
      "Pricing"
    ],
    "words": 1240,
    "schema_types": [
      "Organization",
      "FAQPage"
    ]
  },
  "ai_readiness": {
    "ai_crawlers": [
      {
        "bot": "GPTBot",
        "allowed": true
      },
      {
        "bot": "PerplexityBot",
        "allowed": true
      }
    ],
    "readable_without_javascript": true,
    "canonical_on_same_host": true,
    "question_headings": 6,
    "questions_answered_first": 4,
    "structured_data": true
  },
  "on_page": {
    "keyword": "crm pricing",
    "score": 76,
    "checks": [
      "…"
    ]
  },
  "cost_usd": 0.001
}

GET `/api/v1/projects`

Your Ranking projects (the ones you track in the app).

Cost: Free
MCP tool: list_projects

Request

curl https://ranking.bobwork.ai/api/v1/projects \
  -H "Authorization: Bearer $RANKING_KEY"

Response

{
  "items": [
    {
      "id": "p_1a2b3c",
      "name": "Example",
      "domain": "example.com",
      "keywords": 40,
      "prompts": 12
    }
  ],
  "cost_usd": 0.001
}

GET `/api/v1/projects/{id}/rankings`

Latest tracked Google position per keyword from your scheduled checks.

Cost: Free
MCP tool: project_rankings

Request

curl https://ranking.bobwork.ai/api/v1/projects/p_1a2b3c/rankings \
  -H "Authorization: Bearer $RANKING_KEY"

Response

{
  "project": {
    "id": "p_1a2b3c",
    "domain": "example.com"
  },
  "items": [
    {
      "keyword": "whatsapp crm",
      "checked": "2026-10-21",
      "position": 7,
      "ai_overview": {
        "present": true,
        "cited": true
      },
      "competitors": {
        "rival.com": 2
      }
    }
  ],
  "cost_usd": 0.001
}

GET `/api/v1/projects/{id}/ai`

Latest tracked AI answer per prompt × engine, plus visibility with a 95% interval.

Cost: Free
MCP tool: project_ai_visibility

Request

curl https://ranking.bobwork.ai/api/v1/projects/p_1a2b3c/ai \
  -H "Authorization: Bearer $RANKING_KEY"

Response

{
  "project": {
    "id": "p_1a2b3c"
  },
  "summary": {
    "answers": 60,
    "named": 9,
    "visibility": 0.15,
    "visibility_ci95": [
      0.081,
      0.262
    ]
  },
  "items": [
    {
      "prompt": "…",
      "engine": "claude",
      "mentioned": true,
      "cited": false,
      "rank": 2
    }
  ],
  "cost_usd": 0.001
}

Ranking API and MCP server

Authentication

Pricing

MCP setup

Errors and limits

Endpoints

GET /api/v1/account

Request

Response

POST /api/v1/serp

Request

Response

POST /api/v1/ai/answer

Request

Response

POST /api/v1/ai/visibility

Request

Response

POST /api/v1/keywords/ideas

Request

Response

POST /api/v1/keywords/metrics

Request

Response

POST /api/v1/domain/overview

Request

Response

POST /api/v1/domain/keywords

Request

Response

POST /api/v1/domain/competitors

Request

Response

POST /api/v1/backlinks/summary

Request

Response

POST /api/v1/backlinks/referring-domains

Request

Response

POST /api/v1/page/audit

Request

Response

GET /api/v1/projects

Request

Response

GET /api/v1/projects/{id}/rankings

Request

Response

GET /api/v1/projects/{id}/ai

Request

Response

GET `/api/v1/account`

POST `/api/v1/serp`

POST `/api/v1/ai/answer`

POST `/api/v1/ai/visibility`

POST `/api/v1/keywords/ideas`

POST `/api/v1/keywords/metrics`

POST `/api/v1/domain/overview`

POST `/api/v1/domain/keywords`

POST `/api/v1/domain/competitors`

POST `/api/v1/backlinks/summary`

POST `/api/v1/backlinks/referring-domains`

POST `/api/v1/page/audit`

GET `/api/v1/projects`

GET `/api/v1/projects/{id}/rankings`

GET `/api/v1/projects/{id}/ai`