Publish a Held Post

Send a draft or scheduled post to its platforms now

Published Aug 11, 2026·Updated Oct 27, 2026

POST

/v1/social/posts/{postId}/publish

curl -X POST "https://api.orshot.com/v1/social/posts/<POST_ID>/publish" \
  -H "Authorization: Bearer <ORSHOT_API_KEY>"

const res = await fetch("https://api.orshot.com/v1/social/posts/<POST_ID>/publish", {
  method: "POST",
  headers: {
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
});

const data = await res.json();

$ch = curl_init("https://api.orshot.com/v1/social/posts/<POST_ID>/publish");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer <ORSHOT_API_KEY>",
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

require "net/http"
require "json"

uri = URI("https://api.orshot.com/v1/social/posts/<POST_ID>/publish")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer <ORSHOT_API_KEY>"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

Overview#

Publishes a draft or scheduled post immediately, to the accounts it already targets. This is the step that puts the post in front of an audience, and it cannot be undone through Orshot.

To change what goes out, edit the post first.

Endpoint

https://api.orshot.com/v1/social/posts/{postId}/publish

Request#

JavaScript

await fetch("https://api.orshot.com/v1/social/posts/512/publish", {
  method: "POST",
  headers: {
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
});

JSON

{
  "data": {
    "post": {
      "id": 512,
      "status": "published",
      "content": "Our new pricing is live.",
      "is_editable": false,
      "published_at": "2026-08-11T18:02:11.412+00:00"
    },
    "status": "published",
    "platforms": [
      {
        "account_id": 15,
        "platform": "linkedin",
        "username": "acme-inc",
        "name": "Acme Inc",
        "status": "published",
        "url": "https://linkedin.com/feed/update/urn:li:share:1234567890"
      },
      {
        "account_id": 22,
        "platform": "twitter",
        "username": "acmehq",
        "name": "Acme",
        "status": "published",
        "url": "https://twitter.com/acmehq/status/1234567890"
      }
    ]
  }
}

No request body is needed — the post already carries its caption, media and accounts.

Response Fields#

Field	Type	Description
`post`	Object	The updated post. See List Social Posts
`status`	String	Overall outcome: `published`, `processing`, `partial` or `failed`
`platforms`	Array	Per-account results
`platforms[].url`	String	Link to the live post, when the platform returns one immediately
`platforms[].error`	String	Why an account failed
`platforms[].action`	String	Suggested recovery, e.g. `reconnect` for an expired token

A processing status means every targeted platform publishes asynchronously and the post is still in flight. Sync the post to pick up the final URLs.

A partial status means some accounts succeeded and others did not — check each entry in platforms.

Error Responses#

Post already sent (400)#

JSON

{
  "error": "Only draft or scheduled posts can be published"
}

No valid accounts (400)#

JSON

{
  "error": "No valid connected accounts found"
}

Plan required (403)#

JSON

{
  "error": "Social publishing requires a paid plan",
  "code": "plan_required",
  "message": "Publishing is not included in this workspace.",
  "action": { "label": "Open workspace", "path": "" }
}

Discard in progress (409)#

JSON

{
  "error": "This post is being discarded",
  "message": "Wait for the discard to finish before changing it."
}

No account yet (422)#

JSON

{
  "error": "This post needs accounts before it can be published.",
  "code": "accounts_required",
  "message": "Edit the post with the account ids it should go to, then publish it.",
  "action": { "label": "Connect account", "path": "/socials/accounts" }
}

The post was saved with platforms and no account (needs_accounts: true). With no account connected at all the code is no_accounts instead.

Nothing to publish (422)#

The post is no longer saved with the platforms. Edit it (any change sends it again), then publish it.

JSON

{
  "code": "nothing_to_publish",
  "error": "This post has nothing to publish yet",
  "message": "The post is not saved with the platforms any more. Edit it (any change re-sends it), then publish it again."
}

Not found (404)#

JSON

{
  "error": "Post not found"
}

Publish failed (500)#

If publishing fails after the old schedule was cancelled, the post moves back to drafts. The message tells you when that happened.

JSON

{
  "error": "Failed to publish post",
  "message": "Account token expired — reconnect required"
}

Rate Limits#

20 requests per minute per workspace, shared by the publishing and post endpoints. Analytics has its own limit

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