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

# Get an API key with an email (no dashboard, no prior signup)

> Provision an API key using just an email address. The behavior depends
on whether the email already belongs to a confirmed Juicer account:

- **New or unconfirmed email** — returns a short-lived (2 hour)
  temporary API key immediately (Mode A). Subject to a strict per-key
  rate limit until the user confirms the email we send. Once
  confirmed the same key is extended to the standard 12-hour
  session TTL — it is not promoted to a permanent key.
- **Existing confirmed user** — returns a **device authorization**
  request (Mode B) with an `authorization_url` the user must visit to
  approve access. Poll `poll_url` until the key is issued. The
  resulting key is also a 12-hour temporary key.

**Every key issued by this endpoint is time-bounded.** For a long-lived
key, users should generate one from the Developer page in the Juicer
dashboard; that is the only path to a permanent key. The dashboard key
and any number of `/authorize`-issued keys coexist — issuing a new
session key never revokes an existing permanent or session key.




## OpenAPI

````yaml /openapi/v1.yaml post /authorize
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
paths:
  /authorize:
    post:
      tags:
        - Quickstart
      summary: Get an API key with an email (no dashboard, no prior signup)
      description: |
        Provision an API key using just an email address. The behavior depends
        on whether the email already belongs to a confirmed Juicer account:

        - **New or unconfirmed email** — returns a short-lived (2 hour)
          temporary API key immediately (Mode A). Subject to a strict per-key
          rate limit until the user confirms the email we send. Once
          confirmed the same key is extended to the standard 12-hour
          session TTL — it is not promoted to a permanent key.
        - **Existing confirmed user** — returns a **device authorization**
          request (Mode B) with an `authorization_url` the user must visit to
          approve access. Poll `poll_url` until the key is issued. The
          resulting key is also a 12-hour temporary key.

        **Every key issued by this endpoint is time-bounded.** For a long-lived
        key, users should generate one from the Developer page in the Juicer
        dashboard; that is the only path to a permanent key. The dashboard key
        and any number of `/authorize`-issued keys coexist — issuing a new
        session key never revokes an existing permanent or session key.
      operationId: authorize
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  example: ai-dev@example.com
                client_name:
                  type: string
                  description: |
                    Optional free-text name of the calling application. Shown
                    verbatim on the authorization page for Mode B (for example
                    "Acme CLI" or "My Feed Tool"). If omitted, the page uses a
                    generic fallback.
                  example: Acme CLI
      responses:
        '201':
          description: |
            Mode A — temporary API key issued immediately. Valid for 2 hours
            pre-confirmation; extended to 12 hours once the user confirms
            their email. `expires_at` is always present.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: issued
                  api_key:
                    type: string
                    example: jcr_9f...ab
                  expires_at:
                    type: string
                    format: date-time
                  email_confirmation_required:
                    type: boolean
                    example: true
                  rate_limit:
                    type: object
                    description: The rate limit tier applied to this pre-confirmation key
                    properties:
                      requests_per_hour:
                        type: integer
                        example: 60
                      burst_per_minute:
                        type: integer
                        nullable: true
                        example: null
                  upgrade_hint:
                    type: string
                    example: >-
                      Confirm your email to raise your rate limit to 300
                      requests/hour and extend this key to 12 hours.
                  upgrade_url:
                    type: string
                    format: uri
                    description: Link to the plans page where the user can upgrade
        '202':
          description: Mode B — device authorization required
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: pending_authorization
                  request_id:
                    type: string
                  authorization_url:
                    type: string
                    format: uri
                    description: URL the user opens in a browser to approve the request
                  poll_url:
                    type: string
                    format: uri
                    description: URL the client polls for status
                  expires_at:
                    type: string
                    format: date-time
                  poll_interval:
                    type: integer
                    example: 2
                    description: Recommended poll interval in seconds
                  rate_limit:
                    type: object
                    description: The rate limit tier applied to the key once approved
                    properties:
                      requests_per_hour:
                        type: integer
                        example: 300
                      burst_per_minute:
                        type: integer
                        example: 60
                  upgrade_hint:
                    type: string
                    example: >-
                      Visit the Juicer dashboard to upgrade your plan for higher
                      limits.
                  upgrade_url:
                    type: string
                    format: uri
        '422':
          description: Invalid email
        '429':
          description: Too many requests from this IP or for this email
      security: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        API key prefixed with `jcr_`. To obtain a key programmatically
        (no dashboard required), see `POST /v1/authorize`.

````