API & MCP

Authentication

Mint a key in Settings → API access (Scale plan). Keys look like grk_…, are read-only, and are scoped to your workspace. Pass yours as a bearer token — or, as a fallback for tools that can't set headers, as a ?api_key= query parameter. The same key authenticates both the REST API and the MCP server. You can revoke a key any time from the same settings page.

Authorization: Bearer grk_live_9f2c…redacted…

Requests with a missing, unknown, or revoked key return 401 with a JSON body { "error": "Invalid or missing API key" }.

List brands

GET /api/v1/brands — every brand in your workspace with its latest visibility snapshot. Fields are nullfor brands that haven't been tracked yet.

curl -H "Authorization: Bearer grk_live_9f2c…" \
  https://app.genairanker.com/api/v1/brands

{
  "brands": [
    {
      "id": "b3f1c2a4-…",
      "name": "Acme",
      "domain": "acme.com",
      "industry": "SaaS",
      "country": "US",
      "visibility_score": 61,
      "mention_rate": 0.42,
      "last_tracked": "2026-08-16"
    }
  ]
}

Brand detail

GET /api/v1/brands/:id— full detail for one brand: scores by AI engine, top competitors and the source domains cited when a rival wins, the buyer funnel, AI-referred traffic & revenue, revenue by topic, and the authoritative sources AI trusts for your category (Citation Authority). Use an id from the list endpoint. A brand outside your workspace returns 404.

curl -H "Authorization: Bearer grk_live_9f2c…" \
  https://app.genairanker.com/api/v1/brands/b3f1c2a4-…

{
  "brand": {
    "id": "b3f1c2a4-…", "name": "Acme", "domain": "acme.com",
    "industry": "SaaS", "country": "US"
  },
  "visibility": {
    "score": 61, "mention_rate": 0.42, "share_of_answer": 0.31,
    "avg_position": 2.4, "answers_analyzed": 240
  },
  "by_engine": [
    { "engine": "openai", "score": 68, "mention_rate": 0.50 },
    { "engine": "anthropic", "score": 55, "mention_rate": 0.36 }
  ],
  "competitors": [ { "name": "Globex", "mentions": 84 } ],
  "competitor_sources": [ { "domain": "g2.com", "count": 12 } ],
  "funnel": [
    { "stage": "awareness", "score": 55, "mention_rate": 0.40, "prompts": 12 }
  ],
  "ai_traffic": {
    "sessions": 1240, "conversions": 38, "revenue": 310000,
    "currency": "INR", "days": 30,
    "by_engine": [ { "engine": "openai", "sessions": 720 } ]
  },
  "revenue_by_topic": {
    "currency": "INR", "total_revenue": 310000,
    "topics": [
      { "topic": "CRM", "ai_visibility": 0.7, "sessions": 40,
        "revenue": 90000, "state": "money" }
    ]
  },
  "citation_authority": {
    "topics_matched": 6,
    "sources": [
      { "domain": "g2.com", "reach": 9, "you_are_cited": false, "earn": true }
    ]
  }
}

revenue_by_topic is nulluntil there's enough AI-referred revenue to break down by topic. ai_traffic figures cover the trailing days window shown in the response.

Rate limits & format

600 requests per hour per key (shared across the REST API and MCP). Over the limit returns 429 with { "error": "Rate limit exceeded" }. All responses are JSON with permissive CORS (Access-Control-Allow-Origin: *), so you can call the API straight from a browser dashboard. Errors always return a JSON { "error": "…" } with the matching HTTP status.

MCP (Model Context Protocol)

We host a live MCP server so AI agents (Claude, etc.) can query your brands' AI-search visibility, buyer funnel and AI-referred revenue right inside a conversation. It speaks JSON-RPC 2.0 over streamable HTTP (protocol 2025-06-18) at POST /api/mcp, authenticated with the same grk_ API key. Two tools are exposed:

• list_brands — your brands with their latest visibility score and mention rate.
• get_brand — full detail for one brand. Pass brand_id (from list_brands) or a domain.

{
  "mcpServers": {
    "genai-ranker": {
      "type": "http",
      "url": "https://app.genairanker.com/api/mcp",
      "headers": { "Authorization": "Bearer grk_live_9f2c…" }
    }
  }
}

Add that to your MCP client config and ask, e.g., “What's my AI-search visibility for acme.com, and how much revenue did AI drive last month?”