API docs

Website Rank API documentation

Build against Website Rank with token-authenticated intelligence refreshes, public read-only helper endpoints, consistent JSON responses, and a billing model that only spends credits when you ask for fresh data.

View pricing Open Billing

API status Enabled Requests can be served right now.

Live refresh cost 1 credit Only charged when a live refresh is actually queued.

Stored snapshot reads 0 credits Use cached intelligence without spending refresh balance.

Auth model Bearer token Generate a token in Billing after signup. No OAuth flow is exposed.

Full API reference

Use the tabs to jump between setup, the live intelligence endpoint, public helper endpoints, example code, and response/error details.

JSON responses Token auth Async refresh model

Quick start

Create an account and open Billing.
Generate an API token from the Billing page.
Call /api/v1/intelligence/{domain} with an Authorization: Bearer ... header.
Add ?refresh=1 only when you want a fresh background refresh instead of just reading the stored snapshot.
Poll again later without refresh=1 to read the updated snapshot after the worker finishes.

How credits work

Stored snapshot reads cost 0 credits.
A live refresh costs 1 credit.
Credits are only consumed when a live refresh is actually queued.
If you request a brand-new domain with no stored snapshot yet, the API can queue a refresh automatically and charge the live-refresh cost.
Included monthly API requests are added to your API credit balance every billing cycle and unused balance rolls over.

What the API is good for

Reading current Website Rank intelligence snapshots inside dashboards, apps, bots, or internal tools.
Triggering fresh intelligence collection only when you need it.
Searching the public domain index and category payloads for UI builders.
Comparing domains and reading public ranking data without building your own crawler stack.

Important behaviour

The intelligence endpoint is asynchronous. A refresh request queues background work and returns immediately.
Freshly queued domains can return snapshot: null until the worker finishes.
Public helper endpoints are currently read-only and do not require a token.
Token-bearing requests should be made server-side or from trusted environments only.

curl -H "Authorization: Bearer wr_live_your_token_here" \
  "https://website-rank.com/api/v1/intelligence/{domain}?refresh=1"

Authentication methods

The authenticated intelligence endpoint accepts either an Authorization: Bearer ... header or an api_key query/body parameter. Bearer headers are the recommended format.

Bearer header

Authorization: Bearer wr_live_your_token_here

Query parameter

https://website-rank.com/api/v1/intelligence/{domain}?api_key=wr_live_your_token_here

Token lifecycle

Sign in and go to Billing.
Generate a token from the billing/API section.
Store it securely like any other production secret.
Rotate or revoke it from Billing if it is exposed or no longer needed.

There is no public token-issuance API documented here. Token management currently happens through the Website Rank Billing UI.

Authentication notes

Topic	Details
`Authorization` header	Recommended for production apps, server-side code, and SDK wrappers.
`api_key` parameter	Supported for simple requests and quick testing, but avoid exposing it in browser URLs where possible.
Invalid or missing token	Returns `401` with `{"ok": false, "message": "Invalid API token."}`.
API globally disabled	Returns `503` even if the token itself is valid.
Public endpoints	Do not currently require a token, but that behaviour should be treated as public-read access rather than a promise of permanent openness.

GET /api/v1/intelligence/{domain}

Reads the stored intelligence snapshot for a public domain and optionally queues a fresh background refresh.

Auth required GET request 1 credit per live refresh

Endpoint
https://website-rank.com/api/v1/intelligence/{domain}

Purpose
Read a stored snapshot, optionally queue a fresh intelligence refresh.

Query parameters

Name	Type	Meaning
`refresh`	integer/bool-like	When present and not `0`, forces a live background refresh queue request.
`api_key`	string	Alternative to the bearer header for passing the API token.

Domain path parameter

Name	Type	Meaning
`domain`	string	A public domain such as `example.com`. The server normalizes it before lookup.

When credits are charged

You set ?refresh=1 and the server queues a fresh refresh.
There is no stored snapshot yet, so the request must queue one automatically.

When credits are not charged

You read an existing stored snapshot without forcing refresh.
You are only polling later to read completed data.

curl -H "Authorization: Bearer wr_live_your_token_here" \
  "https://website-rank.com/api/v1/intelligence/{domain}?refresh=1"

Example success response

{
  "ok": true,
  "domain": "example.com",
  "refresh_queued": true,
  "served_from_snapshot": false,
  "remaining_credits": 117,
  "credit_cost": 1,
  "configured_credit_cost": 1,
  "snapshot": {
    "domain": "example.com",
    "checked_at": "2026-03-21T07:00:00+00:00",
    "status": "fresh",
    "summary": "Stored intelligence summary text here.",
    "search_intelligence": {
      "queries": ["site:trustpilot.com \"example.com\""],
      "results": []
    }
  }
}

Response fields

