RankZero

The RankZero REST API (/api/v1) — pull per-brand visibility, GSC, and GA4 KPIs server-to-server.

The RankZero REST API exposes the same data as our MCP server over plain HTTP+JSON, so automations and integrations can pull per-brand KPIs server-to-server without speaking MCP.

Authentication

Every request must send a bearer key:

Authorization: Bearer <YOUR_API_KEY>

Keys are issued on request. A key is scoped to one account — it can only read that account's brands (brands the account owns or shares via its organization). There is no all-brands access.

Missing or invalid key → 401.

curl https://www.rankzero.io/api/v1/brands \
  -H "Authorization: Bearer $RANKZERO_API_KEY"

Addressing a brand

The canonical identifier is the brand's id (a stable UUID). Discover your brands and their ids with GET /brands. As a convenience you may also pass a brand's domain or name:

Matches exactly one brand → resolves.
Matches more than one (e.g. two brands on the same domain) → 409 {"error":"ambiguous brand, use id"}.
Matches none (or a brand outside your scope) → 404 {"error":"unknown brand"}.

Reporting period

KPI endpoints accept ?period=, one of 24h, 7d, 30d, 90d. Default 7d.

Endpoints

`GET /brands`

Lists the brands your key can access.

curl https://www.rankzero.io/api/v1/brands \
  -H "Authorization: Bearer $RANKZERO_API_KEY"

[
  { "id": "3f8a1c2e-9b4d-4e7a-bc1f-2d6e5a0b9c11", "name": "Tesla", "domain": "tesla.com" }
]

`GET /brands/{brand}/kpis`

Headline snapshot: visibility, Google Search Console totals, and GA4 sessions by source.

curl "https://www.rankzero.io/api/v1/brands/tesla.com/kpis?period=7d" \
  -H "Authorization: Bearer $RANKZERO_API_KEY"

{
  "brand": "Tesla",
  "period": "7d",
  "asOf": "2026-06-08T12:00:00.000Z",
  "visibility": { "percent": 11.4, "rank": 8 },
  "gsc": { "clicks": 31, "impressions": 1606, "avgPosition": 12.4, "ctr": 0.019 },
  "ga4": {
    "sessionsBySource": [ { "source": "chatgpt.com", "sessions": 3 } ],
    "totalSessions": 42
  }
}

gsc / ga4 are null when that integration isn't connected for the brand (visibility is still returned).
ga4.sessionsBySource is unfiltered — every traffic source is returned so you can apply your own AI-referrer allowlist.

`GET /brands/{brand}/overview`

Own-brand visibility plus the full industry ranking (competitors).

{
  "brand": "Tesla",
  "period": "7d",
  "asOf": "2026-06-08T12:00:00.000Z",
  "visibility": { "percent": 11.4, "rank": 8 },
  "ranking": [
    { "name": "Tesla", "url": "tesla.com", "isOwnBrand": true, "rank": 8, "visibilityPercent": 11.4, "sentiment": 62 }
  ]
}

`GET /brands/{brand}/gsc`

Google Search Console totals for the period.

{
  "brand": "Tesla",
  "period": "7d",
  "asOf": "2026-06-08T12:00:00.000Z",
  "gsc": { "clicks": 31, "impressions": 1606, "avgPosition": 12.4, "ctr": 0.019 }
}

Breakdown by dimension. Add ?dimensions= (comma-separated; one or more of query, page, date, country, device, searchAppearance) to get per-row performance instead of totals — the raw material for opportunity scans (near-miss queries at position 11–20, high-impression/low-CTR pages). Optional ?limit (default 1000). Each row carries the requested dimension(s) plus clicks, impressions, ctr, position. rows is null if GSC isn't connected.

curl "https://www.rankzero.io/api/v1/brands/tesla.com/gsc?dimensions=query&period=30d&limit=1000" \
  -H "Authorization: Bearer $RANKZERO_API_KEY"

