# Publishing

> Create, schedule, queue and publish posts to every network with one call, then track each account's result, retry, edit or unpublish.

A **post** is what you write once. Every account it targets gets a **posting** (`sp_…`) that tracks that network's status, ID, URL and error. A post to Instagram, LinkedIn and X has three postings. The status of the post is the roll-up of its postings.

| Toolset | Endpoints |
|---|---|
| `posts` | [Posts](/docs/api-reference/posts/): create, schedule, retry, edit, unpublish, approvals, notes, postings |
| `queues` | [Queues](/docs/api-reference/queues/): recurring time slots per profile |
| `media` | [Media](/docs/api-reference/media/): uploads, URLs, folders, usage |
| `templates` | [Templates](/docs/api-reference/templates/): reusable content |
| `tools` | [Tools](/docs/api-reference/tools/): validation before you publish |

## Create a post

`POST /v1/posts` creates a draft, schedules it, puts it in a queue or publishes it now. Pick the targets with `account_ids`, a whole `profile_id` or an account `group_id` (both filtered by `platforms`), or `targets` for per-account overrides.

```bash
curl -X POST https://api.socialit.com/v1/posts \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: launch-2026-10-20" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "We just shipped Focus mode.",
    "account_ids": ["sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "sa_7Hc2Lm9Qw4Rt6Yp1Xn3Vb8Kd5Sz"],
    "media_ids": ["med_9Lq2Vx7Bn4Mc1Zr8Tw3Ys6Hd0Kp"],
    "scheduled_at": "2026-10-20T09:00:00",
    "timezone": "Europe/Prague"
  }'
```

| You send | Result |
|---|---|
| `draft: true` (or no schedule field) | Saved as a `draft` |
| `publish_now: true`, or `scheduled_at` in the past | Published right away (`publishing` in the 201 response) |
| `scheduled_at` (+ `timezone`) | Scheduled. Without an offset, the time is wall clock in `timezone` |
| `queue: true` or `queue_id` | The next free slot of that queue (or the profile's default queue) |

Precedence is `draft` > `publish_now` > `queue` > `scheduled_at`. Publishing is asynchronous: poll `GET /v1/posts/{id}` or listen for webhooks. Posts are unlimited on every plan; the per-account daily cap of your plan answers `429 posts_per_day_limit`.

Turn an existing draft into a scheduled post with `POST /v1/posts/{id}/schedule` (`scheduled_at`, `publish_now`, `queue` or `queue_id`), and stop a scheduled one with `POST /v1/posts/{id}/cancel`.

## Lifecycle

| Post status | Meaning |
|---|---|
| `draft` | Not scheduled |
| `pending_approval` | Waiting for an approver (workspace approvals on) |
| `scheduled` | Waiting for its time |
| `publishing` | At least one posting is still running |
| `published` | Every posting published |
| `partially_published` | Some postings published, others failed |
| `failed` | No posting published |
| `cancelled` | Cancelled, or every published posting was unpublished |

Postings are `pending`, `processing` (accepted by the network, final ID not known yet: Instagram and Threads containers, TikTok, Reddit media), `published`, `failed` or `cancelled`. A failed posting has `error`, `error_code` and an `error_category` such as `auth_expired`, `user_content`, `platform_rate_limit` or `quota_exhausted`. Temporary network errors are retried automatically; fix the cause of permanent ones and call `POST /v1/posts/{id}/retry` (optionally with `account_ids`).

## Per-network options

`content` and the media apply to every target. Network-only settings go in `platform_options`, keyed by platform, and are validated against each network's schema. `GET /v1/posts/platform-options` returns every schema.

```json
{
  "content": "Focus mode walkthrough",
  "account_ids": ["sa_youtube…", "sa_instagram…", "sa_x…"],
  "media_ids": ["med_video…"],
  "first_comment": "Full changelog in the replies",
  "platform_options": {
    "youtube": { "title": "Focus mode walkthrough", "privacyStatus": "public", "selfDeclaredMadeForKids": false },
    "instagram": { "shareToFeed": true },
    "x": { "replySettings": "following" }
  },
  "targets": [{ "account_id": "sa_x…", "content": "Focus mode is live. Thread below." }]
}
```

- Keys can be camelCase (as in the schemas) or snake_case. Unknown options are dropped with a `warnings` entry, or rejected with `422` when you send `strict: true`.
- `thread_items` continues the post as a thread on X, Threads, Bluesky and Mastodon.
- `quote_post_id`, `quote_url` and `reply_to_url` publish as a quote or a reply.
- `recycle` re-posts evergreen content on an interval, with optional `content_variations`.

Each [network guide](/docs/networks/) lists the post types, limits and options. Some networks require an explicit choice (TikTok privacy level, YouTube made-for-kids) and have no defaults on purpose.

## Media

Upload once, reuse the ID everywhere:

1. `POST /v1/media/presign` with `filename` and `content_type` returns an `upload_url`.
2. `PUT` the file to `upload_url` with the same `Content-Type` (no auth header).
3. Call `POST /v1/media/{id}/complete`, or just reference the media in a post.

`POST /v1/media` registers a public URL instead, and `media_urls` on a post does the same inline. Videos get a thumbnail and preview; `GET /v1/media/usage` reports storage against your plan.

## Validate first

- `POST /v1/tools/validate/post` checks a draft against every target (length, media, options) and returns `errors` and `warnings` per account.
- `POST /v1/tools/validate/post-length` counts characters the way each network does.
- `POST /v1/tools/validate/media` checks a file against each network's limits.

`POST /v1/posts` runs the same checks and answers `422 validation_failed` with `errors` keyed by field, such as `platform_options.x.replySettings` or `media_ids[1]`.

## After publishing

| Goal | Endpoint |
|---|---|
| Edit the live post (where the network allows it) | `POST /v1/posts/{id}/edit` |
| Change YouTube video metadata | `POST /v1/posts/{id}/update-metadata` |
| Delete it on the networks | `POST /v1/posts/{id}/unpublish` |
| Delete it in Socialit (optionally on networks too) | `DELETE /v1/posts/{id}?delete_on_network=true` |
| Duplicate it as a draft | `POST /v1/posts/{id}/duplicate` |

Networks without edit or delete answer `422 edit_not_supported` or `422 unpublish_not_supported`.

## Queues, approvals and bulk upload

- **Queues** have weekly slots (`day_of_week`, `time`) in their timezone. `GET /v1/queues/next-slot` and `GET /v1/queues/preview` show where the next posts would land.
- **Approvals:** with `require_approval` on (`PATCH /v1/publishing/settings`), posts by members and profile-restricted keys go to `pending_approval`. Approvers call `POST /v1/posts/{id}/approve` or `/reject`. Internal notes live under `/v1/posts/{id}/notes`.
- **Bulk upload:** `POST /v1/posts/bulk-upload` takes a CSV (up to 5,000 rows); add `?dry_run=true` to validate only.

## Webhooks

`post.scheduled`, `post.publishing`, `post.published`, `post.partially_published`, `post.failed`, `post.cancelled`, `post.edited`, `post.unpublished`, `post.deleted`, `post.recycled`, the approval events and `posting.published` / `posting.failed` per account. See [Webhook events](/docs/api-reference/webhook-events/).

---

Source: https://socialit.com/docs/publishing/
