开发者指南
API key、MCP server，以及如何以编程方式查询 AIEO.ee 数据。
dashboard 里的一切都可以编程访问：给脚本与集成用的 REST API，以及给 AI 编码代理用的 MCP server。
API key
在 Settings → MCP（dashboard）中创建。key 是组织级的，以 aieo_ 开头：
readscope —— 所有 GET 端点。read+writescope —— 写操作端点（POST/PATCH/DELETE）。只读 key 调用写操作会得到403。
组织管理（账单、key、成员）仅限会话——API key 无法访问。
REST API
Base URL：https://app.aieo.ee/api（自托管：你的 API 源）。用 Authorization: Bearer aieo_... 认证。
完整路由清单由运行中的应用自动生成，见 API 路由清单。核心流程的手写示例如下。
核心流程示例
所有调用：Authorization: Bearer aieo_...，base https://app.aieo.ee/api。
API key 作用于其所属组织——x-org-id 是会话认证的功能（多组织成员的 dashboard 用户使用），不能切换 API key 的组织。写操作需要 read+write 的 key。
列出项目
curl -H "Authorization: Bearer aieo_YOUR_KEY" \
https://app.aieo.ee/api/projects[
{ "id": "e312a3b6-...", "name": "acmecloud.io", "domain": "acmecloud.io" }
]添加跟踪关键词
每次一个关键词（keyword，2–120 字符）：
curl -X POST -H "Authorization: Bearer aieo_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"keyword":"acmecloud vs hetzner"}' \
https://app.aieo.ee/api/projects/PROJECT_ID/seo/keywords立即运行全部 GEO prompt
curl -X POST -H "Authorization: Bearer aieo_YOUR_KEY" \
https://app.aieo.ee/api/projects/PROJECT_ID/geo/run-all每 prompt × engine 扣 1 credit；同日重跑覆盖当天结果。错误带机器可读 code：超出每日套餐配额返回 402 与 code: "plan_limit"；credits 不足返回 402 与
code: "insufficient_credits"；请求过快返回 429（频率限制）——与配额是两回事。
获取 AI 可见性摘要
curl -H "Authorization: Bearer aieo_YOUR_KEY" \
"https://app.aieo.ee/api/projects/PROJECT_ID/geo/summary?days=14"{ "runs": 80, "mentions": 44, "mentionRate": 55, "citationRate": 12,
"prompts": 6, "sov": [{ "name": "Hetzner", "mentions": 30 }] }生成白标报告
curl -H "Authorization: Bearer aieo_YOUR_KEY" \
https://app.aieo.ee/api/projects/PROJECT_ID/overview/report \
-o report.html错误
错误为 JSON，带 error 消息与（适用时的）机器可读 code
（insufficient_credits、plan_limit、project_paused）；dashboard 把这些 code 映射为本地化文案。注意截断上限与分页的区别：关键词与 GEO runs 列表接受 limit（关键词默认 100 / 上限 200，runs 默认 25 / 上限 100）只限制返回条数——没有 offset，属于单次响应视图；真正支持分页的只有 GSC rows（limit + offset）。
MCP server
AIEO.ee 通过 Model Context Protocol 暴露你的 SEO + GEO 数据——streamable HTTP，仅 POST：
POST https://app.aieo.ee/mcp
Authorization: Bearer aieo_...Claude Code
claude mcp add --transport http aieo https://app.aieo.ee/mcp \
--header "Authorization: Bearer aieo_YOUR_KEY"Cursor
加入 .cursor/mcp.json：
{
"mcpServers": {
"aieo": {
"url": "https://app.aieo.ee/mcp",
"headers": { "Authorization": "Bearer aieo_YOUR_KEY" }
}
}
}Codex CLI
先导出 key，再以环境变量名引用：
export AIEO_API_KEY=aieo_YOUR_KEY加入 ~/.codex/config.toml：
[mcp_servers.aieo]
url = "https://app.aieo.ee/mcp"
bearer_token_env_var = "AIEO_API_KEY"OpenCode
先导出 key，再在 opencode.json（项目根目录或 ~/.config/opencode/）中添加远程 server：
export AIEO_API_KEY=aieo_YOUR_KEY{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"aieo": {
"type": "remote",
"url": "https://app.aieo.ee/mcp",
"headers": { "Authorization": "Bearer {env:AIEO_API_KEY}" }
}
}
}然后就可以问你的代理：「为什么我们这周 AI 可见性下降了？」——它会调用 query_ai_visibility、analyze_citations 等工具。
Skills + MCP
MCP 给代理提供数据与操作；Skill 给它工作方法。Skill 在客户端侧编写（Claude Code、Codex、OpenCode 中是一个 SKILL.md 文件），只需调用上面的 MCP 工具。一个最小的每周复盘示例：
---
name: weekly-geo-review
description: 用 AIEO.ee MCP 工具做项目的每周 AI 可见度复盘。
---
1. 调用 query_ai_visibility（days: 14），记录各引擎的变化。
2. 调用 analyze_citations，列出替代我们被引用的域名。
3. 调用 find_content_gap，选出最大的一个内容缺口。
4. 针对它调用 generate_content_brief（需要 write 权限的 key）。
5. 回复：变了什么、为什么、本周该发布什么。WorkBuddy、千问办公、豆包等 AI Agent 同理：支持自定义 MCP（streamable HTTP）的客户端可直接连接；暂不支持的，可在 Skill 里用同一个 Bearer key 调用 REST API。具体接入方式以各产品当前版本为准。
每个工具、其真实输入 schema 与 scope 要求都由 server 自身的定义生成：MCP 工具 Reference。
速率限制
MCP 请求按组织限流（撰写时为 60 请求/分钟）。超限返回 429 与 Retry-After 头。