> ## 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.

# Create a post

> Sends text and media to one or more channels, now or at `scheduled_at`. The send is
asynchronous: the `201` shows every channel as `pending`; the outcome arrives through
the `publishing.post.published` / `publishing.post.failed` webhooks or by reading the
post back.

**Idempotency.** The `Idempotency-Key` header is required. A repeat with the same key
and the same body answers the stored post with `200` (and `meta.replayed: true`); the
same key with a different body is refused with `idempotency_key_reused`. Retry a
timed-out request with the same key and it cannot publish twice.

**Media** are public http(s) URLs the supplier fetches at publish time; they are not
copied, so they must stay reachable until the post is live. `kind` is `image` or
`video`, inferred from the URL's extension when omitted; a URL whose kind cannot be
told is refused.

**Up-front refusals** (`422`, nothing written): a channel that needs reconnecting
(`channel_needs_reconnecting`, with a reconnect link under `action` when one could
be issued), no content, bad media, a schedule in the past or without a timezone
offset, a content format the network does not have (`invalid_format`, with
`details.formats`), an `Idempotency-Key` over 255 characters, more than 50 X posts in
any 24 hours (`x_daily_cap_reached`, with `details.resets_at`; a deleted post that already
went out on X still counts), or a network's own
refusal from the supplier's dry run (`validation_failed`, with `details.channels[]`
naming each refusing channel and its reasons). Publishing is paused with `402` while
the card for the channels was declined or the subscription is unpaid.

**Limits:** 10 creates a minute per key (`429` with `Retry-After`).




## OpenAPI

````yaml /openapi/v1.yaml post /publishing/posts
openapi: 3.1.0
info:
  title: Juicer API v1
  version: 1.0.0
  description: >
    The Juicer API provides two products under one API key:


    1. **Integration API** — Programmatically manage feeds, sources, posts, and
    moderation

    2. **Data API** — Query social posts for a handle or hashtag without
    creating a feed


    ## Authentication

    All requests require a Bearer token in the Authorization header:

    ```

    Authorization: Bearer jcr_your_api_key_here

    ```

    API keys can be created from the Developer page in the Juicer dashboard,

    **or** programmatically via `POST /v1/authorize` — see step 0 of the

    Quick Start below. No prior signup or dashboard access is required.


    ## Quick Start


    Create a feed, add a source, and get the embed code:


    ```bash

    # 0. Get an API key (no dashboard needed)

    curl -X POST https://api.juicer.io/v1/authorize \
      -H "Content-Type: application/json" \
      -d '{"email": "you@example.com", "client_name": "My Tool"}'
    # New email → returns `api_key` immediately (temporary until email
    confirmed).

    # Existing user → returns an `authorization_url` (user approves) and a

    # `poll_url`; GET the poll_url until it returns the `api_key`.


    # 1. Check your account

    curl https://api.juicer.io/v1/account \
      -H "Authorization: Bearer jcr_your_key"

    # 2. See available platforms

    curl https://api.juicer.io/v1/platforms \
      -H "Authorization: Bearer jcr_your_key"

    # 3. Create a feed

    curl -X POST https://api.juicer.io/v1/feeds \
      -H "Authorization: Bearer jcr_your_key" \
      -H "Content-Type: application/json" \
      -d '{"name": "My Brand Feed"}'

    # 4. Add a YouTube source

    curl -X POST https://api.juicer.io/v1/feeds/{feed_id}/sources \
      -H "Authorization: Bearer jcr_your_key" \
      -H "Content-Type: application/json" \
      -d '{"platform": "YouTube", "term": "NASA", "term_type": "username"}'

    # 5. Get embed code for your website

    curl https://api.juicer.io/v1/feeds/{feed_id}/embed \
      -H "Authorization: Bearer jcr_your_key"
    ```


    The embed endpoint returns ready-to-use snippets:


    - **JavaScript** — `<script>` tag for any website

    - **iframe** — For platforms that don't allow JavaScript

    - **WordPress shortcode** — `[juicer name='your-feed']`

    - **WordPress PHP** — `<?php juicer_feed('name=your-feed'); ?>`


    ## Discovering Platforms


    Use `GET /platforms` to see all available social media platforms and their

    supported term types (username, hashtag, mentions, etc.) before creating
    sources.

    Each term type includes its OAuth connection requirements, so you know
    upfront

    whether the user needs to connect an account first.


    ## Connecting Social Accounts


    Several platforms require a connected social account before you can create

    sources. The exact list and the per-term-type requirement depend on the

    caller's account configuration — always discover requirements at runtime

    from `GET /platforms` (the `requires_connection` field on each term type)

    or `GET /social_accounts/status`. The flow when a connection is needed:


    1. `GET /social_accounts/status` — check which platforms need connecting

    2. `POST /social_accounts/connect_url` with `{"provider": "facebook"}` —
    generates a magic link

    3. User clicks the link — it signs them in and starts the authorization flow
    (no Juicer login needed)

    4. `GET /social_accounts` — verify the account is now connected

    5. Create sources for that platform as normal


    The magic link expires in 30 minutes and can only be used once. This makes

    it suitable for AI agents and CLI tools that need to walk a user through

    social account setup.


    **Note:** If you try to create a source that requires a connected account

    and none is available, the API returns a `422` error with

    `error.code = "social_account_required"` and an `error.action` containing

    a magic link the user can click to complete the connection.


    ## Plan Limits


    Your plan determines how many feeds and sources you can create. If you hit

    a limit, the API returns a `422` error with `error.code =
    "feed_limit_reached"`

    or `"source_limit_reached"`, along with an `error.action` of type
    `"upgrade_plan"`

    that includes a magic link to the upgrade page with the correct plan
    pre-selected.
