Posts

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

List posts

GET

https://api.omnisocials.com/v1

/posts

List posts › query Parameters

status

string · enum

Filter by status. published and the legacy alias posted are equivalent. in_approval matches posts waiting for a reviewer in an approval workflow. rejected matches posts an approver declined via POST /posts/{id}/reject. warning matches partially failed posts (some platforms published, some failed) — these do NOT match failed, which only matches posts where every platform failed.

Enum values:

draft

in_approval

scheduled

posting

published

failed

warning

rejected

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 https://api.omnisocials.com/v1/posts \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "id",
      "status": "draft",
      "type": "post",
      "story_slides": {
        "key": [
          {
            "index": 0,
            "native_post_id": "native_post_id",
            "url": "url",
            "media_url": "media_url",
            "media_type": "image",
            "published_at": "2024-08-25T15:00:00Z"
          }
        ]
      },
      "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"
      },
      "retry_of": "retry_of",
      "retries": [
        "string"
      ],
      "created_at": "2024-08-25T15:00:00Z",
      "approval_status": "none",
      "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"
            ]
          }
        ]
      },
      "threads": {
        "location": {
          "id": "17841400000000000",
          "name": "Griffith Observatory",
          "address": "address",
          "city": "Los Angeles",
          "country": "United States"
        },
        "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",
          "pending": true,
          "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",
          "pending": true,
          "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",
          "pending": true,
          "comment_id": "comment_id",
          "url": "url",
          "error": "error",
          "posted_at": "2024-08-25T15:00:00Z"
        },
        "carousel_as_images": true
      },
      "linkedin_page": {
        "first_comment": "first_comment",
        "first_comment_result": {
          "status": "posted",
          "pending": true,
          "comment_id": "comment_id",
          "url": "url",
          "error": "error",
          "posted_at": "2024-08-25T15:00:00Z"
        },
        "carousel_as_images": true
      },
      "youtube": {
        "first_comment": "first_comment",
        "first_comment_result": {
          "status": "posted",
          "pending": true,
          "comment_id": "comment_id",
          "url": "url",
          "error": "error",
          "posted_at": "2024-08-25T15:00:00Z"
        }
      },
      "tiktok": {
        "title": "title",
        "first_comment": "first_comment",
        "first_comment_result": {
          "status": "posted",
          "pending": true,
          "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

https://api.omnisocials.com/v1

/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 (views/likes/comments/shares, plus average_time_watched, full_video_watched_rate, total_time_watched, favorites, reach when the workspace enabled TikTok comments — the Business API authorization), 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 for most platforms — expect a few seconds of latency across many platforms. X is the exception: because X's API bills every returned post, X results may be served from a snapshot up to 24 hours old. The snapshot refreshes immediately after you publish to X through OmniSocials, so your own new posts always appear. 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). When omitted, X returns up to 10 (its API bills per returned post); pass an explicit limit to get more from X.

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

https://api.omnisocials.com/v1

/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 https://api.omnisocials.com/v1/posts/:id \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "id",
    "status": "draft",
    "type": "post",
    "story_slides": {
      "key": [
        {
          "index": 0,
          "native_post_id": "native_post_id",
          "url": "url",
          "media_url": "media_url",
          "media_type": "image",
          "published_at": "2024-08-25T15:00:00Z"
        }
      ]
    },
    "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"
    },
    "retry_of": "retry_of",
    "retries": [
      "string"
    ],
    "created_at": "2024-08-25T15:00:00Z",
    "approval_status": "none",
    "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"
          ]
        }
      ]
    },
    "threads": {
      "location": {
        "id": "17841400000000000",
        "name": "Griffith Observatory",
        "address": "address",
        "city": "Los Angeles",
        "country": "United States"
      },
      "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",
        "pending": true,
        "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",
        "pending": true,
        "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",
        "pending": true,
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      },
      "carousel_as_images": true
    },
    "linkedin_page": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "pending": true,
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      },
      "carousel_as_images": true
    },
    "youtube": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "pending": true,
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "tiktok": {
      "title": "title",
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "pending": true,
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    }
  }
}

json

application/json

Delete a post

DELETE

https://api.omnisocials.com/v1

/posts/{id}

Delete a post › path Parameters

id

string · required

Delete a post › Responses

Post deleted

No data returned

Update a post

PATCH

https://api.omnisocials.com/v1

/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). For type 'story', each item is one slide (max 10, published in order).

CreatePostRequest/properties/media

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, Pinterest, Instagram (images) and LinkedIn (images). 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

