Tài Liệu API

REST API của PostClaw cho phép quản lý bài đăng, nền tảng, automation và tạo AI theo chương trình.

Base URL: https://api.postclaw.fun/v1

Xác Thực

Tất cả request cần Bearer token. Tạo API key tại Cài đặt → API Keys.

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

Key có phạm vi: read, write, hoặc admin. Dùng phạm vi tối thiểu cần thiết.

Giới Hạn Tốc Độ

Gói	Request/phút
Free	30
Pro	120
Business	600

Header giới hạn tốc độ trả về trong mỗi response:

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

Endpoints

Bài Đăng

# Danh sách bài đăng
GET /v1/posts?status=scheduled&limit=20

# Tạo bài đăng
POST /v1/posts
{
  "content": "Caption của bạn ở đây",
  "platforms": ["twitter", "linkedin"],
  "scheduled_at": "2026-04-01T09:00:00Z",
  "media_ids": ["media_abc123"]
}

# Lấy bài đăng
GET /v1/posts/{id}

# Hủy bài đăng đã lên lịch
DELETE /v1/posts/{id}

Media

# Tải media
POST /v1/media
Content-Type: multipart/form-data
# Trả về: { "id": "media_abc123", "url": "...", "type": "image" }

# Danh sách thư viện media
GET /v1/media?type=image&limit=50

Nền Tảng

# Danh sách tài khoản đã kết nối
GET /v1/platforms

# Ngắt kết nối tài khoản
DELETE /v1/platforms/{id}

Tạo AI

# Tạo văn bản bài đăng
POST /v1/ai/text
{
  "prompt": "Thông báo tính năng mới: dark mode",
  "platform": "twitter",
  "tone": "casual"
}

# Tạo hình ảnh
POST /v1/ai/image
{
  "prompt": "Bàn làm việc tối giản, ánh sáng tự nhiên",
  "size": "1024x1024"
}

Automation

# Danh sách automation
GET /v1/automations

# Kích hoạt automation thủ công
POST /v1/automations/{id}/trigger
{ "input": "https://example.com/bai-viet" }

Webhook

Đăng ký URL để nhận sự kiện:

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

Cấu trúc payload sự kiện:

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

Phản Hồi Lỗi

Tất cả lỗi theo cấu trúc nhất quán:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Quá nhiều request. Thử lại sau 60 giây.",
    "retry_after": 60
  }
}

Mã lỗi phổ biến: unauthorized, forbidden, not_found, validation_error, rate_limit_exceeded, platform_error.

SDK

SDK chính thức đang được phát triển. Hiện tại, dùng bất kỳ HTTP client nào. API được tài liệu đầy đủ tại api.postclaw.fun/docs (spec OpenAPI 3.1 có thể tải xuống).