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

# Posts

> Posts are the unit of publication in PublishBuddy. Each post targets one profile and moves through a well-defined lifecycle.

A **post** is a planned publication. It carries text, optional media, and per-network settings, targets exactly **one** profile, and moves through a predictable lifecycle from creation to publication.

If you need to publish the same content to several profiles, create one post per profile.

## Lifecycle

```text theme={null}
draft ──▶ needs_approval ──▶ waiting ──▶ publishing ──▶ published
                                              │
                                              └──▶ failed
```

| Status           | Meaning                                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| `draft`          | Created but not yet ready to publish. Sit in the dashboard until someone (or your code) updates them. |
| `needs_approval` | Submitted for review under your workspace's approval policy.                                          |
| `waiting`        | Scheduled or queued, waiting for its publish time.                                                    |
| `publishing`     | Currently being pushed to the social network.                                                         |
| `published`      | Successfully published. The `url` field now contains the live URL.                                    |
| `failed`         | Publication failed. `error_message` explains why.                                                     |

The response field `friendly_status` is the user-facing label (e.g. "Scheduled for Dec 25" instead of the raw `waiting`).

## Publish types

The `publish_type` field controls **when** a post goes live:

| `publish_type`                  | Behaviour                                                                                                  |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `now`                           | Publish as soon as the API accepts the request.                                                            |
| `schedule_using_fixed_datetime` | Publish at a specific UTC datetime. Set `publish_at` in ISO 8601.                                          |
| `queue_using_timeslots`         | Add the post to the profile's posting queue. It will pick the next free timeslot defined for that profile. |

The dashboard refers to these as **Post now**, **Schedule**, and **Add to queue** respectively.

### Queues and timeslots

Each profile has a configurable **queue** — a recurring weekly schedule of timeslots (e.g. "Tue 9am, Thu 2pm, Sat 11am"). Posts created with `publish_type: queue_using_timeslots` get assigned to the next available slot automatically. Slots are managed in the dashboard's queue editor.

## Media

Posts can carry one or more media files. Attach them by setting `media_content_ids` to an array of IDs from the [media library](/concepts/media-library).

Each network has its own rules:

* **X** — up to 4 images, or 1 video.
* **Instagram feed** — 1 image/video, or up to 10 in a carousel.
* **Instagram Reels** — exactly 1 video.
* **TikTok / YouTube Shorts** — exactly 1 video.
* **Facebook / LinkedIn** — varies by network.

The API validates these constraints when you create a post and returns a `422` with a descriptive message if the combination is invalid.

## Per-network parameters

The `PostResource` schema includes nullable fields for parameters specific to a single network. Only set them when targeting that network:

```jsonc theme={null}
{
  "profile_id": "...",
  "text": "...",
  "media_content_ids": [],
  "publish_type": "schedule_using_fixed_datetime",
  "publish_at": "2026-12-25T09:00:00Z",

  // TikTok-only
  "post_visibility": "Everyone",
  "commercial_content_type": "YourBrand",
  "interaction_ability": "AllowComment,Stitch,Duet",

  // YouTube-only
  "title": "My video title",
  "category": "22",
  "license": "youtube",
  "privacy_status": "public",

  // Pinterest-only
  "target_url": "https://example.com/landing-page",
  "social_profile_entity_id": "board_xxx...",

  // Instagram Reels (trial reels)
  "trial_params": { "graduation_strategy": "MANUAL" }
}
```

Refer to `POST /workspaces/{workspace}/posts` in the [API reference](/api-reference/introduction) for the canonical request shape.

## Reading a published post's URL

Once `status` becomes `published`, the `url` field contains the canonical URL on the social network. The related `social_post` object holds network-specific identifiers (e.g. Instagram media ID, X tweet ID) that you can use to fetch metrics or reply.

## Editing posts

You can update a post while it's still in `draft`, `needs_approval`, or `waiting`. Once it transitions to `publishing` or beyond, edits are rejected — at that point, the content is in the social network's hands.

Use `PUT /posts/{post}` to update, or `DELETE /posts/{post}` to cancel a scheduled post before it publishes.

## Comments and notes

Posts support two collaboration features:

* **Comments** — discussion threads visible inside the dashboard for the team to review content before it publishes. They are returned on `PostResource.comments`.
* **Notes** — short labels (think Post-it sticky notes) attached to a post. Returned on `PostResource.notes`.

Both are workspace-internal — they're never sent to the social network.

## Next

<CardGroup cols={2}>
  <Card title="Schedule posts" icon="calendar" href="/guides/schedule-posts">
    A walkthrough of all three publish types.
  </Card>

  <Card title="Media library" icon="folder" href="/concepts/media-library">
    Uploading and organising assets that posts can use.
  </Card>
</CardGroup>