Skip to main content
Publishing lets your app post to social accounts your customers connect, through one API. A channel is one connected social account; a post is text and media sent to one or more channels, now or at a scheduled time.

What it costs

Each connected channel is billed monthly on a graduated scale, where each channel pays the rate of the tier it falls in: For example, 25 channels cost 10 × $4.50 + 15 × $2.99 = $89.85 a month. The publishing billing cycle starts when the first channel connects: that channel is charged a full month at once, and every channel connected later is charged for the rest of the current cycle, normally within the hour (on the next invoice when the remainder is under 50 cents before tax, or while a declined card is waiting for a new one). From then on the channel is on every monthly invoice until it is disconnected. Disconnecting takes the channel off the next monthly invoice; what it already owes for this cycle is still charged, including a connect charge the hourly collection has not taken yet, and there are no refunds or credits for partial months: swapping one channel for another mid-cycle is a second charge, and disconnecting the last channel ends the cycle (a connect charge still pending is invoiced at once), so the next first channel starts a new one with a full month. The channel list quotes the current total and what one more channel adds, before coupons and tax, which show on the invoice. The publishing API is for the account’s owners and managers: a collaborator’s key is refused on every publishing endpoint, since a post can reach every channel of the account. Connecting and disconnecting channels also needs a permanent key, because they change what the account pays; creating and reading posts works with any active owner or manager key, temporary ones included.

1. Connect a channel

Ask for a connection link for the network:
Open connection_url in a browser, or send it to whoever holds the LinkedIn account. They authorize on LinkedIn and land on your redirect_url with ?connected=true&channel_id=…, with connected=false if they backed out, or with connected=false&error=… when the return trip could not be completed (the link expired or was already used, its slot was taken, or the supplier did not answer): ask for a new link then. Without a redirect_url they land on a Juicer page that says whether the account connected and that they can close the tab. The hosted page accepts the link until expires_at; each link completes once. The card step. On an account with no card on file and no publishing subscription yet, the first call answers 402 payment_required with action.checkout_url: a hosted page that saves a card. An account already paying for a plan by card skips this step. Nothing is charged by saving it; the first channel that connects starts the subscription. Pass redirect_url and the person lands back on it with ?card=saved (or ?card=cancelled); without one they land on a Juicer page that says whether the card was saved. Call connect_url again once the card is saved. Accounts that pay by invoice are asked to contact support instead. Then list your channels:
Each channel carries an id (what you address posts to), its network, handle and a status: connected, expiring_soon (the authorization lapses within seven days) or needs_reconnecting. meta quotes the monthly total.

2. Create a post

The answer is 201 with the post and one pending target per channel: sending is asynchronous. Omit scheduled_at to publish now; when set, it is an ISO 8601 time with a timezone offset (Z or +01:00). Idempotency. Idempotency-Key is required: a string you choose (up to 255 characters), unique per post you intend to create. If a request times out, send it again with the same key; the API answers the post it already created (200, meta.replayed: true) rather than publishing twice. The same key with a different body is refused. Media rules. Media are public http(s) URLs. The publishing supplier fetches them at publish time; they are not copied, so they must stay reachable until the post is live (and until the networks have processed it, which for video can be minutes). kind is image or video; it is inferred from the URL’s extension when omitted, and a URL whose kind cannot be told is refused. Each network has its own limits on sizes, aspect ratios and formats; a post that breaks them is refused up front with the network’s reason. Network options. Per channel, in the network’s own option names: a Reddit subreddit and title, a Pinterest boardId, a Google Business Profile callToAction. Unknown names are dropped. The content format, where a network distinguishes one, is the channel entry’s own format field beside network_options: Reel or Story on Instagram and Facebook, Short on YouTube, Thread on X (case-sensitive; any other value, or a format on another network, is refused with invalid_format). Up-front refusals come back as 422 with a code you can act on: channel_needs_reconnecting (with a reconnect link under action when one could be issued; otherwise ask for one with reconnect_url), validation_failed (with details.channels[] naming each channel the network refused and why), x_daily_cap_reached (50 X posts per account per 24 hours; details.resets_at says when the window turns. Deleting a post that already went out on X does not free its place, since X keeps counting it), invalid_media, invalid_scheduled_at, invalid_format. Nothing is written when a request is refused.

3. Watch it land

Subscribe a webhook to publishing.post.published and publishing.post.failed:
Each fires once each time the post settles: published once every channel is live, failed when at least one channel refused it and none is still in flight. A retry that settles again fires again. The body carries the post with targets[], one per channel, each with its status, the live post_url, or an error in the network’s words. Or read the post back:
A failed channel can be sent again with POST /publishing/posts/{id}/retry (once per channel). A scheduled post can be moved with PATCH /publishing/posts/{id} (scheduled_at only; content cannot be edited in place) and withdrawn with DELETE; in the few seconds after creation, while the post is still being handed to the networks, both answer 409 post_in_handoff. When a delete takes some channels down but not others (422 delete_refused), the channels it took down read removed and the post keeps its status from the rest; call DELETE again to retry the others. Engagement counts per channel are at GET /publishing/posts/{id}/analytics, refreshed when the supplier says they are stale (at least fifteen minutes apart); they are read for Instagram, Facebook, X, LinkedIn, TikTok, Reddit, YouTube and Bluesky, and answer measured: false for the other networks.

4. Reconnect a channel

Authorizations lapse: a network revokes them, a password changes, LinkedIn and TikTok tokens expire. The channel’s status reads needs_reconnecting as soon as its recorded expiry passes; the daily health sweep, the network’s own notice or a refused publish then sends publishing.channel.expired once. Creating a post to such a channel is refused with channel_needs_reconnecting until it is reconnected. Ask for a reconnect link on the same channel id:
Nothing new is billed by a reconnect, and the channel id stays the same, so posts addressed to it keep working once it is back. A channel that needs reconnecting stays billed until you disconnect it. Disconnect a channel with DELETE /publishing/channels/{id}; it stays paid until the end of the current cycle and is off the next monthly invoice; nothing is credited, and a connect charge not yet collected is still taken (disconnecting the last channel invoices it at once).

Limits

  • 60 publishing requests a minute per key, and 10 post creates a minute per key; a 429 carries Retry-After. The connection callback is held to 20 return trips a minute per address.
  • 50 X posts per account in any 24 hours, counted by send time.
  • 429 supplier_busy means the shared publishing supplier budget is momentarily spent; wait Retry-After seconds.