API Reference

Coming Soon — The public REST API is currently on our roadmap and not yet available. The documentation below describes the planned API design. We’ll announce availability on our changelog.

The PostClaw REST API will let you manage posts, platforms, automations, and AI generation programmatically.

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

Authentication

All requests require a Bearer token. Generate API keys under Settings → API Keys.

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

Keys are scoped: read, write, or admin. Use the minimum scope needed.

Rate Limits

Rate limit headers are returned on every response:

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

Endpoints

Posts

# List posts
GET /v1/posts?status=scheduled&limit=20

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

# Get a post
GET /v1/posts/{id}

# Cancel a scheduled post
DELETE /v1/posts/{id}

Media

# Upload media
POST /v1/media
Content-Type: multipart/form-data
# Returns: { "id": "media_abc123", "url": "...", "type": "image" }

# List media library
GET /v1/media?type=image&limit=50

Platforms

# List connected accounts
GET /v1/platforms

# Disconnect an account
DELETE /v1/platforms/{id}

AI Generation

# Generate post text
POST /v1/ai/text
{
  "prompt": "Announce our new feature: dark mode",
  "platform": "twitter",
  "tone": "casual"
}

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

Automations

# List automations
GET /v1/automations

# Trigger automation manually
POST /v1/automations/{id}/trigger
{ "input": "https://example.com/article" }

Webhooks

Register a URL to receive events:

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

Event payload structure:

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

Error Responses

All errors follow a consistent shape:

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

Common error codes: unauthorized, forbidden, not_found, validation_error, rate_limit_exceeded, platform_error.

SDKs

Official SDKs are in progress. For now, use any HTTP client. The API is fully documented at app.postclaw.fun/docs (OpenAPI 3.1 spec available for download).