Posts overview - SocialAPI.AI

The Posts API is a content publishing API: one endpoint to publish and schedule photos, videos, carousels, stories, and reels across Instagram, Facebook, TikTok, LinkedIn, YouTube, Threads, and Zalo, with per-platform delivery status. Publishing uses a single endpoint, POST /v1/posts, with per-platform behavior controlled by the platform_data field. This page compares capabilities across all platforms at a glance. For full details on a specific platform, see the deep-dive pages linked below. Use POST /v1/posts/validate to check constraints before publishing, and GET /v1/posts/validate to fetch platform-specific constraints (e.g. TikTok’s per-creator privacy levels and duration limits).

Attaching media

Photos and videos are attached through the ordered media array. Each item sets a source_type: an uploaded library file (media_id), a public URL we fetch at publish time (url), or media you uploaded to the platform yourself (platform_attachment_id, supported on Instagram, Threads, LinkedIn, LinkedIn Page, and X/Twitter). The older flat media_ids array still works and is equivalent to a list of media_id sources. See the Media uploads guide for upload paths, URL rules, and storage limits.

Capability matrix

Capability	Instagram	Facebook	LinkedIn	Threads	TikTok	YouTube	X / Twitter	Google
Create post	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Update post	No	Yes (text only)	Yes (text only)	No	No	Yes	No	Yes (text only)
Delete post	No	Yes	Yes	Yes	No	Yes	Yes	Yes
Schedule	Yes	Yes	Yes	Yes	No	Native	No	Yes
First comment	Yes (best-effort)	Yes (best-effort)	No	No	No	Yes (best-effort)	No	No
Image	Yes	Yes	Yes	Yes	Yes (1-35)	Thumbnail	No	Yes (1)
Video	Yes (as Reel)	Yes	Yes	Yes	Yes	Yes	No	No
Carousel	Yes (2-10)	Yes (2-10)	Yes (2-20)	Yes (2-20)	Photo carousel only	No	No	No
Max media per post	10	10	20	20	35 (photo) / 1 (video)	1 (video + thumb)	0 (text only)	1

Retrieving a post

GET /v1/posts/{pid} and GET /v1/posts/{pid}/metrics accept either identifier:

The SocialAPI post ID (UUID) returned when the post was created.
A platform post ID: the platform’s own ID for a published target, for example a TikTok video ID or a Facebook post ID.

A platform post ID resolves to the SocialAPI post it was published from, so you can fetch a post or its live metrics using the ID you already track on the platform side. If a platform post ID happens to match more than one post across your accounts, the API returns 409 with code ambiguous_post_id; retry with the SocialAPI post ID. Mutating endpoints (update, delete, publish, retry, unpublish) accept only the SocialAPI post ID.

Deleting posts

DELETE /v1/posts/{pid} is best-effort and never lets the dashboard drift from the platform. For a draft, scheduled, or failed post (nothing was ever published), the post is removed locally. For a published post, SocialAPI calls each platform’s delete API in turn:

If the platform deletes the copy, that target is cleared.
If the platform does not support deletion (for example TikTok) or the delete call fails, that copy stays live and the post is kept (shrunk to the targets that are still live), not removed. A post is fully removed only when no live copy remains.

The response is a per-platform result, not a bare acknowledgement:

{
  "success": true,
  "deleted": false,
  "results": [
    { "platform": "instagram", "account_id": "acc_...", "outcome": "deleted" },
    { "platform": "tiktok", "account_id": "acc_...", "outcome": "not_supported", "message": "Operation not supported for this platform" }
  ]
}

deleted is true only when the post was fully removed. Each entry in results has an outcome of deleted, not_supported, or failed. A failed target can be retried; a not_supported target must be removed on the platform itself. See DELETE /v1/posts/{pid} in the API reference for the full schema.

Core field handling

How each platform interprets the shared PostDraft fields:

