The Bold GEO REST API.

Getting started

The Bold GEO REST API is the same data your dashboard renders, available over HTTPS as JSON. Use it to embed your Visibility Score in your own marketing reports, sync mentions into your CRM, or build a custom Slack notifier.

Base URL - all endpoints are relative to:

https://api.boldgeo.co/v1

All responses are JSON. All write endpoints accept JSON request bodies. Date/time fields are ISO-8601 UTC.

Authentication

The API uses bearer-token authentication. Every request must include an Authorization header with your secret key.

Generating an API key

Open your dashboard → Settings → API keys → Create new key. Name it (e.g. production, looker-pipeline), choose a scope (read or read+write), and copy the key. The key is shown once - store it in your secret manager immediately.

Using the API key

Include the key in every request:

Authorization: Bearer bg_live_4d51c87220eb47fa60bbd04c0ff0c5d9

Example cURL request

curl https://api.boldgeo.co/v1/visibility \
  -H "Authorization: Bearer $BOLDGEO_API_KEY" \
  -H "Accept: application/json"

Endpoints

Four resources. Same envelope on every response: { data, meta }. meta always includes request_id, ratelimit_remaining, and generated_at.

Visibility Score

Returns the current daily 0–100 Visibility Score for your tracked domain, plus the 30-day trend.

Query parameters

Example response

{
  "data": {
    "domain": "yourbrand.com",
    "score": 67,
    "score_delta_30d": 11.4,
    "trend": [
      { "date": "2026-04-14", "score": 55.6 },
      { "date": "2026-04-15", "score": 56.2 },
      { "date": "2026-05-14", "score": 67.0 }
    ]
  },
  "meta": {
    "request_id": "req_8f2c1a",
    "ratelimit_remaining": 998,
    "generated_at": "2026-05-14T09:42:00Z"
  }
}

Mention stream

Every AI answer that named your brand. Paginated, filterable by engine and date.

Query parameters

Example response

{
  "data": [
    {
      "id": "men_2c8a1f4d",
      "engine": "chatgpt",
      "prompt": "best CRM for SaaS sales teams",
      "captured_at": "2026-05-14T09:38:00Z",
      "position": 1,
      "sentiment": "positive",
      "snippet": "...the most commonly recommended tool is <Your Brand>...",
      "citation_url": "https://yourbrand.com/sales"
    }
  ],
  "meta": {
    "request_id": "req_b09e7c",
    "next_cursor": "men_2c8a1f4c",
    "ratelimit_remaining": 997
  }
}

Benchmarks

Your share of voice vs. the competitive set, by engine and by week.

Example response

{
  "data": {
    "category": "B2B SaaS CRM",
    "window": "30d",
    "competitors": [
      { "name": "Folk CRM", "share_pct": 28, "is_you": false },
      { "name": "Your brand", "share_pct": 22, "is_you": true },
      { "name": "HubSpot", "share_pct": 18, "is_you": false }
    ]
  }
}

Action Plan

The current week's five prescribed actions, ranked by expected Visibility Score lift.

Example response

{
  "data": {
    "week_of": "2026-05-12",
    "actions": [
      { "id": 1, "title": "Publish a comparison page vs. Folk CRM", "expected_lift_pts": 3.2, "category": "content" },
      { "id": 2, "title": "Add FAQ schema to /pricing", "expected_lift_pts": 1.8, "category": "technical" },
      { "id": 3, "title": "Get cited on g2.com category page", "expected_lift_pts": 2.4, "category": "authority" }
    ]
  }
}

Rate limits

All API keys are rate-limited per minute. Limits are enforced on a rolling window and surfaced in every response.

Every response includes:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1715679720

When you exceed the limit you'll get an HTTP 429 with a Retry-After header. Implement exponential backoff with jitter.

Error codes

Errors use standard HTTP status codes plus a structured JSON body.

Error response format

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is not valid or has been revoked.",
    "request_id": "req_8f2c1a"
  }
}

SDKs & libraries

Official SDKs are thin wrappers around the REST API. We publish two right now and accept community-maintained ports.

Python (requests)

import os, requests

API_KEY = os.environ["BOLDGEO_API_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
BASE = "https://api.boldgeo.co/v1"

r = requests.get(f"{BASE}/visibility", headers=HEADERS)
r.raise_for_status()
score = r.json()["data"]["score"]
print(f"Current Visibility Score: {score}")

JavaScript / Node (fetch)

const KEY = process.env.BOLDGEO_API_KEY;
const r = await fetch("https://api.boldgeo.co/v1/visibility", {
  headers: { Authorization: `Bearer ${KEY}` }
});
if (!r.ok) throw new Error(`HTTP ${r.status}`);
const { data } = await r.json();
console.log("Score:", data.score);

Other languages

Any language with an HTTP client works - the API has no quirks. Community-maintained clients we know of: Go, Ruby, PHP. Email support@boldgeo.co with a link if you maintain one and we'll list it here.

Changelog

Breaking changes get 90 days' notice via email and a banner on this page. Non-breaking additions (new fields, new endpoints) ship freely.

v1.3 - 14 May 2026

Added citation_url to /mentions responses. Non-breaking.

v1.2 - 28 Apr 2026

New endpoint /benchmarks. X-RateLimit-* headers added on every response.

v1.1 - 14 Mar 2026

Added /action-plan. Cursor pagination on /mentions.

v1.0 - 1 Mar 2026

Public release. /visibility and /mentions endpoints.