# SuperX

- [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.
- [Agent skills](https://docs.superx.so/skills.md): 32 goal-shaped recipes, one per SuperX skill, each with its CLI chain, its MCP tool chain, and the point where it hands back to a person.
- [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, the calling key's name and scopes, and the AI credit pool.
- [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 sent to other accounts, newest first. A reply to one of your own posts is a thread continuation, a post in its own right: it is listed under `GET /v1/posts` and never here.
- [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. Totals and series cover the account's own posts: original posts plus thread continuations, which are replies to the account's own posts. Replies to other accounts and reposts are counted separate…
- [Write post drafts in your voice](https://docs.superx.so/api-reference/scheduling/write-post-drafts-in-your-voice.md): Writes post drafts from a brief, in the account's own voice. Nothing is scheduled and nothing is stored: the response is text for you to review and edit, then send to `POST /v1/scheduled-posts` to save a draft or schedule it.
- [Rewrite a post in your voice](https://docs.superx.so/api-reference/scheduling/rewrite-a-post-in-your-voice.md): Rewrites a post in the account's own voice, as close to or as far from the original as you ask. `closeness: 0` keeps only the idea, `closeness: 100` stays very close to the original wording.
- [List drafts and scheduled posts](https://docs.superx.so/api-reference/scheduling/list-drafts-and-scheduled-posts.md): The account's drafts and scheduled posts, most recently updated first, so page 1 is the newest work. Use `page` to walk back through older ones rather than raising `limit`. That ordering covers every `status`, not just drafts: scheduled and sent posts come back most recently updated first too.
- [Create a draft or scheduled post, or publish now](https://docs.superx.so/api-reference/scheduling/create-a-draft-or-scheduled-post-or-publish-now.md): Creates a post: a draft when `scheduled_for` is omitted, a scheduled post otherwise. Works for your main account or any account linked to it (`account_id`); accounts shared with you are read-only. Supports the `Idempotency-Key` header for safe retries (see the Idempotency guide). Successful creation…
- [Retime queued posts in bulk](https://docs.superx.so/api-reference/scheduling/retime-queued-posts-in-bulk.md): Moves up to 500 queued posts to new times in ONE transaction: either every move lands or none do.
- [Enable auto retweet on queued posts in bulk](https://docs.superx.so/api-reference/scheduling/enable-auto-retweet-on-queued-posts-in-bulk.md): Turns Auto Retweet on for up to 100 queued posts at once.
- [Delete queued posts in bulk](https://docs.superx.so/api-reference/scheduling/delete-queued-posts-in-bulk.md): Deletes up to 100 QUEUED posts at once and refunds their post quota. `POST`, not `DELETE`, because the ids travel in a body.
- [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. Works for your main account or any account linked to it (`account_id`); accounts shared with you are read-only.
- [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. Works for your main account or any account linked to it (`account_id`); accounts shared with you are read-only.
- [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.
- [Edit one selected piece of a post](https://docs.superx.so/api-reference/tools/edit-one-selected-piece-of-a-post.md): Edits the piece of a post you select, keeping the style of the text around it. Pass the selection as `text` and the whole post as `full_text`, and the edit is written to drop straight back into place.
- [Rewrite a post one preset way](https://docs.superx.so/api-reference/tools/rewrite-a-post-one-preset-way.md): Applies one preset rewrite to a whole post.
- [Check a statement against a web search](https://docs.superx.so/api-reference/tools/check-a-statement-against-a-web-search.md): Runs a web search for the statement and reports `true`, `false` or `unknown` with a one-sentence comment and the sources it read.
- [Score a draft against this account's own posts](https://docs.superx.so/api-reference/tools/score-a-draft-against-this-accounts-own-posts.md): Scores ONE draft from 0 to 100 against the account's OWN recent posts, and says what helped and what hurt in plain English. The counters block gives the multiple to expect on likes, replies, reposts+quotes and views versus that account's own median post, taken from measured calibration bands rather…
- [Sort recent posts on a topic into Read, Pass or Not sure](https://docs.superx.so/api-reference/tools/sort-recent-posts-on-a-topic-into-read-pass-or-not-sure.md): Searches recent public posts for a topic and sorts them into three lanes: `read`, `pass` and `unsure`. Up to 40 posts a run.
- [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.
- [Read an audience list](https://docs.superx.so/api-reference/audience/read-an-audience-list.md): A page of the account's followers, following, repliers or reposters from SuperX's synced snapshot.
- [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.
- [Get one contact](https://docs.superx.so/api-reference/audience/get-one-contact.md): One person's stored profile (handle, name, bio, location, website, follower counts, verified status) plus the lists you created that they are a member of, each with the `member_id` the remove endpoints take.
- [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.
- [List notes on a contact](https://docs.superx.so/api-reference/audience/list-notes-on-a-contact.md): The private notes this account has written about one person, newest first. Notes live inside SuperX and are never posted anywhere. Not paginated: notes are per-contact and few.
- [Add a note to a contact](https://docs.superx.so/api-reference/audience/add-a-note-to-a-contact.md): Write a private note about one person. The note is attributed to the account it was written as (`created_by`), which for an API write is the account named by `account_id` (your main account when omitted).
- [Delete a note on a contact](https://docs.superx.so/api-reference/audience/delete-a-note-on-a-contact.md): Returns 204 with no body. Deleting an already-deleted note, or a note belonging to another contact, returns 404 `note_not_found`. That is the only check - deleting works on any id the account already has a note on, whether or not that person is still one of its contacts. Works for your main account…
- [Edit a note on a contact](https://docs.superx.so/api-reference/audience/edit-a-note-on-a-contact.md): Replace one note's body. The note must belong to the contact in the path: a note id from another contact returns 404 `note_not_found`. That is the only check - editing works on any id the account already has a note on, whether or not that person is still one of its contacts. Works for your main acco…
- [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.
- [Search the inspiration media index](https://docs.superx.so/api-reference/inspiration/search-the-inspiration-media-index.md): Search the cross-platform media index behind the SuperX app's Inspiration > Media tab: short-form video and image posts from X, Instagram, YouTube, Threads, Reddit and LinkedIn, with captions, a content summary and engagement counts. Use it for visual format and hook research, 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.
- [Create a contact list](https://docs.superx.so/api-reference/contact-lists/create-a-contact-list.md): Create a list you can add people to. Names are NOT unique: the SuperX app allows two lists with the same name and this endpoint matches it, so read `GET /v1/contact-lists` first if the caller expects one list per name. No `Idempotency-Key`: a replay creates a second list, which is visible in the ind…
- [Delete a contact list](https://docs.superx.so/api-reference/contact-lists/delete-a-contact-list.md): Delete a list you created, and with it its membership. The people themselves are untouched, but a signal agent depositing into this list stops until it is repointed in the SuperX app. Returns 204 with no body; a second delete returns 404 `list_not_found`. System lists return 400 `system_list_read_on…
- [Rename a contact list](https://docs.superx.so/api-reference/contact-lists/rename-a-contact-list.md): Rename a list you created. System lists are managed automatically and return 400 `system_list_read_only`. Works for your main account or any account linked to it (`account_id`); accounts shared with you are read-only. Needs the write scope.
- [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. Works…
- [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`. Works for your main account or any account linked to it (`account_id`); accounts shared with you are read-only. Needs the write scope.
- [Add contact list members in bulk](https://docs.superx.so/api-reference/contact-lists/add-contact-list-members-in-bulk.md): Add up to 500 people to a list you created, by numeric X user id.
- [Remove contact list members in bulk](https://docs.superx.so/api-reference/contact-lists/remove-contact-list-members-in-bulk.md): Remove up to 500 members from a list you created, by member id (the `id` from `GET /v1/contact-lists/{id}/members`).
- [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`. Works for your main account or any account linked to it (`account_id`); accounts shared with you are read-only.
- [Update a signal agent](https://docs.superx.so/api-reference/signals/update-a-signal-agent.md): Edit an agent's `name`, `icp_description`, `precision_mode`, `destination_list_id`, `status`, or any combination. At least one field is required.
- [Add a signal to an agent](https://docs.superx.so/api-reference/signals/add-a-signal-to-an-agent.md): Add one thing for the agent to watch: a search (`keyword_watch`), an account's posts (`profile_watch`), the people an account follows (`follower_watch`), or the members of a public X list (`list_watch`). New leads start arriving over the following minutes and days; nothing is returned synchronously.
- [Remove a signal from an agent](https://docs.superx.so/api-reference/signals/remove-a-signal-from-an-agent.md): Remove one signal. Leads it already found stay, and so does the agent's de-duplication state. Removing the agent's LAST signal is allowed: the agent stays, finding nothing, until a signal is added back. Deleting the same id again returns 404 `signal_not_found`. Works for your main account or any acc…
- [Set feedback on a lead](https://docs.superx.so/api-reference/signals/set-feedback-on-a-lead.md): Record the account's verdict on one lead - `fit`, `not_fit`, or `null` to clear it.
- [Search for leads on X now](https://docs.superx.so/api-reference/signals/search-for-leads-on-x-now.md): One live keyword search over X, scored against an ideal-customer profile, returned in the response.
- [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…
- [Suggest keyword watches](https://docs.superx.so/api-reference/signals/suggest-keyword-watches.md): Turns a plain description of an audience into 2 or 3 keyword-watch ideas, the same ones the SuperX app stages when a user sets up a signal agent. Each suggestion is plain language, not an X search query: compilation happens when the keyword is added to an agent.
- [Expand an audience description into a rubric](https://docs.superx.so/api-reference/signals/expand-an-audience-description-into-a-rubric.md): Turns a plain description of an audience into the structured rubric signal agents score people against: who the ideal customer is, the needs that make someone a fit, the disqualifiers, and one example of a match and a non-match.
- [Build an audience profile from a website](https://docs.superx.so/api-reference/signals/build-an-audience-profile-from-a-website.md): Reads a product or company website and infers who its ideal customers are on X: an audience description, the scoring rubric, and keyword-watch ideas, in one call. A bare domain is accepted.
- [List Engage feeds](https://docs.superx.so/api-reference/engage/list-engage-feeds.md): The account's saved Engage feeds: the keyword and list feeds it browses in the SuperX app's Engage tab. Feeds are created and edited in the app; this endpoint only reads them. `fetch_units` is what one fetch of that feed costs against the feed bucket (list feeds count as up to 3, resolved exactly at…
- [Create an Engage feed](https://docs.superx.so/api-reference/engage/create-an-engage-feed.md): Save a new Engage feed on the account: a set of keywords, a public X list, or one of the account's own contact lists. The feed appears in `GET /v1/engage/feeds`, can be fetched with `GET /v1/engage/feeds/{id}/posts`, and shows up for the person in the SuperX app's Engage tab.
- [Delete an Engage feed](https://docs.superx.so/api-reference/engage/delete-an-engage-feed.md): Remove a saved feed. If it was the feed the SuperX app has open, the first remaining feed takes over (or none, when the last feed goes). Posts the feed surfaced are not stored on it and are unaffected. Deleting the same id again returns 404 `feed_not_found`. Works for your main account or any accoun…
- [Update an Engage feed](https://docs.superx.so/api-reference/engage/update-an-engage-feed.md): Rename a saved feed, replace what it watches, or both. Send at most ONE source family per call (`keywords`, `x_list_id`/`x_list_url`, or `list_id`); two families in one body is a 400, because the intent is ambiguous. The feed keeps its id and its place in the account's feed list, so a feed may chang…
- [Get posts from an Engage feed](https://docs.superx.so/api-reference/engage/get-posts-from-an-engage-feed.md): Candidate posts from one saved feed, with the author profile and engagement metrics you need to score them for relevance, author size and recency.
- [Get mentions of the account](https://docs.superx.so/api-reference/engage/get-mentions-of-the-account.md): The posts that @-mention the selected account right now, newest first (or ranked by engagement with `sort=top`), each with the post it replies to and one further level of ancestry.
- [Draft one reply to a post](https://docs.superx.so/api-reference/engage/draft-one-reply-to-a-post.md): Writes ONE reply draft in the account's own voice, using the same engine, prompts and voice settings as the Generate Reply button in the SuperX app.
- [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 Workers](https://docs.superx.so/api-reference/workers/list-workers.md): The account's Workers, newest first: the scheduled AI writers set up in the SuperX app, each with its voice, topic source, shape, batch size, schedule and next run time.
- [List Worker suggestions](https://docs.superx.so/api-reference/workers/list-worker-suggestions.md): The posts the account's Workers wrote, newest first. The default `status=to_review` is the app's "To review" queue: suggestions nobody has drafted, scheduled or dismissed yet.
- [Save a suggestion as a draft](https://docs.superx.so/api-reference/workers/save-a-suggestion-as-a-draft.md): Turn one Worker suggestion into a DRAFT post. Nothing is posted to X: the draft shows up in the user's Drafts in the app and at the top of `GET /v1/scheduled-posts?status=draft`, and the response gives you its `post_id` directly.
- [Schedule a suggestion](https://docs.superx.so/api-reference/workers/schedule-a-suggestion.md): Turn one Worker suggestion into a SCHEDULED post. The SuperX scheduler posts it at `scheduled_for`, the same as any other queued post, so confirm the time and the text with the user before you call this.
- [Dismiss a suggestion](https://docs.superx.so/api-reference/workers/dismiss-a-suggestion.md): Drop one Worker suggestion out of the "To review" queue. No post is created and no post is removed: a suggestion already saved as a draft or a scheduled post keeps that post, which you delete separately with `DELETE /v1/scheduled-posts/{id}` if that is what the user wants.
- [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…
- [Rebuild the generated style guide](https://docs.superx.so/api-reference/context/rebuild-the-generated-style-guide.md): Rewrites the account's GENERATED style guide from its recent posts, the same way the Style Guide button on the SuperX app's Context page does. The result is exactly the `style_guide.generated` block `GET /v1/context` returns.
- [Refresh a product from its page](https://docs.superx.so/api-reference/context/refresh-a-product-from-its-page.md): Re-reads a saved product's page and refreshes its stored name, description and details, the same way the SuperX app's Context page does. The url comes from the SAVED product, never from the request: change it with `PATCH /v1/context/products/{id}` first if it moved.
- [Queue a DM campaign](https://docs.superx.so/api-reference/dms/queue-a-dm-campaign.md): Queues direct messages to up to 100 X users.
- [Read one DM campaign](https://docs.superx.so/api-reference/dms/read-one-dm-campaign.md): The messages this campaign queued, with a count per status. `pending` has not gone out yet and can still be cancelled; `sending` is in flight and cannot be stopped.
- [Cancel a campaign's unsent messages](https://docs.superx.so/api-reference/dms/cancel-a-campaigns-unsent-messages.md): Deletes every message of this campaign still waiting to go out, queued-for-now and scheduled-for-a-later-day alike, and releases the monthly allowance they were holding.
- [List the DM queue](https://docs.superx.so/api-reference/dms/list-the-dm-queue.md): The account's bulk DM rows, newest first: what is waiting, what went out and what failed. Rows queued in the SuperX app appear here too, with `campaign_id: null`.
- [DM allowances and usage](https://docs.superx.so/api-reference/dms/dm-allowances-and-usage.md): The account's DM caps and how much of each is used. These are PLAN limits, not AI credits, and nothing here is charged.
- [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`. Tags are workspace-wide, so this is a main-account write and any other `account_id` returns `403 writes_main_…
- [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). Tags are workspace-wide, so this is a main-account write and any other `account_id` returns `403 writes_main_account_only`.
- [Rename or recolor a tag](https://docs.superx.so/api-reference/tags/rename-or-recolor-a-tag.md): Provide `name` and/or `color`. Tags are workspace-wide, so this is a main-account write and any other `account_id` returns `403 writes_main_account_only`.
- [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. Works for your main account or any account linked to it (`account_id`); accounts shared with you are read-only.
- [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. Works for your main account or any account linked to it (`account_id`); accounts shared with you are read-only.
- [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. Works for your main account or any account linked to it (`account_id`); accounts shared with you are read-only.
- [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`. Steer the artwork with `style_id` (one of the account's saved styles, fr…
- [List saved cover styles](https://docs.superx.so/api-reference/articles/list-saved-cover-styles.md): The article cover styles the account saved in the SuperX app: the art direction of a cover it kept, or a description it typed, with a thumbnail. Pass a style's `id` as `style_id` to `POST /v1/articles/{id}/cover` to render in that look.
- [List datasets](https://docs.superx.so/api-reference/datasets/list-datasets.md): The audience collections Ask SuperX built for the key owner in the app: the repliers, quoters or reposters of a post, the members of an X list, the owner's own posts or replies, or a research brief. Newest first, expired datasets excluded.
- [Collect an audience into a dataset](https://docs.superx.so/api-reference/datasets/collect-an-audience-into-a-dataset.md): Collect the repliers, quote posters or reposters of a post, the members of a public X list, or the account's own posts or replies, into a stored dataset you can then read, export, or copy into a contact list.
- [Get a dataset](https://docs.superx.so/api-reference/datasets/get-a-dataset.md): One dataset's status, counts and coverage.
- [Get dataset rows](https://docs.superx.so/api-reference/datasets/get-dataset-rows.md): A page of a ready dataset's rows.
- [Export a dataset as CSV](https://docs.superx.so/api-reference/datasets/export-a-dataset-as-csv.md): The whole dataset as a CSV file.
- [Add a dataset's people to a contact list](https://docs.superx.so/api-reference/datasets/add-a-datasets-people-to-a-contact-list.md): Copy the people in a ready dataset into a contact list you created.
- [Draft outreach messages onto a research dataset](https://docs.superx.so/api-reference/datasets/draft-outreach-messages-onto-a-research-dataset.md): Writes one personalized message per person in a research dataset, following the `format` you supply.
- [Refine a dataset by what each person wrote](https://docs.superx.so/api-reference/datasets/refine-a-dataset-by-what-each-person-wrote.md): Judges each row's own text against a natural-language `criterion` and keeps or drops it, then optionally sorts and caps what is left into a NEW dataset. The source dataset is never modified.
- [Look up one public post live](https://docs.superx.so/api-reference/x-lookups/look-up-one-public-post-live.md): Read one public X post as it is right now: full text (never shortened), author, engagement counts, media, link card, and the quoted post one level deep when there is one.
- [Top replies to a public post](https://docs.superx.so/api-reference/x-lookups/top-replies-to-a-public-post.md): The best-liked DIRECT replies to a public post, read live from X.
- [Look up one public profile live](https://docs.superx.so/api-reference/x-lookups/look-up-one-public-profile-live.md): Read one public X profile as it is right now: bio, location, link, follower and following counts, post count, join date and pinned post id. The handle may be given with or without a leading `@`.
- [Latest posts of a public account](https://docs.superx.so/api-reference/x-lookups/latest-posts-of-a-public-account.md): One live timeline page (about 20 posts) for any public account, newest first, with engagement counts. The up-to-the-minute source for what an account just posted.
- [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](/api-reference/openapi.yaml)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.