socioi.comDocs

Posts

Create drafts, schedule, publish now, and manage posts.

MethodPathDescription
GET/postsList (?status=DRAFT|SCHEDULED|PUBLISHED|FAILED)
GET/posts/:idGet one
POST/postsCreate
POST/posts/:id/schedule{ "scheduledAt": "ISO" } (alias date also accepted)
PATCH/posts/:id/status{ "status": "draft" | "schedule" }
DELETE/posts/:idDelete

Create — type

ValueBehavior
draftSaved only
scheduleRequires date (UTC ISO)
nowQueued immediately for the worker

Shorthand body

JSON
{
  "type": "schedule",
  "date": "2026-09-20T10:00:00.000Z",
  "content": "Hello from Socioi",
  "channelIds": ["clx_channel_id"],
  "mediaIds": ["clx_media_id"]
}

Shorthand channelIds cannot set per-channel settings (for example Pinterest boardId). Use posts[] when you need provider settings.

Per-channel body

JSON
{
  "type": "now",
  "posts": [
    {
      "channelId": "clx_channel_id",
      "content": "Hello Instagram",
      "mediaIds": ["clx_media_id"],
      "settings": { "__type": "instagram" }
    }
  ]
}

Identical captions across items are merged into one post with multiple targets. If captions or media differ, the response is { "posts": [ … ] } instead of a single post object.

Scheduling an existing post

POST /posts/:id/schedule is only allowed for the user who created the post (API key creator, or the user who authorized the OAuth token). Otherwise the API returns 403.

If you PATCH status to schedule and the post has no prior schedule time, the API uses the current time.

Validation

  • Every channelIds / posts[].channelId must be a channel connected to your workspace that you're allowed to use, and every mediaIds entry must be a media asset in your workspace — otherwise 403. Duplicate media ids are ignored.
  • Provider settings are validated server-side (for example a YouTube title over 100 characters, or TikTok brandContent with SELF_ONLY, returns 400 with the reason).
  • YouTube and TikTok require a video in mediaIds.

Provider settings details: Provider settings.