API 接口文档

左侧选择接口,右侧查看说明与示例。所有对外接口都需要 API Key。

Semrush 关键词单笔入库

单笔写入一条 Semrush 关键词(可选带排名 URL)。处理规则与 /admin/file-upload 上传「Semrush关键词Excel」后台异步导入一致:按 keyword 唯一;仅当新 timestamp 的日期比库内更新才覆盖指标;同时提供 url+position 时写入 seo_websites / seo_domain。

POST /api/admin/seo-ranking/ingest

与批量上传的关系

Excel 异步任务会对每一行做字段映射、时间戳比较、关键词 upsert,排名格式再写域名与网站排名。本接口对单行执行相同逻辑。

  • 必需:Keyword(或 keyword)
  • 已存在且新日期不更新 → skipped(不改指标)
  • 已存在且日期更新 → 只覆盖有值且变化的字段 → updated
  • 不存在 → created
  • 同时有 URL + Position → 同步处理 seo_domain / seo_websites

认证

Authorization: Bearer <API_KEY> 或登录态 Token;亦可 X-API-Key。

请求示例:纯关键词(keyword 格式)

POST /api/admin/seo-ranking/ingest
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "keyword": "ai image upscaler",
  "searchVolume": 2400,
  "keywordDifficulty": 38,
  "cpc": 1.25,
  "keywordIntents": "commercial",
  "trends": "12,18,22,30,28,35,40",
  "timestamp": "2026-11-17"
}

请求示例:带排名(ranking 格式)

{
  "keyword": "ai image upscaler",
  "searchVolume": 2400,
  "keywordDifficulty": 38,
  "cpc": 1.25,
  "timestamp": "2026-11-17",
  "url": "https://example.com/tools/upscaler",
  "position": 7,
  "previousPosition": 12,
  "traffic": 320,
  "trafficPercentage": 4.5,
  "trafficCost": 88.2
}

也可用 Excel 原始列名

{
  "Keyword": "ai image upscaler",
  "Volume": 2400,
  "Keyword Difficulty": 38,
  "CPC (USD)": 1.25,
  "Intent": "commercial",
  "Trends": "12,18,22,30,28,35,40",
  "Timestamp": "2026-11-17"
}

响应

{
  "success": true,
  "data": {
    "action": "created",
    "keywordId": 99881,
    "keyword": "ai image upscaler",
    "format": "keyword_format",
    "website": null
  }
}

关键词 action:created|updated|skipped。 若写入排名,website.action 同为 created / updated / skipped。

MCP

工具名 ingest_semrush_keyword,参数使用 camelCase(keyword / searchVolume / url / position 等)。