开发者
API 路由清单
全部公开 REST 端点，由运行中的路由表生成，并标注认证方式与 scope。
由 createApp() 生成——与 API server 运行的路由表同源。平台/管理员/webhook 等内部端点已排除。
Base URL： https://app.aieo.ee/api · 认证： Authorization: Bearer aieo_...（API key）或 dashboard 会话 cookie。
使用 API key 的写操作（POST/PATCH/DELETE）需要 write scope；只读 key 会得到 403。API key 始终作用于其所属组织；x-org-id 是面向多组织成员的会话认证功能，不能切换 API key 的组织。
核心流程的手写请求/响应示例将在下一文档阶段补充；本清单是完整的、自动生成的接口面。
AI 可见性（GEO）
| 方法 | 路径 | 认证 | 说明 |
|---|---|---|---|
DELETE | /api/projects/:projectId/geo/prompts/:promptId | 会话或 API key | 删除跟踪 prompt。 |
GET | /api/projects/:projectId/geo/citations | 会话或 API key | AI 引擎在跟踪 prompt 中引用了哪些域名。 |
GET | /api/projects/:projectId/geo/engines | 会话或 API key | 分引擎可见性汇总（只统计已完成的新口径运行；旧版采样数据不计入）。 |
GET | /api/projects/:projectId/geo/executions/active | 会话或 API key | 仍在进行中的 GEO 运行：排队、等待 DeepSeek 闲时窗口、发送中、收集结果中。 |
GET | /api/projects/:projectId/geo/prompts | 会话或 API key | 跟踪 prompt 列表及逐 prompt 统计。 |
GET | /api/projects/:projectId/geo/runs | 会话或 API key | GEO 运行历史（按 prompt×engine×day）。 |
GET | /api/projects/:projectId/geo/runs/:runId | 会话或 API key | 单次 GEO 运行详情：原始回答、提及、引用。 |
GET | /api/projects/:projectId/geo/series | 会话或 API key | 按日可见性时间序列（图表用）。 |
GET | /api/projects/:projectId/geo/sov | 会话或 API key | AI 回答中各品牌的 share of voice。 |
GET | /api/projects/:projectId/geo/summary | 会话或 API key | AI 可见性摘要：回溯窗口内的提及率、引用率（?days）。 |
PATCH | /api/projects/:projectId/geo/prompts/:promptId | 会话或 API key | 更新 prompt（text/engines/active）。 |
POST | /api/projects/:projectId/geo/prompts | 会话或 API key | 创建跟踪 prompt（文本、分类、引擎）。GEO 只在发起时运行。 |
POST | /api/projects/:projectId/geo/prompts/:promptId/run | 会话或 API key | 把一个 prompt 在其引擎上作为一个运行请求执行（可选 idempotencyKey、engines、DeepSeek 策略 offpeak|immediate）。需要订阅；每次先冻结最高费用，按实际费用结算。 |
POST | /api/projects/:projectId/geo/run-all | 会话或 API key | 把全部启用 prompt 在其引擎上作为一个运行请求执行（最多 50 次）。需要 idempotencyKey 和预览返回的 priceVersion；可选 DeepSeek 策略。 |
POST | /api/projects/:projectId/geo/run-all/preview | 会话或 API key | 运行全部启用 prompt 的约价和最高价，以及需要确认的 priceVersion。 |
POST | /api/projects/:projectId/geo/run-requests | 会话或 API key | 创建 GEO 运行请求：items（≤ 50，每项 promptId、engine、可选 policy）与 idempotencyKey。整体接受（同一事务冻结每次运行的最高费用）或整体拒绝；同一 key + 同一 items 返回原请求。 |
POST | /api/projects/:projectId/geo/run-requests/preview | 会话或 API key | 运行前预估费用：典型与最高用量单位（1 单位 = $0.0001），以及尚无核实价格的引擎。不冻结、不调用供应商。 |
SEO 情报
| 方法 | 路径 | 认证 | 说明 |
|---|---|---|---|
DELETE | /api/projects/:projectId/seo/keywords/:keywordId | 会话或 API key | 移除跟踪关键词。 |
GET | /api/projects/:projectId/seo/backlink-gap | 会话或 API key | 竞对拥有而本项目缺失的反链。 |
GET | /api/projects/:projectId/seo/backlinks | 会话或 API key | 反链概况与头部链接。 |
GET | /api/projects/:projectId/seo/competitor-discovery | 会话或 API key | 从存量 SERP 快照发现共同出现的竞对（重叠分）。 |
GET | /api/projects/:projectId/seo/competitor-discovery/:domain/keywords | 会话或 API key | 单个被发现竞对的共现关键词下钻。 |
GET | /api/projects/:projectId/seo/competitors | 会话或 API key | 竞对矩阵：重叠度与排名对比。 |
GET | /api/projects/:projectId/seo/competitors/missing | 会话或 API key | 竞对有排名而本项目没有的关键词（?brandId）。 |
GET | /api/projects/:projectId/seo/distribution | 会话或 API key | 累计排名桶（top3、top10、top20、top100）。 |
GET | /api/projects/:projectId/seo/domain-overview | 会话或 API key | 项目已跟踪关键词的聚合视图：排名摘要、估算流量、top pages、SERP 特性、已存储反链与竞对矩阵。 |
GET | /api/projects/:projectId/seo/intersection | 会话或 API key | 全部所选竞对（2–4 个）最近 10 天内均进 top-20 的关键词，附各竞对排名。 |
GET | /api/projects/:projectId/seo/keyword-gap | 会话或 API key | 对选定竞对的关键词差距。 |
GET | /api/projects/:projectId/seo/keywords | 会话或 API key | 跟踪关键词表：排名、搜索量、难度、意图。 |
GET | /api/projects/:projectId/seo/serp | 会话或 API key | 单关键词实时 SERP 查询（按需调用数据源）。 |
GET | /api/projects/:projectId/seo/serp-features | 会话或 API key | 最近 7 天 SERP 特性统计（仅演示模式启发式标记；真实特性检测未接入）。 |
GET | /api/projects/:projectId/seo/summary | 会话或 API key | SEO 头部指标（平均排名、跟踪关键词数、估算流量）。 |
POST | /api/projects/:projectId/competitors | 会话或 API key | 为项目添加竞对品牌/域名。 |
POST | /api/projects/:projectId/seo/keywords | 会话或 API key | 添加跟踪关键词（受套餐限制）。 |
POST | /api/projects/:projectId/seo/refresh | 会话或 API key | 为项目排队一次排名刷新。 |
POST | /api/projects/:projectId/seo/research | 会话或 API key | 种子词关键词研究（配置 DataForSEO 时使用真实数据）。 |
Search Console 与集成
| 方法 | 路径 | 认证 | 说明 |
|---|---|---|---|
DELETE | /api/projects/:projectId/integrations/bing | 会话，仅组织 owner/admin | 断开 Bing Webmaster。已同步的 Bing 搜索数据会被删除，AI Performance 的导入保留。 |
DELETE | /api/projects/:projectId/integrations/bing-ai/imports/:importId | 会话 cookie | 删除一次导入（管理员或上传者本人）。 |
DELETE | /api/projects/:projectId/integrations/gsc | 会话，仅组织 owner/admin | 断开 GSC。已存数据保留；重新连接同一站点会继续使用，连接别的站点会替换。 |
GET | /api/projects/:projectId/integrations/bing | 会话或 API key | 项目的 Bing Webmaster 连接状态：站点、各同步步骤的状态、待选站点。 |
GET | /api/projects/:projectId/integrations/bing-ai/compare | 会话或 API key | 在 canCompare 允许时比较两次导入 a（之前）和 b（之后）。总览：汇总。检索词：按检索词原文对齐，给出共同和单边的个数，分页；期间为估算或天数不同时会标注。主题组合不比较。 |
GET | /api/projects/:projectId/integrations/bing-ai/imports | 会话或 API key | 列出项目的 AI Performance 导入（不含明细）、每种文件最新的一次，以及提醒开关。 |
GET | /api/projects/:projectId/integrations/bing-ai/imports/:importId | 会话或 API key | 按种类返回单次导入。总览：每日引用和被引页面数、汇总、28 天对比、连续为 0、读取时的差异。检索词：整次导入的汇总加第一页明细（这里不接受搜索，请用 POST …/rows）。主题：全部行。 |
GET | /api/projects/:projectId/integrations/bing/auth-url | 会话，仅组织 owner/admin | 发起 Bing Webmaster OAuth（一次性 state URL，webmaster.read）。假冒会话会被拒绝。 |
GET | /api/projects/:projectId/integrations/bing/crawl-stats | 会话或 API key | Bing 每日抓取计数（抓取页数、已索引、入链、各类状态码），取 Bing 提供的最近 days=7..180 天。 |
GET | /api/projects/:projectId/integrations/gsc | 会话或 API key | 项目 GSC 连接状态。 |
GET | /api/projects/:projectId/integrations/gsc/auth-url | 会话，仅组织 owner/admin | 发起 GSC OAuth（一次性 state URL）。 |
GET | /api/projects/:projectId/search-analytics/insights | 会话或 API key | GSC 洞察：type=striking|cannibalization|ctr|decay|brand，days=28|90。返回状态；只有时段内数据完整时才返回结果行。 |
GET | /api/projects/:projectId/search-analytics/rows | 会话或 API key | GSC 按 query 或 page 维度的明细行（窗口内聚合，CTR/排名按展示加权），并返回时段和缺失的日期。 |
GET | /api/projects/:projectId/search-analytics/summary | 会话或 API key | Google Search Console 摘要（点击、展示、CTR、排名）。窗口截止到最近一个已导入的日期，并返回时段和缺失的日期。 |
PATCH | /api/projects/:projectId/integrations/bing | 会话，仅组织 owner/admin | 在账号的已验证站点之间切换 Bing 站点；原站点已同步的数据会被删除。连接在此期间变化时返回 409。 |
PATCH | /api/projects/:projectId/integrations/bing-ai/settings | 会话 cookie | 开关导入过期提醒（owner/admin）。 |
PATCH | /api/projects/:projectId/integrations/gsc | 会话，仅组织 owner/admin | 切换已连接的 GSC 站点；原站点的数据会被删除，并重新导入 90 天历史。 |
POST | /api/projects/:projectId/integrations/bing-ai/imports | 会话 cookie | 上传 Bing AI Performance 导出的 CSV（multipart：files[] 和 meta）：总览、检索词或主题组合。检索词和主题需要逐个文件给出导出时在 Bing 里选的范围（meta.periods / meta.period）。按文件返回结果，按文件名核对站点并用签名凭据确认，每个项目每个 UTC 日最多 30 个文件。 |
POST | /api/projects/:projectId/integrations/bing-ai/imports/:importId/rows | 会话或 API key | 一次检索词导入的一页明细。搜索词放在 JSON 请求体里（search、limit 最多 200、offset、sort），不进网址访问日志；整次导入的汇总不受搜索影响。 |
POST | /api/projects/:projectId/integrations/bing/confirm | 会话，仅组织 owner/admin | 没有已验证站点匹配项目域名时，在 OAuth 之后确认 Bing 站点。 |
POST | /api/projects/:projectId/integrations/bing/sync | 会话或 API key | 触发一次 Bing 同步，取 Bing 当前提供的全部数据；正在同步时返回 mode=busy。 |
POST | /api/projects/:projectId/integrations/gsc/backfill/retry | 会话，仅组织 owner/admin | 重新启动因多次失败而停止的 GSC 历史数据导入。 |
POST | /api/projects/:projectId/integrations/gsc/confirm | 会话，仅组织 owner/admin | OAuth 后确认站点选择（pending_token 流程）。 |
POST | /api/projects/:projectId/integrations/gsc/sync | 会话或 API key | 触发 GSC 同步最近 16 天（重拉最近 4 天、补齐缺失日期）；正在导入时返回 mode=busy。 |
内容缺口与 Brief
| 方法 | 路径 | 认证 | 说明 |
|---|---|---|---|
GET | /api/projects/:projectId/content/briefs | 会话或 API key | 列出已生成的内容 brief。 |
GET | /api/projects/:projectId/content/briefs/:briefId | 会话或 API key | 单个内容 brief（大纲、实体、FAQ）。 |
GET | /api/projects/:projectId/content/gaps | 会话或 API key | 内容缺口：竞对 top-10 有排名而本项目没有的关键词。 |
POST | /api/projects/:projectId/content/gaps/:gapId/brief | 会话或 API key | 为一个缺口生成内容 brief（计量：先冻结最高费用，按实际 token 费用结算）。 |
POST | /api/projects/:projectId/content/recompute-gaps | 会话或 API key | 基于当前排名重新计算内容缺口。 |
技术审计
| 方法 | 路径 | 认证 | 说明 |
|---|---|---|---|
GET | /api/projects/:projectId/audit/latest | 会话或 API key | 最近一次审计运行及评分问题。 |
POST | /api/projects/:projectId/audit | 会话或 API key | 排队一次技术 SEO 站点审计（爬虫，maxPages）。 |
Growth Agent 与建议
| 方法 | 路径 | 认证 | 说明 |
|---|---|---|---|
GET | /api/projects/:projectId/agent/conversations | 会话或 API key | 列出 Growth Agent 会话。 |
GET | /api/projects/:projectId/agent/conversations/:conversationId/messages | 会话或 API key | 单个会话的消息列表。 |
GET | /api/projects/:projectId/recommendations | 会话或 API key | 项目的优先级增长建议。 |
GET | /api/projects/:projectId/recommendations/:recId/review | 会话或 API key | 页面任务的前后对比：改动后的 Google 窗口和审计复查。 |
PATCH | /api/projects/:projectId/recommendations/:recId | 会话或 API key | 更新建议状态（完成/忽略）。 |
POST | /api/projects/:projectId/agent/analyze | 会话或 API key | 运行完整诊断分析（按实际 token 费用计量；requestKey 使重试无害）。 |
POST | /api/projects/:projectId/agent/chat | 会话或 API key | 向 Growth Agent 发消息（按实际 token 费用计量）。 |
POST | /api/projects/:projectId/agent/conversations | 会话或 API key | 创建 Growth Agent 会话。 |
组织、API Key 与账单
| 方法 | 路径 | 认证 | 说明 |
|---|---|---|---|
DELETE | /api/org/keys/:keyId | 会话，仅组织 owner/admin | 吊销 API key——仅 owner/admin。 |
GET | /api/org | 会话或 API key | 当前组织概况：套餐、订阅资格、按来源的用量余额、用量包、成员数。 |
GET | /api/org/billing/checkout-status | 会话，仅组织 owner/admin | 回跳页轮询：这次结账的付款是否已记入我们的记录。 |
GET | /api/org/billing/invoices | 会话，仅组织 owner/admin | 付款记录及 Dodo 开具的发票链接，按时间倒序。 |
GET | /api/org/invitations | 会话，仅组织 owner/admin | 列出待处理成员邀请——仅 owner/admin。 |
GET | /api/org/keys | 会话或 API key | 列出组织 API keys（脱敏）。 |
GET | /api/org/usage | 会话或 API key | 近 30 天按类型的活动计数（不是金额，余额见 GET /api/org）。 |
PATCH | /api/org | 会话，仅组织 owner/admin | 更新组织设置（名称等）——仅 owner/admin 会话。 |
POST | /api/org/billing/cancel | 会话，仅组织 owner/admin | 在计费周期结束时取消订阅（附流失原因问卷）。 |
POST | /api/org/billing/checkout | 会话，仅组织 owner/admin | 为 $10 月付套餐打开 Dodo 托管结账页（另加税费）；需要「立即开始服务」的确认。 |
POST | /api/org/billing/portal | 会话，仅组织 owner/admin | 打开 Dodo 客户门户（付款方式、发票、税务信息）。 |
POST | /api/org/billing/resume | 会话，仅组织 owner/admin | 恢复待取消的订阅。 |
POST | /api/org/billing/topup | 会话，仅组织 owner/admin | 用量包结账：1–50 个 $10 用量包（另加税费），支付成功起 365 天有效（仅限订阅用户）；需要「立即开始服务」的确认。 |
POST | /api/org/keys | 会话，仅组织 owner/admin | 创建 API key（可选 read+write scope）——仅 owner/admin。 |
POST | /api/org/leave | 会话 cookie | 退出组织（最后一位 owner 拒绝）。 |
POST | /api/org/transfer-ownership | 会话，仅组织 owner/admin | 原子化转让组织所有权（org 锁 + 角色互换）。 |
项目与总览
| 方法 | 路径 | 认证 | 说明 |
|---|---|---|---|
GET | /api/projects | 会话或 API key | 列出当前组织的项目（网站）。 |
GET | /api/projects/:projectId/overview | 会话或 API key | 仪表盘总览：Growth Score 输入、趋势亮点。 |
GET | /api/projects/:projectId/overview/report | 会话或 API key | 项目白标 HTML 增长报告。 |
POST | /api/projects | 会话或 API key | 创建项目（域名、名称）——受套餐限制。 |
账号与通知
| 方法 | 路径 | 认证 | 说明 |
|---|---|---|---|
GET | /api/account/export | 会话 cookie | 导出账号个人数据（GDPR 风格 JSON）。 |
GET | /api/account/preferences | 会话 cookie | 读取账号偏好：语言与每周摘要退订状态。 |
GET | /api/notifications | 仅会话（不接受 API key） | 列出当前用户的站内通知（API key 拒绝访问）。 |
GET | /api/notifications/unread-count | 仅会话（不接受 API key） | 未读通知数。 |
PATCH | /api/account/preferences | 会话 cookie | 更新账号偏好：语言（'en' | 'zh'，驱动界面与事务邮件语言）和/或 digestOptOut（每周增长摘要退订）。 |
POST | /api/account/delete | 会话 cookie | 删除账号（先取消独占组织的 Dodo 订阅，再级联清理其数据；存在共享组织时 409，Dodo 无法确认取消时 502）。 |
POST | /api/notifications/mark-read | 仅会话（不接受 API key） | 标记通知已读（按 ids 或全部）。 |
免费工具
| 方法 | 路径 | 认证 | 说明 |
|---|---|---|---|
POST | /api/tools/robots | 会话或 API key | 免费工具：抓取并解析站点 robots.txt。 |
POST | /api/tools/schema | 会话或 API key | 免费工具：从 URL 提取结构化数据（schema.org）。 |
POST | /api/tools/serp | 会话或 API key | 免费工具：对查询做实时 SERP 检查（DataForSEO 或 mock 池）。 |
POST | /api/tools/sitemap | 会话或 API key | 免费工具：抓取并汇总站点 sitemap。 |
元信息
| 方法 | 路径 | 认证 | 说明 |
|---|---|---|---|
GET | /api/projects/:projectId/ai-readiness/latest | 会话或 API key | 最近一次 AI 可读性检查，以及最近一份完成的报告（分数、结论、修复步骤）。 |
GET | /api/projects/:projectId/ai-readiness/runs | 会话或 API key | AI 可读性历史，按时间倒序（游标分页；只在同一口径内显示分数变化）。 |
GET | /api/projects/:projectId/ai-readiness/runs/:runId | 会话或 API key | 单次 AI 可读性检查及其报告；按保留策略清理后 report 为 pruned。 |
GET | /api/projects/:projectId/page-priorities | 会话或 API key | 优先页面：按 URL 键合并后的 Google 衰退，再按最近一次已完成的审计筛选。AI 页面级规则标为暂不可用。 |
GET | /health | 公开 | 存活探针：服务名与当前配置的 AI 引擎 ID 列表。 |
PATCH | /api/projects/:projectId/rank-settings | 会话，仅组织 owner/admin | 项目的自动排名检查：rankCadence daily|weekly|off 与 rankDepth 10|20|50|100（仅组织管理员）。 |
POST | /api/projects/:projectId/ai-readiness/runs | 会话或 API key | 对项目主域名发起一次免费的 AI 可读性检查（有进行中或 10 分钟内完成的检查时直接返回；每个组织每个 UTC 日 20 次）。 |
POST | /api/projects/:projectId/page-priorities/tasks | 会话或 API key | 把一个优先页面加入任务，基线由服务端固定。每个页面只有一个未完成的任务。 |