API — overview

GEO Platform exposes a public REST API under /v1/. Principle: anything the dashboard shows can be pulled as data. The API is for real-time access powering dashboards and automations; for bulk dumps use Export (CSV / JSONL) and BigQuery Sync.

• Base URL: https://geoplatform.pl/v1/
• Version: v1
• Format: JSON
• Authentication: X-API-Key header

Full reference (auto from OpenAPI)

An interactive reference of all endpoints is coming in the next phase — it will be rendered automatically from OpenAPI (/api/openapi.json). Below is the foundation you need to start.

Authentication

You create API keys in the app (the API Keys section). Every request sends the key in a header:

curl -H "X-API-Key: geo_your_key" \
  https://geoplatform.pl/v1/visibility/summary

• A key is workspace-scoped and has assigned scopes, e.g. visibility:read, products:read, attribution:read, brand-safety:read, orders:read, orders:write.
• Package gating is above the scope — product / attribution / brand-safety endpoints require the package to include the given feature (otherwise 403), regardless of the key's scope.

Response format

Newer endpoints return a consistent envelope { data, meta }:

{
  "data": [ /* records or object */ ],
  "meta": {
    "generated_at": "2026-07-19T10:30:00Z",
    "total": 42,
    "period_days": 30,
    "next_cursor": null
  }
}

First-generation endpoints keep their original flat shape (for backward compatibility).

Cursor pagination

Lists that can grow use cursor pagination:

curl -H "X-API-Key: geo_your_key" \
  "https://geoplatform.pl/v1/products?limit=50"
# in the response: meta.next_cursor -> pass it as ?cursor=... for the next page

The cursor is opaque — pass it back unchanged.

Rate limits

Every key has a per-minute limit. We return headers on every response so you can self-throttle:

• X-RateLimit-Limit — per-minute limit,
• X-RateLimit-Remaining — remaining requests in the current window,
• X-RateLimit-Reset — seconds until the window resets.

When the limit is exceeded the API returns 429 Too Many Requests.

Errors

Errors use standard HTTP codes:

Code	Meaning
401	missing / invalid API key
403	missing scope or feature not in package
404	resource not found
429	rate limit exceeded
400	invalid parameters (e.g. a bad cursor)

Example data areas

• Visibility: GET /v1/visibility/summary, /visibility/timeseries, /visibility/questions
• Products: GET /v1/products, /products/visibility/summary, /products/share-of-shelf
• Attribution: GET /v1/attribution/revenue, /attribution/roi, /attribution/timeseries
• Brand Safety: GET /v1/brand-safety/hallucinations, /brand-safety/summary
• Orders: POST /v1/orders, POST /v1/orders/batch, GET /v1/orders