New publish time (ISO 8601, must be in the future). A draft becomes scheduled. A post that is waiting for approval keeps its in_approval status and only its time moves. Send null to unschedule back to draft.

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 constraints: carousels hard-cap at 5 images — attaching more responds 400 validation_error at create/schedule time. Pinterest's v5 API also 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. Both checks 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

CreatePostRequest/properties/threads

Threads options: thread mode via thread_parts, location tag via location_id.

CreatePostRequest/properties/google_business

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.

object

LinkedIn Profile options. MERGED into the stored options: keys you omit keep their current value. first_comment: a string sets it, null/empty clears it. carousel_as_images: true publishes 2+ images as a plain image gallery, false/null reverts to the default PDF document carousel.

object

LinkedIn Company Page options. Same merge semantics as linkedin.

linkedin_poll

object | null

Replaced wholesale — send the full desired state for BOTH channels, not just the one you're changing. Pass null (or { "linkedin": null, "linkedin_page": null }) to clear every poll and revert to normal posts; set just one channel's key to null to clear only that channel's poll while keeping the other.

Update a post › Responses

Post updated

Post

PATCH/posts/{id}

curl https://api.omnisocials.com/v1/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",
    "is_ai_generated": false
  },
  "tiktok": {
    "title": "title",
    "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,
    "first_comment": "first_comment"
  },
  "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"
      }
    ]
  },
  "threads": {
    "location_id": "17841400000000000",
    "location": {
      "id": "17841400000000000",
      "name": "Griffith Observatory",
      "address": "address",
      "city": "Los Angeles",
      "country": "United States"
    },
    "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"
      }
    ]
  },
  "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"
    }
  },
  "linkedin": {
    "first_comment": "first_comment",
    "carousel_as_images": false
  },
  "linkedin_page": {
    "first_comment": "first_comment",
    "carousel_as_images": false
  },
  "linkedin_poll": {
    "linkedin": {
      "question": "question",
      "options": [
        "string"
      ],
      "duration": "ONE_DAY"
    },
    "linkedin_page": {
      "question": "question",
      "options": [
        "string"
      ],
      "duration": "ONE_DAY"
    }
  }
}'

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",
    "is_ai_generated": false
  },
  "tiktok": {
    "title": "title",
    "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,
    "first_comment": "first_comment"
  },
  "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"
      }
    ]
  },
  "threads": {
    "location_id": "17841400000000000",
    "location": {
      "id": "17841400000000000",
      "name": "Griffith Observatory",
      "address": "address",
      "city": "Los Angeles",
      "country": "United States"
    },
    "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"
      }
    ]
  },
  "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"
    }
  },
  "linkedin": {
    "first_comment": "first_comment",
    "carousel_as_images": false
  },
  "linkedin_page": {
    "first_comment": "first_comment",
    "carousel_as_images": false
  },
  "linkedin_poll": {
    "linkedin": {
      "question": "question",
      "options": [
        "string"
      ],
      "duration": "ONE_DAY"
    },
    "linkedin_page": {
      "question": "question",
      "options": [
        "string"
      ],
      "duration": "ONE_DAY"
    }
  }
}

json

Example Responses

{
  "data": {
    "id": "id",
    "status": "draft",
    "type": "post",
    "story_slides": {
      "key": [
        {
          "index": 0,
          "native_post_id": "native_post_id",
          "url": "url",
          "media_url": "media_url",
          "media_type": "image",
          "published_at": "2024-08-25T15:00:00Z"
        }
      ]
    },
    "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"
    },
    "retry_of": "retry_of",
    "retries": [
      "string"
    ],
    "created_at": "2024-08-25T15:00:00Z",
    "approval_status": "none",
    "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"
          ]
        }
      ]
    },
    "threads": {
      "location": {
        "id": "17841400000000000",
        "name": "Griffith Observatory",
        "address": "address",
        "city": "Los Angeles",
        "country": "United States"
      },
      "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",
        "pending": true,
        "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",
        "pending": true,
        "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",
        "pending": true,
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      },
      "carousel_as_images": true
    },
    "linkedin_page": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "pending": true,
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      },
      "carousel_as_images": true
    },
    "youtube": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "pending": true,
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "tiktok": {
      "title": "title",
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "pending": true,
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    }
  }
}

json

application/json

Create a new post

POST

https://api.omnisocials.com/v1

/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.

Stories (type: "story"): 1 to 10 media items. Each item is one slide and publishes as its own story on Instagram and Facebook, in the order given. Per-platform objects can give each platform its own slide list. Videos max 60 s per slide. After publishing, story_slides lists every slide's native id and URL; published_urls keeps the first slide.

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