Field	Type	Meaning
`ok`	boolean	True when the token was accepted and the request was processed.
`domain`	string	The normalized domain Website Rank actually used internally.
`refresh_queued`	boolean	True when a live refresh job was queued.
`served_from_snapshot`	boolean	True when the current response came from existing stored intelligence data.
`remaining_credits`	integer	Your remaining API credit balance after this request was processed.
`credit_cost`	integer	Credits charged by this specific request.
`configured_credit_cost`	integer	The current server-side live-refresh cost setting.
`snapshot`	object\|null	The stored intelligence snapshot, or `null` when nothing has been stored yet.

Public helper endpoints

These endpoints currently expose public Website Rank data without requiring a token. They are useful for read-only search, compare, category, and leaderboard interfaces.

GET /api/search

Public

Searches both the tracked-site index and the discovered-domain index.

Request
https://website-rank.com/api/search?q=example

Parameter	Type	Meaning
`q`	string	Search query text. Empty queries return empty arrays.

{
  "query": "example",
  "tracked": [],
  "discovered": []
}

GET /api/compare

Public

Compares multiple domains using the same row builder that powers the public Compare page.

Request
https://website-rank.com/api/compare?domains=example.com,competitor.com

Parameter	Type	Meaning
`domains`	string	Comma- or space-separated domain list.

{
  "data": []
}

GET /api/site/{domain}

Public

Returns the broader domain overview payload used for the public domain shell.

Request
https://website-rank.com/api/site/{domain}

Field	Meaning
`ready`	Whether the cached overview exists yet.
`site`, `metrics`, `rating`	Core overview blocks when available.
`live_state`, `refresh_state`	Current refresh and queue metadata.
`urlscan_report`	Stored URLScan block if present.

GET /api/urlscan/{domain}

Public

Returns the stored URLScan report block for a domain.

Request
https://website-rank.com/api/urlscan/{domain}

{
  "ok": true,
  "domain": "example.com",
  "urlscan_report": null
}

GET /api/leaderboard

Public

Returns the top public leaderboard rows.

Request
https://website-rank.com/api/leaderboard

{
  "data": []
}

GET /api/movers-pulse

Public

Returns live discovery and queue pulse data for the Discovery surface. Responses are marked no-store because the numbers are designed to stay live.

Request
https://website-rank.com/api/movers-pulse

GET /api/site-categories

Public

Returns the category picker payload used by Website Rank interfaces.

Request
https://website-rank.com/api/site-categories

{
  "ok": true,
  "payload": {}
}

cURL: read a stored snapshot

curl -H "Authorization: Bearer wr_live_your_token_here" \
  "https://website-rank.com/api/v1/intelligence/{domain}"

cURL: force a live refresh

curl -H "Authorization: Bearer wr_live_your_token_here" \
  "https://website-rank.com/api/v1/intelligence/{domain}?refresh=1"

JavaScript fetch

const response = await fetch('https://website-rank.com/api/v1/intelligence/{domain}?refresh=1', {
  headers: {
    Authorization: 'Bearer wr_live_your_token_here'
  }
});

const data = await response.json();
console.log(data.refresh_queued, data.snapshot);

PHP

$ch = curl_init('https://website-rank.com/api/v1/intelligence/{domain}?refresh=1');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer wr_live_your_token_here',
    ],
]);

$raw = curl_exec($ch);
$data = json_decode($raw, true);
curl_close($ch);

Python

import requests

response = requests.get(
    'https://website-rank.com/api/v1/intelligence/{domain}?refresh=1',
    headers={'Authorization': 'Bearer wr_live_your_token_here'},
    timeout=30,
)
response.raise_for_status()
payload = response.json()
print(payload['remaining_credits'])

Polling pattern

1. Request /api/v1/intelligence/{domain}?refresh=1
2. Read the immediate response
3. If snapshot is null or stale, wait briefly
4. Request /api/v1/intelligence/{domain} again without refresh=1
5. Repeat until the stored snapshot you need is available

Status codes

Code	When it happens
`200`	Request succeeded and a response payload was returned.
`401`	Missing, invalid, or unauthorised API token.
`402`	Not enough API credits to queue a live refresh.
`422`	The supplied domain was invalid after normalization.
`503`	API access is globally disabled or, for some public endpoints, the installer is not complete.

Error examples

{
  "ok": false,
  "message": "Invalid API token."
}

{
  "ok": false,
  "message": "Not enough API credits remaining for a live intelligence refresh.",
  "remaining_credits": 0,
  "configured_credit_cost": 1}

{
  "ok": false,
  "message": "Enter a valid public domain."
}

Integration notes

Refreshes are queue-based, so do not assume a forced refresh returns fresh crawl output in the same response.
The public site overview and helper endpoints can return partial data when a domain is still being processed.
Use stored snapshots for read-heavy apps and reserve forced refreshes for user-triggered events, scheduled sync points, or explicit “refresh now” actions.
Because token auth is simple bearer-token auth, protect tokens as secrets and do not hardcode them into public client bundles.