Freepost 开发者文档
通过 Freepost 的 REST API、MCP 和 Agent 技能管理草稿,并发布到已连接的社媒账号。
概览
使用 REST 查询托管账号、上传媒体、校验和管理草稿、立即发布或排期,以及查询投递状态。
交互式客户端可通过 OAuth 连接远程 MCP,本地客户端可使用 API 密钥连接 stdio MCP。Freepost 技能提供完整操作流程和各平台的写作指引。
身份验证
工作区所有者可在「设置 → API 密钥」创建密钥。REST 请求需发送 Authorization: Bearer <工作区 API 密钥>。为每个集成单独创建密钥,并按需授予权限和账号访问。
支持 OAuth 的 MCP 客户端会打开 Freepost 登录和授权页面。选择工作区、可访问的账号和需要授予的权限。可在「设置 → 已连接应用」撤销授权。
| 权限 | 允许的操作 |
|---|---|
posts:read | 读取工作区内容和发布投递记录。 |
posts:write | 校验、创建、编辑和删除草稿。 |
publish:write | 立即发布草稿。 |
accounts:read | 查询已授权账号、平台规则和工作区用量。 |
media:read | 列出媒体并读取媒体文件。 |
media:write | 上传或导入媒体。 |
schedules:write | 为草稿排期,或取消尚未发送的排期。 |
webhooks:manage | 使用未限制账号的工作区密钥管理 Webhook 并查看投递日志。 |
analytics:read | 在弃用期内通过旧版数据分析工具读取工作区摘要。 |
REST 快速入门
先在 Freepost 连接社媒账号,并在终端设置 FREEPOST_API_KEY。以下示例要求目标账号支持纯文本发布。发布前请查询平台规则、上传所需媒体,并校验草稿。
列出账号,再把目标账号的 ID 设为 ACCOUNT_ID。
FREEPOST_API_URL=https://freepost.io curl --fail-with-body -sS "$FREEPOST_API_URL/api/v1/accounts" \ -H "Authorization: Bearer $FREEPOST_API_KEY"创建草稿。每份新草稿使用新的 DRAFT_KEY,将返回的 data.id 保存为 POST_ID。
curl --fail-with-body -sS "$FREEPOST_API_URL/api/v1/posts" \ -H "Authorization: Bearer $FREEPOST_API_KEY" \ -H 'Content-Type: application/json' \ -H "Idempotency-Key: $DRAFT_KEY" \ -d '{"content":"Hello from Freepost","targetAccounts":["'"$ACCOUNT_ID"'"]}'使用新的 PUBLISH_KEY 发布。重试同一次操作时,沿用原来的密钥和请求。用同一个密钥发送变更后的请求会返回 409。
curl --fail-with-body -sS -X POST "$FREEPOST_API_URL/api/v1/posts/$POST_ID/publish" \ -H "Authorization: Bearer $FREEPOST_API_KEY" \ -H "Idempotency-Key: $PUBLISH_KEY"如果结果为 pending,将 data.deliveryId 设为 DELIVERY_ID 后轮询投递状态。也可以从草稿目标的 latestPublicationId 找回投递 ID。
curl --fail-with-body -sS "$FREEPOST_API_URL/api/v1/publications/$DELIVERY_ID" \ -H "Authorization: Bearer $FREEPOST_API_KEY"
配置 MCP
基于 Streamable HTTP 的远程 MCP
在 MCP 客户端添加以下远程服务器地址,然后登录并授权。程序化集成也可通过工作区 API 密钥访问此地址。
https://freepost.io/api/mcp本地 stdio MCP
使用 Node.js 22 或更新版本,从 Freepost 源码构建命令行程序。将示例路径替换为本机的绝对路径。
pnpm --filter @freepost/mcp buildClaude Desktop 和 Cursor 的 JSON 配置
{
"mcpServers": {
"freepost": {
"command": "node",
"args": [
"/absolute/path/to/freepost/packages/mcp/dist/server.js"
],
"env": {
"FREEPOST_API_URL": "https://freepost.io",
"FREEPOST_API_KEY": "YOUR_WORKSPACE_API_KEY"
}
}
}
}Codex 的 config.toml 配置
请在启动 Codex 的环境中设置 FREEPOST_API_KEY。
[mcp_servers.freepost]
command = "node"
args = ["/absolute/path/to/freepost/packages/mcp/dist/server.js"]
env_vars = ["FREEPOST_API_KEY"]
[mcp_servers.freepost.env]
FREEPOST_API_URL = "https://freepost.io"接口列表
| 操作 | 方法 | 路径 | 权限 | 风险级别 | 幂等键 |
|---|---|---|---|---|---|
accounts.list | GET | /api/v1/accounts | accounts:read | read | 无需 |
usage.get | GET | /api/v1/usage | accounts:read | read | 无需 |
platforms.rules | GET | /api/v1/platforms/rules | accounts:read | read | 无需 |
posts.get | GET | /api/v1/posts/{id} | posts:read | read | 无需 |
publications.get | GET | /api/v1/publications/{id} | posts:read | read | 无需 |
media.upload | POST | /api/v1/media | media:write | draft | 无需 |
posts.validate | POST | /api/v1/posts/validate | posts:write | draft | 无需 |
posts.create | POST | /api/v1/posts | posts:write | draft | 必填* |
posts.update | PATCH | /api/v1/posts/{id} | posts:write | draft | 无需 |
posts.delete | DELETE | /api/v1/posts/{id} | posts:write | draft | 无需 |
posts.publish | POST | /api/v1/posts/{id}/publish | publish:write | external | 必填* |
posts.schedule | POST | /api/v1/posts/{id}/schedule | schedules:write | external | 必填 |
schedules.cancel | POST | /api/v1/schedules/{id}/cancel | schedules:write | external | 无需 |
* 新集成必须提供。旧版 REST 客户端仍可发送不带幂等键的请求。
OpenAPI JSON发布结果
| 结果 | 客户端操作 |
|---|---|
succeeded | 平台已确认发布。若响应提供了平台内容 ID 或链接,即可使用。 |
pending | Freepost 已接收投递。使用投递 ID 轮询,或等待 Webhook。 |
failed | 查看 code 和 message。只有 retryable 为 true 时才重试,并按 retryAfter(秒)等待。 |
unknown | 先到目标账号核对实际结果,再回 Freepost 确认投递。结果未知时请勿重新发送。 |
发布节奏与请求限流
每个账号都有已配置的最短发布间隔和单日上限。通过 platforms.rules 查询限制,通过 accounts.list 查询 postsLeftToday 和 nextAllowedPublishAt。凭证也可设置跨账号单日上限,单日计数在 UTC 午夜重置。
默认每分钟允许 120 次读取、30 次写入、5 次发布类请求及 10 次高消耗请求。REST 和 stdio 共用工作区限流计数,远程 MCP 按验证后的凭证计数。REST 触发限流时可能返回 Retry-After 和 X-RateLimit-* 响应头。
所有套餐都包含 Agent 接入。读取和校验不消耗套餐额度。创建草稿与产品界面共享工作区的单日创建额度。免费套餐每月有 20 次外部发布额度,在每月第一天的 UTC 午夜重置。已发送的投递即使结果未知也计入用量。付费套餐没有外部发布月度上限。
调用 GET /api/v1/usage 或 MCP 的 usage_get,查询工作区本月用量、是否执行上限、重置时间和当日剩余内容创建额度。
Webhook
在「设置 → Webhook」订阅事件,也可用 webhooks:manage 权限调用 /api/v1/webhooks。Freepost 会重试失败的投递。解析 JSON 前,请用原始请求字节验证签名。
可订阅事件
publication.succeededpublication.failedpublication.unknownpublication.resolvedschedule.dispatchedaccount.needs_reauth
Node.js 签名验证示例
import { createHmac, timingSafeEqual } from "node:crypto";
export async function verifyFreepostWebhook(request, secret) {
const body = Buffer.from(await request.arrayBuffer());
const signature = request.headers.get("Freepost-Signature") ?? "";
const match = /^t=(0|[1-9][0-9]{0,15}),v1=([a-f0-9]{64})$/.exec(signature);
if (!secret || !match || match[0] !== signature) return null;
const sentAt = Number(match[1]);
const now = Math.floor(Date.now() / 1000);
if (!Number.isSafeInteger(sentAt) || Math.abs(now - sentAt) > 300) return null;
const expected = createHmac("sha256", secret)
.update(match[1] + ".")
.update(body)
.digest();
if (!timingSafeEqual(expected, Buffer.from(match[2], "hex"))) return null;
return JSON.parse(body.toString("utf8"));
}签名无效时返回 401。通过持久化存储按事件 ID 去重,处理成功后返回 HTTP 2xx。Freepost-Delivery 是 Webhook 投递 ID,Freepost-Event 是事件类型。手动重投会沿用事件 ID。
错误处理
REST 错误包含 error.code 和 error.message,可能附有 error.details。发布响应也可在 data 中返回投递失败结果。
| HTTP 状态码 | 原因与下一步 |
|---|---|
400 | 修正无效的请求参数,或补上必填的幂等键。 |
401 | 提供有效的 API 密钥,或重新连接远程 MCP 客户端。 |
402 | EXTERNAL_PUBLISH_LIMIT_REACHED。升级工作区套餐,或等到下一个 UTC 月。 |
403 | 检查所需权限、工作区角色和套餐限制。 |
404 | 此凭证无法读取该资源。请核对 ID 以及工作区或账号权限。 |
409 | 幂等键已用于其他请求,或资源当前状态与此操作冲突。 |
410 | 资源或旧版 RPC 已停用。若操作已有投递记录,可继续查询现有投递。 |
422 | 修正请求。草稿校验问题可能出现在 error.details.problems 中。 |
429 | 按 Retry-After 或返回的发布节奏间隔等待。 |
503 | 服务暂时不可用。带幂等键的操作应沿用原请求和幂等键重试。 |
更新日志
提供 REST v1、远程 MCP、stdio MCP、Agent 技能、带签名的 Webhook 以及外部发布用量查询。
POST /api/v1/mcp/{tool} 自 2026 年 11 月 20 日起弃用,并从 2027 年 1 月 19 日 00:00 UTC 起返回 410。请迁移到远程 MCP、stdio MCP 的标准工具或 REST v1。旧版响应提供 Deprecation、Sunset 和 Link 响应头。
配置 stdio MCP