Posts

Create, schedule, update, publish, and delete social media posts across every connected channel — the core of the OmniSocials API.

List posts

GET

/posts

List posts › query Parameters

status

string · enum

Filter by status

Enum values:

draft

scheduled

posted

failed

limit

integer · max: 100

Number of posts to return

Default: 20

offset

integer

Number of posts to skip

Default: 0

List posts › Responses

200

List of posts

Post[]

Pagination

GET/posts

curl /posts \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "id",
      "status": "draft",
      "type": "post",
      "content": {},
      "accounts": [
        "string"
      ],
      "media": {
        "key": [
          {
            "url": "url",
            "id": "id",
            "channel": "channel",
            "alt": "alt"
          }
        ]
      },
      "location_id": "location_id",
      "collaborators": [
        "string"
      ],
      "user_tags": [
        {
          "username": "username",
          "x": 0,
          "y": 0,
          "image_index": 0
        }
      ],
      "schedule_at": "2024-08-25T15:00:00Z",
      "app_url": "https://app.omnisocials.com/create-post/1024",
      "published_urls": {
        "facebook": "https://www.facebook.com/123456789/posts/987654321",
        "instagram": "https://www.instagram.com/p/Cxyz123ABC/",
        "linkedin": "https://www.linkedin.com/feed/update/urn:li:share:7191234567890",
        "x": "https://x.com/yourhandle/status/1791234567890123456"
      },
      "created_at": "2024-08-25T15:00:00Z",
      "approval_status": "approval_status",
      "errors": {
        "facebook": "Already Posted: These photos were already posted.",
        "instagram": "Instagram couldn't accept one of your images. Check that every image is JPEG/PNG, at least 320×320, has an aspect ratio between 4:5 and 1.91:1, and isn't visually flagged by Instagram. Re-upload or replace the offending image and try again."
      },
      "source": "source",
      "updated_at": "2024-08-25T15:00:00Z",
      "x": {
        "reply_settings": "",
        "paid_partnership": true,
        "made_with_ai": true,
        "thread_parts": [
          {
            "id": "id",
            "text": "text",
            "media_urls": [
              "https://www.example.com/path/to/resource"
            ]
          }
        ]
      },
      "bluesky": {
        "thread_parts": [
          {
            "id": "id",
            "text": "text",
            "media_urls": [
              "https://www.example.com/path/to/resource"
            ]
          }
        ]
      },
      "mastodon": {
        "thread_parts": [
          {
            "id": "id",
            "text": "text",
            "media_urls": [
              "https://www.example.com/path/to/resource"
            ]
          }
        ]
      },
      "instagram": {
        "first_comment": "first_comment",
        "first_comment_result": {
          "status": "posted",
          "comment_id": "comment_id",
          "url": "url",
          "error": "error",
          "posted_at": "2024-08-25T15:00:00Z"
        }
      },
      "facebook": {
        "first_comment": "first_comment",
        "first_comment_result": {
          "status": "posted",
          "comment_id": "comment_id",
          "url": "url",
          "error": "error",
          "posted_at": "2024-08-25T15:00:00Z"
        }
      },
      "linkedin": {
        "first_comment": "first_comment",
        "first_comment_result": {
          "status": "posted",
          "comment_id": "comment_id",
          "url": "url",
          "error": "error",
          "posted_at": "2024-08-25T15:00:00Z"
        }
      },
      "linkedin_page": {
        "first_comment": "first_comment",
        "first_comment_result": {
          "status": "posted",
          "comment_id": "comment_id",
          "url": "url",
          "error": "error",
          "posted_at": "2024-08-25T15:00:00Z"
        }
      },
      "youtube": {
        "first_comment": "first_comment",
        "first_comment_result": {
          "status": "posted",
          "comment_id": "comment_id",
          "url": "url",
          "error": "error",
          "posted_at": "2024-08-25T15:00:00Z"
        }
      }
    }
  ],
  "pagination": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "has_more": true
  }
}

json

application/json

List the user's recent posts fetched live from the connected platforms

GET

/posts/recent-platform

Returns the most recent posts pulled directly from each connected platform's API (Instagram, TikTok, X, YouTube, Facebook, LinkedIn, and more), including content that was published outside OmniSocials. This is the fallback for brand-new workspaces that have not published anything through OmniSocials yet, so GET /posts (which only lists OmniSocials posts) comes back empty. Each post is enriched with normalized engagement / impressions / engagement_rate so you can rank across platforms without re-deriving per-platform rules. Metrics are only present where the platform exposes them for historical posts: X, TikTok, Bluesky, Mastodon, Instagram (likes/comments/reach/views/saves/shares, via one insights call per post), Facebook, and YouTube return counts, while Threads, Pinterest, and Google Business return captions only (metrics: {}). LinkedIn personal profiles cannot be listed live (LinkedIn grants no such permission to apps), so their results contain posts published through OmniSocials with their latest collected stats; TikTok results are backfilled the same way for photo posts the video list omits. Fetched live on every call, so it is not cached — expect a few seconds of latency across many platforms. Requires the analytics:read scope.

List the user's recent posts fetched live from the connected platforms › query Parameters

limit

integer · max: 50

Max posts to fetch per connected platform (1-50, default 25).

Default: 25

platforms

string

Optional comma-separated platform filter (e.g. "instagram,tiktok"). Defaults to every connected platform. Unsupported values return 400.

List the user's recent posts fetched live from the connected platforms › Responses

Recent posts across connected platforms, newest first

object[]

count

integer

connected_platforms

string[]

errors

object

Per-platform error messages for any platform that failed to fetch.

note

string

current_date

string · date

Get a post by ID

GET

/posts/{id}

Get a post by ID › path Parameters

id

string · required

Post ID

Get a post by ID › Responses

Post details

Post

GET/posts/{id}