bluesky — max 4 images per post; cannot mix images and video
mastodon — max 4 media items per post; cannot mix images and video
x — max 4 images per post; cannot mix images and video
instagram — max 10 items in a carousel; images and videos can be mixed in one carousel
threads — max 10 items in a carousel; images and videos can be mixed in one carousel
tiktok — max 35 items per photo post; cannot mix photos and videos in one post
pinterest — max 5 images per carousel pin (videos are exempt — they publish as single video pins)
facebook, linkedin, linkedin_page — cannot mix images and video in one post (their APIs accept images only or a single video)

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." } } (Pinterest wording: "Pinterest carousel pins support a maximum of 5 images. Please remove some images and try again."). 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, 16 GB with Premium / Premium+ (in practice bounded by the 1 GB URL-ingest / 100 MB direct-upload limits) · 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 free tier, 125 min when the connected X account has Premium or Premium+ (tier detected automatically; reconnect X after upgrading) · 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.

X link-post credits: X's API bills posts whose text contains a URL at a premium ($0.20 vs $0.015), and OmniSocials passes that fee through as prepaid credits at X's rate card (20 credits per URL-containing tweet; threads are billed per part that contains a link). Credits are purchased in euros: 1 credit = €0.01, top-ups of €5-500 in the dashboard. When a create/schedule targets X and the text contains a URL, the 201 response includes a warnings array entry (code: "x_url_post_credits") with credits_required, the company's current credits_balance, and the enforcement state. At publish time the credits are debited; if the balance can't cover it, the X target alone fails with an INSUFFICIENT_CREDITS message in its error_message (other platforms in the post publish normally) and the post can be retried after topping up in Settings → Organisation → Billing → Credits. Posts without links, analytics, and everything else on X stay free.

Schedule-time gate: every scheduled X link post reserves its cost until it publishes. Scheduling (or publishing) a new X link post that would push the total reserved past the balance is refused with 402 x_credits_insufficient (details carries credits_required, credits_balance, credits_reserved). Drafts are never gated; posts publishing before the enforcement date are never gated.

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. A 'story' takes 1 to 10 media items: each item is one slide, published as its own story in the order given (Instagram and Facebook have no multi-slide story container). More than 10 returns 400 validation_error.

Enum values:

post

story

reel

Default: post

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, TikTok with comments enabled) — 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.

approval_workflow_id

string

Id of an approval workflow (see GET /approval-workflows) to route this post through. The post is created with status in_approval and approval_status: pending instead of scheduled: the workflow's first-step approvers are notified (dashboard badge, email, Slack), they review it in the dashboard's Approvals page, and it publishes at schedule_at only once the last step approves it (dashboard, or POST /posts/{id}/approve). A rejection leaves it rejected. Requires schedule_at; cannot be combined with publish_now. Errors: 404 workflow_not_found (not a workflow of this company/workspace), 400 validation_error (missing schedule_at, publish_now set, or the workflow has no approvers on its first step).

Example: 57823504

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

linkedin_poll

object | null

Non-sponsored LinkedIn poll(s) — independent per channel, keyed by linkedin (personal profile) / linkedin_page (company page). A poll is mutually exclusive with media and a link share on that channel's post — a poll takes priority over both at publish time. Requires content.linkedin (or content.default) as that channel's caption/commentary; the poll itself only carries the question/options/duration.

object

TikTok options

object

X (Twitter) options

object

Bluesky options

object

Mastodon options

object

Threads options: thread mode via thread_parts, location tag via location_id.

object

Create a new post › Responses

Post created

Post

object[]

Non-blocking notices about this post. Currently only x_url_post_credits (X link-post fee pass-through).

POST/posts/create

