popkitpopkitAPI
中EN
开始使用

popkit REST API

把 popkit 的能力以 REST 风格开放给你的脚本、自动化平台与后端:一份长期凭证,就能读账号与内容、存草稿、排期、发布、回评论、看数据。它与 popkit 的 MCP Server 同源 —— 同一套 scope、限流、幂等与审计,只是换了一种调用方式。

Base URL

https://popkit.loxily.com/api/v1

全部端点只走 HTTPS,请求与响应都是 JSON(Content-Type: application/json)。路径里的 v1 是大版本:同一版本内只做向后兼容的追加(新字段、新端点、新枚举值),调用方解析时请忽略不认识的字段。

从这里开始

快速开始

签发凭证 → 第一个请求 → 存草稿 → 排期,五分钟走完。

鉴权与权限

Bearer 凭证怎么来、scope 与发布落点怎么配、如何撤销。

约定

响应信封、分页游标、幂等键、限流与日上限、时间格式。

错误码

13 个机器码、对应的 HTTP 状态与处理办法。

OpenAPI 3.1

/docs/api/openapi.json,可直接导入 Postman / Swagger / 代码生成器。

MCP 接入文档

给 Claude、Cursor 这类 AI 客户端用的另一种接法,能力一致。

端点总览(20 个)

按业务域分组。每个端点单独一页,含参数表、cURL / JavaScript / Python 样例与各状态码的响应示例。

工作区与账号 — 我是谁、有哪些账号、配额还剩多少。

方法路径说明
GET/api/v1/workspace工作区上下文
GET/api/v1/accounts已连接账号

内容 — 草稿、排期、修改、改期、送审与预检。

方法路径说明
GET/api/v1/posts内容列表
GET/api/v1/posts/{postId}内容详情
POST/api/v1/posts新建内容
PATCH/api/v1/posts/{postId}修改内容
POST/api/v1/posts/precheck发布预检
POST/api/v1/posts/{postId}/reschedule改期
POST/api/v1/posts/{postId}/submit提交审批
POST/api/v1/posts/{postId}/cover-suggestions推荐封面
POST/api/v1/posts/{postId}/cover设为封面

对外发布 — 真正外发的两个端点:确认发布与发布 / 重投。

方法路径说明
POST/api/v1/posts/{postId}/confirm确认发布
POST/api/v1/posts/{postId}/publish发布 / 重投

媒体 — 把图片 / 视频交给 popkit,换取可发布的媒体 URL。

方法路径说明
POST/api/v1/media上传素材

评论互动 — 评论收件箱与以账号名义回复。

方法路径说明
GET/api/v1/comments评论收件箱
POST/api/v1/comments/{commentId}/replies回复评论

选题库 — 规划页看板的分组与选题。

方法路径说明
GET/api/v1/ideas选题列表
POST/api/v1/ideas新建选题
PATCH/api/v1/ideas/{ideaId}修改选题

数据 — 与站内分析页同口径的指标概览。

方法路径说明
GET/api/v1/analytics/summary数据概览

响应信封

成功
{
  "data": {
    "…": "…"
  },
  "meta": {
    "requestId": "3f9c1e2a-7d4b-4c1e-9a6f-0b2d8e5c7a11"
  }
}
失败
{
  "error": {
    "code": "forbidden",
    "message": "credential lacks scope posts:write",
    "params": {
      "scope": "posts:write"
    }
  },
  "meta": {
    "requestId": "3f9c1e2a-7d4b-4c1e-9a6f-0b2d8e5c7a12"
  }
}
字段类型说明
dataobject成功时的数据主体,形状随端点而异。
error.codestring机器错误码,按它分支处理;完整表见 错误码。
error.messagestring | null英文自纠提示,给开发者 / 模型看,不是界面文案。
error.paramsobject | null机器可读的补充参数,如 { limit, used }、{ scope }。
meta.requestIdstring本次请求 id(也在 X-Request-Id 响应头里),排障时带上。
meta.replayedboolean?true 表示这是同一个 Idempotency-Key 的缓存结果。

与 MCP Server 的关系

REST 与 MCP 是同一个能力核心的两个门面:20 个端点与 20 个 MCP 工具一一对应,入参 schema 逐字节相同,限流与幂等缓存也按凭证共享(用 REST 调了 5 次发布,MCP 这边同一凭证的发布额度也少 5 次)。无人值守的脚本 / 自动化平台用 REST,有人在场的 AI 助手用 MCP(它支持 OAuth 授权与两步确认)。

MCP 接入文档