Pull your figures with the API

Base URL

All endpoints hang under one host. Responses are JSON.

https://api.geony.ai

Authentication

You create an API key in the organization settings in the app (only an organization admin can do that). You see the full key exactly once, so keep it safe; if you lose it, you create a new one. Keys begin with geony_ so a leaked key is recognizable to secret scanners.

Send the key as a Bearer token in the Authorization header:

Authorization: Bearer geony_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The key is strictly read-only: any method other than GET returns a 403. The data is limited to the organization of the key; a workspace-limited key sees only its own workspaces.

A first request

Start with your workspaces; from there you get the ids that the other endpoints need.

curl https://api.geony.ai/v1/workspaces \
  -H "Authorization: Bearer $GEONY_API_KEY"

Example response:

[
  {
    "id": "ws_3f2a…",
    "name": "Acme Nederland",
    "slug": "acme-nederland"
  }
]

Core endpoints

Example: projects in a workspace

curl https://api.geony.ai/v1/workspaces/ws_3f2a.../projects \
  -H "Authorization: Bearer $GEONY_API_KEY"

Example response:

[
  {
    "id": "prj_9b1c…",
    "name": "Acme.nl",
    "domain": "acme.nl",
    "archivedAt": null,
    "visibilityScoreBp": 3600,
    "lastRunAt": "2026-08-01T06:00:00.000Z"
  }
]

Fields ending in Bp are basis points: 3600 means 36%. This keeps percentages whole numbers, without rounding errors.

Example: the visibility overview

With the optional parameter period (day, week or month) you choose the aggregation.

curl "https://api.geony.ai/v1/projects/prj_9b1c.../overview?period=week" \
  -H "Authorization: Bearer $GEONY_API_KEY"

Example response:

{
  "periodStart": "2026-07-27T00:00:00.000Z",
  "entities": [
    {
      "entityId": "ent_1a2b…",
      "entityName": "Acme",
      "entityType": "brand",
      "isPrimary": true,
      "observationsN": 180,
      "presentN": 65,
      "presenceRateBp": 3600,
      "presenceCiLowBp": 2600,
      "presenceCiHighBp": 4700,
      "visibilityScoreBp": 3400,
      "sovBp": 2800,
      "citationShareBp": 1500
    }
  ]
}

The fields presenceCiLowBp and presenceCiHighBp are the lower and upper bound of the 95% confidence interval, also in basis points. From the example: 36% visible, interval 26 to 47%.

More read-only endpoints

Under the same authentication and tenant model, these GETs are available too. They work on the same projects:

MCP server for AI assistants

The same read-only data is also available as an MCP server (Model Context Protocol), so an AI assistant like Claude, Cursor or ChatGPT can query your measurement data directly without you writing scripts yourself. The server is a thin, read-only layer over this API and uses the same geony_ key.

It offers tools for your workspaces and projects, and per project for the visibility overview, the questions, the sources, the cited pages, sentiment, the work list, notifications, the trend and the AI Readiness. Connecting is done via two environment variables:

{
  "mcpServers": {
    "geony": {
      "command": "geony-mcp",
      "env": {
        "GEONY_API_BASE": "https://api.geony.ai",
        "GEONY_API_KEY": "geony_..."
      }
    }
  }
}

Because the key is read-only, the assistant cannot change anything: it queries the data and reasons about it. Beta on the Bureau and Enterprise plan, just like the API.

Errors

The API uses ordinary HTTP status codes and a compact error shape.

{ "error": "forbidden" }