> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superx.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Accounts

> Main, linked and shared accounts, the account_id selector, and degraded responses.

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

```bash theme={null}
curl https://api.superx.so/v1/accounts \
  -H "Authorization: Bearer sxk_..."
```

```json theme={null}
{
  "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.