curl --request POST \
--url https://api.superx.so/v1/scheduled-posts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"text": "Shipping day.",
"scheduled_for": "2026-07-08T15:00:00Z"
}
'{
"data": {
"id": "V1StGXR8_Z5jdHi6B-myT",
"status": "scheduled",
"scheduled_for": "2026-07-08T15:00:00.000Z",
"parts": [
{
"text": "Shipping day."
}
],
"title": null,
"scratchpad": null,
"tags": [],
"created_at": "2026-07-06T10:00:00.000Z"
}
}{
"error": {
"code": "invalid_media",
"message": "Unknown object_key: u123/api_..._chart.png. Upload media first via POST /v1/media."
}
}{
"error": {
"code": "invalid_api_key",
"message": "Unknown or revoked API key"
}
}{
"error": {
"code": "writes_main_account_only",
"message": "Accounts shared with you are read-only through the API. Writes work on your own main and linked accounts."
}
}{
"error": {
"code": "account_not_found",
"message": "No account with that id belongs to this key"
}
}{
"error": {
"code": "idempotency_key_reuse",
"message": "This Idempotency-Key was already used with a different request body."
}
}{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded for the Pro plan (30 requests/min). Upgrade for higher limits.",
"retry_after": 42
}
}{
"error": {
"code": "internal_error",
"message": "Failed to fetch posts"
}
}{
"error": {
"code": "upstream_error",
"message": "Failed to fetch scheduled posts. Try again shortly."
}
}{
"error": {
"code": "upstream_unavailable",
"message": "The scheduling service is temporarily unavailable. Retry with the same Idempotency-Key."
}
}Scheduling
Create a draft or scheduled post, or publish now
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 returns 201.
Publishing now. Send scheduled_for: "now" and the post goes to X
immediately. This is irreversible, so the rules are tighter:
Idempotency-Keyis REQUIRED (400 invalid_parameterwithout it). Reuse the same key on any retry: it never publishes twice.titleandscratchpadare rejected with400(a published post has no draft to organize), and Bluesky is never cross-posted.- A retry that arrives while the first attempt is still publishing
returns
409 idempotency_in_flightwith aRetry-Afterheader. After that window the API checks whether the first attempt landed and replays its result instead of posting again. - The
201carriesstatus: "sent"withposted_at,x_post_idandurl, andscheduled_for: null. - Advanced settings and Auto DM inherit your Default Post Settings exactly as they do for a scheduled post.
- A thread that fails part way through leaves no scheduled-post record
at all, so check
GET /v1/postsbefore retrying: the parts X did accept are already live.
Images attach per part: parts[].media is an array of
{ object_key, alt_text? } items, with object_key from
POST /v1/media (uploaded bytes required first). Up to 4 images or
exactly 1 GIF per part; alt_text is capped at 1,000 characters.
Video is not supported yet.
Advanced settings (auto_retweet, auto_delete, auto_plug,
auto_dm, super_followers_only): omit a setting to inherit its
Default Post Settings value from the SuperX app, send an object (or
true/false for super_followers_only) to override, or send
null to turn it off for this post. Exactly five settings inherit
this way: auto retweet, auto delete, auto plug, auto DM, and Super
Followers only. Other composer defaults (for example Bluesky
cross-posting or share-with-followers) are never applied to API
posts.
auto_dm direct-messages the people who reply to or repost the post
once it is live. Your plan caps how many posts a month may carry one
(posts_with_auto_dm in GET /v1/dm/limits): when that cap stops
it, the post is still created and the response carries
auto_dm_skipped: true instead of failing. Reading a post back shows
that an auto DM is attached but never its message text.
POST
/
v1
/
scheduled-posts
curl --request POST \
--url https://api.superx.so/v1/scheduled-posts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"text": "Shipping day.",
"scheduled_for": "2026-07-08T15:00:00Z"
}
'{
"data": {
"id": "V1StGXR8_Z5jdHi6B-myT",
"status": "scheduled",
"scheduled_for": "2026-07-08T15:00:00.000Z",
"parts": [
{
"text": "Shipping day."
}
],
"title": null,
"scratchpad": null,
"tags": [],
"created_at": "2026-07-06T10:00:00.000Z"
}
}{
"error": {
"code": "invalid_media",
"message": "Unknown object_key: u123/api_..._chart.png. Upload media first via POST /v1/media."
}
}{
"error": {
"code": "invalid_api_key",
"message": "Unknown or revoked API key"
}
}{
"error": {
"code": "writes_main_account_only",
"message": "Accounts shared with you are read-only through the API. Writes work on your own main and linked accounts."
}
}{
"error": {
"code": "account_not_found",
"message": "No account with that id belongs to this key"
}
}{
"error": {
"code": "idempotency_key_reuse",
"message": "This Idempotency-Key was already used with a different request body."
}
}{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded for the Pro plan (30 requests/min). Upgrade for higher limits.",
"retry_after": 42
}
}{
"error": {
"code": "internal_error",
"message": "Failed to fetch posts"
}
}{
"error": {
"code": "upstream_error",
"message": "Failed to fetch scheduled posts. Try again shortly."
}
}{
"error": {
"code": "upstream_unavailable",
"message": "The scheduling service is temporarily unavailable. Retry with the same Idempotency-Key."
}
}Authorizations
A SuperX API key ("sxk_..."), created in the SuperX app under Account > API / MCP / CLI. Keys are server-side secrets.
Headers
Unique key (max 64 characters) for safe retries. Replays carry the "Idempotency-Replayed" response header set to "true". Keys are retained for 24 hours.
Maximum string length:
64Body
application/json
The post text (single post). Provide either text or parts. Media rides parts, so a post with media, including a media-only post, uses parts.
Thread parts, 1 to 25 items. Total text across parts is limited to 25,000 characters. A part's text is optional when the part has media (a media-only post) and comes back as an empty string. A post with no text and no media at all is rejected.
Show child attributes
Show child attributes
UTC ISO-8601 with explicit Z or offset: at least 60 seconds in the future, at most 18 months out. Omit to create a draft. The literal string "now" publishes to X immediately and requires an Idempotency-Key (see the operation description).
Draft title shown in the SuperX app. Organizational only, never posted.
Maximum string length:
300Private working notes attached to the post. Never posted.
Maximum string length:
30000Tag ids to assign (from GET /v1/tags). Unknown ids fail the whole request with 400 unknown_tag before anything is created.
Maximum array length:
20Auto retweet. Omit to inherit your Default Post Settings; null turns it off for this post.
Show child attributes
Show child attributes
Auto delete underperforming posts. Omit to inherit your defaults; null turns it off for this post.
Show child attributes
Show child attributes
Auto plug: reply with a template once the post hits a likes threshold. Omit to inherit your defaults; null turns it off for this post. Unknown template ids fail with 400 unknown_plug_template.
Show child attributes
Show child attributes
Auto DM: message the people who reply to or repost this post once it is live. Omit to inherit your defaults; null turns it off for this post.
Show child attributes
Show child attributes
Post to Super Followers only. Omit to inherit your defaults.
Any account you own, meaning your main account (the default when omitted) or one linked to it. An account shared with you returns 403 writes_main_account_only.
Response
The created post (echo of the accepted request, not the stored row). Replayed idempotent requests also return this body with the "Idempotency-Replayed" header set to "true". Applied advanced settings, inherited or explicit, are NOT echoed here; read them back via GET /v1/scheduled-posts, adding ?status=sent for a post published with scheduled_for: "now".
Show child attributes
Show child attributes