REST APIv1Beta
Geolix API
Everything the dashboard shows, available as JSON over HTTPS with a single API key.
curl https://api.geolix.ai/api/v1/projects \
-H "x-api-key: glx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"- base url
- https://api.geolix.ai/api/v1
- auth
- x-api-key header; keys are created in app.geolix.ai settings
- format
- JSON request and response, UTF-8
- rate limit
- Throttled requests get a 429 with a Retry-After, see rate limits
- status
- BetaPaths and payloads may still change; breaking changes are announced on this page first.
Overview
Geolix continuously checks how visible a brand is in AI search platforms such as ChatGPT, Perplexity and Gemini. The API exposes the same data as the dashboard: brands, projects, monitored intents, detection runs and the aggregated board metrics.
Resources are organised the REST way: GET reads, POST creates or triggers, PATCH updates, DELETE archives or deactivates (nothing is hard-deleted).
Getting started
Create an API key
Sign in at app.geolix.ai, open Settings → API keys and choose Create key.
- Name — a label you will recognise later, such as
CI pipeline - Scope —
orgreaches every project in the organisation;projectis bound to one project - Copy it now — the full key is shown once; the server keeps only a hash
Make the first request
curl https://api.geolix.ai/api/v1/projects \
-H "x-api-key: glx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"The response lists the projects the key can see:
[{
"id": "prj_xxx",
"name": "My Brand",
"status": "active"
}]Read the board
With a project id, read its board metrics for the last 30 days:
curl "https://api.geolix.ai/api/v1/board?project_id=prj_xxx&days=30" \
-H "x-api-key: glx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Omit project_id to get the default (first active) project.
Authentication
Every request carries the key in the x-api-key header. Keys are not accepted as query parameters, which would end up in access logs.
curl https://api.geolix.ai/api/v1/projects \
-H "x-api-key: glx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Key format
glx_live_ prefix followed by 32 hex characters, 41 characters in total. The full key is shown once at creation; the server stores a SHA-256 hash and never the plaintext.
Key scopes
| Scope | Access | Typical use |
|---|---|---|
org | All projects in the organisation | Cross-project integrations, automated reporting |
project | The bound project only | Single-project CI/CD, keys handed to outside collaborators |
Permissions
A key inherits the role of the member who created it.
| Operation | Requires |
|---|---|
Read — GET | Any organisation member |
Write — POST PATCH DELETE | Organisation owner or admin |
Brands
A brand is the thing being monitored; competitors are brands too.
| Method | Path | Description |
|---|---|---|
| GET | /brands | List brands |
| POST | /brands | Create a brand |
| GET | /brands/{id} | Brand details |
| PATCH | /brands/{id} | Update a brand |
Projects
A project ties one brand to its competitors, the intents to monitor and the platform scope; detection is scheduled per project.
| Method | Path | Description |
|---|---|---|
| GET | /projects | List projects |
| POST | /projects | Create a project |
| GET | /projects/{id} | Project details |
| PATCH | /projects/{id} | Update a project |
| DELETE | /projects/{id} | Archive a project |
| GET | /projects/{id}/queries | List intents |
| POST | /projects/{id}/queries | Add intents |
| POST | /projects/{id}/runs | Trigger a detection run |
| GET | /projects/{id}/runs | List detection runs |
Board
Board endpoints return aggregated metrics. All of them accept project_id、days and platforms query parameters, defaulting to the default project, 30 days and every platform.
| Method | Path | Description |
|---|---|---|
| GET | /board | Overview: visibility, share of voice, sentiment, rank |
| GET | /board/sources | Sources: domains and URLs cited by AI answers |
| GET | /board/gap | Competitive gap |
| GET | /board/by-intent | Metrics broken down by intent |
| GET | /board/chats | Raw question-and-answer records |
Runs & queries
| Method | Path | Description |
|---|---|---|
| GET | /runs/{id} | Run details and progress |
| POST | /runs/{id}/cancel | Cancel a running detection |
| PATCH | /queries/{id} | Update an intent |
| DELETE | /queries/{id} | Deactivate an intent (no longer run or aggregated) |
API keys
| Method | Path | Description |
|---|---|---|
| POST | /api-keys/list | List keys (no plaintext) |
| POST | /api-keys/create | Create a key; the plaintext is returned once |
| POST | /api-keys/delete | Revoke a key, effective immediately |
Errors
Every error has the same shape:
{
"error": {
"code": "unauthorized",
"message": "not logged in"
}
}| HTTP | code | Meaning |
|---|---|---|
| 400 | invalid_* | Invalid input; the suffix names the field |
| 401 | unauthorized | Missing, invalid or revoked key |
| 402 | insufficient_credits | The change needs more credits than the plan has left to allocate |
| 402 | plan_limit | Over the plan's cap on brands, competitors or platforms |
| 403 | forbidden | The role cannot perform this write |
| 404 | not_found | Not found, or not in your organisation |
| 409 | project_paused | The project is paused; resume it before triggering a run |
| 429 | rate_limited | Over the rate limit; see Retry-After |
Rate limits
There is no fixed per-key quota during the beta. Bursts that are too large are throttled: the response is a 429 with code rate_limited and a Retry-After header in seconds; wait it out and retry.
Detection has its own budget: adding intents, platforms or regions is checked against the plan's credits at configuration time, and the endpoint returns a 402 when they run out, rather than silently skipping runs later.