REST API · v1 · read-only

Pull your AI-visibility data into your own stack

A read-only REST API over the data Rankwise already computes — citations, Share of Voice, dimension scores, and visibility events. Wire it into Looker Studio, your BI, or agency reporting without screen-scraping.

Get your API keyBrowse endpoints
Base path
/api/v1
Auth
Bearer rw_live_…
Plan
Growth and above
Quick start

Three steps to your first response

  1. 1

    Create a key

    In the dashboard, go to Settings → API and create a key. The secret is shown once — store it in a secret manager.

  2. 2

    Make a request

    Send the key as a bearer token against any endpoint, passing ?domain= for a domain you track.

    Request
    curl "https://tryrankwise.com/api/v1/citations?domain=example.com" \
  -H "Authorization: Bearer rw_live_your_key_here"
  3. 3

    Get JSON back

    Every endpoint returns application/json with an X-Rankwise-Version header. Responses are freshly workspace-scoped per request (no-store).

Authentication

Bearer keys, hashed at rest

Every request except the discovery index sends a workspace API key as a bearer token.

Authorization: Bearer rw_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

A key is rw_live_ + 32 random bytes, shown to you exactly once, at creation. Only its SHA-256 hash is stored — the raw secret is never persisted and can't be recovered. Lose it, mint a new one.

Verification hashes the presented key and compares in constant time. Revoked keys authenticate nothing but are retained for audit. Keys are created by workspace admins only.

Plan gate
  • Free✕ 402 · upgrade required
  • Starter✕ 402 · upgrade required
  • Trial (14-day)✓ Full access (evaluate it)
  • Growth✓ Full access
  • Scale✓ Full access

A key minted on a paid plan that later downgrades stops working (returns 402), by design — the key isn't deleted, the plan just no longer permits it.

Endpoints

Five read-only GETs

All endpoints return JSON. ?domain= accepts a bare hostname — schemes, www., and paths are normalized off.

GET/api/v1public

Discovery index

A self-describing catalog of every endpoint plus the MCP pointer. No key required — the quickest “is this live?” check.

Response
{
  "object": "api_index",
  "version": "1",
  "endpoints": [
    { "path": "/api/v1/citations", "method": "GET" },
    { "path": "/api/v1/share-of-voice", "method": "GET" },
    { "path": "/api/v1/dimensions", "method": "GET" },
    { "path": "/api/v1/events", "method": "GET" }
  ],
  "agents": { "mcp": "/api/mcp" }
}
GET/api/v1/citations key required

Citations

Latest citation status per query × engine, with the URLs each engine cited and a rolled-up citation rate.

domain
required — a domain you track
Response
{
  "object": "citations",
  "domain": "example.com",
  "generatedAt": "2026-07-07T12:00:00.000Z",
  "summary": {
    "queriesTotal": 20,
    "queriesCited": 8,
    "citationRate": 40
  },
  "surfaces": [
    { "surface": "perplexity", "label": "Perplexity",
      "cited": 5, "probed": 12, "rate": 42 }
  ],
  "queries": [
    {
      "query": "best crm for startups",
      "cited": true,
      "position": 2,
      "surfaces": [
        { "surface": "perplexity", "status": "cited",
          "citedUrls": ["https://example.com/crm-guide"] }
      ]
    }
  ]
}
GET/api/v1/share-of-voice key required

Share of Voice

The latest measured AI Share-of-Voice snapshot — you vs. competitors. Returns measured: false (with a note) until a snapshot exists.

domain
required — a domain you track
Response
{
  "object": "share_of_voice",
  "domain": "example.com",
  "measured": true,
  "shareOfVoice": 34,
  "leaderboard": [
    { "domain": "example.com", "isOwn": true,
      "citations": 12, "mentions": 5 },
    { "domain": "competitor.com", "isOwn": false,
      "citations": 20, "mentions": 8 }
  ]
}
GET/api/v1/dimensions key required

Dimensions

Latest per-dimension AI-visibility scores with confidence bands and the top recommendations behind each.

domain
required — a domain you track
Response
{
  "object": "dimensions",
  "domain": "example.com",
  "dimensions": [
    {
      "dimension": "crawler_access",
      "label": "Crawler access",
      "score": 90,
      "confidence": "high",
      "recommendations": ["Allow GPTBot in robots.txt"]
    }
  ]
}
GET/api/v1/events key required

Visibility events

Workspace events, newest first: citations won/lost, fixes proposed, goals reached. Poll with ?since set to the newest createdAt you've seen.

since
optional — ISO-8601 lower bound
limit
optional — default 50, max 100
Response
{
  "object": "events",
  "count": 2,
  "events": [
    {
      "type": "citation_won",
      "domain": "example.com",
      "createdAt": "2026-07-06T00:00:00.000Z",
      "payload": {
        "queryText": "best crm for startups",
        "surface": "perplexity"
      }
    }
  ]
}
Errors

One envelope, documented statuses

{
  "error": {
    "code": "invalid_key",
    "message": "That API key is invalid or has been revoked."
  }
}
  • 401missing_keyNo Authorization: Bearer header
  • 401invalid_keyUnknown, malformed, or revoked key
  • 402upgrade_requiredValid key, but the workspace plan isn't API-tier
  • 404domain_not_found?domain= isn't a domain this workspace tracks
  • 400missing_domainA domain-scoped endpoint called without ?domain=
  • 429rate_limitedPer-key rate limit tripped — back off and retry

Rate limiting

Best-effort per key: roughly 120 requests/minute sustained with a burst allowance. It's a courtesy limiter, not a hard SLA — don't design around exact numbers, and back off on 429.

Scoping & privacy

A key reads only its own workspace — domain resolution never falls through to another tenant. Responses go through explicit serializers that whitelist every field; internal ids and raw payloads are never echoed.

Building for an AI agent?

Don't script this REST API — connect the MCP endpoint at /api/mcp directly to an MCP-capable model. MCP is the agent-ready surface (tool discovery, structured tool calls); this REST API is for dashboards, BI, and glue scripts.

Open the MCP endpoint

Ready to pull your data?

Create a key in seconds. The API is available on the Growth plan and above — trials included, so you can evaluate it end-to-end.

Get your API key