> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autoposting.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Posts

> Schedule once, publish everywhere — create text, image, and video posts across all platforms simultaneously with per-platform customization.

Posts are the core publishing unit. Write once, target multiple platforms, and Autoposting handles per-platform delivery, retries, and status tracking independently — so a failure on one platform never blocks another.

## Status Lifecycle

| Status | Description |
| - | - |
| `draft` | Saved, not queued for publishing |
| `scheduled` | Queued with a future `scheduledAt` datetime |
| `validating` | Token health, media, and platform constraints being checked |
| `validated` | All checks passed; handed to platform adapters |
| `publishing` | Platform publish jobs running |
| `published` | All targeted platforms reported success |
| `partial` | At least one platform succeeded, at least one failed |
| `failed` | All targeted platforms failed |
| `billing_hold` | Paused — subscription suspended |
| `render_pending` | Waiting for a clip render to complete |
| `archived` | Excluded from all publishing and analytics |

## Create and Schedule a Post

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://app.autoposting.ai/api-proxy/posts \
    -H "Authorization: Bearer sk_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "brandSlug": "brand_slug",
      "text": "Excited to share our latest update!",
      "platforms": ["x", "linkedin"],
      "scheduledAt": "2025-06-15T14:00:00Z"
    }'
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch("https://app.autoposting.ai/api-proxy/posts", {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      brandSlug: "brand_slug",
      text: "Excited to share our latest update!",
      platforms: ["x", "linkedin"],
      scheduledAt: "2025-06-15T14:00:00Z",
    }),
  });
  const { data } = await res.json();
  ```
</CodeGroup>

Omit `scheduledAt` to save a draft. Publish explicitly with `POST /posts/:id/publish`, or schedule it with `PUT /posts/:id/schedule`.

For Facebook Pages formats, explicit Page selection, per-Page outcomes and recovery, see [Facebook Pages beta](/concepts/facebook-pages).

## Platform Options

<Tabs>
  <Tab title="X (Twitter)">
    Publish threads by passing the `thread` array — each item becomes a chained reply.

    ```json theme={null}
    {
      "text": "1/ Here's everything we shipped this quarter.",
      "thread": ["2/ First: faster scheduling.", "3/ Second: AI rewrite."],
      "platforms": ["x"]
    }
    ```

    Supports polls via a `poll` object with `options` (2–4 strings) and `durationMinutes`.
  </Tab>

  <Tab title="LinkedIn">
    Up to 20 images per carousel post. Character limit: 3,000 (personal) or 700 (org pages).

    ```json theme={null}
    { "text": "Proud to announce...", "platforms": ["linkedin"] }
    ```
  </Tab>

  <Tab title="Instagram">
    | Option | Description |
    | - | - |
    | `thumbOffsetMs` | Thumbnail frame offset in milliseconds |
    | `shareToFeed` | Share Reel to feed as well |
    | `coverUrl` | Custom cover image URL |
    | `collaborators` | Up to 3 collaborator usernames |
  </Tab>

  <Tab title="Threads">
    | Option | Values | Description |
    | - | - | - |
    | `replyToId` | string | Reply to an existing Threads post |
    | `replyControl` | `everyone`, `accounts_you_follow`, `mentioned_only` | Who can reply |
  </Tab>

  <Tab title="YouTube">
    | Option | Max | Description |
    | - | - | - |
    | `title` | 100 chars | Required for YouTube posts |
    | `description` | 5,000 chars | Video description |
    | `privacyStatus` | — | `public`, `private`, or `unlisted` |
    | `tags` | — | Array of tag strings |
    | `madeForKids` | — | COPPA compliance flag |
  </Tab>
</Tabs>

## Scheduling

Pass an absolute ISO 8601 datetime in `scheduledAt`. Schedules are evaluated in the brand's configured timezone but stored in UTC.

<Note>
  A cron runs every minute to move `scheduled` posts whose `scheduledAt` has passed into `validating`. Expired tokens cause failure at validation — not at publish time.
</Note>

## Retry Failed Posts

When a post is `failed` or `partial`, retry only the failed platforms without recreating the post.

```bash theme={null}
curl -X POST https://app.autoposting.ai/api-proxy/posts/:id/retry \
  -H "Authorization: Bearer sk_your_api_key"
```

## AI Tools

**Rewrite** — adjust tone or improve quality without changing meaning:

```bash theme={null}
curl -X POST https://app.autoposting.ai/api-proxy/posts/:id/rewrite \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "tone": "professional", "platform": "linkedin" }'
```

**Score** — rate text for likely engagement. Returns `hook`, `retention`, `clarity`, `visual` (each 0–100) plus `viralityScore`.

## Media Attachments

Upload files via `POST /media/presign` to get a presigned URL, then reference the returned URL in your post's `media` array.

<Warning>
  Platform constraints differ: X allows up to 4 images or 1 video; Instagram Reels require video; YouTube requires exactly 1 video. Posts violating these constraints fail at `validating`.
</Warning>

<CardGroup cols={2}>
  <Card title="Platforms" icon="link" href="/concepts/platforms">
    Character limits, media rules, and OAuth for each platform.
  </Card>

  <Card title="Brands" icon="building" href="/concepts/brands">
    Every post belongs to a brand with its own connected accounts.
  </Card>

  <Card title="Clips" icon="scissors" href="/concepts/clips">
    Publish rendered video clips directly as scheduled posts.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/concepts/webhooks">
    Get notified when posts publish, fail, or change status.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.