# SuperX

## Docs

- [Introduction](https://docs.superx.so/introduction.md): The SuperX public API: your Twitter/X content, analytics and audience data over simple REST endpoints.
- [Authentication](https://docs.superx.so/authentication.md): API keys, scopes and how to keep them safe.
- [Accounts](https://docs.superx.so/accounts.md): Main, linked and shared accounts, the account_id selector, and degraded responses.
- [Rate limits](https://docs.superx.so/rate-limits.md): Per-plan request limits, response headers and how to back off.
- [Errors](https://docs.superx.so/errors.md): The error envelope, every error code, and one legacy exception to know about.
- [Idempotency](https://docs.superx.so/idempotency.md): Safely retry POST /v1/scheduled-posts without creating duplicates.
- [CLI & agent skill](https://docs.superx.so/cli.md): Use the SuperX API from your terminal with the superx CLI, or hand it to an AI agent with the superx-agent skill.
- [MCP server](https://docs.superx.so/mcp-server.md): Connect Claude Code, Codex, ChatGPT, and Claude directly to your SuperX data with the hosted SuperX MCP server.
- [Changelog](https://docs.superx.so/updates.md): API changes, newest first.
- [Get the key owner](https://docs.superx.so/api-reference/identity/get-the-key-owner.md): Returns the key owner, their plan, and the calling key's name and scopes.
- [List your accounts](https://docs.superx.so/api-reference/identity/list-your-accounts.md): The accounts this key may act on: your main account plus any linked accounts. When linked accounts cannot be verified, the response degrades to the main account only and carries a top-level `degraded: true` flag; retry shortly for the full list.
- [List published posts](https://docs.superx.so/api-reference/content/list-published-posts.md)
- [List replies you sent](https://docs.superx.so/api-reference/content/list-replies-you-sent.md): Replies the selected account has posted, newest first.
- [Get analytics](https://docs.superx.so/api-reference/analytics/get-analytics.md): Totals and a per-day series (posts, engagement, impressions, follower samples) for the selected account. Default range is the last 30 days; the maximum range is 366 days.
- [List replies you received](https://docs.superx.so/api-reference/audience/list-replies-you-received.md): Every stored reply the selected account has received across all of its posts, with the replier's profile and the replied-to post when available.
- [List engaged contacts](https://docs.superx.so/api-reference/audience/list-engaged-contacts.md): People who engaged with the selected account over the moving 90-day window, with reply and repost tallies.
- [List one contact's replies to you](https://docs.superx.so/api-reference/audience/list-one-contacts-replies-to-you.md): The stored reply history from one contact to the selected account, with the replied-to post when available.
- [Search the inspiration library](https://docs.superx.so/api-reference/inspiration/search-the-inspiration-library.md): Search a library of 50M+ real high-performing posts by topic. Use the results for structures, hooks and angles to remix, never to copy.
- [List contact lists](https://docs.superx.so/api-reference/contact-lists/list-contact-lists.md): The selected account's contact lists: system lists first (Followers, Following, Repliers, Reposters; `is_system: true` with a `kind`), then lists you created, newest first. System lists are read-only and index-only: their members are not readable through the API and `member_count` is 0 for them.
- [List contact list members](https://docs.superx.so/api-reference/contact-lists/list-contact-list-members.md): Members of one contact list you created. Includes a 90-day `engaged_count` (replies + reposts to the account) per member. System lists return 400 `system_list_not_supported`.
- [Add a contact list member](https://docs.superx.so/api-reference/contact-lists/add-a-contact-list-member.md): Add a person to a list you created, by `handle` (live profile lookup) or by `x_user_id` (numeric X user id already known to SuperX). Exactly one of the two. Naturally idempotent: adding someone already in the list returns 200 with the existing member and `duplicate: true`, and writes nothing. Main a…
- [Remove a contact list member](https://docs.superx.so/api-reference/contact-lists/remove-a-contact-list-member.md): Remove a member from a list you created. Returns 204 with no body. Removing an already-removed member returns 404 `member_not_found`. Main account only; needs the write scope.
- [List signal agents](https://docs.superx.so/api-reference/signals/list-signal-agents.md): The account's signal agents: the automated lead finders from the SuperX app. Each agent watches one or more signals (profiles, followers, keywords, or lists) and scores the people it finds against its ideal customer profile. Agents can be created, paused, resumed, and deleted through the API; name,…
- [Create a signal agent](https://docs.superx.so/api-reference/signals/create-a-signal-agent.md): Create a signal agent: it watches X for the given keywords and scores the people it finds against `icp_description`. Matching leads land in Signals (and `GET /v1/signals/leads`) over the following minutes and days; nothing is returned synchronously.
- [Delete a signal agent](https://docs.superx.so/api-reference/signals/delete-a-signal-agent.md): Delete an agent. The leads it already saved and its destination contact list stay untouched. Deleting the same id again returns 404 `agent_not_found`. Main account only in v1.
- [Pause or resume a signal agent](https://docs.superx.so/api-reference/signals/pause-or-resume-a-signal-agent.md): Status-only lifecycle: `active` or `paused`. Paused agents stop finding leads; resuming picks up where the agent left off (a resume is rejected with `invalid_request` when the agent's destination list is gone; point it at a new list in the SuperX app first). Other fields (name, ICP, precision, desti…
- [List signal leads](https://docs.superx.so/api-reference/signals/list-signal-leads.md): The leads the account's signal agents have found, newest first: people who matched an agent's ideal customer profile, with their profile, the match score and rationale, whether the lead has been saved to the agent's contact list yet (`deposited`/`deposited_at`), and provenance describing how the lea…
- [Presign an image upload](https://docs.superx.so/api-reference/media/presign-an-image-upload.md): Registers an image upload and returns a presigned `upload_url`. PUT the raw file bytes to `upload_url` within 20 minutes, with the `Content-Type` header set to the same `file_type` you declared here. Then reference the returned `object_key` in `parts[].media` on the scheduled-posts create/update end…
- [List drafts and scheduled posts](https://docs.superx.so/api-reference/scheduling/list-drafts-and-scheduled-posts.md)
- [Create a draft or scheduled post](https://docs.superx.so/api-reference/scheduling/create-a-draft-or-scheduled-post.md): Creates a post: a draft when `scheduled_for` is omitted, a scheduled post otherwise. Main account only in v1. Supports the `Idempotency-Key` header for safe retries (see the Idempotency guide). Successful creation returns `201`.
- [Delete a draft or scheduled post](https://docs.superx.so/api-reference/scheduling/delete-a-draft-or-scheduled-post.md): Deletes the post and refunds any quota it held. Main account only in v1.
- [Edit a draft or scheduled post](https://docs.superx.so/api-reference/scheduling/edit-a-draft-or-scheduled-post.md): Partial update: only the fields you send change; everything else on the post (including fields the API does not expose) is preserved. Main account only in v1.
- [List plug templates](https://docs.superx.so/api-reference/scheduling/list-plug-templates.md): Lists your auto-plug reply templates (authored in the SuperX app under Default Post Settings). Pass a template id as `auto_plug.template_id` when creating or updating a scheduled post.
- [Get context settings](https://docs.superx.so/api-reference/context/get-context-settings.md): The account's Context settings in one document: the background SuperX's AI uses when writing for the account. `profile_description` grounds the voice and personalizes the daily content mix and search; `interests` are the highest-priority content topics; `rules` are mandatory instructions on every AI…
- [Update context settings](https://docs.superx.so/api-reference/context/update-context-settings.md): Edit any subset of the Context settings; only the fields you send change. Strings accept `null` to clear (style-guide overrides then revert to the generated guide). Arrays fully REPLACE the stored list: send every value the account should keep, `[]` clears. `voice.favorite_creators` takes X username…
- [Replace the product list](https://docs.superx.so/api-reference/context/replace-the-product-list.md): Reconciles the account's products to exactly the submitted list (max 5). CAUTION: this is a FULL REPLACE by url - any existing product whose url is missing from the payload is removed. To edit one product without touching the others, use PATCH /v1/context/products/{id}. Removal is reversible: re-add…
- [Remove one product](https://docs.superx.so/api-reference/context/remove-one-product.md): Removes one product by its numeric id (from GET /v1/context). Reversible: re-adding the same url via PATCH or PUT restores the product with its scraped details intact.
- [Add or edit one product](https://docs.superx.so/api-reference/context/add-or-edit-one-product.md): Edits one product without touching the others. `{id}` is either a numeric product id (from GET /v1/context) or a URL-encoded product url. By url the call upserts: it edits the product with that url or creates it when it does not exist yet (cap 5) - this is the single-product create path. Only the fi…
- [Get queue settings](https://docs.superx.so/api-reference/queue/get-queue-settings.md): The account's posting schedule: the predefined time slots the queue fills and the timezone they run in (the Edit Queue modal in the SuperX app). `slots` are `{ time, days }` entries with 0 = Sunday, sorted by time; `slot_count` is the total number of time and day pairs. `timezone_is_default` and `sl…
- [Update queue settings](https://docs.superx.so/api-reference/queue/update-queue-settings.md): Changes the account's posting schedule. Send `slots`, `timezone`, or both; only what you send changes. `slots` is a FULL REPLACE (max 50 entries, one per unique time, each with at least one weekday, 0 = Sunday); `[]` clears every predefined slot and leaves the queue all-custom.
- [List tags](https://docs.superx.so/api-reference/tags/list-tags.md): Tags organize drafts and scheduled posts. They are scoped to the workspace owner and shared across linked accounts. Sorted by name A-Z.
- [Create a tag](https://docs.superx.so/api-reference/tags/create-a-tag.md): Names are unique per workspace. `color` is a palette name the SuperX app renders (rose, amber, lime, emerald, teal, cyan, blue, indigo, violet, fuchsia, slate, stone); it defaults to `blue`. Main account only in v1.
- [Delete a tag](https://docs.superx.so/api-reference/tags/delete-a-tag.md): Deletes the tag and removes it from every draft and scheduled post that carries it (the posts themselves are untouched). Main account only in v1.
- [Rename or recolor a tag](https://docs.superx.so/api-reference/tags/rename-or-recolor-a-tag.md): Provide `name` and/or `color`. Main account only in v1.
- [List articles](https://docs.superx.so/api-reference/articles/list-articles.md): Long-form X Articles for the selected account, newest-updated first. Article bodies do NOT appear in lists; fetch one article for its markdown body.
- [Create an article draft](https://docs.superx.so/api-reference/articles/create-an-article-draft.md): Creates a draft. `content_markdown` (max 400KB) converts to the article's stored rich-text form: headings (h1-h3), bullet and numbered lists (one nesting level), blockquotes, bold/italic/strikethrough, links, images by http(s) URL, and bare X post URLs alone on a line as embeds. Constructs the forma…
- [Get an article](https://docs.superx.so/api-reference/articles/get-an-article.md): One article including `content_markdown`. Articles edited in the SuperX editor can carry rich-text constructs markdown cannot express exactly; those degrade to their text content in the markdown view.
- [Delete an article](https://docs.superx.so/api-reference/articles/delete-an-article.md): Deletes the article. Scheduled articles refund the quota their scheduling deducted. Main account only in v1.
- [Edit an article](https://docs.superx.so/api-reference/articles/edit-an-article.md): Partial edit. Only provided fields change. `content_markdown` replaces the WHOLE body. `cover_url` attaches an http(s) image as the cover; `null` removes the cover. Main account only in v1.
- [Publish an article to X now](https://docs.superx.so/api-reference/articles/publish-an-article-to-x-now.md): Publishes the article immediately from its STORED title, body, and cover. Irreversible: the article goes live publicly and post quota is spent. Requires X Premium on the connected account; without it the publish fails with 403 `x_premium_required`. X also enforces its own article limits (10 drafts a…
- [Schedule or reschedule an article](https://docs.superx.so/api-reference/articles/schedule-or-reschedule-an-article.md): Schedules the article for `scheduled_for` (UTC ISO-8601 with an explicit Z or offset, more than 2 minutes in the future; no maximum horizon). Scheduling a draft deducts post quota, refunded on unschedule or delete. Rescheduling an already scheduled article is a free time-only move. Supports `Idempot…
- [Unschedule an article](https://docs.superx.so/api-reference/articles/unschedule-an-article.md): Pulls a scheduled article back to draft and refunds exactly the quota its scheduling deducted. Main account only in v1.
- [Generate an AI cover image](https://docs.superx.so/api-reference/articles/generate-an-ai-cover-image.md): Generates a 2.5:1 cover image from the article's TITLE (a title is required) and, by default, attaches it as the article's cover. `attach: false` generates without touching the current cover; attach later via PATCH `cover_url`. `style_text` (max 8000 chars) steers the artwork.
- [Machine-readable quickstart](https://docs.superx.so/api-reference/meta/machine-readable-quickstart.md): A short markdown quickstart (auth header, base URL, endpoint list, rate limits). No authentication required.

## OpenAPI Specs

- [openapi](https://docs.superx.so/api-reference/openapi.yaml)