Copy page

Guides

Creating Posts

Posts are the core resource of the OmniSocials API. A single post can target one or many connected accounts, be a feed post, story, or reel, carry media, be scheduled, and have per-platform overrides.

Minimal request

The smallest valid post is text to one account:

Code
curl -X POST https://api.omnisocials.com/v1/posts/create \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "default": "Hello from the API" },
    "accounts": ["your-account-id"]
  }'

A successful response returns the new post record with "status": "draft". Drafts are NOT published automatically. Call POST /posts/:id/publish to publish, or use POST /posts/create-and-publish to create and publish in one call.

Content

The content field accepts either a string (same text on every selected channel) or an object keyed by channel ID (per-platform text).

Flat string:

Code
{
  "content": "Same text on every channel",
  "accounts": ["channel-a", "channel-b"]
}

Per-platform:

Code
{
  "content": {
    "default": "Check out our new feature",
    "x": "New feature just shipped 🚀",
    "linkedin": "We just shipped a new feature. Here's what it does..."
  },
  "accounts": ["channel-a", "channel-b", "channel-c"]
}

The default key is the fallback for channels without an explicit override. Character limits are enforced per platform. A post that exceeds any selected platform's limit fails validation.

Accounts and channels

Pass one or more account IDs in the accounts array. Get account IDs from GET /accounts. An account ID is tied to a specific channel (e.g. a specific Instagram profile), not just a platform.

Connecting social accounts is done through OAuth in the OmniSocials dashboard, not through the API. Once connected, they are available to every API key in the workspace.

Post types

The type field selects feed post, story, or reel. It defaults to post if omitted.

Type	Description	Supported platforms
post	Regular feed post	All platforms
story	24 hour story	Instagram, Facebook, Snapchat
reel	Short-form vertical video	Instagram, Facebook, YouTube, TikTok

Stories and reels require media. Posting a story or reel without media returns 400.

Attaching media

There are two ways to attach media. Both can be combined in the same request.

1. Upload first, then reference by ID. Upload files through POST /media/upload or POST /media/upload-from-url, then pass the returned IDs in media_ids.

Code
{
  "content": { "default": "Check out these photos" },
  "accounts": ["your-account-id"],
  "media_ids": ["123", "124"]
}

2. Inline URLs. Pass external image or video URLs in media_urls. The API downloads them for you and attaches them to the post. Maximum 10 URLs.

Code
{
  "content": { "default": "Check out these photos" },
  "accounts": ["your-account-id"],
  "media_urls": [
    "https://example.com/photo1.jpg",
    "https://example.com/photo2.jpg"
  ]
}

Per-platform media. Both media_ids and media_urls accept either a flat array (same media on every selected channel) or an object keyed by channel ID. A default key inside the object is the fallback for channels without an explicit override. Pass an empty array to opt a channel out of media.

Code
{
  "media_urls": {
    "default": ["https://example.com/photo.jpg"],
    "instagram": ["https://example.com/square.jpg"],
    "pinterest": ["https://example.com/tall.jpg"],
    "x": []
  }
}

Link previews

To share a URL as a rich preview card (thumbnail + title + description) on platforms that support it, pass link_url on the post body. This is what LinkedIn calls an "article share" and what Facebook calls a "link post". Without it, a URL in the post text just renders as plain text and no preview card is generated.

Code
{
  "content": "Check out our latest write-up",
  "accounts": ["your-linkedin-account-id", "your-facebook-account-id"],
  "link_url": "https://example.com/blog/new-feature",
  "link_title": "New Feature Launch",
  "link_description": "What it does and why it matters."
}

Field	Required	Notes
link_url	yes	Must be a valid http(s) URL. Switching the post into link-share mode.
link_title	no	Used by LinkedIn directly. Facebook ignores it and fetches the page's OG title server-side.
link_description	no	Same behaviour as link_title.
link_thumbnail_url	no	Reserved for forward compatibility. Both platforms currently auto-fetch the OG image.

Supported channels. LinkedIn (linkedin, linkedin_page) and Facebook (facebook). X auto-renders preview cards from any URL in the tweet body, so link_url is not needed there. Other channels (Instagram, TikTok, etc.) ignore link_url and post the text as-is.

Media vs link share. LinkedIn and Facebook both treat media posts and link-share posts as mutually exclusive. If a request includes both media_urls/media_ids and link_url, media wins and link_url is ignored for those channels.

Scheduling

To schedule a post, add scheduled_at as an ISO 8601 timestamp in UTC. OmniSocials publishes within a 1 minute window of the requested time.

Code
{
  "content": { "default": "Friday update" },
  "accounts": ["your-account-id"],
  "scheduled_at": "2026-04-18T14:00:00Z"
}

Scheduled posts move from draft to scheduled to posted automatically. You can also schedule a post by creating a draft and calling PUT /posts/:id to set scheduled_at later.

Platform-specific options

Some platforms support fields that do not apply anywhere else (Pinterest board IDs, YouTube privacy settings, TikTok comment controls, etc.). Pass these as top-level keys on the request body, using the channel ID as the key name.

Code
{
  "content": { "default": "New pin" },
  "accounts": ["your-pinterest-account-id"],
  "media_urls": ["https://example.com/pin.jpg"],
  "pinterest": {
    "board_id": "123456789",
    "title": "Spring inspiration",
    "link": "https://example.com/spring",
    "alt_text": "Pastel-toned flower bouquet on a marble table"
  }
}

See the Platforms section for a per-platform breakdown of supported options.

Publishing

Draft posts do nothing until you publish them. Three ways to publish:

1. Create and publish in one call. Use POST /posts/create-and-publish with the same body as /posts/create.
2. Publish an existing draft. POST /posts/:id/publish. No body required.
3. Schedule it. Set scheduled_at on creation. The platform publishes automatically at that time.

Successful publish returns "status": "posted" and populates the platform-specific URL fields (e.g. linkedin_posted_url, instagram_posted_url).

Updating and deleting

Only drafts and scheduled posts can be updated. PUT /posts/:id accepts any fields from the create body. Posted posts are immutable. To change a live post, delete it and recreate.

DELETE /posts/:id removes the post from OmniSocials. For posted posts, this also attempts to delete the post from the underlying platform (where supported). For scheduled posts, it cancels the scheduled publish.

Post statuses

Status	Meaning
draft	Created but not published or scheduled
scheduled	Waiting to be published at scheduled_at
posted	Successfully published to the platform
partially_posted	Published to some but not all selected channels (check failed_platforms)
failed	Publish attempt failed on every selected channel

Failed posts include a failed_platforms array with one entry per channel explaining why. Retry with POST /posts/:id/retry-failed-platforms.