popkitpopkitAPI
中EN
对外发布

发布 / 重投

对已存在的内容执行发布:审批通过(approved)的内容出站,或失败(failed)内容重试(可指定 accountId 只重投一个账号)。给 approved 内容传 scheduledAt 则改为定时发布(走排期档权限)。其它状态一律拒绝。

POST/api/v1/posts/{postId}/publish
publish:executeschedule:write发布档限流Idempotency-Key 必填

鉴权与护栏

  • 请求头 Authorization: Bearer <长期凭证>,凭证在设置页「接入外部系统 → 长期凭证」签发,见 鉴权与权限。
  • 凭证需带 scope publish:execute / schedule:write(任一即可调用;具体能用哪一档由凭证的发布落点白名单决定);签发者在工作区里的角色也要允许该动作。
  • 限流:发布档,每分钟 5 次(按凭证计),超出回 429 并带 Retry-After。
  • 幂等:必须带 Idempotency-Key(缺了回 400);同键重试原样回第一次结果并带 meta.replayed: true。

路径参数

postIdstring必填

内容 id。

请求体(application/json)

accountIdstring可选

只重投这一个账号(失败重试时用)。

scheduledAtdatetime (ISO 8601, with timezone)可选

给 approved 内容指定时间 = 改成定时发布。

clientRequestIdstring必填

幂等键(8–128 chars of [A-Za-z0-9_.:-]);推荐放在 Idempotency-Key 请求头,头与 body 都给时以头为准。

响应

成功返回 HTTP 200,信封为 { data, meta };右侧(窄屏在本页末尾)给出了各状态码的示例。所有错误都是 { error: { code, message, params }, meta },按机器码处理而不是按 message 匹配,码表见 错误码。

状态码可能的错误码
400invalid_input
401unauthenticated
402plan_limit
403forbidden / workspace_not_found
404not_found
409no_account / needs_reauth / replay
429rate_limited
500internal
502platform_error
503external_writes_off

示例

请求
curl -X POST "https://popkit.loxily.com/api/v1/posts/pst_01J8ZK3R7QW6M2/publish" \
  -H "Authorization: Bearer popkit_it_••••••••" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme-2026-09-21-001" \
  -d '{
  "accountId": "acc_01J8Y…"
}'
响应
已进入发布
{
  "data": {
    "postId": "pst_01J8ZK3R7QW6M2",
    "status": "publishing",
    "scheduledAt": null,
    "deepLink": "https://popkit.loxily.com/history?post=pst_01J8ZK3R7QW6M2"
  },
  "meta": {
    "requestId": "6a1d0c9e-2b7f-4e3a-8c5d-1f0e9b8a7c71"
  }
}
MCP 接入文档