> ## Documentation Index
> Fetch the complete documentation index at: https://juicer.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Publishing

> Publish to Instagram, LinkedIn, X, TikTok and nine more networks from your own app: connect a channel, create a post, watch it land through webhooks.

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:

| Channels on the account | Price per channel, monthly |
| - | - |
| 1–10 | \$4.50 |
| 11–100 | \$2.99 |
| 101 and more | \$1.99 |

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:

```bash theme={null}
curl -X POST https://api.juicer.io/v1/publishing/channels/connect_url \
  -H "Authorization: Bearer jcr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"network": "linkedin", "redirect_url": "https://app.example.com/channels"}'
```

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:

```bash theme={null}
curl https://api.juicer.io/v1/publishing/channels \
  -H "Authorization: Bearer jcr_your_key"
```

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

```bash theme={null}
curl -X POST https://api.juicer.io/v1/publishing/posts \
  -H "Authorization: Bearer jcr_your_key" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Doors open at 9 tomorrow.",
    "media": [{"url": "https://cdn.example.com/poster.jpg"}],
    "channels": [{"id": "9b2c…"}, {"id": "e41f…", "network_options": {"subreddit": "webdev"}}],
    "scheduled_at": "2026-11-01T08:00:00Z"
  }'
```

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`:

```bash theme={null}
curl -X POST https://api.juicer.io/v1/webhooks \
  -H "Authorization: Bearer jcr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://app.example.com/hooks/juicer", "subscribed_events": ["publishing.post.published", "publishing.post.failed", "publishing.channel.expired"]}'
```

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:

```bash theme={null}
curl https://api.juicer.io/v1/publishing/posts/{id} \
  -H "Authorization: Bearer jcr_your_key"
```

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:

```bash theme={null}
curl -X POST https://api.juicer.io/v1/publishing/channels/{id}/reconnect_url \
  -H "Authorization: Bearer jcr_your_key"
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.