Fuxux Accounts API

openapi: 3.2.0
info:
  title: Fuxux Accounts 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: Accounts
  description: Connected social accounts
paths:
  /api/accounts:
    get:
      tags:
      - Accounts
      summary: List connected social accounts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        platform:
                          type: string
                        platform_username:
                          type: string
                          nullable: true
                        platform_avatar_url:
                          type: string
                          nullable: true
                        token_expires_at:
                          type: string
                          format: date-time
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                        status:
                          type: string
                          enum:
                          - connected
                          - expired
                          description: '"expired" means the account must be reconnected in the Fuxux dashboard before it can publish again.'
                        scopes:
                          type: array
                          items:
                            type: string
                          description: The permissions the platform actually granted to this connection (empty when the platform doesn't report them). A connection can be healthy and still lack one, for example the permission to read engagement.
                        via_reminder:
                          type: boolean
                          description: 'True for a reminder account: Fuxux reminds the user to post by hand instead of publishing through the platform, so `status` doesn''t apply to it.'
                required:
                - accounts
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getApiAccounts
      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`.