curl /posts/:id \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "id",
    "status": "draft",
    "type": "post",
    "content": {},
    "accounts": [
      "string"
    ],
    "media": {
      "key": [
        {
          "url": "url",
          "id": "id",
          "channel": "channel",
          "alt": "alt"
        }
      ]
    },
    "location_id": "location_id",
    "collaborators": [
      "string"
    ],
    "user_tags": [
      {
        "username": "username",
        "x": 0,
        "y": 0,
        "image_index": 0
      }
    ],
    "schedule_at": "2024-08-25T15:00:00Z",
    "app_url": "https://app.omnisocials.com/create-post/1024",
    "published_urls": {
      "facebook": "https://www.facebook.com/123456789/posts/987654321",
      "instagram": "https://www.instagram.com/p/Cxyz123ABC/",
      "linkedin": "https://www.linkedin.com/feed/update/urn:li:share:7191234567890",
      "x": "https://x.com/yourhandle/status/1791234567890123456"
    },
    "created_at": "2024-08-25T15:00:00Z",
    "approval_status": "approval_status",
    "errors": {
      "facebook": "Already Posted: These photos were already posted.",
      "instagram": "Instagram couldn't accept one of your images. Check that every image is JPEG/PNG, at least 320×320, has an aspect ratio between 4:5 and 1.91:1, and isn't visually flagged by Instagram. Re-upload or replace the offending image and try again."
    },
    "source": "source",
    "updated_at": "2024-08-25T15:00:00Z",
    "x": {
      "reply_settings": "",
      "paid_partnership": true,
      "made_with_ai": true,
      "thread_parts": [
        {
          "id": "id",
          "text": "text",
          "media_urls": [
            "https://www.example.com/path/to/resource"
          ]
        }
      ]
    },
    "bluesky": {
      "thread_parts": [
        {
          "id": "id",
          "text": "text",
          "media_urls": [
            "https://www.example.com/path/to/resource"
          ]
        }
      ]
    },
    "mastodon": {
      "thread_parts": [
        {
          "id": "id",
          "text": "text",
          "media_urls": [
            "https://www.example.com/path/to/resource"
          ]
        }
      ]
    },
    "instagram": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "facebook": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "linkedin": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "linkedin_page": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "youtube": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    }
  }
}

json

application/json

Delete a post

DELETE

/posts/{id}

Delete a post › path Parameters

id

string · required

Delete a post › Responses

Post deleted

No data returned

Update a post

PATCH

/posts/{id}

Update a post › path Parameters

id

string · required

Update a post › Request Body

content

object

accounts

string[]

type

string · enum

Change post type (draft only)

Enum values:

post

story

reel

CreatePostRequest/properties/media

Media IDs from POST /media/upload. Flat array or per-platform object. Any entry may be an { id, alt } object to carry a per-media accessibility description (alt text, max 1500 chars).

CreatePostRequest/properties/media

Media IDs from POST /media/upload. Flat array or per-platform object. Any entry may be an { id, alt } object to carry a per-media accessibility description (alt text, max 1500 chars).

CreatePostRequest/properties/media_urls

External image/video/PDF URLs to download and attach (max 10 total, each file ≤ 100 MB). Flat array or per-platform object. Any entry may be a { url, alt } object to carry a per-media accessibility description (alt text, max 1500 chars) — delivered to Mastodon, Bluesky, X and Pinterest. When using per-platform format, 'default' acts as fallback for selected platforms without their own key. A PDF URL is rasterized into one image slide per page (max 20, in order) — on LinkedIn it publishes as a swipeable document, elsewhere as an image carousel; slides inherit the entry's alt. For files over 100 MB (up to 1 GB), upload first via POST /v1/media/upload-from-url and attach the returned media id via the media field; oversized media_urls fail with code file_too_large.

schedule_at

string · date-time

location_id

CreatePostRequest/properties/location_id

Instagram only. Facebook Place/Page ID to tag the post's location with (e.g. a dealership or storefront). Applied to single-image and carousel feed posts via Instagram's content-publishing location_id. Find a Place's Page ID via Facebook's Pages Search API. Ignored by other platforms. Send an empty string on PATCH to clear it.

Example: 1234567890

collaborators

string[] · maxItems: 3

Instagram only. Up to 3 public Instagram usernames to invite as co-authors (the 'Collab' feature). Applied to image, carousel, and reel posts — NOT Stories. Invited users get an invitation in the Instagram app; once accepted, the post also appears on their profile and feed. Usernames are case-insensitive and a leading '@' is stripped. Private accounts and non-existent usernames are rejected by Instagram at publish time. Ignored by other platforms. Send an empty array on PATCH to clear collaborators.

Example: ["therock","kevinhart4real"]

object[]

Instagram only. Tag public Instagram accounts at specific positions on a photo. Photos only — NOT video, reels, or stories. For a single image omit image_index (or set 0); for a carousel, set image_index to the 0-based slide the tag belongs to (tags attach to that slide's image). Public accounts only; private/non-existent usernames are rejected by Instagram at publish time. Ignored by other platforms. Send an empty array on PATCH to clear tags.

Example: [{"username":"therock","x":0.5,"y":0.8}]

CreatePostRequest/properties/pinterest

Pinterest-specific options. Attach 2–5 images via media_urls.pinterest (or the flat media_urls) to publish a single carousel pin; the title, description, link, and alt_text apply to the whole pin. A single image or a single video still publishes as a normal image / video pin. Carousel constraint: Pinterest's v5 API requires every slide in a carousel pin to share the same aspect ratio (1% tolerance). If you attach mixed-ratio images and try to schedule or publish, the API responds 400 validation_error with mismatched_slides: [n, ...] listing the 1-indexed slide numbers that need to be re-cropped or removed. The check is run when publish_now: true, when schedule_at is set, and when PATCH flips a draft to a scheduled status — drafts are exempt so you can iterate on media.

CreatePostRequest/properties/youtube

YouTube Shorts options. Only applies when type is reel and youtube is among the selected accounts.

object

Instagram Reel options. MERGED into the stored options: keys you omit keep their current value (so updating share_to_feed cannot silently clear a Trial Reel flag or reel music set elsewhere); pass a key explicitly as null to clear it.

CreatePostRequest/properties/tiktok

TikTok options

CreatePostRequest/properties/x

X (Twitter) options

CreatePostRequest/properties/bluesky

Bluesky options

CreatePostRequest/properties/mastodon

Mastodon options

Update a post › Responses

Post updated

Post

PATCH/posts/{id}

curl /posts/:id \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "content": {},
  "accounts": [
    "string"
  ],
  "type": "post",
  "media": [
    "string"
  ],
  "media_ids": [
    "string"
  ],
  "media_urls": [
    "https://www.example.com/path/to/resource"
  ],
  "schedule_at": "2024-08-25T15:00:00Z",
  "location_id": "1234567890",
  "collaborators": [
    "therock",
    "kevinhart4real"
  ],
  "user_tags": [
    {
      "username": "therock",
      "x": 0.5,
      "y": 0.8
    }
  ],
  "pinterest": {
    "board_id": "board_id",
    "title": "title",
    "link": "link",
    "video_cover": "video_cover",
    "alt_text": "alt_text"
  },
  "youtube": {
    "title": "title",
    "tags": [
      "string"
    ],
    "privacy_status": "public",
    "category_id": "category_id",
    "made_for_kids": false,
    "notify_subscribers": false,
    "contains_synthetic_media": false,
    "first_comment": "first_comment"
  },
  "instagram": {
    "share_to_feed": false,
    "thumbnail_type": "from-video",
    "thumb_offset": 0,
    "cover_url": "cover_url",
    "audio_id": "587784541076604",
    "audio_volume": 100,
    "video_volume": 100,
    "first_comment": "first_comment",
    "is_trial_reel": false,
    "trial_graduation_strategy": "MANUAL"
  },
  "tiktok": {
    "privacy_level": "PUBLIC_TO_EVERYONE",
    "disable_comment": false,
    "disable_duet": false,
    "disable_stitch": false,
    "video_cover_timestamp_ms": 0,
    "is_aigc": false,
    "brand_content_toggle": false,
    "brand_organic_toggle": false,
    "auto_add_music": false
  },
  "x": {
    "reply_settings": "",
    "paid_partnership": false,
    "made_with_ai": false,
    "thread_parts": [
      {
        "text": "1/3 — our results are in 👇",
        "media_ids": [
          "12345"
        ]
      },
      {
        "text": "2/3 — grab your free pick here: https://example.com/signup"
      },
      {
        "text": "3/3 — and here'\''s the slip 🎁",
        "media_ids": [
          "12346"
        ]
      }
    ]
  },
  "bluesky": {
    "thread_parts": [
      {
        "text": "1/3 — our results are in 👇"
      },
      {
        "text": "2/3 — read the full writeup: https://example.com/post"
      },
      {
        "text": "3/3 — thanks for reading! #buildinpublic"
      }
    ]
  },
  "mastodon": {
    "thread_parts": [
      {
        "text": "1/3 — our picks are in 👇"
      },
      {
        "text": "2/3 — read the full writeup: https://example.com/post"
      },
      {
        "text": "3/3 — thanks for reading! #fediverse"
      }
    ]
  }
}'

