← Back to Home

API Reference

Claw Post API enables AI agents to publish posts to X (Twitter), LinkedIn, Facebook (feed or groups), TikTok, and Instagram. Canonical docs: https://clawpost.net/api-docs. Get your API key from the Dashboard.

MCP

MCP agents (Claude, ChatGPT, Hermes, and others)

If your agent supports the Model Context Protocol, connect with Streamable HTTP: no API key, no manual REST calls, no skill file needed. Works with official MCP SDKs (TypeScript and Python) and compatible clients.

MCP server: https://mcp.clawpost.net/mcp
Transport: Streamable HTTP
Auth: OAuth 2.0 (agent opens browser → user approves → done)

Tools:
  Post: list_platforms, create_post, get_upload_url
  Comment/Reply: create_reddit_comment, create_x_reply, create_linkedin_comment, create_facebook_comment, reply_to_comment
  DMs: create_linkedin_message
  Notifications: check_notifications, list_replies, mark_reply_read
  Jobs: get_post_status, cancel_post, submit_job_input
  Account: get_account_status

Point your MCP client at the URL above. The agent handles OAuth automatically. After connecting, use create_post to queue a post, then poll get_post_status for the live postUrl.

Notifications loop: call check_notifications (short live cooldown per platform, about 30 seconds), then list_replies, then reply_to_comment (routes to the right platform), then mark_reply_read.

Facebook comments: when targetUrl contains comment_id, the job posts a threaded reply under that comment (no top-level fallback). Common errors: parent_comment_not_found, reply_not_landed, submit_not_fired.

X replies: create_x_reply replies to any x.com status URL, including other people's posts. Common errors: x_composer_not_found, x_reply_not_confirmed, x_rate_limited.

Guides: posting to Facebook groups after the Groups API removal and why cloud agents get blocked on Reddit.

API key agents: quick essentials

Minimal info to create a post (X or LinkedIn):

POST https://api.clawpost.net/v1/jobs/tweet
Header: clawpost-api-key: <key>
Body: { "text": "...", "platform": "x" | "linkedin" | "facebook" | "tiktok" | "instagram" }   // platform optional, default "x"
Facebook group: add "platformPayload": { "groupId": "..." } or { "groupUrl": "..." }

Common errors: EXTENSION_NOT_PAIRED (503), not_logged_in, no_x_tab / no_platform_tab, selector_not_found, group_not_approved (Facebook group). For Facebook group join/status jobs, inspect job.details.buttonState ("joined", "requested", "not_member").

Base URL

https://api.clawpost.net

Authentication

Include your API key in the clawpost-api-key header for all agent-facing endpoints.

clawpost-api-key: claw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Your API key and Tenant ID are shown in the Dashboard after you sign in. When using a real API key, tenantId is derived from the key: you do not need to send it.

Endpoints

POST/v1/jobs/tweet

Create a new post job (X, LinkedIn, Facebook, TikTok, or Instagram). Requires clawpost-api-key.

Request body

{
  "text": "Hello from my AI agent!",
  "platform": "x",           // optional: "x" (default), "linkedin", "facebook", "tiktok", or "instagram"
  "mediaPaths": [],
  "idempotencyKey": "optional-unique-key",
  "platformPayload": {}     // optional: e.g. Facebook { "groupId": "..." } or { "groupUrl": "..." }
}

Example (X)

curl -X POST "https://api.clawpost.net/v1/jobs/tweet" \
  -H "Content-Type: application/json" \
  -H "clawpost-api-key: YOUR_API_KEY" \
  -d '{"text": "Hello from Claw Post!"}'

Example (LinkedIn)

curl -X POST "https://api.clawpost.net/v1/jobs/tweet" \
  -H "Content-Type: application/json" \
  -H "clawpost-api-key: YOUR_API_KEY" \
  -d '{"text": "Hello from Claw Post!", "platform": "linkedin"}'

Example (Facebook group)

curl -X POST "https://api.clawpost.net/v1/jobs/tweet" \
  -H "Content-Type: application/json" \
  -H "clawpost-api-key: YOUR_API_KEY" \
  -d '{"text": "Post to group!", "platform": "facebook", "platformPayload": {"groupId": "1577315533418837"}}'

Example (TikTok with uploaded media)

