Publish to Social

Publish images or videos directly to connected social accounts

Published ·Updated

POST
/v1/social/publish
curl -X POST "https://api.orshot.com/v1/social/publish" \
  -H "Authorization: Bearer <ORSHOT_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": [],
    "platforms": [],
    "content": "<CONTENT>",
    "media_url": "<MEDIA_URL>"
  }'

Publish content to your connected social media accounts. Use this when you already have a media URL (e.g., from a previous render) and want to post it without rendering again.

To publish as part of a render in a single call, use the publish parameter on Render from Studio Template instead.

Endpoint#

POST /social/publish#

Endpoint
https://api.orshot.com/v1/social/publish

Request Example#

JavaScript
await fetch("https://api.orshot.com/v1/social/publish", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
  body: JSON.stringify({
    accounts: [1, 2],
    content: "Check out our latest design!",
    media_url: "https://storage.orshot.com/.../image.png",
  }),
});

Find your account IDs using the List Social Accounts endpoint. In the dashboard, open Social Posting → Accounts, then use Copy ID in an account's ⋯ menu.

Choosing when it goes out#

One field decides this: status. It takes three values: published, draft and scheduled. The post endpoints report the same values. The publish response itself reports a draft as drafted.

statusWhat happens
publishedPosts immediately. This is the default when you omit status
draftHeld by Orshot. Reaches no platform until you publish it explicitly
scheduledQueued for scheduled_for. Requires that field

Schedule a Post#

JavaScript
await fetch("https://api.orshot.com/v1/social/publish", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
  body: JSON.stringify({
    accounts: [1],
    content: "This will be posted later!",
    media_url: "https://storage.orshot.com/.../image.png",
    status: "scheduled",
    scheduled_for: "2030-01-15T10:00:00Z",
    timezone: "America/New_York",
  }),
});

scheduled_for must be at least 60 seconds in the future, and is only valid with status: "scheduled" — pairing it with a draft or an immediate post is rejected rather than quietly ignored.

Before an account is connected#

A draft or scheduled post does not need a connected account. Send platforms (required, at least one) instead of accounts and it is saved with needs_accounts: true; it goes out once an account for those platforms is connected and the post is given its ids (see Update a post). Free workspaces can hold 50 such posts. When the workspace already has an account on every platform named, the post is not saved: the response is 422 with code: "accounts_required" and the account ids to pass.

JavaScript
await fetch("https://api.orshot.com/v1/social/publish", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    content: "Five new colorways, same fit you love.",
    media_url: "https://example.com/image.png",
    platforms: ["instagram", "tiktok"],
    status: "scheduled",
    scheduled_for: "2030-01-15T14:00:00Z",
  }),
});
// → { data: { post_id: 2160, status: "scheduled", platforms: [], needs_accounts: true, post: { ... } } }

Publishing right away (status: "published") always needs accounts. Without them the request is refused with 422 and code: "no_accounts".

Save as Draft#

JavaScript
await fetch("https://api.orshot.com/v1/social/publish", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
  body: JSON.stringify({
    accounts: [1, 2, 3],
    content: "Draft post — will publish later from the dashboard",
    media_url: "https://storage.orshot.com/.../image.png",
    status: "draft",
  }),
});

A draft is held by Orshot and reaches no platform until you publish it. From there you can read it back, edit it, publish it or discard it — see List Social Posts for finding a post's ID.

Platform-Specific Options#

JavaScript
await fetch("https://api.orshot.com/v1/social/publish", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
  body: JSON.stringify({
    accounts: [1, 2, 3],
    content: "New product launch!",
    media_url: "https://storage.orshot.com/.../image.png",
    platformOptions: {
      "1": { firstComment: "Follow us for more updates!" },
      "2": { title: "Product Launch", link: "https://acme.com/launch" },
    },
    tiktokSettings: { autoAddMusic: true },
    tags: ["launch"],
  }),
});

Request Parameters#