Example Request Body

{
  "content": {},
  "accounts": [
    "string"
  ],
  "type": "post",
  "media": [
    "string"
  ],
  "media_ids": [
    "string"
  ],
  "media_urls": [
    "https://www.example.com/path/to/resource"
  ],
  "schedule_at": "2024-08-25T15:00:00Z",
  "location_id": "1234567890",
  "collaborators": [
    "therock",
    "kevinhart4real"
  ],
  "user_tags": [
    {
      "username": "therock",
      "x": 0.5,
      "y": 0.8
    }
  ],
  "pinterest": {
    "board_id": "board_id",
    "title": "title",
    "link": "link",
    "video_cover": "video_cover",
    "alt_text": "alt_text"
  },
  "youtube": {
    "title": "title",
    "tags": [
      "string"
    ],
    "privacy_status": "public",
    "category_id": "category_id",
    "made_for_kids": false,
    "notify_subscribers": false,
    "contains_synthetic_media": false,
    "first_comment": "first_comment"
  },
  "instagram": {
    "share_to_feed": false,
    "thumbnail_type": "from-video",
    "thumb_offset": 0,
    "cover_url": "cover_url",
    "audio_id": "587784541076604",
    "audio_volume": 100,
    "video_volume": 100,
    "first_comment": "first_comment",
    "is_trial_reel": false,
    "trial_graduation_strategy": "MANUAL"
  },
  "tiktok": {
    "privacy_level": "PUBLIC_TO_EVERYONE",
    "disable_comment": false,
    "disable_duet": false,
    "disable_stitch": false,
    "video_cover_timestamp_ms": 0,
    "is_aigc": false,
    "brand_content_toggle": false,
    "brand_organic_toggle": false,
    "auto_add_music": false
  },
  "x": {
    "reply_settings": "",
    "paid_partnership": false,
    "made_with_ai": false,
    "thread_parts": [
      {
        "text": "1/3 — our results are in 👇",
        "media_ids": [
          "12345"
        ]
      },
      {
        "text": "2/3 — grab your free pick here: https://example.com/signup"
      },
      {
        "text": "3/3 — and here's the slip 🎁",
        "media_ids": [
          "12346"
        ]
      }
    ]
  },
  "bluesky": {
    "thread_parts": [
      {
        "text": "1/3 — our results are in 👇"
      },
      {
        "text": "2/3 — read the full writeup: https://example.com/post"
      },
      {
        "text": "3/3 — thanks for reading! #buildinpublic"
      }
    ]
  },
  "mastodon": {
    "thread_parts": [
      {
        "text": "1/3 — our picks are in 👇"
      },
      {
        "text": "2/3 — read the full writeup: https://example.com/post"
      },
      {
        "text": "3/3 — thanks for reading! #fediverse"
      }
    ]
  }
}

json

Example Responses

{
  "data": {
    "id": "id",
    "status": "draft",
    "type": "post",
    "content": {},
    "accounts": [
      "string"
    ],
    "media": {
      "key": [
        {
          "url": "url",
          "id": "id",
          "channel": "channel",
          "alt": "alt"
        }
      ]
    },
    "location_id": "location_id",
    "collaborators": [
      "string"
    ],
    "user_tags": [
      {
        "username": "username",
        "x": 0,
        "y": 0,
        "image_index": 0
      }
    ],
    "schedule_at": "2024-08-25T15:00:00Z",
    "app_url": "https://app.omnisocials.com/create-post/1024",
    "published_urls": {
      "facebook": "https://www.facebook.com/123456789/posts/987654321",
      "instagram": "https://www.instagram.com/p/Cxyz123ABC/",
      "linkedin": "https://www.linkedin.com/feed/update/urn:li:share:7191234567890",
      "x": "https://x.com/yourhandle/status/1791234567890123456"
    },
    "created_at": "2024-08-25T15:00:00Z",
    "approval_status": "approval_status",
    "errors": {
      "facebook": "Already Posted: These photos were already posted.",
      "instagram": "Instagram couldn't accept one of your images. Check that every image is JPEG/PNG, at least 320×320, has an aspect ratio between 4:5 and 1.91:1, and isn't visually flagged by Instagram. Re-upload or replace the offending image and try again."
    },
    "source": "source",
    "updated_at": "2024-08-25T15:00:00Z",
    "x": {
      "reply_settings": "",
      "paid_partnership": true,
      "made_with_ai": true,
      "thread_parts": [
        {
          "id": "id",
          "text": "text",
          "media_urls": [
            "https://www.example.com/path/to/resource"
          ]
        }
      ]
    },
    "bluesky": {
      "thread_parts": [
        {
          "id": "id",
          "text": "text",
          "media_urls": [
            "https://www.example.com/path/to/resource"
          ]
        }
      ]
    },
    "mastodon": {
      "thread_parts": [
        {
          "id": "id",
          "text": "text",
          "media_urls": [
            "https://www.example.com/path/to/resource"
          ]
        }
      ]
    },
    "instagram": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "facebook": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "linkedin": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "linkedin_page": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "youtube": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    }
  }
}

