Skip to main content

Publish to social networks with the Juicer API

Connect social channels and publish posts through the Juicer API or MCP server. Learn the connect flow, card setup, billing, webhooks, and common errors.

Written by Mario T.

API publishing lets your own app or AI agent connect social channels and publish posts to them through the Juicer API. It is a product of its own, separate from the Publishing workspace in the dashboard (see Publishing: schedule and publish posts to your social networks), with its own channels, its own posts, and per-channel billing. Full endpoint details live in the API reference at developers.juicer.io.

What you can do with API publishing

  • Connect channels on Instagram, Facebook, LinkedIn, TikTok, X, Reddit, YouTube, Bluesky, Pinterest, Google Business Profile, Snapchat, Telegram, and Threads. In API calls, send the network's id instead: instagram, facebook, linkedin, tiktok, twitter (X), reddit, youtube, bluesky, pinterest, gmb (Google Business Profile), snapchat, telegram or threads.

  • Create posts for one or more channels, publish them right away or schedule them.

  • Manage posts by rescheduling, deleting, retrying, and reading analytics.

  • Get notified through webhook events when a post is published or fails, and when a channel needs to be reconnected.

  • Use an AI agent through the Juicer MCP server, which has ten publishing tools.

Before you start

API publishing is for account owners and managers. Connecting, reconnecting, and disconnecting a channel also need a permanent API key, because they change what your account is billed for. Temporary keys can list channels and create posts, but they cannot change channels. Every key you create under API keys on the API page is permanent. Open it from API & MCP in your account menu and click Generate key.

API keys section of the API page with two keys, Website integration and AI agent, and the Generate key button

Connect a channel

Connecting is a browser round trip that your end customer completes on the social network.

  1. Send a POST to /v1/publishing/channels/connect_url with the network you want, for example instagram. You can add a redirect_url to send the person back to your own page afterward.

  2. The response contains a connection_url, an expires_at time, and the monthly price of one more channel.

  3. Send the person to the connection_url. They authorize the account on the network.

  4. Juicer records the channel and sends them to your redirect_url, or to a Juicer result page if you did not give one.

Use GET /v1/publishing/channels to list connected channels, and DELETE /v1/publishing/channels/{id} to disconnect one. If a channel stops working, request a fresh authorization with POST /v1/publishing/channels/{id}/reconnect_url.

Save a card on the first connect

If your account has no card on file for publishing, the first connect answers 402 with an action.checkout_url. Open that hosted page to save a card, then request the connect link again. If you do not set a page of your own, the person lands on a Juicer page that says Card saved or Card not saved.

⚠️ Important: AI agents should show the card page to the user, wait until they confirm the card is saved, and only then ask for the connect link again.

What the person sees after authorizing

When no redirect_url was given, Juicer shows a simple result page that works without a Juicer login. It reads [Network] connected, [Network] not connected, This link can no longer be used, or Connection not confirmed, and tells the person they can close the tab. A cancelled authorization is treated as a normal outcome, not an error.

Juicer result page reading Instagram connected, The account is connected and ready for publishing, You can close this tab now

Publish and track posts

Create a post with POST /v1/publishing/posts and send an Idempotency-Key header, so a retried request never creates a duplicate. The post comes back right away, and each channel settles on its own. Follow the outcome through the publishing.post.published and publishing.post.failed webhook events, or read the post back. The publishing.channel.expired event tells you when a channel needs reconnecting. It fires once, when the channel is first flagged, so reconnect it before you schedule more posts to it.

  • Reschedule a post that is still waiting for its scheduled time by sending a new scheduled_at with PATCH /v1/publishing/posts/{id}. To change the content, create a new post.

  • Retry a failed post with POST /v1/publishing/posts/{id}/retry. Each channel can be retried once.

  • Read analytics with GET /v1/publishing/posts/{id}/analytics. Analytics are counted on Instagram, Facebook, X, LinkedIn, TikTok, Reddit, YouTube and Bluesky. On the other networks the response says measured: false.

How channels are billed

Each connected channel is billed monthly, and each connect response quotes the current price. Your first channel starts the billing cycle and is charged for a full month. Each channel you add after that is billed from the moment it connects to the end of the cycle. There are no refunds for partial months. If you disconnect your last channel, the next one you connect starts a new cycle. If a payment fails, creating posts over the API answers 402 until it's fixed. See the pricing page for current prices.

Troubleshooting

  • 402 when connecting or posting
    Open the action.checkout_url to save a card. If a payment failed, saving a working card there pays what's open and resumes publishing. If your account pays by invoice, the response has no checkout link, so contact us.

  • A permanent API key is required for this action.
    Connecting, reconnecting, and disconnecting need a permanent key. Create one under API keys on the API page.

  • 409 channel_needs_reconnecting
    You asked to connect a network that's already connected but needs a fresh authorization. Open the action.connection_url in the response instead of connecting a second channel.

  • 422 channel_needs_reconnecting
    You created a post for a channel that needs reconnecting. Open the reconnect link under action if the response has one, or request one with POST /v1/publishing/channels/{id}/reconnect_url.

  • 429 supplier_busy
    The publishing service is busy. Wait the number of seconds in the Retry-After header and try again. A 429 rate_limit_exceeded means you sent more than 60 requests a minute with one key, or more than 10 new posts a minute. It also carries Retry-After.

  • 422 invalid_network
    Send one of the network ids listed above, for example twitter for X or gmb for Google Business Profile.

  • This link can no longer be used
    The connection link expired or was already used. Request a new one.

If a channel will not connect or a post does not go out, contact us with the network, the channel or post id, and the error code from the response, and we will take a look.

Did this answer your question?