List Posts

A post is a single piece of content fanned out to one or more connected social accounts. Each target produces a social posting carrying its own publish status.

The post object

{
  "id": "pst_2Xa9kQ1mB3cD4eF5gH6iJ7kL8m",
  "status": "scheduled",
  "content": "Big news today 🚀",
  "strict": false,
  "queue_id": null,
  "scheduled_at": "2026-06-26T15:00:00.000Z",
  "published_at": null,
  "error": null,
  "created_at": "2026-06-25T08:00:00.000Z",
  "updated_at": "2026-06-25T08:00:00.000Z"
}

status is one of draft, scheduled, publishing, published, or failed.

GET/v1/posts

Query parameters

Optional query filters: status, from (ISO), to (ISO), unscheduled (true/false), profile_id (only posts targeting accounts in that profile).

{
  "posts": [
    {
      "id": "pst_2Xa9kQ1mB3cD4eF5gH6iJ7kL8m",
      "status": "scheduled",
      "content": "Big news today 🚀",
      "strict": false,
      "queue_id": null,
      "scheduled_at": "2026-06-26T15:00:00.000Z",
      "published_at": null,
      "error": null,
      "created_at": "2026-06-25T08:00:00.000Z",
      "updated_at": "2026-06-25T08:00:00.000Z"
    }
  ]
}

Each post includes its targets (platform + per-target status) and attached media.

Create Post

POST/v1/posts

Body parameters

Field	Type	Notes
`content`	string	Required. 1–5000 chars.
`target_account_ids`	string[]	Required. Social account IDs (`sa_...`).
`media_ids`	string[]	Optional. Media IDs (`med_...`). Allowed with `quote_post_id` (Threads/Bluesky keep media; X/LinkedIn clamp media when quoting unless `strict`).
`quote_post_id`	string	Optional. Socialit post ID (`pst_...`) to quote. The source must already be published on a quote-capable network (X, Threads, LinkedIn, or Bluesky). Resolved per target platform at publish time.
`scheduled_at`	ISO date	Optional. Schedule for later.
`queue_id`	string	Optional. Assign the next open slot from a queue. Mutually exclusive with `scheduled_at`.
`publish`	boolean	Optional. Publish immediately (if no `scheduled_at`).
`strict`	boolean	Optional. Fail on media-constraint violations instead of clamping.
`config_by_platform`	object	Optional. Per-platform overrides.

Omit scheduled_at, queue_id, and publish to save a draft. Scheduling or publishing checks your credit balance and returns 402 if insufficient. Using queue_id returns 409 if the queue has no free upcoming slot.

Quote posts return 404 QuotePostNotFound if the source is missing, or 400 QuotePostNotPublished if it has no published quote-capable target.

POST /v1/posts

curl -X POST https://api.socialit.com/v1/posts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Big news today 🚀",
    "target_account_ids": ["sa_2Xa...", "sa_3Yb..."],
    "media_ids": ["med_2Xa..."],
    "scheduled_at": "2026-06-26T15:00:00.000Z"
  }'

{
  "post": {
    "id": "pst_2Xa9kQ1mB3cD4eF5gH6iJ7kL8m",
    "status": "scheduled",
    "content": "Big news today 🚀",
    "strict": false,
    "quote_post_id": null,
    "queue_id": null,
    "scheduled_at": "2026-06-26T15:00:00.000Z",
    "published_at": null,
    "error": null,
    "created_at": "2026-06-25T08:00:00.000Z",
    "updated_at": "2026-06-25T08:00:00.000Z"
  }
}

Get Post

GET/v1/posts/:id

Returns the post with its attached media, per-target targets (including external_url, status, and credits_charged), and credits_total.

{
  "post": {
    "id": "pst_2Xa9kQ1mB3cD4eF5gH6iJ7kL8m",
    "status": "scheduled",
    "content": "Big news today 🚀",
    "strict": false,
    "quote_post_id": null,
    "queue_id": null,
    "scheduled_at": "2026-06-26T15:00:00.000Z",
    "published_at": null,
    "error": null,
    "created_at": "2026-06-25T08:00:00.000Z",
    "updated_at": "2026-06-25T08:00:00.000Z"
  }
}

Update Post

PATCH/v1/posts/:id

Update content, media_ids, strict, or config_by_platform on a draft/scheduled post.

PATCH /v1/posts/:id

curl -X PATCH https://api.socialit.com/v1/posts/pst_2Xa... \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "content": "Updated copy" }'

{
  "post": {
    "id": "pst_2Xa9kQ1mB3cD4eF5gH6iJ7kL8m",
    "status": "scheduled",
    "content": "Big news today 🚀",
    "strict": false,
    "queue_id": null,
    "scheduled_at": "2026-06-26T15:00:00.000Z",
    "published_at": null,
    "error": null,
    "created_at": "2026-06-25T08:00:00.000Z",
    "updated_at": "2026-06-25T08:00:00.000Z"
  }
}

Retry Post

POST/v1/posts/:id/retry

Re-enqueues publish for every social posting on this post that is currently failed. Targets that already published are not sent again.

Use this after a full failure (status: failed) or a partial success (status: published with one or more failed targets). While a publish job is already running (status: publishing), the request returns 409 PublishInProgress. If no targets failed, it returns 400 NothingToRetry.

Failed targets are reset to pending, the post moves to scheduled, and a new publish job is queued immediately.

{
  "post": {
    "id": "pst_2Xa9kQ1mB3cD4eF5gH6iJ7kL8m",
    "status": "scheduled",
    "content": "Big news today",
    "strict": false,
    "quote_post_id": null,
    "queue_id": null,
    "scheduled_at": "2026-06-26T15:05:00.000Z",
    "published_at": null,
    "error": null,
    "created_at": "2026-06-25T08:00:00.000Z",
    "updated_at": "2026-06-26T15:05:00.000Z"
  }
}

{ "error": "NothingToRetry" }

{ "error": "PublishInProgress" }

Delete Post

DELETE/v1/posts/:id

{ "ok": true }