Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.social-api.ai/llms.txt

Use this file to discover all available pages before exploring further.

Schedule a post by passing the scheduled_at field to POST /v1/posts. SocialAPI holds the post and publishes it at the scheduled time. Multi-platform fan-out works the same way as immediate publishing: one post object, multiple targets, one scheduled time applied to all of them.

​
How scheduling works

Set scheduled_at to an ISO 8601 timestamp in the future. SocialAPI validates the request immediately and queues it for delivery at the specified time. 
curl -X POST https://api.social-api.ai/v1/posts \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Launching next week.",
    "targets": [
      { "account_id": "acc_instagram_01", "platform": "instagram" },
      { "account_id": "acc_facebook_01", "platform": "facebook" }
    ],
    "scheduled_at": "2026-06-01T09:00:00Z"
  }'
Response: 
{
  "id": "post_01HZ9X3Q4R5M6N7P8V2K0W1J",
  "status": "scheduled",
  "scheduled_at": "2026-06-01T09:00:00Z",
  "targets": [
    { "account_id": "acc_instagram_01", "platform": "instagram", "status": "scheduled" },
    { "account_id": "acc_facebook_01", "platform": "facebook", "status": "scheduled" }
  ]
}
Omit scheduled_at (or set it to null) to publish immediately.

​
Managing scheduled posts

​
List scheduled posts

Filter by status to see all upcoming posts: 
curl "https://api.social-api.ai/v1/posts?status=scheduled" \
  -H "Authorization: Bearer $SOCAPI_KEY"

​
Reschedule a post

Update the scheduled time with PATCH: 
curl -X PATCH https://api.social-api.ai/v1/posts/post_01HZ9X3Q4R5M6N7P8V2K0W1J \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-06-02T14:00:00Z" }'

​
Cancel a scheduled post

Delete it before it publishes: 
curl -X DELETE https://api.social-api.ai/v1/posts/post_01HZ9X3Q4R5M6N7P8V2K0W1J \
  -H "Authorization: Bearer $SOCAPI_KEY"
Only posts in scheduled or draft status can be cancelled. Once a post enters publishing, it cannot be stopped.

​
Status lifecycle

Every post moves through this state machine: 
draft --> scheduled --> publishing --> published
                                  \-> partial
                                  \-> failed
StatusMeaning
draftCreated but not yet scheduled or published
scheduledQueued for future delivery at scheduled_at
publishingSocialAPI is actively sending the post to platforms
publishedAll targets delivered successfully
partialSome targets succeeded, some failed (check per-target status)
failedAll targets failed
A post can also be set to cancelled by deleting it while it is in draft or scheduled status.

​
Platform scheduling support

Not all platforms support deferred publishing through their APIs. For platforms that do not support scheduling natively, SocialAPI holds the post server-side and publishes it at the scheduled time.
PlatformNative schedulingMedia typesNotes
InstagramYesImage, Video (Reel), Carousel (2-10)Min 10 min in future, max 75 days
FacebookYesImage, VideoMin 10 min in future
ThreadsYesImage, Video, CarouselMin 10 min in future
LinkedInYesImage, Video, CarouselMin 10 min in future
GoogleNo (server-side)ImageSocialAPI holds and publishes at scheduled time
TikTokNo (server-side)Video, Photo carousel (2-35)SocialAPI holds and publishes at scheduled time
YouTubeComing soonVideoNot yet available
X / TwitterComing soon-Not yet available