curl https://api.omnisocials.com/v1/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"
  ],
  "approval_workflow_id": "57823504",
  "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",
    "is_ai_generated": false
  },
  "facebook": {
    "first_comment": "first_comment"
  },
  "linkedin": {
    "first_comment": "first_comment",
    "carousel_as_images": false
  },
  "linkedin_page": {
    "first_comment": "first_comment",
    "carousel_as_images": false
  },
  "linkedin_poll": {
    "linkedin": {
      "question": "question",
      "options": [
        "string"
      ],
      "duration": "ONE_DAY"
    },
    "linkedin_page": {
      "question": "question",
      "options": [
        "string"
      ],
      "duration": "ONE_DAY"
    }
  },
  "tiktok": {
    "title": "title",
    "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,
    "first_comment": "first_comment"
  },
  "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"
      }
    ]
  },
  "threads": {
    "location_id": "17841400000000000",
    "location": {
      "id": "17841400000000000",
      "name": "Griffith Observatory",
      "address": "address",
      "city": "Los Angeles",
      "country": "United States"
    },
    "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"
      }
    ]
  },
  "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"
  ],
  "approval_workflow_id": "57823504",
  "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",
    "is_ai_generated": false
  },
  "facebook": {
    "first_comment": "first_comment"
  },
  "linkedin": {
    "first_comment": "first_comment",
    "carousel_as_images": false
  },
  "linkedin_page": {
    "first_comment": "first_comment",
    "carousel_as_images": false
  },
  "linkedin_poll": {
    "linkedin": {
      "question": "question",
      "options": [
        "string"
      ],
      "duration": "ONE_DAY"
    },
    "linkedin_page": {
      "question": "question",
      "options": [
        "string"
      ],
      "duration": "ONE_DAY"
    }
  },
  "tiktok": {
    "title": "title",
    "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,
    "first_comment": "first_comment"
  },
  "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"
      }
    ]
  },
  "threads": {
    "location_id": "17841400000000000",
    "location": {
      "id": "17841400000000000",
      "name": "Griffith Observatory",
      "address": "address",
      "city": "Los Angeles",
      "country": "United States"
    },
    "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"
      }
    ]
  },
  "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",
    "story_slides": {
      "key": [
        {
          "index": 0,
          "native_post_id": "native_post_id",
          "url": "url",
          "media_url": "media_url",
          "media_type": "image",
          "published_at": "2024-08-25T15:00:00Z"
        }
      ]
    },
    "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"
    },
    "retry_of": "retry_of",
    "retries": [
      "string"
    ],
    "created_at": "2024-08-25T15:00:00Z",
    "approval_status": "none",
    "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"
          ]
        }
      ]
    },
    "threads": {
      "location": {
        "id": "17841400000000000",
        "name": "Griffith Observatory",
        "address": "address",
        "city": "Los Angeles",
        "country": "United States"
      },
      "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",
        "pending": true,
        "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",
        "pending": true,
        "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",
        "pending": true,
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      },
      "carousel_as_images": true
    },
    "linkedin_page": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "pending": true,
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      },
      "carousel_as_images": true
    },
    "youtube": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "pending": true,
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "tiktok": {
      "title": "title",
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "pending": true,
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    }
  },
  "warnings": [
    {
      "code": "x_url_post_credits",
      "message": "message",
      "credits_required": 20,
      "credits_balance": 0,
      "enforced": true,
      "enforce_from": "2026-08-14"
    }
  ]
}

json

application/json

Create and publish a post immediately

POST

https://api.omnisocials.com/v1

/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

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.

approval_workflow_id

string

Example: 57823504

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

linkedin_poll

object | null

object

TikTok options

object

X (Twitter) options

object

Bluesky options

object

Mastodon options

object

Threads options: thread mode via thread_parts, location tag via location_id.

object

Create and publish a post immediately › Responses

Post created and queued for immediate publishing

Post

POST/posts/create-and-publish

