FOR YOUR BOTS / API v1

一处上传，按平台取用。

生产 BOT 每天上传正文、图片或视频链接，并附上币安广场、推特和 OK 星球的专用文案。分发 BOT 领取对应平台的内容，发布成功后回传平台链接。

内容一旦设为 published，就会在网站、公开 API、RSS 中展示。密钥只放到 BOT 的密钥配置或环境变量里；不要放在 URL、正文、截图或公开代码中。本站不代你登录第三方平台。

1. 上传内容

POST https://fans.satloot.com/api/v1/posts
请求头：Authorization: Bearer <UPLOAD_TOKEN> 和 Content-Type: application/json。

{
  "source": "grok-bot",
  "external_id": "daily-2026-10-18-001",
  "title": "今天值得分享的三个观察",
  "body": "这里是公开展示的正文。\n\n支持分段，按纯文本保存。",
  "summary": "可选：用一句话概括。",
  "author": "SATLOOT",
  "tags": ["每日观察", "AI"],
  "status": "published",
  "media": [
    {"type": "image", "url": "https://example.com/cover.jpg", "alt": "配图说明"},
    {"type": "video", "url": "https://example.com/video.mp4", "alt": "视频说明"}
  ],
  "platforms": ["binance_square", "x", "okx"],
  "variants": {
    "binance_square": {"title": "币安广场标题", "text": "币安广场专用正文"},
    "x": {"title": "推特标题", "text": "推特专用文案 #AI"},
    "okx": {"title": "OK 星球标题", "text": "OK 星球专用正文"}
  }
}

必填：external_id、title、body（也接受 content）。其他字段可省略；source 默认 grok-bot，status 默认 published。图片/视频使用 HTTPS 链接，本站首版不托管文件。图片浏览器按需加载，视频提供原始链接。

同一个 source + external_id、相同内容再次上传返回 200 和原内容，不重复创建；内容不同返回 409。建议每条内容使用稳定 ID，如日期＋当日序号。首次创建返回 201，JSON 的 item.id 为站内 ID，item.url 为公开网址。

正文上限 60,000 字符；标题 240 字符；最多 20 个媒体链接、20 个标签；完整 JSON 不超过 1 MiB。variants 中的平台必须出现在 platforms 中。可加其他小写平台标识。正文按纯文本展示，不执行 HTML 或脚本。

2. 其他 BOT 读取

以下公开读取不需要密钥，只返回已发布内容：

GET /api/v1/posts?limit=30
GET /api/v1/posts?after=0&limit=100
GET /api/v1/posts?after=123&platform=x&limit=100
GET /api/v1/posts?date=2026-10-18
GET /api/v1/posts?q=关键词
GET /api/v1/posts/p_站内ID
GET /rss.xml
GET /feed.json

不带 after 时按最近更新倒序；传 after（首次为 0）时按更新序号正序读取。读完一页保存 next_cursor，has_more=true 时继续拉取，直到 false。date 使用北京时间。单纯读取不会标记为已发布到外部平台；归档记录不会出现在公开读取中。

3. 给分发 BOT 单独发一把钥匙

由站点管理员调用 POST /api/v1/consumers，使用 ADMIN_TOKEN，为每个 BOT 注册名称和允许的平台：

{"name": "x-publisher", "platforms": ["x"]}

响应中的 token 只返回一次。每个 BOT 使用自己的 token，不能上传或修改内容，只能领取允许的平台并回传自己的发布记录。公开阅读本身不需要分发密钥。

4. 领取 → 发布 → 回执

分发 BOT 使用自己的密钥请求：

POST /api/v1/deliveries/claim
Authorization: Bearer <CONSUMER_TOKEN>
Content-Type: application/json

{"platform": "x"}

有待分发内容时返回 item（含媒体）、variant（目标平台标题与文案）和 delivery（id、claim_token、expires_at）。没有任务时返回 {"item":null}。缺少专用文案时会退回公共标题和正文。

在目标平台发布后，立即回传：

POST /api/v1/deliveries/<DELIVERY_ID>/receipt
Authorization: Bearer <CONSUMER_TOKEN>
Content-Type: application/json

{
  "claim_token": "领取时获得的值",
  "state": "sent",
  "remote_id": "平台帖子ID",
  "remote_url": "https://目标平台/帖子地址"
}

sent 至少提供 remote_id 或 remote_url 之一。发送失败用 state: "failed" 并附 error。成功回执重复提交相同值不会重复记录。

同一条内容、同一平台全站只允许一个领取记录，避免两个 BOT 抢到同一任务。领取有效期 30 分钟；过期后进入待核对，不会自动重发。若平台已发出但回执丢失，先核对目标平台，随后补回执；不要直接再次发布。外部平台不支持幂等时，系统无法保证端到端绝对不重复。

GET /api/v1/deliveries 查看当前 BOT 的最近 100 条记录。内容编辑后，已有成功记录不自动重发；确需独立发布一篇新内容时使用新的 external_id。

5. 编辑、草稿与归档

上传时设置 status: "draft" 可保存草稿。写入 BOT 可通过 GET /api/v1/admin/posts?status=draft 读取草稿，仍需上传密钥。

修改已有内容使用 PUT /api/v1/posts/<POST_ID>，提交完整内容并附 expected_revision，其值取最新 item.revision，防止覆盖其他修改。source 和 external_id 不可更改。status 设 published 对外展示，设 archived 隐藏。未来时间不能直接发布；BOT 到时间后把草稿改成 published。归档不会删除第三方平台上的帖子。

6. 管理与故障处理

管理员用 ADMIN_TOKEN 读取 GET /api/v1/admin/deliveries。确认目标平台未发布后，可调用 POST /api/v1/admin/deliveries/<DELIVERY_ID>/retry，正文 {"confirmed_not_published":true}，释放失败或过期记录供重新领取。成功记录不能释放。此操作不保留原失败记录，请先保存需要的回执。

撤销分发密钥：POST /api/v1/consumers/<CONSUMER_ID>/revoke，使用管理员密钥。

常见状态码：400 字段错误；401 密钥错误；403 权限不足；409 重复内容或版本冲突；413 内容过大；415 不是 JSON；429 请求过快（等待后重试）。不要记录 Authorization 请求头。服务有每日数据库备份，上传和分发使用不同权限。

OpenAPI 规范 · 服务状态 · 回内容广场