json

application/json

Create a new post

POST

/posts/create

Create a new post. You can attach media by uploading first (media/media_ids) or by passing external URLs (media_urls) which will be downloaded and processed automatically. Both can be combined.

Required media: Instagram and TikTok posts need at least one image/video. Pinterest posts need an image and a board_id. Posts without required media will be rejected with a 400 error.

Per-platform media caps (enforced at submit, not at publish time):

bluesky — max 4 images per post
mastodon — max 4 media items per post
x — max 4 images per post
instagram — max 10 items in a carousel
threads — max 10 items in a carousel
tiktok — max 35 items per photo post; cannot mix photos and videos in one post

Exceeding any cap returns 400 { error: { code: "validation_error", message: "<Platform> allows up to N media items per post. You attached M, please remove M-N." } }. The Pinterest carousel aspect-ratio constraint (2–5 same-ratio images) is enforced the same way; see the Pinterest section for the mismatched_slides response shape.

Per-platform video file-size caps (validated via ffprobe; drafts exempt): Mastodon 99 MB · Bluesky 100 MB · Instagram 300 MB · X 512 MB (free tier) · Threads / Reddit 1 GB · Pinterest 2 GB · Facebook / TikTok 4 GB · LinkedIn 5 GB · YouTube 256 GB. Upload requests are capped at 100 MB on top of these — anything bigger is rejected before media processing with code: file_too_large.

Per-platform video duration caps (validated via ffprobe; drafts exempt): Facebook Post 240 min / Reel 90 s · Instagram 15 min (Post + Reel) · TikTok 10 min (Post + Reel) · YouTube Short 3 min · X 140 s · Bluesky 180 s · Threads 5 min · LinkedIn 10 min · Pinterest 15 min · Reddit 15 min · Mastodon (instance-dependent).

Cap violations return 400 { error: { code: "validation_error", message: "<Platform> only allows videos up to <cap> — yours is <duration>. Trim the video or deselect <Platform>." } } (duration) or "This video (<size>) is too large for <Platform>. ..." (size). When multiple platforms reject the same upload, each contributes one sentence to the message. See API_DEVELOPER_GUIDE.md → "Per-Platform Media Limits" and "Per-Platform Video Duration Caps" for the full table with source citations.

Create a new post › Request Body

CreatePostRequest

content

object · required

Post content. Use 'default' for all platforms, or platform-specific keys: instagram, facebook, linkedin, linkedin_page, youtube, tiktok, pinterest, x, threads, bluesky, mastodon, google_business. Coming soon: reddit, snapchat.

Example: {"default":"Hello world!","instagram":"Hello from IG! #awesome"}

accounts

string[] · required

Social accounts to post to. Each entry is either:

A bare platform name (e.g. "youtube", "linkedin_page"), or
The composite ID returned by GET /v1/accounts in the form "<workspace_id>_<platform>" (e.g. "844008_youtube").

The composite form's workspace prefix must match the workspace your API key belongs to. Mismatched or unknown ids return 400 validation_error with an "Unknown account/platform" message — always source ids from GET /v1/accounts for the API key in use.

type

string · enum

Post type: 'post' (feed), 'story' (Instagram/Facebook), 'reel' (Instagram/Facebook/YouTube/TikTok). A 'reel' must have video media (MP4/MOV); an image is rejected with 400 validation_error at schedule/publish — use 'post' to share an image.

Enum values:

post

story

reel

Default: post

Media IDs from POST /media/upload. Flat array or per-platform object. Any entry may be an { id, alt } object to carry a per-media accessibility description (alt text, max 1500 chars).

schedule_at

string · date-time

ISO 8601 datetime to schedule. Omit for draft.

publish_now

boolean

Set true to publish immediately

link_url

string · uri

URL to share as a rich preview card on platforms that support link-share posts (currently LinkedIn and Facebook). When set on a text post, the URL renders as a preview tile with thumbnail / title / description instead of plain text. Ignored on platforms that don't support link shares (Instagram, TikTok, etc.) and on posts that already have media attached — media takes precedence.

Example: https://goodlightai.com/blog/new-feature

link_title

string

Optional title for the link-share preview. LinkedIn uses this directly when set. Facebook ignores this — it fetches OG metadata server-side. Omit to let LinkedIn auto-fetch the page title.

link_description

string

Optional description for the link-share preview. LinkedIn uses this when set; Facebook auto-fetches the OG description. Omit to defer to OG metadata.

link_thumbnail_url

string · uri

