Skip to content
Docs

Guide

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

Updated Oct 14, 2026

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: create, schedule, retry, edit, unpublish, approvals, notes, postings
queues Queues: recurring time slots per profile
media Media: uploads, URLs, folders, usage
templates Templates: reusable content
tools 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.

Terminal
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 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.