# XBeast documentation

> XBeast is a Twitter/X automation platform. This file contains the full XBeast documentation (guides and Public API reference) in one place.

Human-readable pages: https://xbeast.io/docs

## Contents

- [How to Automate Tweets with XBeast](https://xbeast.io/docs/automate-tweets.md): Learn how to set up automated tweet generation and scheduling using presets and the schedule feature.
- [How to Use the XBeast Queue System](https://xbeast.io/docs/queue-system.md): Prepare your own tweets and drop them into pre-scheduled time slots without picking dates manually.
- [XBeast Public API v1](https://xbeast.io/docs/api.md): Schedule and publish your own tweets through XBeast — with auto-reply and auto-retweet — using a simple REST API.
- [API Authentication](https://xbeast.io/docs/api-authentication.md): Create API keys and authenticate requests with a Bearer token.
- [API Errors](https://xbeast.io/docs/api-errors.md): HTTP status codes and error payload format returned by the XBeast Public API.
- [Accounts API](https://xbeast.io/docs/api-accounts.md): List X, LinkedIn, Bluesky, and Threads accounts connected to your XBeast workspace.
- [Credits API](https://xbeast.io/docs/api-credits.md): Check remaining XBeast credits for the current billing month.
- [Media API](https://xbeast.io/docs/api-media.md): Upload images and videos to attach when scheduling posts.
- [Posts API](https://xbeast.io/docs/api-posts.md): Schedule tweets, post immediately, enable auto-reply and auto-retweet, then list, update, or cancel posts.

---

# How to Automate Tweets with XBeast

> Learn how to set up automated tweet generation and scheduling using presets and the schedule feature.

Source: https://xbeast.io/docs/automate-tweets

XBeast makes it easy to automate your Twitter presence by generating and scheduling tweets automatically. Follow these simple steps to set up automated tweet generation using presets and scheduling.

## Step 1: Create a Preset

Start by creating a preset that defines the style and content type for your automated tweets.

1. **Go to Presets:** Navigate to https://xbeast.io/presets
2. **Click "New Preset":** This will open the preset creation dialog
3. **Select the "Good Morning" template:** This will create a new preset configured for morning tweets. You can customize it later if needed.

## Step 2: Schedule Your Preset

Once you have a preset, schedule it to automatically generate tweets for the week ahead.

1. **Go to Schedule:** Navigate to https://xbeast.io/schedule#schedule
2. **Click "Schedule Content":** This opens the scheduling interface
3. **Select your preset:** Choose the preset you created in Step 1 (or the "Good Morning" preset if you used the template)
4. **Select the days:** Choose which days of the week you want XBeast to generate tweets for. XBeast will automatically create posts for the week ahead based on your selections.

## Step 3: Review Generated Posts

After scheduling, XBeast will generate posts according to your preset. Review them before they go live.

1. **Go to Upcoming Posts:** Navigate to https://xbeast.io/schedule#upcoming
2. **Review the generated posts:** You'll see all the posts that XBeast has generated for the upcoming week. You can edit, delete, or approve them as needed.

### Next Steps

Once you've set up your first automated preset, you can:

- Create additional presets for different types of content (evening posts, threads, etc.)
- Customize your presets to match your unique voice and style
- Schedule multiple presets across different days for a diverse content mix
- Review and refine your automated posts regularly to ensure quality

[Go to Presets](https://xbeast.io/presets)

[Go to Schedule](https://xbeast.io/schedule)

---

# How to Use the XBeast Queue System

> Prepare your own tweets and drop them into pre-scheduled time slots without picking dates manually.

Source: https://xbeast.io/docs/queue-system

The Queue system lets you prepare tweets in advance and ship them into pre-defined time slots — without manually picking dates and times each time. It's ideal when you write your own content but want a consistent posting rhythm.

## What is the Queue?

Queue slots are recurring time windows on your weekly schedule. When you're ready to post, click **Queue** on any draft or generated post and XBeast assigns it to the next open slot automatically.

**Presets vs Queues:** Presets fully automate your tweets — XBeast generates and schedules them for you. Queues let you prepare tweets in advance and ship them when you're ready.

## Prerequisites

- **Premium plan** — queuing posts requires XBeast Premium
- **Connected X account** — link at least one account in your dashboard
- **Posting enabled** — turn on posting for your account on the Dashboard; otherwise queued posts are pushed forward instead of publishing
- **Queue slots configured** — at least one queue slot on your Schedule tab

## Step 1: Create Queue Slots

Queue slots are pre-scheduled time slots that let you quickly add posts without manually setting dates and times — just click "Queue" when you're ready to post.

1. **Go to Schedule:** Navigate to https://xbeast.io/schedule#schedule
2. **Open the Schedule tab** and click **"Schedule Content"**
3. **Select Source → Queue** (not Preset)
4. **Choose days and a time range** — e.g. Monday–Friday, 9:00 AM–11:00 AM. XBeast picks a random time within that window for each queued post.
5. **Optional:** Configure auto retweet, auto reply, auto plug, or community settings for posts in this slot
6. **Click "Add To Schedule"** — your queue slot appears in the weekly schedule with a Queue tag

## Step 2: Prepare Posts

Write or generate the tweets you want to queue. Prepared posts live in Drafts until you queue or schedule them.

1. **Drafts:** Go to https://xbeast.io/drafts and click **New Post** to write a tweet manually
2. **Generate:** Use https://xbeast.io/generate to create AI-generated content, then save it as a draft

## Step 3: Queue a Post

1. Open a draft or generated post and click the **Queue** button
2. In the popover, select the X account you want to post from
3. Click **Queue** — XBeast assigns the post to the next available queue slot
4. The button shows **Queued** once the post is scheduled for that account

## Step 4: Review Upcoming Posts

Review everything before it goes live on the Upcoming tab.

1. **Go to Upcoming:** Navigate to https://xbeast.io/schedule#upcoming
2. **Review queued posts** — edit content, cancel, or use Tweet Now if needed
3. **Empty slots** show as "Queue Slot" placeholders with a link to Drafts — queue a post and it will show up there

## Queue vs Schedule

Use **Queue** for your recurring workflow when you have queue slots set up. Use **Schedule** when you need a specific one-off date and time.

|  | Queue | Schedule |
| --- | --- | --- |
| Time picking | Automatic — next available queue slot | Manual — pick exact date and time |
| Requires queue slots | Yes | No |
| Content source | Your own prepared posts | Any post you choose |
| Premium required | Yes | Yes |

## Tips & Limits

- One post per queue slot per day — add more slots if you want more daily posts
- Maximum of 7 tweets per X account per day (all scheduled and sent posts combined)
- Publishing to X costs 1 credit per post (a thread counts as one). Posts with a URL cost 8 extra credits
- Queue slots look ahead up to 30 days when finding the next open slot
- Queued posts inherit auto retweet, auto reply, auto plug, and community settings from their queue slot

## Troubleshooting

- **"No queue slots found"** — add a queue slot on the Schedule tab first
- **"No available queue slots found in the next 30 days"** — all slots are full; add more slots or wait for posts to publish
- **"Upgrade to XBeast premium to queue posts"** — queuing requires a Premium plan
- **Posts not publishing** — check that posting is enabled on your Dashboard for that account

[Go to Schedule](https://xbeast.io/schedule)

[Go to Drafts](https://xbeast.io/drafts)

[Upgrade to Premium](https://xbeast.io/premium)

---

# XBeast Public API v1

> Schedule and publish your own tweets through XBeast — with auto-reply and auto-retweet — using a simple REST API.

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

The XBeast Public API lets you **schedule and publish your own tweets** through a connected X (Twitter) account — including auto-reply and auto-retweet. You do not need XBeast AI generation. Bring text and media from your CMS, bot, or script.

> **Premium required**
>
> API keys and all /api/v1 endpoints are available on paid XBeast plans only.

## Base URL

```text
https://xbeast.io/api/v1
```

## What you can do

- [Schedule a tweet](https://xbeast.io/docs/api-posts.md) for a specific time, or post immediately
- Turn on auto-reply and auto-retweet for that post
- [Upload images or video](https://xbeast.io/docs/api-media.md) (or pass an HTTPS media URL)
- [List connected accounts](https://xbeast.io/docs/api-accounts.md) and [check remaining credits](https://xbeast.io/docs/api-credits.md)

## Quick start

1. Subscribe to a [**paid plan**](https://xbeast.io/premium).
2. Connect an X account from the [**dashboard**](https://xbeast.io/dashboard).
3. Create an API key on [**Developer API**](https://xbeast.io/developers). Copy it once.
4. Call `GET /api/v1/accounts` to get an `account_id`.
5. Call `POST /api/v1/posts` with your tweet, `scheduled_at`, and optional auto-reply / auto-retweet.

### Example: schedule a tweet at noon with auto-reply

**POST /api/v1/posts**

```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": "Hello from my own content pipeline." }],
    "scheduled_at": "2026-08-25T16:00:00.000Z",
    "auto_reply": { "enabled": true, "max": 10 },
    "auto_retweet": { "enabled": true, "after_hours": 8 }
  }'
```

## Endpoints

- [Authentication](https://xbeast.io/docs/api-authentication.md) — Bearer API keys
- [Errors](https://xbeast.io/docs/api-errors.md) — status codes and payload
- [GET /accounts](https://xbeast.io/docs/api-accounts.md)
- [GET /credits](https://xbeast.io/docs/api-credits.md)
- [POST /media](https://xbeast.io/docs/api-media.md)
- [Posts](https://xbeast.io/docs/api-posts.md) — create, list, get, update, cancel

## Limits

- Up to 5 active API keys per user
- Publishing to X costs 1 credit per post, charged after a successful send. Posts that contain a URL cost 8 extra credits
- Up to 7 scheduled or posted tweets per connected account per day (account timezone)
- Scheduled posts are published by XBeast cron; they must fall in the posting window when due
- Auto-reply and auto-retweet require a paid plan (same as the app)

## FAQ

#### Do I need my own X developer account?

No. Connect your X account in XBeast. The API publishes through that connection.

#### Can I skip AI-generated posts?

Yes. This API is for bring-your-own content. Presets and AI generation stay in the XBeast app.

#### Where do I create a key?

In the app: [Developer API](https://xbeast.io/developers). The full secret is shown only once.

[Authentication](https://xbeast.io/docs/api-authentication.md)

---

# API Authentication

> Create API keys and authenticate requests with a Bearer token.

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

Every Public API request must include an API key in the `Authorization` header. Keys start with `xb_live_` and are hashed at rest. The full key is shown only when you create it.

> **Treat keys like passwords**
>
> Anyone with the key can schedule and publish as your connected accounts. Revoke leaked keys immediately.

## Create a key

1. Open https://xbeast.io/developers while logged in.
2. Use a paid XBeast plan (free accounts cannot create keys).
3. Name the key (for example Production) and click Create key.
4. Copy the secret. You will not see it again.

You can have up to 5 active keys. Revoke unused keys from the same page.

## Request header

```http
Authorization: Bearer xb_live_YOUR_KEY
```

**Example**

```bash
curl "https://xbeast.io/api/v1/credits" \
  -H "Authorization: Bearer xb_live_YOUR_KEY"
```

## Rules

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| Scheme | Bearer | Yes | Only Bearer tokens are accepted. Cookie session auth is not used on /api/v1. |
| Prefix | string | Yes | Keys must start with xb_live_. |
| Plan | paid | Yes | Free plans receive 403 forbidden even with a valid-looking header. |

## Failed auth

Missing, malformed, revoked, or unknown keys return `401` with `error.code: unauthorized`. See [Errors](https://xbeast.io/docs/api-errors.md).

[List accounts](https://xbeast.io/docs/api-accounts.md)

---

# API Errors

> HTTP status codes and error payload format returned by the XBeast Public API.

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

Errors use a consistent JSON body. Successful responses return the resource directly (or a wrapper like `{ "accounts": [...] }`).

## Error body

```json
{
  "error": {
    "code": "validation_error",
    "message": "scheduled_at must be in the future"
  }
}
```

## Codes

| HTTP | code | When |
| --- | --- | --- |
| 401 | unauthorized | Missing, invalid, or revoked API key. |
| 403 | forbidden | Free plan, posting disabled on the account, or updating/deleting a posted post. |
| 404 | not_found | Account or post does not exist (or is not yours / not API-created). |
| 422 | validation_error | Invalid JSON, past scheduled_at, bad media, or invalid auto-retweet hours. |
| 422 | rate_limit_exceeded | Daily post cap reached for that account (7 scheduled + posted posts that day). |
| 422 | insufficient_credits | Not enough credits to publish (1 per post, plus 8 if the post contains a URL). |
| 500 | post_failed | Publish-now succeeded locally but the social network did not return a post id. |
| 500 | internal_error | Unexpected server error. |

---

# Accounts API

> List X, LinkedIn, Bluesky, and Threads accounts connected to your XBeast workspace.

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

Returns social accounts connected to the API key owner. Use `id` as `account_id` when creating posts. Tokens are never included.

**`GET /api/v1/accounts`**

## Response

```json
{
  "accounts": [
    {
      "id": "123456789",
      "handle": "yourhandle",
      "platform": "x",
      "timezone": "America/New_York"
    }
  ]
}
```

#### Account object

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | — | Platform user id. Pass as account_id on posts. |
| handle | string | — | Username / handle. |
| platform | string | — | x, linkedin, bluesky, or threads. |
| timezone | string | — | IANA timezone used for the daily post limit. |

**curl**

```bash
curl "https://xbeast.io/api/v1/accounts" \
  -H "Authorization: Bearer xb_live_YOUR_KEY"
```

[Create a post](https://xbeast.io/docs/api-posts.md)

---

# Credits API

> Check remaining XBeast credits for the current billing month.

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

Returns the same monthly credit totals shown on the XBeast dashboard. Credits reset on the first of each month. Publishing a post to X costs 1 credit (plus 8 if it contains a URL), charged after a successful send.

**`GET /api/v1/credits`**

```json
{
  "credits_used": 120,
  "credits_available": 880,
  "credits_limit": 1000,
  "resets_at": "2026-09-01T00:00:00.000Z"
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| credits_used | number | — | Credits consumed this calendar month. |
| credits_available | number | — | Remaining credits (limit minus used, never below 0). |
| credits_limit | number | — | Plan monthly allowance. |
| resets_at | string (ISO 8601) | — | Start of next month (UTC), when usage counters reset. |

**curl**

```bash
curl "https://xbeast.io/api/v1/credits" \
  -H "Authorization: Bearer xb_live_YOUR_KEY"
```

---

# Media API

> Upload images and videos to attach when scheduling posts.

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

Upload an image or video to XBeast storage. Use the returned HTTPS `url` as `tweets[].media_url` when creating a post. You can also skip this endpoint and pass any public HTTPS media URL.

### Upload a file

**`POST /api/v1/media`**

Send `multipart/form-data` with a single field named `file`.

#### Limits

| Kind | Max size | Formats |
| --- | --- | --- |
| Image | 5 MB | PNG, JPEG, GIF, WebP |
| Video | 100 MB | MP4, MOV (QuickTime), WebM |

## Response (201)

```json
{
  "url": "https://....supabase.co/storage/v1/object/public/images/USER_ID/uuid.jpg",
  "type": "image"
}
```

`type` is `image` or `video`.

**curl**

```bash
curl -X POST "https://xbeast.io/api/v1/media" \
  -H "Authorization: Bearer xb_live_YOUR_KEY" \
  -F "file=@/path/to/image.jpg"
```

---

# 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)