ParameterTypeRequiredDescription
accountsArrayFor publishedAccount IDs to publish to (see List Social Accounts). A draft or scheduled post may leave it out and name platforms instead
platformsArrayNoPlatform ids (instagram, tiktok, ...) for a draft or scheduled post saved before any account is connected. Ignored when accounts is sent
contentStringNoCaption/text for the post (max 5000 characters). Each platform has a lower limit. See Caption limits
media_urlStringNoURL of the image or video to publish
media_urlsArrayNoMultiple media URLs for carousel posts (use instead of media_url)
statusStringNopublished (default), draft or scheduled — see above
scheduled_forStringNoISO 8601 timestamp, at least 60 seconds ahead. Required with status: "scheduled", invalid otherwise
timezoneStringNoIANA timezone string for scheduling (e.g., "America/New_York", "Europe/London")
platformOptionsObjectNoPer-account options keyed by account ID (see below). platform_options also accepted
tiktokSettingsObjectNoRoot-level TikTok options for photo posts. autoAddMusic: true asks TikTok to add recommended music. photoCoverIndex picks which image is the cover (default 0)
tagsArrayNoUp to 10 labels for your own reporting, e.g. ["launch"]. Each is lowercased and cut to 40 characters

Platform Options#

Pass platform-specific options keyed by account ID:

PlatformOptionDescription
LinkedInfirstCommentAuto-post a first comment
LinkedIndisableLinkPreviewDisable the link preview card
PinteresttitlePin title
PinterestlinkDestination URL for the pin
YouTubetitleVideo title (100 characters max)
YouTubevisibilitypublic (default), unlisted or private
YouTubethumbnailCustom thumbnail image URL (see below)

