Skip to main content
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

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. Some take it as a query parameter and some as a body field, so check the endpoint in the API reference for where it goes. 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 on your own accounts, reads on every account

Writes work on any account you own: your main account and every account you linked to it. Pass that account’s account_id on the write, or leave account_id out to use your main account. Reads work for every account in the list. Accounts other people shared with you are read-only through the API. A write that targets one returns 403 writes_main_account_only (the code is unchanged for compatibility; the message explains the shared-account rule). Run those writes from the SuperX app instead. Two surfaces have their own rules:
  • Tags are workspace-wide: one set of tags covers all your linked accounts, so POST, PATCH and DELETE /v1/tags accept only your main account and return 403 writes_main_account_only for any other account_id. The tags you manage there apply everywhere.
  • Context and queue settings are per-account, and unlike other writes they also accept a shared account_id. PATCH /v1/context and the /v1/context/products endpoints return 403 editor_restricted on a share with editor permission: only the account owner can change what the AI knows about the account. PATCH /v1/queue-settings stays open to editor-permission shares, which mirrors the SuperX app, where running the queue is what a delegate is there for.
POST /v1/media takes no account_id. Uploads belong to you rather than to one X account, so an object_key can be attached to a post on any of your accounts.

​
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.