Fuxux AI API

openapi: 3.2.0
info:
  title: Fuxux AI API
  version: 1.1.0
  description: 'Schedule and publish to 14 social platforms, manage connected accounts, upload media, and generate AI captions from your own apps, agents, or CI pipelines. Every endpoint below mirrors something you can do in the Fuxux dashboard. ## Access

    The API is included in every paid plan (Creator, Growth or Pro), at no extra cost. API keys aren''t available on the Free plan. ## Authentication

    Send your **personal API key** on every authenticated request:


    `Authorization: Bearer fx_live_…`


    Create keys on the **API keys** page of the dashboard. The full secret is shown **only once** when you create or rotate a key; store it in an environment variable. You can have up to **10 active keys** and create or rotate up to **20 a day**. Use one key per integration: rotating a key revokes the old one, so a shared key breaks every client that uses it. `GET /api/settings/profile` is the recommended connection test: it''s cheap and has no side effects. A key on an account without a paid plan is refused with 401, like a wrong key. ## Posting

    `POST /api/posts` publishes immediately, schedules with `scheduled_at`, or saves a draft with `draft: true`. Send `scheduled_at` with `Z` or an offset (`2027-01-15T09:30:00-08:00`): a time without one is read as UTC, not as the account''s time zone. `captions` maps each platform id to its caption. Add `targets` to choose exact accounts and per-platform options; it is how you pick between several accounts on one platform. Platform ids: `twitter`, `instagram`, `linkedin`, `facebook`, `tiktok`, `youtube`, `bluesky`, `threads`, `pinterest`, `discord`, `kick`, `twitch`, `telegram`, `slack`. Reddit and Google Business Profile aren''t supported. Each platform''s own rules still apply (for example, Instagram and TikTok need media). Connect accounts in Fuxux first, then list them with `GET /api/accounts`. ## Rate limits and polling

    **120 requests/min per key** and **300/min per account** across all keys; creating posts is limited to **30 per 5 minutes**. Over a limit you get **429** with `Retry-After` (seconds) — wait that long. Don''t poll: publishing settles on the order of minutes, so check a post''s status at most once a minute (or use a webhook). ## Webhooks

    Set a webhook URL on the API keys page to receive a `post.finished` event when a post''s publishing completes. In a team space, the space owner''s webhook also receives the events for posts their members publish. Its `status` is `published` when at least one platform succeeded; `outcome` is exact (`published`, `partially_failed` or `failed`) and `failed_platforms` lists what failed. The body also carries the post''s `workspace_id` (space) and, in each result, the `account_id` of the connected account. A delivery that gets no answer, a 5xx, 408 or 429 is retried with growing waits (about 2 min, 10 min, 30 min, 2 h, 6 h; 6 attempts in all); any other 4xx is final. Every attempt has the same body and `X-Fuxux-Delivery-Id` (drop repeats by it) and an `X-Fuxux-Delivery-Attempt` number. Each delivery is signed: `X-Fuxux-Signature: sha256=` is the HMAC-SHA256 of the raw body with your webhook secret.'
servers:
- url: https://www.fuxux.com
  description: Production
tags:
- name: AI
  description: In-app AI caption generation (authenticated)
paths:
  /api/ai/generate:
    post:
      tags:
      - AI
      summary: Generate platform captions from a prompt
      description: 'Enforces the plan''s AI limits: a monthly number on Free, and fair-use limits per day and per month on paid plans. When a limit is reached the response is **429** with `code: "ai_limit"` and an `ai_limit` object (`reason`, `used`, `limit`, `resetsAt`). Valid platform ids: `twitter`, `instagram`, `linkedin`, `facebook`, `tiktok`, `youtube`, `bluesky`, `threads`, `pinterest`, `discord`, `twitch`, `kick`, `telegram`, `slack`, `google-business`. Reddit is not available here. Ids that are not recognised are ignored; repeated ids count once.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - prompt
              - platforms
              properties:
                prompt:
                  type: string
                  maxLength: 500
                platforms:
                  type: array
                  items:
                    type: string
                  maxItems: 13
                  description: Platforms to generate in one call
                regenerate:
                  type: string
                  description: If set, only this platform id is regenerated; `platforms` is ignored for selection.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiCaptionsResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: User rate limit or monthly AI cap
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Misconfiguration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Upstream model error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postApiAiGenerate
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          description: Present on some refusals, for example `post_quota_reached`, `x_allowance`, `reddit_web_only`.
    AiCaptionsResponse:
      type: object
      properties:
        captions:
          type: object
          additionalProperties:
            type: string
          description: Platform id → generated caption