YouTube thumbnail. thumbnail is a public https URL to a JPEG, PNG or GIF of 2 MB or less (1280×720 is YouTube's size). It is set as the video's custom thumbnail. It works on regular videos and Shorts. A thumbnail never fails the post. If the URL is not reachable, not one of those image types or over 2 MB, the video is posted without it and that account's result carries a warning saying why. A thumbnail on any other platform is ignored with a warning.

TikTok recommended music is set at the root level via tiktokSettings, not per account — it applies to every TikTok photo post in the request.

Earlier field names#

Before status existed, timing was expressed with isDraft: true and schedule: { scheduledFor }. Both still work and need no migration. status takes precedence if you send both.

The one combination that no longer passes is isDraft: true together with a schedule — it used to be accepted and stored a draft carrying a schedule that could never fire. Say which one you mean instead.

Response Example#

JSON
{
  "data": {
    "post_id": 42,
    "status": "published",
    "platforms": [
      {
        "account_id": 1,
        "platform": "twitter",
        "username": "acmehq",
        "name": "Acme HQ",
        "status": "published",
        "url": "https://twitter.com/acmehq/status/1234567890"
      },
      {
        "account_id": 2,
        "platform": "linkedin",
        "username": "acme-inc",
        "name": "Acme Inc",
        "status": "published",
        "url": "https://linkedin.com/feed/update/urn:li:share:1234567890"
      }
    ],
    "post_ids": [42]
  }
}

Response Fields#

FieldTypeDescription
post_idIntegerUnique identifier for the post
post_idsArrayOrshot post IDs. One publish can create more than one post. post_id is the first
statusStringOverall status: published, scheduled, drafted, partial, processing, or failed
platformsArrayPer-account results
platforms[].account_idIntegerExact connected account targeted by this result
platforms[].platformStringPlatform name
platforms[].usernameStringAccount username
platforms[].nameStringAccount display name
platforms[].statusStringpublished, scheduled, drafted, failed, or an in-flight status like pending or publishing
platforms[].urlStringLink to the published post (when available)
platforms[].errorStringError message (only on failure)
platforms[].actionStringSuggested recovery action on failure (e.g. reconnect)

A partial status means some accounts succeeded and others failed. Check each platforms[].status for details. A processing status means the post is still in flight on the platforms, for example Instagram and TikTok, which publish asynchronously.

Still publishing (202)#

When a platform is slow to answer, you get 202 with status: "processing". The post keeps going. Read it with Get a Social Post after a minute. Do not send it again.

JSON
{
  "message": "Still publishing. Read the post in a minute to see how it went; do not publish it again.",
  "data": {
    "post_id": 42,
    "post_ids": [42],
    "status": "processing",
    "platforms": []
  }
}

If the publish fails on every targeted account, you get 422 with status: "failed" and the reason for each account in platforms[].error.

Format Compatibility#

Not all formats work on every platform:

FormatUnsupported Platforms
PDFEvery platform except LinkedIn
MP4, WebM, GIFGoogle Business
PNG, JPG, WebPYouTube (video-only platform)
AVIF, SVGTikTok (JPEG, PNG or WebP only)
No media (caption only)Instagram, TikTok, Pinterest, YouTube

If some accounts are incompatible with the media format, they are skipped and returned with status: "failed" and a reason in the error field. A draft can be saved without media and given media later.

Caption limits#

Each platform caps the caption. A caption over the limit fails on that account.

PlatformLimit (characters)
X280 (each link counts as 23)
Instagram2200
LinkedIn3000
TikTok2200 for video, 90 for photo posts
Pinterest800
Bluesky300
Threads500
Telegram1024 with media
Google BusinessAbout 1500
Discord2000

X limits#

X charges for every post sent through its API, and charges more for a post with a link. Each connected X account includes:

LimitPer X accountResets
Posts with a link25 a month ($39 and $99 plans), 80 ($160 and $280), 100 ($349 and up)The 1st of each month, 00:00 UTC
Posts of any kind15 a day00:00 UTC

A link is any URL or domain in the text, such as https://example.com or example.com. Posts without a link do not use the monthly allowance. A post counts in the month and day it goes out, so a scheduled post counts at its scheduled time. Drafts count nothing until they are scheduled or published.

Every X result in platforms carries the account's limits after the post, and a note once 5 or fewer link posts are left:

JSON
{
  "account_id": 63,
  "platform": "twitter",
  "status": "published",
  "limits": {
    "link_posts": { "used": 21, "limit": 25, "left": 4, "resets_at": "2026-12-01T00:00:00.000Z" },
    "posts_today": { "used": 3, "limit": 15, "left": 12, "resets_at": "2026-11-20T00:00:00.000Z" }
  },
  "note": "X account jornal has 4 of 25 posts with a link left this month (resets Dec 1)."
}

When an X account is over a limit, the X part of the post is left out with code: "x_link_limit" or code: "x_daily_limit", and the other accounts still get the post. A post that only goes to that X account answers 429 with the same code. List accounts shows each X account's limits before you post.

Rate Limits#

This endpoint is rate limited to 20 requests per minute per workspace. Rate limit headers are included in every response:

HeaderDescription
X-RateLimit-LimitMaximum requests per minute
X-RateLimit-RemainingRemaining requests in the current window
Retry-AfterSeconds to wait (only on 429 responses)

Error Responses#

CodeDescription
400No accounts and no platforms
400Content exceeds 5000 characters
400Invalid scheduled_for timestamp. The message names schedule.scheduledFor
400scheduled_for must be at least 60 seconds ahead
400No valid connected accounts found for the given IDs, or the accounts need to be reconnected
401Invalid or expired API key
403Missing Authorization header
403Social publishing requires a paid plan
422code: "no_accounts": publishing now without accounts. Save the post as a draft or schedule it, or connect an account
422No compatible platforms for the media format
422Publish attempted but failed on every targeted account
429Rate limit exceeded
429code: "waiting_posts_limit": a Free workspace already holds 50 posts without an account
429code: "x_link_limit": the X account used its 25 posts with a link this month. Post without the link, or schedule it for next month
429code: "x_daily_limit": the X account sent 50 posts today. Schedule it for tomorrow

Errors about accounts and plans carry a code and an action ({ "label": "Connect account", "path": "/socials/accounts" }) beside error and message, so a client can offer the next step.

Was this page helpful?

Ready to automate?

Start rendering images, PDFs and videos from your templates in under 2 minutes. Free plan, no credit card.

Get your API key
  • Image, PDF and video generation via API
  • Visual editor with AI and smart layouts
  • Zapier, Make, MCP and 40+ integrations
  • White-label embed for your own app
  • 100 free credits a month, no credit card required