Clawpost

Setup

Required environment variable:

• CLAW_API_KEY — your API key (starts with claw_). Generate one following the steps above.

Optional:

• CLAW_API_URL — defaults to https://clawpost.dev. Only set this if using a self-hosted instance.

All endpoints are under {{CLAW_API_URL}}/api/claw/v1/ (default: https://clawpost.dev/api/claw/v1/).

Authentication

Every request needs the header:

Authorization: Bearer {{CLAW_API_KEY}}

Important: Passing JSON in shell commands

When sending JSON data with curl, always use a heredoc to avoid shell escaping issues with quotes and special characters:

curl -s -X POST URL \
  -H "Authorization: Bearer {{CLAW_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{"key": "value"}
EOF

All examples below use this pattern. Do not use -d '{...}' with single quotes — it breaks when content contains quotes, newlines, or special characters.

Response Format

All responses follow this shape:

{
  "success": true,
  "message": "Human-readable summary",
  "data": { ... },
  "error": { "code": "ERROR_CODE", "details": "..." }
}

Always read the message field — it's designed to be relayed directly to the user.

Endpoints

Check Status

Verify your API key works and see what's connected.

curl -s {{CLAW_API_URL}}/api/claw/v1/status \
  -H "Authorization: Bearer {{CLAW_API_KEY}}"

List Connected Platforms

curl -s {{CLAW_API_URL}}/api/claw/v1/platforms \
  -H "Authorization: Bearer {{CLAW_API_KEY}}"

Check Credits

curl -s {{CLAW_API_URL}}/api/claw/v1/credits \
  -H "Authorization: Bearer {{CLAW_API_KEY}}"

List Posts

Filter by status (draft, published, scheduled, failed) and platform (linkedin, twitter).

curl -s "{{CLAW_API_URL}}/api/claw/v1/posts?status=draft&platform=linkedin&limit=10" \
  -H "Authorization: Bearer {{CLAW_API_KEY}}"

X Post History

Retrieve your X (Twitter) post history from the cached profile data. This is a read-only endpoint - no credits are used.

Query parameters:

• type - posts, replies, or all (default: all)
• limit - max results, 1-100 (default: 20)
• period - 7d, 30d, 90d, or all (default: all)

curl -s "{{CLAW_API_URL}}/api/claw/v1/history/x?type=posts&period=30d&limit=10" \
  -H "Authorization: Bearer {{CLAW_API_KEY}}"

The response includes a summary object with aggregated metrics (totalPosts, totalReplies, totalLikes, totalRetweets, totalRepliesReceived, totalImpressions, topPost) and a posts array with individual tweet details, metrics, media, and reply context.

Get Single Post

curl -s {{CLAW_API_URL}}/api/claw/v1/posts/POST_ID \
  -H "Authorization: Bearer {{CLAW_API_KEY}}"

Each post includes an availableActions array (e.g., ["publish", "schedule", "update", "delete"]).

Post Object Fields

Every post includes a postType field:

• "original" — a regular post composed by the user
• "quote" — a quote tweet of another post (X only)
• "reply" — a reply to another post (X only)
• "remix" — an original tweet inspired by another post (X only)

When postType is "quote", "reply", or "remix", the post also includes a reference object with the original tweet's context:

{
  "postType": "quote",
  "content": "User's commentary text",
  "reference": {
    "tweetId": "1234567890",
    "text": "The original tweet text that was quoted",
    "author": "originalAuthor"
  }
}

This lets you see exactly what was quoted/replied to alongside the user's own text.

Create a Draft

curl -s -X POST {{CLAW_API_URL}}/api/claw/v1/drafts \
  -H "Authorization: Bearer {{CLAW_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{"content": "Your post text here", "platform": "linkedin"}
EOF

Platform: "linkedin" or "twitter". Twitter content must be ≤ 280 characters.

Update a Draft

curl -s -X PUT {{CLAW_API_URL}}/api/claw/v1/posts/POST_ID \
  -H "Authorization: Bearer {{CLAW_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{"content": "Updated post text"}
EOF

Delete a Draft

curl -s -X DELETE {{CLAW_API_URL}}/api/claw/v1/posts/POST_ID \
  -H "Authorization: Bearer {{CLAW_API_KEY}}"

Publish a Draft

curl -s -X POST {{CLAW_API_URL}}/api/claw/v1/posts/POST_ID/publish \
  -H "Authorization: Bearer {{CLAW_API_KEY}}"

Direct Publish (No Draft Step)

curl -s -X POST {{CLAW_API_URL}}/api/claw/v1/publish \
  -H "Authorization: Bearer {{CLAW_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{"content": "Publishing this directly!", "platform": "linkedin"}
EOF

Schedule a Draft

curl -s -X POST {{CLAW_API_URL}}/api/claw/v1/posts/POST_ID/schedule \
  -H "Authorization: Bearer {{CLAW_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{"scheduledAt": "2026-06-15T10:00:00Z"}
EOF

Direct Schedule (No Draft Step)

curl -s -X POST {{CLAW_API_URL}}/api/claw/v1/schedule \
  -H "Authorization: Bearer {{CLAW_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{"content": "Scheduled post!", "platform": "linkedin", "scheduledAt": "2026-06-15T10:00:00Z"}
EOF

AI Generate Post

Let AI write a post based on your prompt. Optional: tone and platform.

curl -s -X POST {{CLAW_API_URL}}/api/claw/v1/ai/generate \
  -H "Authorization: Bearer {{CLAW_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{"prompt": "Write about the importance of code reviews", "platform": "linkedin"}
EOF

AI Refine Post

Improve existing content with instructions.

curl -s -X POST {{CLAW_API_URL}}/api/claw/v1/ai/refine \
  -H "Authorization: Bearer {{CLAW_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{"content": "Original post text...", "instructions": "Make it shorter and punchier", "platform": "linkedin"}
EOF

Workflow Tips

1. Quick publish: Use /publish to post immediately without creating a draft.
2. Review flow: Create a draft with /drafts, refine with /ai/refine, then publish with /posts/ID/publish.
3. Cross-post: Make separate calls for LinkedIn and Twitter — each is a separate post.
4. Check before publishing: Call /platforms to verify the target platform is connected.
5. Twitter limit: Tweets must be ≤ 280 characters. The API will reject longer content with a clear message.

Error Codes