curl https://api.omnisocials.com/v1/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"
  ],
  "approval_workflow_id": "57823504",
  "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",
    "is_ai_generated": false
  },
  "facebook": {
    "first_comment": "first_comment"
  },
  "linkedin": {
    "first_comment": "first_comment",
    "carousel_as_images": false
  },
  "linkedin_page": {
    "first_comment": "first_comment",
    "carousel_as_images": false
  },
  "linkedin_poll": {
    "linkedin": {
      "question": "question",
      "options": [
        "string"
      ],
      "duration": "ONE_DAY"
    },
    "linkedin_page": {
      "question": "question",
      "options": [
        "string"
      ],
      "duration": "ONE_DAY"
    }
  },
  "tiktok": {
    "title": "title",
    "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,
    "first_comment": "first_comment"
  },
  "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"
      }
    ]
  },
  "threads": {
    "location_id": "17841400000000000",
    "location": {
      "id": "17841400000000000",
      "name": "Griffith Observatory",
      "address": "address",
      "city": "Los Angeles",
      "country": "United States"
    },
    "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"
      }
    ]
  },
  "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"
  ],
  "approval_workflow_id": "57823504",
  "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",
    "is_ai_generated": false
  },
  "facebook": {
    "first_comment": "first_comment"
  },
  "linkedin": {
    "first_comment": "first_comment",
    "carousel_as_images": false
  },
  "linkedin_page": {
    "first_comment": "first_comment",
    "carousel_as_images": false
  },
  "linkedin_poll": {
    "linkedin": {
      "question": "question",
      "options": [
        "string"
      ],
      "duration": "ONE_DAY"
    },
    "linkedin_page": {
      "question": "question",
      "options": [
        "string"
      ],
      "duration": "ONE_DAY"
    }
  },
  "tiktok": {
    "title": "title",
    "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,
    "first_comment": "first_comment"
  },
  "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"
      }
    ]
  },
  "threads": {
    "location_id": "17841400000000000",
    "location": {
      "id": "17841400000000000",
      "name": "Griffith Observatory",
      "address": "address",
      "city": "Los Angeles",
      "country": "United States"
    },
    "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"
      }
    ]
  },
  "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",
    "story_slides": {
      "key": [
        {
          "index": 0,
          "native_post_id": "native_post_id",
          "url": "url",
          "media_url": "media_url",
          "media_type": "image",
          "published_at": "2024-08-25T15:00:00Z"
        }
      ]
    },
    "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"
    },
    "retry_of": "retry_of",
    "retries": [
      "string"
    ],
    "created_at": "2024-08-25T15:00:00Z",
    "approval_status": "none",
    "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"
          ]
        }
      ]
    },
    "threads": {
      "location": {
        "id": "17841400000000000",
        "name": "Griffith Observatory",
        "address": "address",
        "city": "Los Angeles",
        "country": "United States"
      },
      "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",
        "pending": true,
        "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",
        "pending": true,
        "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",
        "pending": true,
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      },
      "carousel_as_images": true
    },
    "linkedin_page": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "pending": true,
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      },
      "carousel_as_images": true
    },
    "youtube": {
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "pending": true,
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    },
    "tiktok": {
      "title": "title",
      "first_comment": "first_comment",
      "first_comment_result": {
        "status": "posted",
        "pending": true,
        "comment_id": "comment_id",
        "url": "url",
        "error": "error",
        "posted_at": "2024-08-25T15:00:00Z"
      }
    }
  }
}

json

application/json

Publish a post immediately

POST

https://api.omnisocials.com/v1

/posts/{id}/publish

Publish a post immediately › path Parameters

id

string · required

Publish a post immediately › Responses

Post queued for publishing

object

Retry the failed platforms of a failed or partially failed post

POST

https://api.omnisocials.com/v1

/posts/{id}/retry

Re-publishes ONLY the platforms that failed, on the same post — platforms that already succeeded are never re-published. Works on posts with status failed (every platform failed) or warning (some platforms failed). The retry is processed asynchronously by the publishing queue, usually within a minute; poll GET /posts/{id} to see the outcome (status becomes published and published_urls gains the platform URL on success, or the platform's entry reappears in errors on another failure). Each platform can be retried at most 3 times; after that, create a new post. Platforms dismissed with 'ignore' in the dashboard are not retried.

Retry the failed platforms of a failed or partially failed post › path Parameters

id

string · required

Retry the failed platforms of a failed or partially failed post › Responses

Retry queued

object

Approve a post that is waiting for approval

POST

https://api.omnisocials.com/v1

/posts/{id}/approve

Approves the current step of the post's approval workflow, on behalf of the user who owns this API key. That user must be a listed approver for the workflow's CURRENT step — steps are approved in order, and a key holder who is only an approver on a later step gets forbidden until earlier steps clear. If this is the last step, the post is finalized immediately: it moves to scheduled (future schedule_at) or posting (due now or in the past). If more steps remain, the post stays in_approval and the next step's approvers are notified. Check approval_status on GET /posts/{id} first — only a post with status in_approval can be approved.

Approve a post that is waiting for approval › path Parameters

id

string · required

Approve a post that is waiting for approval › Responses

Approval recorded

object

Reject a post that is waiting for approval

POST

https://api.omnisocials.com/v1

/posts/{id}/reject

Rejects the post's approval workflow on behalf of the user who owns this API key. That user must be a listed approver for the workflow's CURRENT step. Unlike approval, a rejection stops the whole workflow immediately — not just the current step — and the post's status becomes rejected. An optional comment explaining the rejection is stored on the decision and posted into the post's review thread.

Reject a post that is waiting for approval › path Parameters

id

string · required

Reject a post that is waiting for approval › Request Body optional

comment

string · maxLength: 2000

Optional reason for the rejection, shown to the requester and other approvers.

Reject a post that is waiting for approval › Responses

Rejection recorded

object

Media