Optional thumbnail image URL for the preview card. Currently not yet applied to LinkedIn (would require uploading to LinkedIn's image API first); included for forward compatibility.

source

string

Self-reported origin of the integration creating this post. Defaults to 'api' if omitted. Use 'zapier', 'make', 'n8n', etc. to identify your integration.

location_id

string

Example: 1234567890

collaborators

string[] · maxItems: 3

Example: ["therock","kevinhart4real"]

object[]

Example: [{"username":"therock","x":0.5,"y":0.8}]

hashtag_set

string

Name of a saved hashtag set (see GET /hashtag-sets) to apply to this post, matched case-insensitively. The set's tags are merged in ONCE at create time — the post stores plain text, so later edits to the set never change this post. Tags already present in a caption are skipped (case-insensitive), and hard platform caps (Instagram 30) are enforced with a 400 hashtag_limit_exceeded before the platform can reject the post. Mutually interchangeable with hashtag_set_id.

Example: Fitness Brand

hashtag_set_id

string

Id of a saved hashtag set to apply. Same behavior as hashtag_set; pass one or the other.

hashtag_placement

string · enum

Where the set's tags land. caption_append (default) appends them to each target platform's caption after a blank line. first_comment puts them in the auto first comment on comment-capable platforms (Instagram, Facebook, LinkedIn Profile/Page, YouTube) — appended after any first_comment you passed explicitly — and falls back to caption_append on platforms without a comment API. Stories always use captions (first comments are never posted on Stories).

Enum values:

caption_append

first_comment

Default: caption_append

hashtag_platforms

string[]

Optional subset of the post's selected platforms to apply the set to (e.g. only ["instagram", "tiktok"]). Defaults to all selected platforms.

object

YouTube Shorts options. Only applies when type is reel and youtube is among the selected accounts.

object

Instagram Reel options

object

Facebook options

object

LinkedIn Profile options

object

LinkedIn Company Page options

object

TikTok options

object

X (Twitter) options

object

Bluesky options

object

Mastodon options

object

Google Business Profile options. Use to publish EVENT or OFFER posts in addition to STANDARD, attach a call-to-action button, or both. STANDARD posts can also use this object purely to add a CTA. The shape mirrors Google's LocalPost JSONB exactly; see https://developers.google.com/my-business/reference/rest/v4/accounts.locations.localPosts#LocalPost.

Caption rules (enforced at scheduling — text that violates these returns validation_error 400 before the post is saved): • No phone numbers in the caption (use a CALL button instead). • No inline URLs / bare domains / email addresses (use a LEARN_MORE, BOOK, SHOP, SIGN_UP, or ORDER button instead). • Caption max 1500 characters. • Media optional (text-only posts allowed). If attached: exactly one JPEG/PNG/WebP image (no video, no carousels). • The workspace must have a Google Business location selected (Settings → Organisation → Workspaces → Google Business) before scheduling.

Create a new post › Responses

Post created

Post

POST/posts/create

curl /posts/create \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "content": {
    "default": "Hello world!",
    "instagram": "Hello from IG! #awesome"
  },
  "accounts": [
    "string"
  ],
  "type": "post",
  "media": [
    "string"
  ],
  "media_urls": [
    "https://www.example.com/path/to/resource"
  ],
  "schedule_at": "2024-08-25T15:00:00Z",
  "publish_now": true,
  "link_url": "https://goodlightai.com/blog/new-feature",
  "link_title": "link_title",
  "link_description": "link_description",
  "link_thumbnail_url": "https://www.example.com/path/to/resource",
  "source": "source",
  "location_id": "1234567890",
  "collaborators": [
    "therock",
    "kevinhart4real"
  ],
  "user_tags": [
    {
      "username": "therock",
      "x": 0.5,
      "y": 0.8
    }
  ],
  "hashtag_set": "Fitness Brand",
  "hashtag_set_id": "hashtag_set_id",
  "hashtag_placement": "caption_append",
  "hashtag_platforms": [
    "string"
  ],
  "pinterest": {
    "board_id": "board_id",
    "title": "title",
    "link": "link",
    "video_cover": "video_cover",
    "alt_text": "alt_text"
  },
  "youtube": {
    "title": "title",
    "tags": [
      "string"
    ],
    "privacy_status": "public",
    "category_id": "category_id",
    "made_for_kids": false,
    "notify_subscribers": false,
    "contains_synthetic_media": false,
    "first_comment": "first_comment"
  },
  "instagram": {
    "share_to_feed": false,
    "thumbnail_type": "from-video",
    "thumb_offset": 0,
    "cover_url": "cover_url",
    "audio_id": "587784541076604",
    "audio_volume": 100,
    "video_volume": 100,
    "first_comment": "first_comment",
    "is_trial_reel": false,
    "trial_graduation_strategy": "MANUAL"
  },
  "facebook": {
    "first_comment": "first_comment"
  },
  "linkedin": {
    "first_comment": "first_comment"
  },
  "linkedin_page": {
    "first_comment": "first_comment"
  },
  "tiktok": {
    "privacy_level": "PUBLIC_TO_EVERYONE",
    "disable_comment": false,
    "disable_duet": false,
    "disable_stitch": false,
    "video_cover_timestamp_ms": 0,
    "is_aigc": false,
    "brand_content_toggle": false,
    "brand_organic_toggle": false,
    "auto_add_music": false
  },
  "x": {
    "reply_settings": "",
    "paid_partnership": false,
    "made_with_ai": false,
    "thread_parts": [
      {
        "text": "1/3 — our results are in 👇",
        "media_ids": [
          "12345"
        ]
      },
      {
        "text": "2/3 — grab your free pick here: https://example.com/signup"
      },
      {
        "text": "3/3 — and here'\''s the slip 🎁",
        "media_ids": [
          "12346"
        ]
      }
    ]
  },
  "bluesky": {
    "thread_parts": [
      {
        "text": "1/3 — our results are in 👇"
      },
      {
        "text": "2/3 — read the full writeup: https://example.com/post"
      },
      {
        "text": "3/3 — thanks for reading! #buildinpublic"
      }
    ]
  },
  "mastodon": {
    "thread_parts": [
      {
        "text": "1/3 — our picks are in 👇"
      },
      {
        "text": "2/3 — read the full writeup: https://example.com/post"
      },
      {
        "text": "3/3 — thanks for reading! #fediverse"
      }
    ]
  },
  "google_business": {
    "topic_type": "STANDARD",
    "cta": {
      "actionType": "LEARN_MORE",
      "url": "https://www.example.com/path/to/resource"
    },
    "event": {
      "title": "title",
      "schedule": {
        "startDate": {
          "year": 0,
          "month": 0,
          "day": 0
        },
        "startTime": {
          "hours": 0,
          "minutes": 0
        },
        "endDate": {
          "year": 0,
          "month": 0,
          "day": 0
        },
        "endTime": {
          "hours": 0,
          "minutes": 0
        }
      }
    },
    "offer": {
      "couponCode": "couponCode",
      "redeemOnlineUrl": "https://www.example.com/path/to/resource",
      "termsConditions": "termsConditions"
    }
  }
}'

Example Request Body

