Skip to main content

Create post

POST 
/posts

Create and schedule a social media post. Specify content, target accounts, and optionally a schedule time. If no scheduled_at is provided, the post is published immediately.

Use platform_content to customise content per platform — override captions, set Instagram content type (Story, Reels, Post), configure TikTok privacy, set YouTube titles, and more.

Instagram Stories example:

{
  "content": "Check this out!",
  "account_ids": [123],
  "media_ids": ["uuid"],
  "platform_content": {
    "instagram": { "contentType": "Story" }
  }
}

Request Body Schema​

POST /posts — Content-Type: application/json

FieldTypeRequiredDescription
contentstringYesThe text content of the post
account_idsinteger[]YesArray of social account IDs to post to (from GET /accounts)
scheduled_atstring (ISO 8601)NoDatetime to schedule the post. Omit to publish immediately.
timezonestringNoIANA timezone (e.g. America/New_York). Defaults to UTC.
media_idsstring[] (UUID)NoArray of media UUIDs to attach (from POST /media/upload)
platform_contentobjectNoPlatform-specific content overrides and settings (see below)

platform_content structure​

Use the platform key as the object key. Each platform object can contain a content override and a settings object.

Supported platform keys: instagram, tiktok, youtube, linkedin, x, facebook, threads

Instagram example with settings:

{
  "platform_content": {
    "instagram": {
      "content": "Instagram-specific caption with #hashtags",
      "contentType": "Reels",
      "settings": {
        "altText": "Image description for accessibility",
        "coverPhotoTimestamp": 2.5
      }
    }
  }
}
PlatformSettingsValues
instagramcontentType"Post", "Story", "Reels", "Trial Reel"
instagramaltTextstring (max 100 chars)
tiktokprivacyLevel"PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY"
tiktokallowComments, allowDuet, allowStitchboolean (default true)
youtubetitlestring (required for YouTube, max 100 chars)
youtubeprivacyStatus"public", "unlisted", "private"
youtubetagsstring[]
linkedinvisibility"PUBLIC", "CONNECTIONS", "LOGGED_IN_MEMBERS"
xreplySettings"everyone", "following", "mentionedUsers"
facebookvideoType"reel", "video"

Full Request Example​

{
  "content": "Excited to share our latest update! Check it out.",
  "account_ids": [2280, 2282, 2285],
  "scheduled_at": "2026-04-15T14:30:00.000Z",
  "timezone": "America/New_York",
  "media_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
  "platform_content": {
    "instagram": {
      "content": "Excited to share our latest update! #newfeature #launch",
      "contentType": "Reels"
    },
    "x": {
      "content": "Excited to share our latest update! Check it out."
    }
  }
}

Response Examples​

201 — Post created​

{
  "data": {
    "post_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "scheduled",
    "scheduled_for": "2026-04-15T14:30:00.000Z",
    "accounts_count": 3,
    "message": "Post scheduled for 3 accounts."
  },
  "error": null,
  "meta": {
    "request_id": "a1b2c3d4",
    "timestamp": "2026-04-10T12:00:00.000Z"
  }
}

400 — Validation error​

{
  "data": null,
  "error": {
    "message": "Missing required fields: content and account_ids are required.",
    "code": "validation_error"
  },
  "meta": {
    "request_id": "e5f6g7h8",
    "timestamp": "2026-04-10T12:00:00.000Z"
  }
}

401 — Unauthorized​

{
  "data": null,
  "error": {
    "message": "Invalid API key. Check that the key is correct and has not been deleted.",
    "code": "invalid_api_key"
  },
  "meta": {
    "request_id": "i9j0k1l2",
    "timestamp": "2026-04-10T12:00:00.000Z"
  }
}

429 — Rate limited​

{
  "data": null,
  "error": {
    "message": "Rate limit exceeded. Try again in 30 seconds.",
    "code": "rate_limited"
  },
  "meta": {
    "request_id": "m3n4o5p6",
    "timestamp": "2026-04-10T12:00:00.000Z"
  }
}

Request​

Responses​

Post created