Fuxux Media API

openapi: 3.2.0
info:
  title: Fuxux Media 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: Media
  description: Upload files for posts
paths:
  /api/media/upload:
    post:
      tags:
      - Media
      summary: Upload media for posts
      description: 'Multipart form field `file`. Fuxux allows up to **50 MB**, but the hosting platform hard-caps any single request body at **~4.5 MB** — larger files fail here regardless of the 50 MB limit; host them yourself and pass a public HTTPS URL in `media_urls` instead. Allowed types: JPEG, PNG, GIF, WebP, MP4, MOV, WebM.


        An uploaded file that no post uses (in `media_urls`) is deleted after **48 hours**, so attach it to a post or draft within two days.'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Public URL
          content:
            application/json:
              schema:
                type: object
                required:
                - url
                - path
                properties:
                  url:
                    type: string
                    format: uri
                  path:
                    type: string
        '400':
          description: Missing file or disallowed type/size
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: The plan's media storage is full (JSON error), or the request body is over ~4.5 MB and was refused by the hosting platform before it reached Fuxux (that answer is not JSON; use `/api/media/presign` for large files)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many uploads in a short time, or the day's upload allowance is used up; wait for the time in the Retry-After header
        '500':
          description: Upload failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postApiMediaUpload
      x-operation-id-source: derived
  /api/media/presign:
    post:
      tags:
      - Media
      summary: Prepare a direct upload (any size up to 50 MB)
      description: 'Returns a short-lived `uploadUrl`. Send the file''s bytes to it with `PUT` and the same `Content-Type`, then use `url` in `media_urls`. The file never passes through the API, so the ~4.5 MB request limit of `POST /api/media/upload` does not apply. Allowed types: JPEG, PNG, GIF, WebP, MP4, MOV, WebM. The upload counts against your storage and daily upload allowance when this is called. A file that no post uses (in `media_urls`) is deleted after **48 hours**.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - filename
              - contentType
              - size
              properties:
                filename:
                  type: string
                  maxLength: 255
                  description: Must end with the usual extension for its type (.jpg, .png, .gif, .webp, .mp4, .mov or .webm)
                contentType:
                  type: string
                  enum:
                  - image/jpeg
                  - image/png
                  - image/gif
                  - image/webp
                  - video/mp4
                  - video/quicktime
                  - video/webm
                size:
                  type: integer
                  minimum: 1
                  maximum: 52428800
                  description: File size in bytes
      responses:
        '200':
          description: Upload URL and the file's public URL
          content:
            application/json:
              schema:
                type: object
                required:
                - uploadUrl
                - url
                - path
                - contentType
                properties:
                  uploadUrl:
                    type: string
                    format: uri
                    description: Presigned URL; PUT the file here with the same Content-Type
                  url:
                    type: string
                    format: uri
                    description: Public URL of the file once uploaded
                  path:
                    type: string
                  contentType:
                    type: string
        '400':
          description: Missing fields, disallowed type or size, or a file name that doesn't match its type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: A signed-in session that has not finished its second sign-in step
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Media storage is full on your plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited or daily upload allowance reached; honor `Retry-After`
        '500':
          description: Could not prepare upload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postApiMediaPresign
      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`.