{
  "brand": "Tesla",
  "period": "30d",
  "asOf": "2026-06-08T12:00:00.000Z",
  "dimensions": ["query"],
  "rows": [
    { "query": "electric suv range", "clicks": 12, "impressions": 480, "ctr": 0.025, "position": 13.4 }
  ]
}

`GET /brands/{brand}/ga4`

GA4 sessions broken down by source (unfiltered).

{
  "brand": "Tesla",
  "period": "7d",
  "asOf": "2026-06-08T12:00:00.000Z",
  "ga4": {
    "sessionsBySource": [ { "source": "chatgpt.com", "sessions": 3 } ],
    "totalSessions": 42
  }
}

`GET /brands/{brand}/competitors`

The brand's tracked competitors.

{
  "brand": "Tesla",
  "asOf": "2026-06-08T12:00:00.000Z",
  "competitors": [
    { "id": "…", "name": "Rivian", "url": "https://rivian.com", "isOwnBrand": false }
  ]
}

`GET /brands/{brand}/citations`

Sources cited in AI answers, with content-type categorization. Accepts ?period, ?limit (default 50), ?country, ?provider (chatgpt|gemini|perplexity|anthropic|google_ai_overview).

{
  "brand": "Tesla",
  "period": "30d",
  "asOf": "2026-06-08T12:00:00.000Z",
  "sources": [
    {
      "source_url": "https://www.youtube.com/watch",
      "page_title": "…",
      "domain": "youtube.com",
      "usage_pct": 22.22,
      "avg_citations": 1,
      "prompt_texts": ["best electric SUV"],
      "content_type": "video"
    }
  ]
}

`GET /brands/{brand}/mentions`

Recent prompt runs that mention the brand / its competitors. Accepts ?period, ?limit (default 50).

{
  "brand": "Tesla",
  "period": "7d",
  "asOf": "2026-06-08T12:00:00.000Z",
  "mentions": [
    {
      "run_id": "…",
      "prompt_text": "best electric SUV",
      "model": "chatgpt",
      "output_preview": "…",
      "brands_mentioned_name": ["Tesla", "Rivian"]
    }
  ]
}

`GET /brands/{brand}/prompts`

The brand's active tracked prompts — the ones being monitored (paginated, 50/page). Accepts ?page, ?search. Distinct from the suggestion queue below.

{
  "brand": "Tesla",
  "asOf": "2026-06-08T12:00:00.000Z",
  "page": 1,
  "pageSize": 50,
  "count": 15,
  "prompts": [
    { "id": "…", "text": "best electric SUV", "country": "United States", "isActive": true, "createdAt": "…" }
  ]
}

`GET /brands/{brand}/prompt-suggestions`

The suggestion queue — questions you could add to tracking (largely GSC-derived), distinct from the tracked prompts above. Accepts ?type, ?status (single value or comma-separated).

{
  "brand": "Tesla",
  "asOf": "2026-06-08T12:00:00.000Z",
  "count": 12,
  "suggestions": [
    {
      "id": "…",
      "promptText": "which electric SUV has the longest range",
      "suggestionType": "gsc",
      "status": "pending",
      "anchorQuery": "electric SUV range",
      "confidenceScore": 0.82,
      "sourceQuery": "longest range electric suv",
      "country": "United States",
      "source": { "clicks": 12, "impressions": 480, "ctr": 0.025, "position": 8.3 },
      "createdAt": "…"
    }
  ]
}

`GET /search`

Searches the RankZero knowledge base (docs, glossary, blog). Not brand-scoped. Requires ?query (?q also accepted); optional ?locale.

{
  "query": "visibility",
  "results": [
    { "id": "/docs/metrics/visibility", "type": "page", "url": "/docs/metrics/visibility", "content": "…" }
  ]
}

Errors

Errors are flat JSON: { "error": "<message>" }.

Status	Meaning
`401`	Missing/invalid API key (or API not configured).
`404`	`unknown brand` — not found, or outside your key's scope.
`409`	`ambiguous brand, use id` — a domain/name matched more than one brand.
`500`	`internal error`.

REST API Reference

Base URL