Field	Instagram	Facebook	LinkedIn	Threads	TikTok	YouTube	X / Twitter	Google
`text`	Caption (max 2200 chars)	Post message	Commentary	Post text (max 500 chars)	Video description	Video description	Tweet text (max 280)	Summary
`media`	Determines image/video/carousel	First item only; photo or video	Image or video	Image or video	Video, or photo carousel	Single video	Up to 4 photos, or one video, or one GIF	Single image
`first_comment`	Posted as a comment after publish (best-effort, non-blocking)	Posted as a comment after publish (best-effort, non-blocking)	Not supported	Not supported	Not supported	Posted as a comment after publish (best-effort, non-blocking)	Not supported	Not supported
`scheduled_at`	Deferred publish	Deferred publish	Deferred publish	Deferred publish	Not supported	Not supported	Not supported	Not supported

Platform-specific `platform_data` summary

Each platform accepts optional fields inside platform_data.<platform>. For the full reference, see the per-platform page. Pass these inside each target’s platform_data object (per-target overrides supported).

Platform	Required fields	Notable optional fields
Instagram	None	`alt_text`, `location_id`, `share_to_feed`, `cover_url`
Facebook	None	`link`, `cta_type`, `cta_link`, `min_age`, `max_age` (text, link, album posts); `alt_text` (single-photo); `title` (single-video)
LinkedIn	None	`disable_reshare`, `cta_label`, `cta_url`, `article_url`, `article_title`, `article_description`, `media_title`, `alt_text`, `alt_texts`
Threads	None	`reply_control`, `link_attachment`
TikTok	`privacy_level`	`media_type`, `brand_content_toggle`, `disable_duet`, `disable_stitch`, `disable_comment`, `is_aigc`, `video_cover_timestamp_ms`
YouTube	None	`category_id`, `tags`, `made_for_kids`, `embeddable`, `notify_subscribers`, `publish_at`
X / Twitter	None	`reply_settings` (`following`, `mentionedUsers`, `subscribers`, `verified`)
Google	None (defaults to STANDARD)	`topicType` (STANDARD, EVENT, OFFER, ALERT), `updateMask`
Zalo	None	None (article title falls back to `text`)

Required OAuth scopes

Platform	Scopes
Instagram	`instagram_business_basic`, `instagram_business_manage_comments`, `instagram_business_manage_messages`, `instagram_business_content_publish`
Facebook	`pages_show_list`, `pages_read_engagement`, `pages_read_user_content`, `pages_manage_engagement`, `pages_manage_metadata`, `pages_messaging`, `pages_manage_posts`, `public_profile`, `business_management`
LinkedIn	`r_liteprofile`, `r_organization_social`, `w_organization_social`, `r_organization_social_feed`, `w_organization_social_feed`, `rw_organization_admin`
Threads	`threads_basic`, `threads_content_publish`, `threads_read_replies`, `threads_delete`
TikTok	`user.info.basic`, `user.info.profile`, `video.publish`, `video.upload`
YouTube	`https://www.googleapis.com/auth/youtube.force-ssl`
X / Twitter	`tweet.read`, `tweet.write`, `tweet.moderate.write`, `users.read`, `dm.read`, `dm.write`, `like.write`, `offline.access` (BYOK; you configure your own app)
Google	`https://www.googleapis.com/auth/business.manage`

Per-platform deep dives

Instagram

Images, videos, reels, carousels. Meta Graph API.

Facebook

Text, photo, and video posts. Facebook Pages API.

Organization page posts. LinkedIn Marketing API.

Threads

Text, image, video posts. Threads API.

TikTok

Video and photo carousel posts. TikTok Content Posting API.

YouTube

Video uploads. YouTube Data API v3.

X / Twitter

Tweets with text or images. X API v2.

Google

Business Profile local posts. Google My Business API v4.

Zalo

Official Account articles and videos. Zalo Official Account Open API.

​Attaching media

​Capability matrix

​Retrieving a post

​Deleting posts

​Core field handling

​Platform-specific platform_data summary

​Required OAuth scopes

​Per-platform deep dives