Posts API

Create, list, update, and cancel posts you send through the API. This is the endpoint for bring-your-own tweet text and media, with optional auto-reply and auto-retweet — the same engines used in the XBeast app.

Post object

{
  "id": "10932",
  "account_id": "123456789",
  "status": "scheduled",
  "scheduled_at": "2026-08-25T16:00:00.000Z",
  "tweets": [
    { "text": "Hello from my CMS.", "media_url": "https://example.com/image.jpg" }
  ],
  "auto_reply": {
    "enabled": true,
    "max": 10,
    "like": false,
    "verified_only": false
  },
  "auto_retweet": { "enabled": true, "after_hours": 8 },
  "tweet_id": null,
  "url": null,
  "source": "api",
  "created_at": "2026-08-24T18:01:00.000Z"
}

Field	Type	Required	Description
Field	Type	Required	Description
`id`	string	—	XBeast post id.
`account_id`	string	—	Connected account id.
`status`	string	—	scheduled, posted, cancelled, error, or draft.
`scheduled_at`	string (ISO 8601)	—	When the tweet should go live (UTC).
`tweets`	array	—	Thread items. One item is a single tweet.
`tweets[].text`	string	see note	Tweet body. Required if media_url is omitted.
`tweets[].media_url`	string	see note	HTTPS image or video URL. Required if text is empty.
`auto_reply`	object	—	Auto-reply settings applied after publish.
`auto_retweet`	object	—	enabled and after_hours (1–24).
`tweet_id`	string \| null	—	Network post id after publish.
`url`	string \| null	—	Public post URL after publish.
`source`	string	—	Always api for posts created here.

Create a post

POST/api/v1/posts

Omit scheduled_at (or send null) to publish immediately. A future ISO 8601 datetime schedules the post. Past times are rejected.

Body

Field	Type	Required	Description
Field	Type	Required	Description
`account_id`	string	Yes	From GET /api/v1/accounts.
`tweets`	array	Yes	At least one { text, media_url? }.
`scheduled_at`	string \| null	No	Future ISO 8601. Omit or null to post now.
`auto_reply.enabled`	boolean	No	Reply to early comments (within 3 hours). Paid plans.
`auto_reply.max`	number	No	10, 20, 30, 40, or 50. Default 10.
`auto_reply.like`	boolean	No	Like the comment when replying.
`auto_reply.verified_only`	boolean	No	Only reply to verified accounts.
`auto_retweet.enabled`	boolean	No	Repost after after_hours. Undo happens automatically ~12 hours later.
`auto_retweet.after_hours`	integer	No	1–24. Default 8.

Schedule

curl -X POST "https://xbeast.io/api/v1/posts" \
  -H "Authorization: Bearer xb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "YOUR_ACCOUNT_ID",
    "tweets": [{ "text": "Shipping at noon.", "media_url": "https://example.com/img.jpg" }],
    "scheduled_at": "2026-08-25T16:00:00.000Z",
    "auto_reply": { "enabled": true, "max": 10, "like": false, "verified_only": false },
    "auto_retweet": { "enabled": true, "after_hours": 8 }
  }'

Post now

curl -X POST "https://xbeast.io/api/v1/posts" \
  -H "Authorization: Bearer xb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "YOUR_ACCOUNT_ID",
    "tweets": [{ "text": "Going out now." }]
  }'

Immediate posts return status: posted, tweet_id, and url when the network accepts them. The account must belong to you and have posting enabled. Publishing to X costs 1 credit per post (a thread counts as one). Posts with a URL cost 2 extra credits. Daily cap: 7 scheduled + posted tweets per account per day.

List posts

GET/api/v1/posts

Lists posts created via the API for the key owner.

Query

Field	Type	Required	Description
Field	Type	Required	Description
`status`	string	No	scheduled, posted, cancelled, error, or draft.
`account_id`	string	No	Filter by connected account.
`limit`	number	No	Default 50, max 100.

curl "https://xbeast.io/api/v1/posts?status=scheduled&limit=20" \
  -H "Authorization: Bearer xb_live_YOUR_KEY"

Response: { "posts": [ ...Post ] }

Get a post

GET/api/v1/posts/:id

curl "https://xbeast.io/api/v1/posts/10932" \
  -H "Authorization: Bearer xb_live_YOUR_KEY"

Update a post

PATCH/api/v1/posts/:id

Only unsent posts. You cannot update a posted or cancelled post. Changing scheduled_at or account_id re-checks the daily cap.

Body (all optional)

Field	Type	Required	Description
Field	Type	Required	Description
`account_id`	string	No	Move to another connected account.
`tweets`	array	No	Replace thread content.
`scheduled_at`	string	No	Must be a future datetime (cannot clear to post-now via PATCH).
`auto_reply`	object	No	Same shape as create.
`auto_retweet`	object	No	Same shape as create.

curl -X PATCH "https://xbeast.io/api/v1/posts/10932" \
  -H "Authorization: Bearer xb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-08-25T18:00:00.000Z" }'

Cancel or delete

DELETE/api/v1/posts/:id

Scheduled posts are cancelled (they stay in history as cancelled). Drafts are deleted. Posted posts cannot be deleted via the API.

curl -X DELETE "https://xbeast.io/api/v1/posts/10932" \
  -H "Authorization: Bearer xb_live_YOUR_KEY"

{ "message": "Post cancelled" }

Docs