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.
In the dashboard, go to Settings → API and create a key. The secret is shown once, so store it in a secret manager.
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"Every endpoint returns application/json with an X-Rankwise-Version header. Responses are freshly workspace-scoped per request (no-store).
Every request except the discovery index sends a workspace API key as a bearer token.
Authorization: Bearer rw_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXA 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.
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.
All endpoints return JSON. ?domain= accepts a bare hostname; schemes, www., and paths are normalized off.
/api/v1publicA 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" }
}/api/v1/citations key requiredLatest citation status per query × engine, with the URLs each engine cited and a rolled-up citation rate.
{
"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"] }
]
}
]
}/api/v1/share-of-voice key requiredThe latest measured AI Share-of-Voice snapshot, you vs. competitors. Returns measured: false (with a note) until a snapshot exists.
{
"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 }
]
}/api/v1/dimensions key requiredLatest per-dimension AI-visibility scores with confidence bands and the top recommendations behind each.
{
"object": "dimensions",
"domain": "example.com",
"dimensions": [
{
"dimension": "crawler_access",
"label": "Crawler access",
"score": 90,
"confidence": "high",
"recommendations": ["Allow GPTBot in robots.txt"]
}
]
}/api/v1/events key requiredWorkspace events, newest first: citations won/lost, fixes proposed, goals reached. Poll with ?since set to the newest createdAt you've seen.
{
"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"
}
}
]
}/api/v1/key key requiredWhich 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
}
}/api/v1/audits key requiredRe-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.
{
"object": "audit",
"domain": "example.com",
"status": "queued",
"credits_charged": 1,
"credits_remaining": 211,
"audits_today": 4,
"daily_cap": 50,
"replayed": false
}/api/v1/sites key requiredThe 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
}
}
]
}/api/v1/keywords key requiredThe 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).
{
"keywords": [
{
"id": "c2d9…",
"day": "2026-11-02",
"title": "SEO Content Audit",
"keyword": "seo content audit",
"state": "planned",
"volume": 170,
"difficulty": 35
}
],
"total": 1
}/api/v1/articles key requiredYour 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).
{
"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
}/api/v1/planner key requiredYour 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": "2026-10-01",
"to": "2026-12-31",
"cards": [
{ "id": "c2d9…", "day": "2026-11-02",
"title": "SEO Content Audit", "state": "planned" }
],
"unscheduled": []
}/api/v1/gsc/summary key requiredClicks, 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 }
]
}/api/v1/usage key requiredYour 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 }
}
}
}{
"error": {
"code": "invalid_key",
"message": "That API key is invalid or has been revoked."
}
}missing_keyNo Authorization: Bearer headerinvalid_keyUnknown, malformed, or revoked keyupgrade_requiredValid key, but the workspace plan isn't API-tierdomain_not_found?domain= isn't a domain this workspace tracksmissing_domainA domain-scoped endpoint called without ?domain=rate_limitedPer-key rate limit tripped, back off and retryinsufficient_scopePOST /audits with a key created without fresh auditsout_of_creditsPOST /audits with no plan credits left; carries upgrade_urldaily_cap_reachedThe key's daily audit cap is used up; resets at 00:00 UTCEach key may make 120 requests a minute and 10,000 a day (UTC). Every response carries RateLimit and RateLimit-Policy headers. A 429 adds Retry-After: wait that many seconds, then retry.
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.
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.
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