API 接口文档

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

Semrush 外链单笔入库

单笔写入一条 Semrush 外链。处理规则与 /admin/file-upload 上传「Semrush外链Excel」后台异步导入完全一致:校验必需字段、超过 6 个月的 first_seen 跳过、计算 quality_score、from_url+competitor_url 重复则跳过。

POST /api/admin/backlinks/ingest

与批量上传的关系

后台上传 Excel 时按行映射列名后写入 backlinks 表;本接口对单行走同一套规则。

  • 必需:Source url / Target url / Anchor(或 from_url / competitor_url / anchor_text)
  • first_seen 早于「当前时间 − 6 个月」→ skipped_old
  • 写入前计算 quality_score(与批量相同公式)
  • 唯一键 from_url + competitor_url 已存在 → skipped_duplicate(等同 createMany skipDuplicates)

认证

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

请求示例(推荐字段名)

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

{
  "from_url": "https://example.com/blog/post",
  "competitor_url": "https://competitor.com/",
  "anchor_text": "best tools",
  "page_authority": 45,
  "source_title": "Example Blog",
  "external_links": 12,
  "internal_links": 30,
  "is_nofollow": false,
  "first_seen": "2026-10-01",
  "last_seen": "2026-11-01"
}

也可用 Excel 原始列名

{
  "Source url": "https://example.com/blog/post",
  "Target url": "https://competitor.com/",
  "Anchor": "best tools",
  "Page ascore": 45,
  "Source title": "Example Blog",
  "External links": 12,
  "Internal links": 30,
  "Nofollow": "false",
  "First seen": "2026-10-01",
  "Last seen": "2026-11-01"
}

响应

{
  "success": true,
  "data": {
    "action": "created",
    "id": 12345,
    "quality_score": 62.5,
    "record": {
      "from_url": "https://example.com/blog/post",
      "competitor_url": "https://competitor.com/",
      "anchor_text": "best tools"
    }
  }
}

action 取值:created|skipped_duplicate|skipped_old

MCP

工具名 ingest_semrush_backlink,参数使用 camelCase(from_url / competitor_url / anchor_text 等)。