Ping endpoint

GET /ping is the lightest call in the Rankbox API. It confirms that a key works and tells you which site the key belongs to, so your integration can show the person "Connected to Example Co" before it syncs anything.

When to call ping

Call GET /ping at these moments:

• When someone pastes a key into your integration. A 200 proves the key is valid and its site is active. Show the returned brand_name so the person can confirm it's the right site: a key belongs to one site, and an account with several sites has one key per site.
• When your integration starts up with a saved key, to confirm it still works before you show a "connected" state.
• Before reporting live URLs, to read the site's website_url and catch a domain mismatch before PATCH /articles/{id} rejects it.

You don't need to ping before every sync. GET /articles authenticates the same way and returns the same 401 or 402 if the key stops working, so a scheduled job can go straight to the articles call.

Request

GET https://rankbox.xyz/api/public/v1/ping

The endpoint takes no parameters and no body. Send the key in the Authorization header.

curl https://rankbox.xyz/api/public/v1/ping \
  -H "Authorization: Bearer $RANKBOX_API_KEY"

const res = await fetch("https://rankbox.xyz/api/public/v1/ping", {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();

if (res.status === 401) showError("That key isn't valid. Create a new one in Rankbox → Integrations.");
else if (res.status === 402) showError(body.error); // the site isn't active on a plan
else if (res.ok) showConnected(body.brand_name ?? "your Rankbox site");

import os
import requests

res = requests.get(
    "https://rankbox.xyz/api/public/v1/ping",
    headers={"Authorization": f"Bearer {os.environ['RANKBOX_API_KEY']}"},
    timeout=20,
)
if res.status_code == 200:
    site = res.json()
    print("Connected to", site["brand_name"] or "your Rankbox site")
else:
    print(res.status_code, res.json().get("error"))

Response

A working key returns 200 with this object:

{
  "ok": true,
  "service": "Rankbox",
  "brand_name": "Example Co",
  "website_url": "https://www.example.com",
  "logo_url": "https://www.example.com/logo.png"
}

All five fields are always present. website_url and logo_url were added in September 2026; a client written before then can ignore them.

The response contains no site id and nothing about the account, plan or other sites. A key reveals only its own site.

What the dashboard shows after the first request

Every request that Rankbox accepts with a key, ping included, records the time as that key's last use. The Integrations page reads it:

• In the setup steps, step 4, See it connect, shows "Listening for your site's first request…" while the key waits, then "Connected — your site called in just now." The page checks every 5 seconds until the first request lands.
• At the top of the page, the status moves from "Waiting for your site's first sync" to "Your site is connected", with Last sync, Delivered and On the way figures beneath it.
• In Your connections, the key's status changes from Waiting to Live, and its row shows "Synced just now".

A request rejected with 401 or 402 doesn't count, so none of these change for a key that doesn't work.

Check the site before you sync

The ping response gives you two checks worth running when someone connects:

Is this the site you expect? If your integration stores articles in one place per site, such as a CMS collection, remember which site it was set up with, and check again when someone pastes a different key. A key for another site would otherwise mix two sites' articles into one collection. The ping response has no site id, so compare website_url and brand_name, and ask the person to confirm when they differ. Don't compare key prefixes: replacing a key gives the same site a new prefix.

Will live URL reports be accepted? PATCH /articles/{id} only accepts URLs on the site's own domain. Compare the host your site publishes on with the host of website_url, ignoring a leading www. and allowing subdomains. A mismatch, such as a site still on a platform's staging address, means every report will fail with 400. Tell the person to publish on their own domain, or to update Website in Dashboard → Settings → Your brand.

function sameSite(a: string, b: string): boolean {
  const host = (value: string) => {
    try {
      const url = new URL(/^https?:\/\//i.test(value) ? value : `https://${value}`);
      return url.hostname.replace(/^www\./i, "").toLowerCase();
    } catch {
      return "";
    }
  };
  const left = host(a);
  const right = host(b);
  if (!left || !right) return false;
  return left === right || left.endsWith(`.${right}`) || right.endsWith(`.${left}`);
}

// sameSite("https://blog.example.com", "https://www.example.com") === true

This check is a convenience. Rankbox also accepts URLs on the domain the site verified in the backlink exchange, which ping doesn't return, so treat a mismatch as a warning and let the PATCH response decide.

Errors

GET /ping returns the same authentication and rate-limit errors as every endpoint. It never returns 400 or 404.

The full 402 message and handling advice are in Errors.

Related

• Authentication and API keys: key format, rotation and storage.
• Articles endpoints: what to call once the key checks out.
• Build a CMS integration: where ping fits in a connect flow.
• Live URLs and verification: why the domain check matters.
• Account and site settings: where the brand name and website are set.