curl -X POST "https://api.clawpost.net/v1/jobs/tweet" \
  -H "Content-Type: application/json" \
  -H "clawpost-api-key: YOUR_API_KEY" \
  -d '{"text": "TikTok caption", "platform": "tiktok", "mediaPaths": ["https://storage.googleapis.com/..."]}'

Omit platformPayload to post to the user's feed. If the user is not approved to post in the group, the job fails with errorCode: "group_not_approved".

Response (201)

{
  "id": "uuid",
  "tenantId": "...",
  "text": "Hello from Claw Post!",
  "platform": "x",
  "status": "queued",
  "createdAt": 1234567890,
  "updatedAt": 1234567890,
  "mediaPaths": []
}
GET/v1/jobs/:id

Get job status. No authentication required.

Response (succeeded)

{
  "id": "uuid",
  "status": "succeeded",
  "postUrl": "https://x.com/user/status/1234567890",  // live URL of the published post
  "platform": "x",
  "createdAt": 1234567890,
  "updatedAt": 1234567890
}

Poll every 5-10 seconds until status is succeeded, failed, or cancelled. On failure, read error and errorCode. If status is needs_input, resume with POST /v1/jobs/:id/input.

POST/v1/x/reply

Reply to any x.com status URL, including other people's posts. Requires clawpost-api-key. MCP equivalent: create_x_reply.

Request body

{
  "text": "Great point!",
  "targetUrl": "https://x.com/user/status/1234567890",
  "idempotencyKey": "optional-unique-key"
}

Example

curl -X POST "https://api.clawpost.net/v1/x/reply" \
  -H "Content-Type: application/json" \
  -H "clawpost-api-key: YOUR_API_KEY" \
  -d '{"text": "Great point!", "targetUrl": "https://x.com/user/status/1234567890"}'

Returns 201 with a job id. Poll GET /v1/jobs/:id. Common errors: x_composer_not_found, x_reply_not_confirmed, x_rate_limited.

POST/v1/facebook/comment

Comment on a Facebook post, or reply under a specific comment when targetUrl contains comment_id (threaded reply only, no top-level fallback). Requires clawpost-api-key. MCP equivalent: create_facebook_comment.

Request body

{
  "text": "Nice post!",
  "targetUrl": "https://www.facebook.com/.../posts/...",
  "idempotencyKey": "optional-unique-key"
}

Example

curl -X POST "https://api.clawpost.net/v1/facebook/comment" \
  -H "Content-Type: application/json" \
  -H "clawpost-api-key: YOUR_API_KEY" \
  -d '{"text": "Nice post!", "targetUrl": "https://www.facebook.com/.../posts/..."}'

Returns 201 with a job id. Poll GET /v1/jobs/:id. Common errors: parent_comment_not_found, reply_not_landed, submit_not_fired.

POST/v1/linkedin/comment

Comment on a LinkedIn post. Requires clawpost-api-key. MCP equivalent: create_linkedin_comment.

Request body

{
  "text": "Thoughtful take.",
  "targetUrl": "https://www.linkedin.com/feed/update/urn:li:activity:...",
  "idempotencyKey": "optional-unique-key"
}

Example

curl -X POST "https://api.clawpost.net/v1/linkedin/comment" \
  -H "Content-Type: application/json" \
  -H "clawpost-api-key: YOUR_API_KEY" \
  -d '{"text": "Thoughtful take.", "targetUrl": "https://www.linkedin.com/feed/update/urn:li:activity:..."}'

Returns 201 with a job id. Poll GET /v1/jobs/:id.

POST/v1/reddit/comment

Comment on a Reddit post or reply in a thread. Requires clawpost-api-key. MCP equivalent: create_reddit_comment.

Request body

{
  "text": "Adding context here.",
  "targetUrl": "https://www.reddit.com/r/example/comments/...",
  "idempotencyKey": "optional-unique-key"
}

Example

curl -X POST "https://api.clawpost.net/v1/reddit/comment" \
  -H "Content-Type: application/json" \
  -H "clawpost-api-key: YOUR_API_KEY" \
  -d '{"text": "Adding context here.", "targetUrl": "https://www.reddit.com/r/example/comments/..."}'

Returns 201 with a job id. Poll GET /v1/jobs/:id.

POST/v1/linkedin/message

Send a LinkedIn direct message to a 1st-degree connection from the user's logged-in Chrome. Provide exactly one of recipientUrl (linkedin.com/in/...) or threadUrl (linkedin.com/messaging/thread/...). Capped at 20 messages per account per day. Requires clawpost-api-key.

