REST APIv1Beta

Geolix API

看板里能看到的每一项数据,都能用一个带 API Key 的 HTTPS 请求拿到。所有接口返回 JSON。

第一个请求

curl https://api.geolix.ai/api/v1/projects \
  -H "x-api-key: glx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

基址: https://api.geolix.ai/api/v1
认证: x-api-key 请求头;Key 在 app.geolix.ai 设置里创建
格式: JSON 请求与响应,UTF-8
限流: 被限流时返回 429,带 Retry-After,见频率限制
状态: Beta接口路径与返回字段仍可能调整;破坏性变更会提前在此页说明。

概览

Geolix 持续检测品牌在 ChatGPT、Perplexity、Gemini 等 AI 搜索平台上的可见性。API 暴露的是与看板同一份数据:品牌、项目、监测意图、检测记录,以及聚合后的看板指标。

资源按 REST 组织: GET 读取, POST 创建或触发, PATCH 更新, DELETE 归档或停用(不物理删除).

快速开始

创建 API Key

名称 — 给调用方起个能认出来的名字,如 CI pipeline
范围 — org 可访问组织内全部项目; project 只绑定一个项目
立即复制 — 完整 Key 只展示这一次,服务端只保存哈希

发出第一个请求

curl https://api.geolix.ai/api/v1/projects \
  -H "x-api-key: glx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

返回你有权访问的项目列表:

[{
  "id": "prj_xxx",
  "name": "My Brand",
  "status": "active"
}]

读取看板

拿到项目 id 后,读它最近 30 天的看板指标:

curl "https://api.geolix.ai/api/v1/board?project_id=prj_xxx&days=30" \
  -H "x-api-key: glx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

不传 project_id 时返回默认(第一个活跃)项目。

认证

每个请求都通过 x-api-key 请求头携带 Key。不支持查询参数传 Key —— 那会进访问日志。

curl https://api.geolix.ai/api/v1/projects \
  -H "x-api-key: glx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Key 格式

glx_live_ 前缀 + 32 位十六进制,共 41 个字符。完整 Key 只在创建时展示一次;服务端存 SHA-256 哈希,明文不落库。

Key 范围

范围	可访问	适用
`org`	组织内全部项目	跨项目集成、自动化报表
`project`	仅绑定的那个项目	单项目 CI/CD、交给外部协作方

权限

Key 继承创建者在组织里的角色。

操作	需要
读 — `GET`	组织任意成员
写 — `POST` `PATCH` `DELETE`	组织 Owner 或 Admin

注意普通成员的 Key 调用写接口会得到 403 forbidden,而不是静默忽略。

品牌

品牌是被监测的主体,竞品也是品牌。

方法	路径	说明
GET	`/brands`	列出品牌
POST	`/brands`	创建品牌
GET	`/brands/{id}`	品牌详情
PATCH	`/brands/{id}`	更新品牌

项目

项目把一个品牌、它的竞品、要监测的意图和平台范围绑在一起;检测按项目调度。

方法	路径	说明
GET	`/projects`	列出项目
POST	`/projects`	创建项目
GET	`/projects/{id}`	项目详情
PATCH	`/projects/{id}`	更新项目
DELETE	`/projects/{id}`	归档项目
GET	`/projects/{id}/queries`	列出监测意图
POST	`/projects/{id}/queries`	添加监测意图
POST	`/projects/{id}/runs`	触发一次检测
GET	`/projects/{id}/runs`	检测记录

看板

看板接口返回聚合后的指标。都接受 project_id、days 与 platforms 查询参数,缺省为默认项目、30 天、全部平台。

方法	路径	说明
GET	`/board`	总览:可见性、声量份额、情绪、排名
GET	`/board/sources`	信源:被 AI 引用的域名与 URL
GET	`/board/gap`	竞品差距
GET	`/board/by-intent`	按意图拆分的指标
GET	`/board/chats`	原始问答记录

检测与意图

方法	路径	说明
GET	`/runs/{id}`	检测详情与进度
POST	`/runs/{id}/cancel`	取消进行中的检测
PATCH	`/queries/{id}`	更新意图
DELETE	`/queries/{id}`	停用意图(不再检测、不再计入聚合)

API Key

方法	路径	说明
POST	`/api-keys/list`	列出 Key(不含明文)
POST	`/api-keys/create`	创建 Key,明文只返回这一次
POST	`/api-keys/delete`	吊销 Key,立即失效

注意这三个接口只认登录会话 Cookie,不认 API Key —— Key 不能管理 Key。

错误码

所有错误都是同一个形状:

{
  "error": {
    "code": "unauthorized",
    "message": "not logged in"
  }
}

HTTP	code	含义
400	`invalid_*`	参数无效;code 后缀指出哪个字段
401	`unauthorized`	缺少 Key、Key 无效或已吊销
402	`insufficient_credits`	本次新增配置超出套餐可再分配的额度
402	`plan_limit`	超出档位的品牌 / 竞品 / 平台数上限
403	`forbidden`	角色不足以执行写操作
404	`not_found`	资源不存在,或不属于你的组织
409	`project_paused`	项目已暂停,先恢复再触发检测
429	`rate_limited`	超过频率限制,看 Retry-After

频率限制

Beta 期间不设固定的每 Key 配额。突发流量过大时会被限流:响应 429,code 为 rate_limited,并带 Retry-After 请求头(秒),等它过去再重试即可。

检测本身另有额度:每次新增意图、平台或地域都会在配置时按套餐额度校验,额度不够时接口返回 402,而不是在运行时静默跳过。

Geolix API

概览#

快速开始#

创建 API Key

发出第一个请求

读取看板

认证#

Key 格式#

Key 范围#

权限#

品牌#

项目#

看板#

检测与意图#

API Key#

错误码#

频率限制#

概览