Accounts

A SuperX user has one main account (the X account they signed up with) and may have linked accounts they also manage. They may also have shared accounts: accounts someone else owns and has shared with them, directly or through a team. API keys belong to the user, and can read data for any of these accounts.

Listing your accounts

curl https://api.superx.so/v1/accounts \
  -H "Authorization: Bearer sxk_..."

{
  "data": [
    {
      "id": "1178367350552305665",
      "username": "mainhandle",
      "name": "Main Account",
      "avatar_url": "https://pbs.twimg.com/profile_images/example.jpg",
      "is_main": true,
      "shared": false,
      "permission": "full"
    },
    {
      "id": "1299139023923867648",
      "username": "brandhandle",
      "name": "Brand Account",
      "avatar_url": "https://pbs.twimg.com/profile_images/example2.jpg",
      "is_main": false,
      "shared": false,
      "permission": "full"
    },
    {
      "id": "1825496686774358017",
      "username": "clienthandle",
      "name": "Client Account",
      "avatar_url": "https://pbs.twimg.com/profile_images/example3.jpg",
      "is_main": false,
      "shared": true,
      "permission": "editor"
    }
  ],
  "pagination": { "page": 1, "limit": 3, "has_more": false }
}

shared is true for accounts another user shared with you (manual shares and team shares alike). permission is full or editor and describes what you may change on that account; your own accounts are always full. Revoking a share removes the account from this list within a few minutes.

Selecting an account

Endpoints that operate on one account accept an account_id parameter (query parameter on GET and DELETE, body field on POST). The value is the account id from /v1/accounts.

Omitted: your main account is used.
An id from your account list: that account is used.
Anything else: 404 account_not_found.

Writes are main-account-only, with two exceptions

Most writes, including POST /v1/scheduled-posts and DELETE /v1/scheduled-posts/{id}, work only for your main account. Passing another account’s account_id to one of them returns 403 writes_main_account_only. Reads work for every account in the list. The exceptions are the per-account settings surfaces, which accept any linked or shared account_id:

PATCH /v1/context and the /v1/context/products endpoints. On a share with editor permission these return 403 editor_restricted: only the account owner can change what the AI knows about the account.
PATCH /v1/queue-settings. Editor-permission shares CAN change the posting schedule, which mirrors the SuperX app, where running the queue is what a delegate is there for.

The degraded flag

Account links and shares are verified against the SuperX app on each request (with a short cache). If that verification is temporarily unavailable, the API fails closed rather than guessing:

GET /v1/accounts returns only your main account and adds a top-level "degraded": true field. Retry shortly for the full list. When the flag is absent, the list is complete.
Requests for any other account_id return 503 accounts_unavailable until verification recovers. Your main account keeps working throughout.

Getting Started

Using the API

CLI & Agents

Updates

Listing your accounts

Selecting an account

Writes are main-account-only, with two exceptions

The degraded flag

​Listing your accounts

​Selecting an account

​Writes are main-account-only, with two exceptions

​The degraded flag

Listing your accounts

Selecting an account

Writes are main-account-only, with two exceptions

The degraded flag