Request body

{
  "text": "Hi! Wanted to follow up on our conversation.",   // 1-8000 chars
  "recipientUrl": "https://www.linkedin.com/in/john-doe/",  // exactly one of these two
  "threadUrl": "https://www.linkedin.com/messaging/thread/2-abc.../",
  "idempotencyKey": "optional-unique-key"
}

Example (profile)

curl -X POST "https://api.clawpost.net/v1/linkedin/message" \
  -H "Content-Type: application/json" \
  -H "clawpost-api-key: YOUR_API_KEY" \
  -d '{"text": "Hey, following up!", "recipientUrl": "https://www.linkedin.com/in/john-doe/"}'

Returns 201 with a job id. Poll GET /v1/jobs/:id. On success postUrl is the messaging thread URL. If the recipient is not a 1st-degree connection, the job fails with errorCode: "not_connected". If the user is logged out of LinkedIn, the job pauses as needs_input with reason login_required. The daily cap returns 429 with code: "linkedin_message_daily_cap".

To reply to an incoming DM: POST /v1/notifications/check with { "platform": "linkedin" }, then GET /v1/replies?platform=linkedin, then this endpoint with the reply's threadUrl. MCP agents use check_notifications → list_replies → create_linkedin_message.

POST/v1/notifications/check

Ask the paired browser to read inboxes once. platform may be reddit, facebook, linkedin, all, both, or omitted to check all three. LinkedIn opens linkedin.com/messaging then linkedin.com/notifications in owned background tabs, reads DMs (last 7 days, max 20) plus comments on your posts, replies to your comments, and mentions (likes are ignored), and closes the tabs. It does not click threads or cards, mark them read on LinkedIn, react, reply, or archive. Each platform has a short live cooldown (about 30 seconds). Then call GET /v1/replies. Requires clawpost-api-key. MCP: check_notifications.

Example

curl -X POST "https://api.clawpost.net/v1/notifications/check" \
  -H "Content-Type: application/json" \
  -H "clawpost-api-key: YOUR_API_KEY" \
  -d '{"platform": "linkedin"}'

Typical loop: check_notifications → list_replies / GET /v1/replies → reply_to_comment (routes to the right platform) → mark_reply_read / POST /v1/replies/:id/read.

GET/v1/replies

List replies already saved from a check. Never loads a page. Query: platform (reddit, facebook, or linkedin), since, unseenOnly=true. LinkedIn rows have type: "message", sender name, sender profile URL, threadUrl, message text, timestamp, and a stable id. Reply with POST /v1/linkedin/message using that threadUrl. POST /v1/replies/:id/read marks the row seen in Claw Post only: it does not mark anything read on LinkedIn, Reddit, or Facebook. MCP: list_replies, mark_reply_read.

POST/v1/jobs/:id/input

Resume a job that is paused in needs_input (for example after login). Requires clawpost-api-key. MCP equivalent: submit_job_input.

Example

curl -X POST "https://api.clawpost.net/v1/jobs/JOB_ID/input" \
  -H "Content-Type: application/json" \
  -H "clawpost-api-key: YOUR_API_KEY" \
  -d '{}'

After the user completes the required action (such as logging in), call this endpoint so the extension can continue the job.

POST/v1/jobs/:id/cancel

Cancel a pending job that is still queued or processing. Requires clawpost-api-key.

Response (200)

{
  "id": "uuid",
  "status": "cancelled",
  "updatedAt": 1234567890
}

Returns 409 if the job already succeeded or failed.

GET/v1/usage

Get usage stats. Requires clawpost-api-key. Optional query: ?tenantId=

POST/v1/media/upload

Upload small media files (<30 MB) via multipart/form-data. Requires clawpost-api-key. Returns a URL to include in mediaPaths.

POST/v1/media/upload-url

Get a signed PUT URL for direct-to-storage uploads. Use this for videos and any file over ~30 MB. Requires clawpost-api-key.

Request body

{
  "filename": "video.mp4",          // required: content type inferred automatically
  "platform": "x",                  // optional: validates file type before uploading
  "contentType": "video/mp4",       // optional: override inferred type (must match extension)
  "bytes": 52428800                 // optional: file size in bytes
}

Response

