Publish to Social
Publish images or videos directly to connected social accounts
Published ·Updated
/v1/social/publishcurl -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>"
}'const res = 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": [],
"platforms": [],
"content": "<CONTENT>",
"media_url": "<MEDIA_URL>"
}),
});
const data = await res.json();import requests
response = requests.post(
"https://api.orshot.com/v1/social/publish",
headers={"Authorization": "Bearer <ORSHOT_API_KEY>"},
json={
"accounts": [],
"platforms": [],
"content": "<CONTENT>",
"media_url": "<MEDIA_URL>"
},
)
data = response.json()$ch = curl_init("https://api.orshot.com/v1/social/publish");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer <ORSHOT_API_KEY>",
"Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
"accounts" => [],
"platforms" => [],
"content" => "<CONTENT>",
"media_url" => "<MEDIA_URL>"
]));
$data = json_decode(curl_exec($ch), true);
curl_close($ch);require "net/http"
require "json"
uri = URI("https://api.orshot.com/v1/social/publish")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer <ORSHOT_API_KEY>"
req["Content-Type"] = "application/json"
req.body = {
"accounts": [],
"platforms": [],
"content": "<CONTENT>",
"media_url": "<MEDIA_URL>"
}.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)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#
https://api.orshot.com/v1/social/publishRequest Example#
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.
status | What happens |
|---|---|
published | Posts immediately. This is the default when you omit status |
draft | Held by Orshot. Reaches no platform until you publish it explicitly |
scheduled | Queued for scheduled_for. Requires that field |
Schedule a Post#
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.
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#
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#
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#
| Parameter | Type | Required | Description |
|---|---|---|---|
accounts | Array | For published | Account IDs to publish to (see List Social Accounts). A draft or scheduled post may leave it out and name platforms instead |
platforms | Array | No | Platform ids (instagram, tiktok, ...) for a draft or scheduled post saved before any account is connected. Ignored when accounts is sent |
content | String | No | Caption/text for the post (max 5000 characters). Each platform has a lower limit. See Caption limits |
media_url | String | No | URL of the image or video to publish |
media_urls | Array | No | Multiple media URLs for carousel posts (use instead of media_url) |
status | String | No | published (default), draft or scheduled — see above |
scheduled_for | String | No | ISO 8601 timestamp, at least 60 seconds ahead. Required with status: "scheduled", invalid otherwise |
timezone | String | No | IANA timezone string for scheduling (e.g., "America/New_York", "Europe/London") |
platformOptions | Object | No | Per-account options keyed by account ID (see below). platform_options also accepted |
tiktokSettings | Object | No | Root-level TikTok options for photo posts. autoAddMusic: true asks TikTok to add recommended music. photoCoverIndex picks which image is the cover (default 0) |
tags | Array | No | Up 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:
| Platform | Option | Description |
|---|---|---|
firstComment | Auto-post a first comment | |
disableLinkPreview | Disable the link preview card | |
title | Pin title | |
link | Destination URL for the pin | |
| YouTube | title | Video title (100 characters max) |
| YouTube | visibility | public (default), unlisted or private |
| YouTube | thumbnail | Custom 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#
{
"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#
| Field | Type | Description |
|---|---|---|
post_id | Integer | Unique identifier for the post |
post_ids | Array | Orshot post IDs. One publish can create more than one post. post_id is the first |
status | String | Overall status: published, scheduled, drafted, partial, processing, or failed |
platforms | Array | Per-account results |
platforms[].account_id | Integer | Exact connected account targeted by this result |
platforms[].platform | String | Platform name |
platforms[].username | String | Account username |
platforms[].name | String | Account display name |
platforms[].status | String | published, scheduled, drafted, failed, or an in-flight status like pending or publishing |
platforms[].url | String | Link to the published post (when available) |
platforms[].error | String | Error message (only on failure) |
platforms[].action | String | Suggested 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.
{
"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:
| Format | Unsupported Platforms |
|---|---|
| Every platform except LinkedIn | |
| MP4, WebM, GIF | Google Business |
| PNG, JPG, WebP | YouTube (video-only platform) |
| AVIF, SVG | TikTok (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.
| Platform | Limit (characters) |
|---|---|
| X | 280 (each link counts as 23) |
| 2200 | |
| 3000 | |
| TikTok | 2200 for video, 90 for photo posts |
| 800 | |
| Bluesky | 300 |
| Threads | 500 |
| Telegram | 1024 with media |
| Google Business | About 1500 |
| Discord | 2000 |
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:
| Limit | Per X account | Resets |
|---|---|---|
| Posts with a link | 25 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 kind | 15 a day | 00: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:
{
"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:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests per minute |
X-RateLimit-Remaining | Remaining requests in the current window |
Retry-After | Seconds to wait (only on 429 responses) |
Error Responses#
| Code | Description |
|---|---|
| 400 | No accounts and no platforms |
| 400 | Content exceeds 5000 characters |
| 400 | Invalid scheduled_for timestamp. The message names schedule.scheduledFor |
| 400 | scheduled_for must be at least 60 seconds ahead |
| 400 | No valid connected accounts found for the given IDs, or the accounts need to be reconnected |
| 401 | Invalid or expired API key |
| 403 | Missing Authorization header |
| 403 | Social publishing requires a paid plan |
| 422 | code: "no_accounts": publishing now without accounts. Save the post as a draft or schedule it, or connect an account |
| 422 | No compatible platforms for the media format |
| 422 | Publish attempted but failed on every targeted account |
| 429 | Rate limit exceeded |
| 429 | code: "waiting_posts_limit": a Free workspace already holds 50 posts without an account |
| 429 | code: "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 |
| 429 | code: "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.
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