API 参考

即将推出 — 公开 REST API 目前在我们的路线图中，尚未正式开放。以下文档描述的是计划中的 API 设计。我们将在 更新日志 中公布上线时间。

PostClaw REST API 将让您以编程方式管理帖子、平台、自动化和 AI 生成。

基础 URL： https://app.postclaw.fun/v1

认证

所有请求均需要 Bearer Token。在 设置 → API 密钥 中生成 API 密钥。

curl https://app.postclaw.fun/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY"

密钥按权限范围划分：read（读取）、write（写入）或 admin（管理员）。请使用最小所需权限。

速率限制

每条响应都会返回速率限制响应头：

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1743484800

端点

帖子

# 列出帖子
GET /v1/posts?status=scheduled&limit=20

# 创建帖子
POST /v1/posts
{
  "content": "Your caption here",
  "platforms": ["twitter", "linkedin"],
  "scheduled_at": "2026-04-01T09:00:00Z",
  "media_ids": ["media_abc123"]
}

# 获取帖子
GET /v1/posts/{id}

# 取消已排期的帖子
DELETE /v1/posts/{id}

媒体

# 上传媒体文件
POST /v1/media
Content-Type: multipart/form-data
# 返回：{ "id": "media_abc123", "url": "...", "type": "image" }

# 列出媒体库
GET /v1/media?type=image&limit=50

平台

# 列出已连接的账号
GET /v1/platforms

# 断开账号连接
DELETE /v1/platforms/{id}

AI 生成

# 生成帖子文案
POST /v1/ai/text
{
  "prompt": "Announce our new feature: dark mode",
  "platform": "twitter",
  "tone": "casual"
}

# 生成图片
POST /v1/ai/image
{
  "prompt": "Clean minimal desk setup, natural light",
  "size": "1024x1024"
}

自动化

# 列出自动化任务
GET /v1/automations

# 手动触发自动化
POST /v1/automations/{id}/trigger
{ "input": "https://example.com/article" }

Webhooks

注册 URL 以接收事件推送：

POST /v1/webhooks
{
  "url": "https://yoursite.com/postclaw-events",
  "events": ["post.published", "post.failed", "automation.completed"]
}

事件载荷结构：

{
  "event": "post.published",
  "timestamp": "2026-04-01T09:00:05Z",
  "data": {
    "post_id": "post_xyz789",
    "platform": "twitter",
    "url": "https://twitter.com/user/status/..."
  }
}

错误响应

所有错误遵循统一格式：

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 60 seconds.",
    "retry_after": 60
  }
}

常见错误代码：unauthorized、forbidden、not_found、validation_error、rate_limit_exceeded、platform_error。

SDK

官方 SDK 正在开发中。目前请使用任意 HTTP 客户端。API 的完整文档位于 app.postclaw.fun/docs（可下载 OpenAPI 3.1 规范）。