Rankwise

npx add-mcp 'https://tryrankwise.com/api/mcp'

Pull your AI-visibility data into your own stack

A REST API over the data Rankwise already computes: citations, Share of Voice, planner keywords, articles and Search Console numbers. Wire it into Looker Studio, your BI, or agency reporting. A key you create with changes allowed can also pause automatic articles, add keywords, move planner cards and replace article text, all free. A key with fresh audits allowed can re-audit a domain within a daily cap you set.

Base path

/api/v1

Auth

Bearer rw_live_…

Plan

Growth and above

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, so 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.

   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).

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
• Free trial (3-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.

Read everything, change what you allow

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

GET /api/v1 public

Discovery index

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

{
  "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" },
    { "path": "/api/v1/key", "method": "GET" },
    { "path": "/api/v1/audits", "method": "POST" }
  ],
  "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)

{
  "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"] }
      ]
    }
  ]
}

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)

{
  "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)

{
  "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)

{
  "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"
      }
    }
  ]
}

GET /api/v1/key key required

Your key

Which scopes the key carries. For a key with fresh audits allowed, also the credit cost per audit, the daily cap and how much of it is left today.

{
  "object": "api_key",
  "scopes": ["read", "audit:run"],
  "audits": {
    "enabled": true,
    "credits_per_audit": 1,
    "daily_cap": 50,
    "remaining_today": 47,
    "credits_remaining": 212
  }
}

POST /api/v1/audits key required

Start a fresh audit (opt-in, spends credits)

Re-crawls and re-scores one domain you track, for 1 plan credit. Only a key created with "Allow fresh audits" ticked (scope audit:run) can call it; every other key gets 403. Send a unique Idempotency-Key header and reuse it on a retry, so a retry never charges twice. Each key has a daily cap you set when you create it.

domain

required, in the JSON body

{
  "object": "audit",
  "domain": "example.com",
  "status": "queued",
  "credits_charged": 1,
  "credits_remaining": 211,
  "audits_today": 4,
  "daily_cap": 50,
  "replayed": false
}

GET /api/v1/sites key required

Your site

The site the key reaches: its id, tracked domains, and whether automatic articles are on and paused. Pause or resume with POST /api/v1/sites/{site_id}/pause and /resume (a key with changes allowed).

{
  "sites": [
    {
      "id": "8f1c…",
      "name": "Acme",
      "domains": [{ "id": "d41a…", "domain": "acme.com" }],
      "automatic_articles": {
        "mode": "full_auto",
        "articles_per_week": 7,
        "paused": false
      }
    }
  ]
}

GET /api/v1/keywords key required

Keywords

The keywords in your Content Planner, one per card, with day, state, volume and difficulty. Add?format=csv for a CSV file. POST up to 50 keywords to add them as cards (free; keywords already planned are skipped).

state

optional (planned, writing, review, published, failed)

format

optional (csv)

{
  "keywords": [
    {
      "id": "c2d9…",
      "day": "2026-11-02",
      "title": "SEO Content Audit",
      "keyword": "seo content audit",
      "state": "planned",
      "volume": 170,
      "difficulty": 35
    }
  ],
  "total": 1
}

GET /api/v1/articles key required

Articles

Your articles, newest first. GET /api/v1/articles/{article_id} reads one (add?include_html=true for the full body). PUT /api/v1/articles/{article_id} replaces the title, meta description, slug or body, and POST /api/v1/articles/bulk-replace does up to 50 at once (a key with changes allowed).

status

optional (ready, generating, published, failed)

page, page_size

optional (page size up to 50)

{
  "articles": [
    {
      "id": "a7e2…",
      "title": "SEO Content Audit: A Step by Step Guide",
      "status": "published",
      "published_url": "https://acme.com/blog/seo-content-audit"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20
}

GET /api/v1/planner key required

Content Planner

Your planner cards by day. Pass from and to (YYYY-MM-DD, up to 120 days). PATCH /api/v1/planner/cards/{card_id} with a day moves a card that is not written yet (a key with changes allowed).

from, to

optional (YYYY-MM-DD)

{
  "from": "2026-10-01",
  "to": "2026-12-31",
  "cards": [
    { "id": "c2d9…", "day": "2026-11-02",
      "title": "SEO Content Audit", "state": "planned" }
  ],
  "unscheduled": []
}

GET /api/v1/gsc/summary key required

Search Console summary

Clicks, impressions and your best articles over the last 28 days, from your synced Search Console data.

{
  "connected": true,
  "days": 28,
  "clicks": 1240,
  "impressions": 48100,
  "best_articles": [
    { "title": "SEO Content Audit", "url": "https://acme.com/blog/seo-content-audit",
      "clicks": 310, "impressions": 9200 }
  ]
}

GET /api/v1/usage key required

Usage

Your plan, credits and limits, plus this key's scopes, its rate-limit windows and which tool groups it may use.

{
  "plan": "growth",
  "credits": 212,
  "api": {
    "scopes": ["read"],
    "rate_limits": {
      "minute": { "limit": 120, "remaining": 119 },
      "day": { "limit": 10000, "remaining": 9870 }
    }
  }
}

One envelope, documented statuses

{
  "error": {
    "code": "invalid_key",
    "message": "That API key is invalid or has been revoked."
  }
}

• 401 missing_key No Authorization: Bearer header
• 401 invalid_key Unknown, malformed, or revoked key
• 402 upgrade_required Valid key, but the workspace plan isn't API-tier
• 404 domain_not_found?domain= isn't a domain this workspace tracks
• 400 missing_domain A domain-scoped endpoint called without?domain=
• 429 rate_limited Per-key rate limit tripped, back off and retry
• 403 insufficient_scope POST /audits with a key created without fresh audits
• 402 out_of_credits POST /audits with no plan credits left; carries upgrade_url
• 429 daily_cap_reached The key's daily audit cap is used up; resets at 00:00 UTC

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.

Without sign-in, the public tools check a site's AI crawler access and readiness and search our guides. Sign in with OAuth (Claude and ChatGPT do this for you) and the agent works in one workspace you pick on the consent screen, with your role in it. You grant up to three scopes: read (domains, scores, citations, briefs, articles), write (free changes, and publishing an article you name) and spend (anything that uses credits or the monthly AI check allowance). Spend and publish tools take an idempotency_key, so a retry never charges twice. A read-only rw_live_ key works too. Billing, API keys, members and CMS connections stay in the app. Disconnect an app any time in workspace settings.

Example prompts

• “Can AI crawlers like GPTBot read example.com?”
• “Score example.com for AI search readiness.”
• “Is this page easy for AI to cite: https://example.com/blog/post”
• “Which of my tracked questions do AI engines cite us for?”
• “Add 'best crm for startups' as a tracked question.”
• “Draft a brief for my biggest citation gap, but ask before approving it.” Open the MCP endpoint

Ready to pull your data?

Create a key in seconds. The API is available on the Growth plan and above, and in the 3-day free trial, so you can evaluate it end to end.

Get your API key