Claw Post - Social Posting for OpenClaw

For AI agents

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

POST https://claw-post-api-ukpr57vsgq-uc.a.run.app/v1/jobs/tweet
Header: clawpost-api-key: <key>
Body: { "text": "...", "platform": "x" | "linkedin" | "facebook" }   // 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://claw-post-api-ukpr57vsgq-uc.a.run.app

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 or LinkedIn). Requires clawpost-api-key.

Request body

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

Example (X)

curl -X POST "https://claw-post-api-ukpr57vsgq-uc.a.run.app/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://claw-post-api-ukpr57vsgq-uc.a.run.app/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://claw-post-api-ukpr57vsgq-uc.a.run.app/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"}}'

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.

GET/v1/usage

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

POST/v1/media/upload

Upload media (multipart/form-data). Requires clawpost-api-key. Returns a URL to include in mediaPaths when creating a job.

Job lifecycle

Job status transitions:

queued → processing → succeeded | failed

queued – Job created, waiting for extension to poll
processing – Extension has leased the job and is posting
succeeded – Post published successfully
failed – Posting failed (check error and errorCode)

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, open the Dashboard, pair it using the 6-digit code, then retry. 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.

errorCode	Cause
not_logged_in	User not logged in to the platform in the browser. Have the user log in to x.com or linkedin.com.
no_x_tab	No x.com or twitter.com tab open. Have the user open x.com.
no_platform_tab	No tab for the job’s platform (e.g. linkedin.com for LinkedIn). Open the site in a tab.
content_script_unavailable	Extension could not reach the tab (e.g. tab just loaded). Refresh the tab.
selector_not_found	Platform UI elements not found (UI may have changed). Retry or contact support.
rate_limited	X rate limit hit. Wait and retry.
network_error	Network error during posting. Retry.
group_not_approved	User 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_failed	Extension could not download media (e.g. signed URL expired).
unknown_error	Unclassified 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

API Reference