Skip to content
X-Buddy
Tiếng Việt

API reference

Publish a post now

post_publish — Publish a post or thread (up to 25 parts, each up to 4 media from media_create_upload) on one account now, through X's composer.

Markdown version

post_publish · Write on X (creates a job)

Publish a post or thread (up to 25 parts, each up to 4 media from media_create_upload) on one account now, through X's composer. The duplicate-text guard applies. Counts against Post. Use post_compose to schedule or post on many accounts.
REST POST /api/public/v1/accounts/{account}/actions/post
MCP tool post_publish
Permission needed posts.manage — Owner, Manager, Operator
Scope group x:publish
Group Actions on X
Shown up front in profiles Operate X accounts

Input

Field Type Required Description
account string (1–100 chars) Yes The X account to use: its X-Buddy account_id (from account_list) or its @handle. Ambiguous names return candidates instead of guessing.
parts array of object (1–25 items) Yes The post, then thread replies.
pin boolean No Pin the first part to the profile after posting.

Result

Creates a job for the X account's VPS. REST waits up to wait seconds (default 15, max 20): when done it returns 200 with the result, otherwise 202 with Location: /api/public/v1/jobs/{job_id}. The final status is succeeded, failed, cancelled or unknown.

Needs an idempotency key (Idempotency-Key, 8–128 characters). Retrying with the same key never repeats the action.

This deletes data or can't be undone. Ask the person before calling it.

A job that ends unknown may already have happened on X: never resend it with a new idempotency key.

Example

Call over REST

curl -X POST "https://reach-link-craft.lovable.app/api/public/v1/accounts/%40your_x_account/actions/post" \
  -H "Authorization: Bearer $XBUDDY_API_KEY" \
  -H "Idempotency-Key: 6f1c2a90-example-key" \
  -H "Content-Type: application/json" \
  -d '{"parts":[{"text":"Hello from X-Buddy"}]}'

Call over MCP

{
  "method": "tools/call",
  "params": {
    "name": "post_publish",
    "arguments": {
      "account": "@your_x_account",
      "parts": [
        {
          "text": "Hello from X-Buddy"
        }
      ],
      "idempotency_key": "6f1c2a90-example-key"
    }
  }
}

Errors you may get

Code HTTP Retryable
unauthorized 401 No
key_expired 401 No
integration_revoked 401 No
connection_not_linked 403 No
integration_paused 403 No
workspace_integrations_paused 403 No
integration_authorization_lost 403 No
workspace_suspended 403 No
forbidden 403 No
invalid_input 422 No
rate_limited 429 Yes
internal 500 Yes
read_only 403 No
idempotency_key_required 428 No
idempotency_conflict 409 No
idempotency_processing 409 Yes
conflict 409 No
precondition_failed 422 No
ambiguous_account 409 No
account_not_allowed 403 No
not_found 404 No
agent_too_old 422 No
unsupported_by_account 422 No

Back to all operations