# Posts API

> Schedule tweets, post immediately, enable auto-reply and auto-retweet, then list, update, or cancel posts.

Source: https://xbeast.io/docs/api-posts

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

```json
{
  "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 |
| --- | --- | --- | --- |
| 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 |
| --- | --- | --- | --- |
| 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 | 5–50 in steps of 5. Default 5. |
| 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**

```bash
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**

```bash
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 8 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 |
| --- | --- | --- | --- |
| status | string | No | scheduled, posted, cancelled, error, or draft. |
| account_id | string | No | Filter by connected account. |
| limit | number | No | Default 50, max 100. |

```bash
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`**

```bash
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 |
| --- | --- | --- | --- |
| 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. |

```bash
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.

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

```json
{ "message": "Post cancelled" }
```

## Related

- [Upload media](https://xbeast.io/docs/api-media.md)
- [List accounts](https://xbeast.io/docs/api-accounts.md)
- [Error codes](https://xbeast.io/docs/api-errors.md)
- [Create an API key](https://xbeast.io/developers)