API Reference

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 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 or failed. On failure, read error and errorCode.

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

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

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.