Fuxux Usage API

openapi: 3.2.0
info:
  title: Fuxux Usage 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: Usage
  description: Plan limits and meters
paths:
  /api/usage:
    get:
      tags:
      - Usage
      summary: Plan limits and current usage
      description: Returns the current plan, active workspace, and usage counters for account and AI limits.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getApiUsage
      x-operation-id-source: derived
components:
  schemas:
    UsageResponse:
      type: object
      properties:
        plan:
          type: string
          enum:
          - free
          - creator
          - growth
          - pro
        limits:
          type: object
          properties:
            accounts:
              type: integer
              description: -1 means unlimited.
            aiPerMonth:
              type: integer
              nullable: true
            postsPerMonth:
              type: integer
              nullable: true
              description: Published posts allowed per month on the plan of the space's owner; null when unlimited.
            xUnitsPerMonth:
              type: integer
              nullable: true
              description: Monthly allowance for publishing to X. 0 means X is not included in the plan. A post is 1 unit, a post with a link 13.
        usage:
          type: object
          properties:
            accounts:
              type: integer
            aiThisMonth:
              type: integer
            postsThisMonth:
              type: integer
            xUnitsThisMonth:
              type: integer
    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`.