servers:
  - url: https://api.juicer.io/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Quickstart
    description: Get an API key with just an email, no dashboard required
  - name: Account
    description: Account info, usage, and limits
  - name: Platforms
    description: Discover available platforms and term types
  - name: Social Accounts
    description: Manage OAuth social account connections needed for certain platforms
  - name: Feeds
    description: Manage feeds (create, update, delete, list)
  - name: Sources
    description: Manage sources within feeds
  - name: Posts
    description: Read, search, and moderate posts
  - name: Embed
    description: Get embed code snippets for your website
  - name: Search
    description: Search posts across all feeds
  - name: Analytics
    description: Feed engagement analytics and performance
  - name: Webhooks
    description: Webhook subscriptions and event delivery
  - name: Data API
    description: One-off post lookups for a handle or hashtag without creating a feed
  - name: Publishing
    description: >
      Publish to connected social accounts (channels) from your own app.
      Connecting a

      channel is a browser round-trip the end customer completes on the network;
      each

      connected channel is billed from the moment it connects to the end of the
      publishing

      billing cycle (which starts with the first channel) and monthly after
      that, with no

      refunds for partial months. See the [Publishing guide](/publishing).
paths:
  /publishing/posts:
    post:
      tags:
        - Publishing
      summary: Create a post
      description: >
        Sends text and media to one or more channels, now or at `scheduled_at`.
        The send is

        asynchronous: the `201` shows every channel as `pending`; the outcome
        arrives through

        the `publishing.post.published` / `publishing.post.failed` webhooks or
        by reading the

        post back.


        **Idempotency.** The `Idempotency-Key` header is required. A repeat with
        the same key

        and the same body answers the stored post with `200` (and
        `meta.replayed: true`); the

        same key with a different body is refused with `idempotency_key_reused`.
        Retry a

        timed-out request with the same key and it cannot publish twice.


        **Media** are public http(s) URLs the supplier fetches at publish time;
        they are not

        copied, so they must stay reachable until the post is live. `kind` is
        `image` or

        `video`, inferred from the URL's extension when omitted; a URL whose
        kind cannot be

        told is refused.


        **Up-front refusals** (`422`, nothing written): a channel that needs
        reconnecting

        (`channel_needs_reconnecting`, with a reconnect link under `action` when
        one could

        be issued), no content, bad media, a schedule in the past or without a
        timezone

        offset, a content format the network does not have (`invalid_format`,
        with

        `details.formats`), an `Idempotency-Key` over 255 characters, more than
        50 X posts in

        any 24 hours (`x_daily_cap_reached`, with `details.resets_at`; a deleted
        post that already

        went out on X still counts), or a network's own

        refusal from the supplier's dry run (`validation_failed`, with
        `details.channels[]`

        naming each refusing channel and its reasons). Publishing is paused with
        `402` while

        the card for the channels was declined or the subscription is unpaid.


        **Limits:** 10 creates a minute per key (`429` with `Retry-After`).
      operationId: createPublishingPost
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishingPostCreate'
      responses:
        '200':
          description: Replay of an earlier request with the same Idempotency-Key and body
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PublishingPost'
                  meta:
                    type: object
                    properties:
                      replayed:
                        type: boolean
        '201':
          description: Post created; every channel pending
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PublishingPost'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        maxLength: 255
      description: >-
        A unique string per post you intend to create. Reuse it on retries of
        the same request.
  schemas:
    PublishingPostCreate:
      type: object
      required:
        - channels
      properties:
        text:
          type: string
        media:
          type: array
          items:
            type: object
            required:
              - url
            properties:
              url:
                type: string
                format: uri
              kind:
                type: string
                enum:
                  - image
                  - video
        first_comment:
          type: string
        scheduled_at:
          type: string
          format: date-time
          description: >-
            ISO 8601 with a timezone offset (`2026-11-01T08:00:00Z`), in the
            future; omit to publish now.
        channels:
          type: array
          minItems: 1
          items:
            type: object
            required:
              - id
            properties:
              id:
                type: string
                format: uuid
              format:
                type: string
                enum:
                  - Reel
                  - Story
                  - Short
                  - Thread
                description: >
                  The content format where the network distinguishes one: `Reel`
                  or `Story` on

                  Instagram and Facebook, `Short` on YouTube, `Thread` on X.
                  Case-sensitive;

                  refused with `invalid_format` for any other network.
              network_options:
                type: object
                additionalProperties: true
                description: >
                  The network's own option names, e.g. `{"subreddit": "webdev"}`
                  for Reddit or

                  `{"boardId": "…"}` for Pinterest.
    PublishingPost:
      type: object
      description: A post created over the Publishing API, with its outcome per channel.
      required:
        - id
        - status
        - targets
        - created_at
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - scheduled
            - publishing
            - published
            - failed
            - removed
          description: |
            `scheduled` until its time comes, `publishing` while channels are
            being sent to, then `published` or `failed` once every channel has
            answered; `removed` once deleted through the API.
        text:
          type: string
          nullable: true
        media:
          type: array
          items:
            type: object
            required:
              - url
              - kind
            properties:
              url:
                type: string
                format: uri
              kind:
                type: string
                enum:
                  - image
                  - video
        first_comment:
          type: string
          nullable: true
        scheduled_at:
          type: string
          format: date-time
          nullable: true
        published_at:
          type: string
          format: date-time
          nullable: true
        failed_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        targets:
          type: array
          description: One entry per channel the post was sent to.
          items:
            $ref: '#/components/schemas/PublishingPostTarget'
    PublishingPostTarget:
      type: object
      required:
        - channel_id
        - network
        - status
      properties:
        channel_id:
          type: string
          format: uuid
          nullable: true
          description: Null once the channel has been disconnected; the outcome is kept.
        network:
          type: string
          enum:
            - instagram
            - facebook
            - linkedin
            - tiktok
            - twitter
            - reddit
            - youtube
            - bluesky
            - pinterest
            - gmb
            - snapchat
            - telegram
            - threads
        status:
          type: string
          enum:
            - pending
            - scheduled
            - published
            - failed
            - removed
          description: >
            `removed` is a channel a delete took down while another channel of
            the post kept it

            up (`422 delete_refused`); it is out of the post's status, and a
            later `DELETE`

            leaves it alone.
        post_url:
          type: string
          format: uri
          nullable: true
          description: Where the post lives on the network, once published.
        scheduled_at:
          type: string
          format: date-time
          nullable: true
        published_at:
          type: string
          format: date-time
          nullable: true
        error:
          type: object
          nullable: true
          description: >-
            Why this channel failed, in the network's own terms where it gave
            any.
          properties:
            code:
              type: string
              nullable: true
            message:
              type: string
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: >
                Machine-readable error code. Possible values:

                - `unauthorized` — Missing or invalid API key

                - `forbidden` — Caller is not permitted (see `message`)

                - `not_found` — Resource not found

                - `parameter_missing` — Required parameter not provided

                - `validation_failed` — Model validation failed (see `details`)

                - `feed_limit_reached` — Plan's feed limit exceeded (see
                `action`)

                - `source_limit_reached` — Feed's source limit exceeded (see
                `action`)

                - `user_limit_reached` — Plan doesn't include team members (see
                `action`)

                - `social_account_required` — OAuth connection needed (see
                `action`)

                - `invalid_platform` — Platform not supported

                - `invalid_provider` — Unknown OAuth provider

                - `invalid_status` — Invalid post status filter

                - `invalid_action_type` — Invalid bulk moderation action

                - `post_unavailable` — Post no longer available on the source
                platform

                - `query_required` — Search query not provided

                - `search_too_broad` — Search timed out; narrow it with
                `feed_ids`, a shorter date range or a more specific query

                - `user_has_connections_in_use` — Removing the user would stop
                feeds that sync on their connections (see `details`)

                - `rate_limit_exceeded` — This key's rate limit; wait
                `Retry-After` seconds

                - `supplier_busy` — The publishing supplier's shared budget is
                spent; wait `Retry-After` seconds

                - `supplier_error` — The publishing supplier refused part of the
                request (see `details`)

                - `payment_required` — Publishing billing must be settled first
                (see `action`)

                - `invalid_network` — Network not supported for publishing

                - `invalid_redirect_url` — `redirect_url` is not an absolute
                http(s) URL

                - `channel_needs_reconnecting` — A channel's authorization
                lapsed (see `action.connection_url`)

                - `network_slot_taken` — The connection link's slot was taken
                meanwhile; ask for a new link

                - `invalid_state` — The connection link expired or was already
                used

                - `idempotency_key_missing` — The `Idempotency-Key` header is
                required

                - `idempotency_key_too_long` — The `Idempotency-Key` header is
                over 255 characters

                - `idempotency_key_reused` — The key was used for a different
                request (see `details.post_id`)

                - `channels_required` — No channel ids were sent

                - `unknown_channel` — A channel id is not one of the account's
                (see `details.channel_id`)

                - `content_required` — Neither text nor media was sent

                - `invalid_media` — A media URL is not an absolute public
                http(s) URL, or its kind is unknown

                - `invalid_scheduled_at` — Not an ISO 8601 time with a timezone
                offset, in the future

                - `invalid_format` — Not a content format the channel's network
                has (see `details.formats`)

                - `x_daily_cap_reached` — 50 X posts per account per 24 hours,
                deleted posts that went out on X included (see
                `details.resets_at`)

                - `post_not_reschedulable` — Only a post still waiting for its
                time can be moved

                - `post_not_deletable` — The post is being sent, or was already
                removed

                - `post_in_handoff` — The post is still being handed to the
                networks; try again in a moment

                - `delete_refused` — A network kept the post live (see
                `details.channels`)

                - `post_not_retryable` — No channel of the post can be retried
              example: feed_limit_reached
            message:
              type: string
              description: Human-readable error message
              example: Your Free plan allows 1 feed(s). Upgrade to create more.
            details:
              type: object
              nullable: true
              description: >
                What the error is about, by code. For a model
                `validation_failed` (feeds, sources,

                webhooks...): field-level messages, `{ "name": ["can't be
                blank"] }`. When `code` is

                `user_has_connections_in_use`, `social_accounts` lists the
                connections (`id`,

                `provider`, `name`, `feed_names`) that feeds still sync on. For
                the

                publishing endpoints: `validation_failed` carries

                `channels: [{ id, network, errors: [...], warnings: [...] }]`;
                `delete_refused` and

                `supplier_error` carry `channels: [{ channel_id, network,
                message }]` (and

                `supplier_error` the `post` as it now stands);
                `idempotency_key_reused` carries

                `post_id`; `unknown_channel` and `channel_needs_reconnecting`
                carry `channel_id`;

                `invalid_media` carries the `index` of the offending item;
                `x_daily_cap_reached`

                carries `cap`, `used`, `requested` and `resets_at`.
              additionalProperties: true
              example:
                name:
                  - can't be blank
            action:
              nullable: true
              description: >
                Actionable fix for the error. Present when the error can be
                resolved

                by the user taking a specific action (upgrading plan or
                connecting a social account).

                The `type` field tells you what kind of action is needed.
              oneOf:
                - $ref: '#/components/schemas/UpgradePlanAction'
                - $ref: '#/components/schemas/ConnectSocialAccountAction'
                - $ref: '#/components/schemas/PaymentRequiredAction'
                - $ref: '#/components/schemas/ReconnectPublishingChannelAction'
    UpgradePlanAction:
      type: object
      description: >
        Returned when a plan limit is hit (feed limit, source limit).

        The `upgrade_url` is a magic link — the user clicks it, gets signed in

        automatically, and lands on the upgrade page with the right plan
        pre-selected.
      properties:
        type:
          type: string
          enum:
            - upgrade_plan
        current_plan:
          type: string
          example: small
        current_plan_display_name:
          type: string
          example: Free
        required_plan:
          type: string
          description: The minimum plan that unlocks this feature
          example: large
        required_plan_display_name:
          type: string
          example: Pro
        upgrade_url:
          type: string
          description: >-
            Magic link — signs user in and redirects to the upgrade page.
            Expires in 30 minutes.
        expires_at:
          type: string
          format: date-time
    ConnectSocialAccountAction:
      type: object
      description: >
        Returned when a source requires an OAuth-connected social account.

        The `connection_url` is a magic link — the user clicks it, gets signed
        in

        automatically, and starts the OAuth authorization flow.
      properties:
        type:
          type: string
          enum:
            - connect_social_account
        provider:
          type: string
          description: OAuth provider to connect
          example: facebook
        connection_url:
          type: string
          description: >-
            Magic link — signs user in and starts OAuth flow. Expires in 30
            minutes.
        expires_at:
          type: string
          format: date-time
    PaymentRequiredAction:
      type: object
      description: >
        Returned with `payment_required`. Open `checkout_url` to save a card. On
        a first

        connect nothing is charged until a channel connects; while publishing is
        paused over a

        declined charge, the open publishing invoices are paid with the new card
        at once.
      required:
        - checkout_url
      properties:
        checkout_url:
          type: string
          format: uri
    ReconnectPublishingChannelAction:
      type: object
      description: >-
        Returned with `channel_needs_reconnecting`. Open `connection_url` to
        authorize the channel again.
      required:
        - channel_id
        - connection_url
      properties:
        channel_id:
          type: string
          format: uuid
        connection_url:
          type: string
          format: uri
        expires_at:
          type: string
          format: date-time
  responses:
    PaymentRequired:
      description: >
        Billing must be settled first. `action.checkout_url` is a hosted page
        that saves a

        card; invoiced accounts get a message to contact support and no link.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >-
        The key may not do this. Publishing needs an owner's or manager's key;
        connecting, reconnecting and disconnecting channels need an owner's or
        manager's permanent key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: >
        Rate limited. `Retry-After` carries the seconds to wait.
        `rate_limit_exceeded` is

        this key's own limit (60 publishing requests a minute, 10 post creates a
        minute);

        `supplier_busy` is the publishing supplier's shared budget, momentarily
        spent.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until the request can be retried.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        API key prefixed with `jcr_`. To obtain a key programmatically
        (no dashboard required), see `POST /v1/authorize`.

````

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