{
  "content": {
    "default": "Hello world!",
    "instagram": "Hello from IG! #awesome"
  },
  "accounts": [
    "string"
  ],
  "type": "post",
  "media": [
    "string"
  ],
  "media_urls": [
    "https://www.example.com/path/to/resource"
  ],
  "schedule_at": "2024-08-25T15:00:00Z",
  "publish_now": true,
  "link_url": "https://goodlightai.com/blog/new-feature",
  "link_title": "link_title",
  "link_description": "link_description",
  "link_thumbnail_url": "https://www.example.com/path/to/resource",
  "source": "source",
  "location_id": "1234567890",
  "collaborators": [
    "therock",
    "kevinhart4real"
  ],
  "user_tags": [
    {
      "username": "therock",
      "x": 0.5,
      "y": 0.8
    }
  ],
  "hashtag_set": "Fitness Brand",
  "hashtag_set_id": "hashtag_set_id",
  "hashtag_placement": "caption_append",
  "hashtag_platforms": [
    "string"
  ],
  "pinterest": {
    "board_id": "board_id",
    "title": "title",
    "link": "link",
    "video_cover": "video_cover",
    "alt_text": "alt_text"
  },
  "youtube": {
    "title": "title",
    "tags": [
      "string"
    ],
    "privacy_status": "public",
    "category_id": "category_id",
    "made_for_kids": false,
    "notify_subscribers": false,
    "contains_synthetic_media": false,
    "first_comment": "first_comment"
  },
  "instagram": {
    "share_to_feed": false,
    "thumbnail_type": "from-video",
    "thumb_offset": 0,
    "cover_url": "cover_url",
    "audio_id": "587784541076604",
    "audio_volume": 100,
    "video_volume": 100,
    "first_comment": "first_comment",
    "is_trial_reel": false,
    "trial_graduation_strategy": "MANUAL"
  },
  "facebook": {
    "first_comment": "first_comment"
  },
  "linkedin": {
    "first_comment": "first_comment"
  },
  "linkedin_page": {
    "first_comment": "first_comment"
  },
  "tiktok": {
    "privacy_level": "PUBLIC_TO_EVERYONE",
    "disable_comment": false,
    "disable_duet": false,
    "disable_stitch": false,
    "video_cover_timestamp_ms": 0,
    "is_aigc": false,
    "brand_content_toggle": false,
    "brand_organic_toggle": false,
    "auto_add_music": false
  },
  "x": {
    "reply_settings": "",
    "paid_partnership": false,
    "made_with_ai": false,
    "thread_parts": [
      {
        "text": "1/3 — our results are in 👇",
        "media_ids": [
          "12345"
        ]
      },
      {
        "text": "2/3 — grab your free pick here: https://example.com/signup"
      },
      {
        "text": "3/3 — and here's the slip 🎁",
        "media_ids": [
          "12346"
        ]
      }
    ]
  },
  "bluesky": {
    "thread_parts": [
      {
        "text": "1/3 — our results are in 👇"
      },
      {
        "text": "2/3 — read the full writeup: https://example.com/post"
      },
      {
        "text": "3/3 — thanks for reading! #buildinpublic"
      }
    ]
  },
  "mastodon": {
    "thread_parts": [
      {
        "text": "1/3 — our picks are in 👇"
      },
      {
        "text": "2/3 — read the full writeup: https://example.com/post"
      },
      {
        "text": "3/3 — thanks for reading! #fediverse"
      }
    ]
  },
  "google_business": {
    "topic_type": "STANDARD",
    "cta": {
      "actionType": "LEARN_MORE",
      "url": "https://www.example.com/path/to/resource"
    },
    "event": {
      "title": "title",
      "schedule": {
        "startDate": {
          "year": 0,
          "month": 0,
          "day": 0
        },
        "startTime": {
          "hours": 0,
          "minutes": 0
        },
        "endDate": {
          "year": 0,
          "month": 0,
          "day": 0
        },
        "endTime": {
          "hours": 0,
          "minutes": 0
        }
      }
    },
    "offer": {
      "couponCode": "couponCode",
      "redeemOnlineUrl": "https://www.example.com/path/to/resource",
      "termsConditions": "termsConditions"
    }
  }
}

json

Example Responses

{
  "data": {
    "id": "id",
    "status": "draft",
    "type": "post",
    "content": {},
    "accounts": [
      "string"
    ],
    "media": {
      "key": [
        {
          "url": "url",
          "id": "id",
          "channel": "channel",
          "alt": "alt"
        }
      ]
    },
    "location_id": "location_id",
    "collaborators": [
      "string"
    ],
    "user_tags": [
      {
        "username": "username",
        "x": 0,
        "y": 0,
        "image_index": 0
      }
    ],
    "schedule_at": "2024-08-25T15:00:00Z",
    "app_url": "https://app.omnisocials.com/create-post/1024",
    "published_urls": {
      "facebook": "https://www.facebook.com/123456789/posts/987654321",
      "instagram": "https://www.instagram.com/p/Cxyz123ABC/",
      "linkedin": "https://www.linkedin.com/feed/update/urn:li:share:7191234567890",
      "x": "https://x.com/yourhandle/status/1791234567890123456"
    },
    "created_at": "2024-08-25T15:00:00Z",
    "approval_status": "approval_status",
    "errors": {
      "facebook": "Already Posted: These photos were already posted.",
      "instagram": "Instagram couldn't accept one of your images. Check that every image is JPEG/PNG, at least 320×320, has an aspect ratio between 4:5 and 1.91:1, and isn't visually flagged by Instagram. Re-upload or replace the offending image and try again."
    },
    "source": "source",
    "updated_at": "2024-08-25T15:00:00Z",
    "x": {
      "reply_settings": "",
      "paid_partnership": true,
      "made_with_ai": true,
      "thread_parts": [
        {
          "id": "id",
          "text": "text",
          "media_urls": [
            "https://www.example.com/path/to/resource"
          ]
        }
      ]
    },
    "bluesky": {
      "thread_parts": [
        {
          "id": "id",
          "text": "text",
          "media_urls": [
            "https://www.example.com/path/to/resource"
          ]
        }
      ]
    },
    "mastodon": {
      "thread_parts": [
        {
          "id": "id",
          "text": "text",
          "media_urls": [
            "https://www.example.com/path/to/resource"
          ]
        }
      ]
    },
    "instagram": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "facebook": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "linkedin": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "linkedin_page": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "youtube": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    }
  }
}

json

application/json

Create and publish a post immediately

POST

/posts/create-and-publish

Creates a new post and publishes it right away — no scheduling needed. Equivalent to calling POST /posts/create with publish_now: true. The post will be queued for immediate publishing to all selected platforms.

Create and publish a post immediately › Request Body

CreatePostRequest

content

object · required

Example: {"default":"Hello world!","instagram":"Hello from IG! #awesome"}

accounts

string[] · required

Social accounts to post to. Each entry is either:

A bare platform name (e.g. "youtube", "linkedin_page"), or
The composite ID returned by GET /v1/accounts in the form "<workspace_id>_<platform>" (e.g. "844008_youtube").

type

string · enum

Enum values:

post

story

reel

Default: post

