Overview & Auth

What this API is (and isn't) today

• Read-only. You can read brands, categories and their prompts, monitoring runs and individual responses, prompt change feeds, date-range analytics, score history, and reports. There is no write/trigger access via API keys yet (creating brands, starting scans, and generating reports are dashboard-only for now).
• Scoped. A key carries some subset of three scopes: brands:read, runs:read, reports:read. A request to an endpoint you don't have the scope for returns 403.
• Org-pinned. A key only ever sees the brands belonging to the organization that created it.
• Add-on gated. The org needs the API access add-on active. Without it, every request returns 403 ("API access is a paid add-on").
• Rate limited. 60 requests per minute, per key. Over that returns 429; retry after a short pause. Walking paginated endpoints sits well under this — a tight retry loop does not.
• Query time capped. A single request's database work is capped at 15 seconds. A request that exceeds it fails rather than running on. If you hit this on a query you believe is reasonable, tell us — the cap is tunable and we would rather raise it than have you work around it.

Base URL

The API base URL is https://api.georeputation.com. All paths below are relative to it.

Authentication

Create a key in the dashboard (Settings → API Keys). The full key is shown once at creation, so copy it then. Only a hash is stored, so it can't be retrieved later. Keys look like:

gr_live_a1b2c3_x7y8z9...................

Send it on every request, either header works:

# Preferred
curl https://api.georeputation.com/api/brands/ \
  -H "Authorization: Bearer gr_live_a1b2c3_x7y8z9..."

# Alternative
curl https://api.georeputation.com/api/brands/ \
  -H "X-API-Key: gr_live_a1b2c3_x7y8z9..."

A missing scope, revoked/expired key, or missing add-on returns 401 or 403 with a JSON detail message.

Conventions

• All response fields are camelCase.
• IDs are returned as strings in response bodies. In path parameters they are typed as integers (e.g. /api/brands/{brandId}/) — pass the numeric id; the same id comes back as a string in the body.
• Timestamps are ISO 8601 (or null).
• List endpoints use page-number pagination: { count, next, previous, results: [...] }, 25 per page. Control with ?page= and ?page_size=.

Reference

Every endpoint, request parameter, and response field is documented in the API Reference, generated directly from the OpenAPI spec that backs the API. It is the source of truth for shapes, so it cannot drift from what the code actually returns.

See Concepts for the cross-cutting behavior that spans multiple endpoints (date-range windows, run/response drill-down, suppressed deltas) and Errors for the scope-to-endpoint map and status codes.