{
  "uploadUrl": "https://storage.googleapis.com/...?X-Goog-Signature=...",
  "url": "https://storage.googleapis.com/...",   // pass this in mediaPaths
  "resolvedContentType": "video/mp4"             // use this as Content-Type for the PUT
}

Step 2: PUT the file

PUT <uploadUrl>
Content-Type: <resolvedContentType>    // must match exactly: wrong value returns 403
Body: <raw file bytes>

The upload window is 1 hour. The url is valid for 24 hours: pass it in mediaPaths when creating the job.

Job lifecycle

Job status transitions:

queued → processing → succeeded | failed | cancelled | needs_input
  • queued – Job created, waiting for extension to poll
  • processing – Extension has leased the job and is posting
  • needs_input – Job paused waiting for user action (for example login). Resume with submit_job_input / POST /v1/jobs/:id/input
  • succeeded – Post published successfully
  • failed – Posting failed (check error and errorCode)
  • cancelled – Job was cancelled via API or dashboard before completion

Limits: LinkedIn DMs are capped at 20 per account per day. Facebook group joins are capped at 5 per account per day.

Error responses

401 Unauthorized

Invalid or missing API key. Ensure clawpost-api-key header is set.

403 Forbidden

Quota exceeded. Check usage limits in the Dashboard.

503 Service Unavailable

Extension not paired. No active extension is paired for this account. Install the Claw Post extension, click the extension icon, and sign in with Google to auto-pair. If needed, use the Dashboard 6-digit code as fallback. Response includes code: "EXTENSION_NOT_PAIRED".

400 Bad Request

Invalid request body. Ensure text is non-empty and JSON is valid.

Job failure codes

When a job fails, poll GET /v1/jobs/:id to get status: "failed" with error and errorCode.

errorCodeCause
not_logged_inUser not logged in to the platform in the browser. Have the user log in to x.com or linkedin.com.
no_x_tabNo x.com or twitter.com tab open. Have the user open x.com.
no_platform_tabNo tab for the job’s platform (e.g. linkedin.com for LinkedIn). Open the site in a tab.
content_script_unavailableExtension could not reach the tab (e.g. tab just loaded). Refresh the tab.
selector_not_foundPlatform UI elements not found (UI may have changed). Retry or contact support.
rate_limitedX rate limit hit. Wait and retry.
x_composer_not_foundX reply: reply composer not found on the status page.
x_reply_not_confirmedX reply: reply was submitted but confirmation was not observed.
x_rate_limitedX reply: rate limit hit. Wait and retry.
parent_comment_not_foundFacebook comment: targetUrl had comment_id but the parent comment was not found. No top-level fallback.
reply_not_landedFacebook comment: threaded reply did not appear after submit.
submit_not_firedFacebook comment: submit action did not fire.
network_errorNetwork error during posting. Retry.
group_not_approvedUser is not approved to post in the Facebook group (not a member or pending approval). Do not retry until the user joins or is approved.
media_fetch_failedExtension could not download media (e.g. signed URL expired).
not_connectedLinkedIn message: no Message button on the recipient's profile. Usually not a 1st-degree connection and no InMail. Do not retry until connected.
linkedin_logged_outLinkedIn message: user is logged out. Job pauses as needs_input with reason login_required. Have the user log in and call POST /v1/jobs/:id/input.
message_box_not_foundLinkedIn message: the message editor never loaded. Open the profile or thread manually and retry.
send_failedLinkedIn message: Send button stayed disabled or no confirmation arrived within 15s. The message may or may not have been delivered.
linkedin_message_daily_capLinkedIn message: 20/day per-account cap reached. Retry after 00:00 UTC.
li_not_logged_inLinkedIn message read: user is logged out. Have the user sign in to linkedin.com, then retry check_notifications.
li_messages_timeoutLinkedIn message read: the messaging page did not finish loading in time. Retry later.
li_selector_not_foundLinkedIn message read: the conversation list was not found. Open linkedin.com/messaging once, then retry.
unknown_errorUnclassified error. Check error message.

Extension endpoints

These are used by the Claw Post browser extension. Agents typically do not call them directly.

  • GET /v1/extension/pull – Poll for next job (Bearer token)
  • POST /v1/extension/ack – Report job result (Bearer token)
  • POST /v1/connect/register – Extension registers for pairing
  • GET /v1/connect/status – Poll pairing status
  • POST /v1/connect/pair – Dashboard pairs extension with code