Media IDs from POST /media/upload. Flat array or per-platform object. Any entry may be an { id, alt } object to carry a per-media accessibility description (alt text, max 1500 chars).

schedule_at

string · date-time

ISO 8601 datetime to schedule. Omit for draft.

publish_now

boolean

Set true to publish immediately

link_url

string · uri

Example: https://goodlightai.com/blog/new-feature

link_title

string

Optional title for the link-share preview. LinkedIn uses this directly when set. Facebook ignores this — it fetches OG metadata server-side. Omit to let LinkedIn auto-fetch the page title.

link_description

string

Optional description for the link-share preview. LinkedIn uses this when set; Facebook auto-fetches the OG description. Omit to defer to OG metadata.

link_thumbnail_url

string · uri

Optional thumbnail image URL for the preview card. Currently not yet applied to LinkedIn (would require uploading to LinkedIn's image API first); included for forward compatibility.

source

string

Self-reported origin of the integration creating this post. Defaults to 'api' if omitted. Use 'zapier', 'make', 'n8n', etc. to identify your integration.

location_id

string

Example: 1234567890

collaborators

string[] · maxItems: 3

Example: ["therock","kevinhart4real"]

object[]

Example: [{"username":"therock","x":0.5,"y":0.8}]

hashtag_set

string

Example: Fitness Brand

hashtag_set_id

string

Id of a saved hashtag set to apply. Same behavior as hashtag_set; pass one or the other.

hashtag_placement

string · enum

Enum values:

caption_append

first_comment

Default: caption_append

hashtag_platforms

string[]

Optional subset of the post's selected platforms to apply the set to (e.g. only ["instagram", "tiktok"]). Defaults to all selected platforms.

object

YouTube Shorts options. Only applies when type is reel and youtube is among the selected accounts.

object

Instagram Reel options

object

Facebook options

object

LinkedIn Profile options

object

LinkedIn Company Page options

object

TikTok options

object

X (Twitter) options

object

Bluesky options

object

Mastodon options

object

Create and publish a post immediately › Responses

Post created and queued for immediate publishing

Post

POST/posts/create-and-publish

curl /posts/create-and-publish \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "content": {
    "default": "Hello world!",
    "instagram": "Hello from IG! #awesome"
  },
  "accounts": [
    "string"
  ],
  "type": "post",
  "media": [
    "string"
  ],
  "media_urls": [
    "https://www.example.com/path/to/resource"
  ],
  "schedule_at": "2024-08-25T15:00:00Z",
  "publish_now": true,
  "link_url": "https://goodlightai.com/blog/new-feature",
  "link_title": "link_title",
  "link_description": "link_description",
  "link_thumbnail_url": "https://www.example.com/path/to/resource",
  "source": "source",
  "location_id": "1234567890",
  "collaborators": [
    "therock",
    "kevinhart4real"
  ],
  "user_tags": [
    {
      "username": "therock",
      "x": 0.5,
      "y": 0.8
    }
  ],
  "hashtag_set": "Fitness Brand",
  "hashtag_set_id": "hashtag_set_id",
  "hashtag_placement": "caption_append",
  "hashtag_platforms": [
    "string"
  ],
  "pinterest": {
    "board_id": "board_id",
    "title": "title",
    "link": "link",
    "video_cover": "video_cover",
    "alt_text": "alt_text"
  },
  "youtube": {
    "title": "title",
    "tags": [
      "string"
    ],
    "privacy_status": "public",
    "category_id": "category_id",
    "made_for_kids": false,
    "notify_subscribers": false,
    "contains_synthetic_media": false,
    "first_comment": "first_comment"
  },
  "instagram": {
    "share_to_feed": false,
    "thumbnail_type": "from-video",
    "thumb_offset": 0,
    "cover_url": "cover_url",
    "audio_id": "587784541076604",
    "audio_volume": 100,
    "video_volume": 100,
    "first_comment": "first_comment",
    "is_trial_reel": false,
    "trial_graduation_strategy": "MANUAL"
  },
  "facebook": {
    "first_comment": "first_comment"
  },
  "linkedin": {
    "first_comment": "first_comment"
  },
  "linkedin_page": {
    "first_comment": "first_comment"
  },
  "tiktok": {
    "privacy_level": "PUBLIC_TO_EVERYONE",
    "disable_comment": false,
    "disable_duet": false,
    "disable_stitch": false,
    "video_cover_timestamp_ms": 0,
    "is_aigc": false,
    "brand_content_toggle": false,
    "brand_organic_toggle": false,
    "auto_add_music": false
  },
  "x": {
    "reply_settings": "",
    "paid_partnership": false,
    "made_with_ai": false,
    "thread_parts": [
      {
        "text": "1/3 — our results are in 👇",
        "media_ids": [
          "12345"
        ]
      },
      {
        "text": "2/3 — grab your free pick here: https://example.com/signup"
      },
      {
        "text": "3/3 — and here'\''s the slip 🎁",
        "media_ids": [
          "12346"
        ]
      }
    ]
  },
  "bluesky": {
    "thread_parts": [
      {
        "text": "1/3 — our results are in 👇"
      },
      {
        "text": "2/3 — read the full writeup: https://example.com/post"
      },
      {
        "text": "3/3 — thanks for reading! #buildinpublic"
      }
    ]
  },
  "mastodon": {
    "thread_parts": [
      {
        "text": "1/3 — our picks are in 👇"
      },
      {
        "text": "2/3 — read the full writeup: https://example.com/post"
      },
      {
        "text": "3/3 — thanks for reading! #fediverse"
      }
    ]
  },
  "google_business": {
    "topic_type": "STANDARD",
    "cta": {
      "actionType": "LEARN_MORE",
      "url": "https://www.example.com/path/to/resource"
    },
    "event": {
      "title": "title",
      "schedule": {
        "startDate": {
          "year": 0,
          "month": 0,
          "day": 0
        },
        "startTime": {
          "hours": 0,
          "minutes": 0
        },
        "endDate": {
          "year": 0,
          "month": 0,
          "day": 0
        },
        "endTime": {
          "hours": 0,
          "minutes": 0
        }
      }
    },
    "offer": {
      "couponCode": "couponCode",
      "redeemOnlineUrl": "https://www.example.com/path/to/resource",
      "termsConditions": "termsConditions"
    }
  }
}'

Example Request Body

