Guide
Publishing
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.
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.
{
"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
warningsentry, or rejected with422when you sendstrict: true. thread_itemscontinues the post as a thread on X, Threads, Bluesky and Mastodon.quote_post_id,quote_urlandreply_to_urlpublish as a quote or a reply.recyclere-posts evergreen content on an interval, with optionalcontent_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:
POST /v1/media/presignwithfilenameandcontent_typereturns anupload_url.PUTthe file toupload_urlwith the sameContent-Type(no auth header).- 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/postchecks a draft against every target (length, media, options) and returnserrorsandwarningsper account.POST /v1/tools/validate/post-lengthcounts characters the way each network does.POST /v1/tools/validate/mediachecks 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-slotandGET /v1/queues/previewshow where the next posts would land. - Approvals: with
require_approvalon (PATCH /v1/publishing/settings), posts by members and profile-restricted keys go topending_approval. Approvers callPOST /v1/posts/{id}/approveor/reject. Internal notes live under/v1/posts/{id}/notes. - Bulk upload:
POST /v1/posts/bulk-uploadtakes a CSV (up to 5,000 rows); add?dry_run=trueto 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.