{
  "content": {
    "default": "Hello world!",
    "instagram": "Hello from IG! #awesome"
  },
  "accounts": [
    "string"
  ],
  "type": "post",
  "media": [
    "string"
  ],
  "media_urls": [
    "https://www.example.com/path/to/resource"
  ],
  "schedule_at": "2024-08-25T15:00:00Z",
  "publish_now": true,
  "link_url": "https://goodlightai.com/blog/new-feature",
  "link_title": "link_title",
  "link_description": "link_description",
  "link_thumbnail_url": "https://www.example.com/path/to/resource",
  "source": "source",
  "location_id": "1234567890",
  "collaborators": [
    "therock",
    "kevinhart4real"
  ],
  "user_tags": [
    {
      "username": "therock",
      "x": 0.5,
      "y": 0.8
    }
  ],
  "hashtag_set": "Fitness Brand",
  "hashtag_set_id": "hashtag_set_id",
  "hashtag_placement": "caption_append",
  "hashtag_platforms": [
    "string"
  ],
  "pinterest": {
    "board_id": "board_id",
    "title": "title",
    "link": "link",
    "video_cover": "video_cover",
    "alt_text": "alt_text"
  },
  "youtube": {
    "title": "title",
    "tags": [
      "string"
    ],
    "privacy_status": "public",
    "category_id": "category_id",
    "made_for_kids": false,
    "notify_subscribers": false,
    "contains_synthetic_media": false,
    "first_comment": "first_comment"
  },
  "instagram": {
    "share_to_feed": false,
    "thumbnail_type": "from-video",
    "thumb_offset": 0,
    "cover_url": "cover_url",
    "audio_id": "587784541076604",
    "audio_volume": 100,
    "video_volume": 100,
    "first_comment": "first_comment",
    "is_trial_reel": false,
    "trial_graduation_strategy": "MANUAL"
  },
  "facebook": {
    "first_comment": "first_comment"
  },
  "linkedin": {
    "first_comment": "first_comment"
  },
  "linkedin_page": {
    "first_comment": "first_comment"
  },
  "tiktok": {
    "privacy_level": "PUBLIC_TO_EVERYONE",
    "disable_comment": false,
    "disable_duet": false,
    "disable_stitch": false,
    "video_cover_timestamp_ms": 0,
    "is_aigc": false,
    "brand_content_toggle": false,
    "brand_organic_toggle": false,
    "auto_add_music": false
  },
  "x": {
    "reply_settings": "",
    "paid_partnership": false,
    "made_with_ai": false,
    "thread_parts": [
      {
        "text": "1/3 — our results are in 👇",
        "media_ids": [
          "12345"
        ]
      },
      {
        "text": "2/3 — grab your free pick here: https://example.com/signup"
      },
      {
        "text": "3/3 — and here's the slip 🎁",
        "media_ids": [
          "12346"
        ]
      }
    ]
  },
  "bluesky": {
    "thread_parts": [
      {
        "text": "1/3 — our results are in 👇"
      },
      {
        "text": "2/3 — read the full writeup: https://example.com/post"
      },
      {
        "text": "3/3 — thanks for reading! #buildinpublic"
      }
    ]
  },
  "mastodon": {
    "thread_parts": [
      {
        "text": "1/3 — our picks are in 👇"
      },
      {
        "text": "2/3 — read the full writeup: https://example.com/post"
      },
      {
        "text": "3/3 — thanks for reading! #fediverse"
      }
    ]
  },
  "google_business": {
    "topic_type": "STANDARD",
    "cta": {
      "actionType": "LEARN_MORE",
      "url": "https://www.example.com/path/to/resource"
    },
    "event": {
      "title": "title",
      "schedule": {
        "startDate": {
          "year": 0,
          "month": 0,
          "day": 0
        },
        "startTime": {
          "hours": 0,
          "minutes": 0
        },
        "endDate": {
          "year": 0,
          "month": 0,
          "day": 0
        },
        "endTime": {
          "hours": 0,
          "minutes": 0
        }
      }
    },
    "offer": {
      "couponCode": "couponCode",
      "redeemOnlineUrl": "https://www.example.com/path/to/resource",
      "termsConditions": "termsConditions"
    }
  }
}

json

Example Responses

{
  "data": {
    "id": "id",
    "status": "draft",
    "type": "post",
    "content": {},
    "accounts": [
      "string"
    ],
    "media": {
      "key": [
        {
          "url": "url",
          "id": "id",
          "channel": "channel",
          "alt": "alt"
        }
      ]
    },
    "location_id": "location_id",
    "collaborators": [
      "string"
    ],
    "user_tags": [
      {
        "username": "username",
        "x": 0,
        "y": 0,
        "image_index": 0
      }
    ],
    "schedule_at": "2024-08-25T15:00:00Z",
    "app_url": "https://app.omnisocials.com/create-post/1024",
    "published_urls": {
      "facebook": "https://www.facebook.com/123456789/posts/987654321",
      "instagram": "https://www.instagram.com/p/Cxyz123ABC/",
      "linkedin": "https://www.linkedin.com/feed/update/urn:li:share:7191234567890",
      "x": "https://x.com/yourhandle/status/1791234567890123456"
    },
    "created_at": "2024-08-25T15:00:00Z",
    "approval_status": "approval_status",
    "errors": {
      "facebook": "Already Posted: These photos were already posted.",
      "instagram": "Instagram couldn't accept one of your images. Check that every image is JPEG/PNG, at least 320×320, has an aspect ratio between 4:5 and 1.91:1, and isn't visually flagged by Instagram. Re-upload or replace the offending image and try again."
    },
    "source": "source",
    "updated_at": "2024-08-25T15:00:00Z",
    "x": {
      "reply_settings": "",
      "paid_partnership": true,
      "made_with_ai": true,
      "thread_parts": [
        {
          "id": "id",
          "text": "text",
          "media_urls": [
            "https://www.example.com/path/to/resource"
          ]
        }
      ]
    },
    "bluesky": {
      "thread_parts": [
        {
          "id": "id",
          "text": "text",
          "media_urls": [
            "https://www.example.com/path/to/resource"
          ]
        }
      ]
    },
    "mastodon": {
      "thread_parts": [
        {
          "id": "id",
          "text": "text",
          "media_urls": [
            "https://www.example.com/path/to/resource"
          ]
        }
      ]
    },
    "instagram": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "facebook": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "linkedin": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "linkedin_page": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "youtube": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    }
  }
}

json

application/json

Publish a post immediately

POST

/posts/{id}/publish

Publish a post immediately › path Parameters

id

string · required

Publish a post immediately › Responses

Post queued for publishing

object

Media