> ## 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. # Publish an article to X now > 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 and 5 publishes per day), which surface as 502 `x_publish_failed` with the failure detail. Supports `Idempotency-Key`, strongly recommended. A 504 `upstream_timeout` is AMBIGUOUS: the publish may still have completed; GET the article and check its status before retrying. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/articles/{id}/publish openapi: 3.1.0 info: title: SuperX API version: 1.0.0 description: > The SuperX public API: your Twitter/X content, analytics, audience and scheduling data over REST. All endpoints require an API key (`Authorization: Bearer sxk_...`) except `GET /v1/docs`. Keys are created in the SuperX app under Account > API / MCP / CLI and are server-side secrets. Timestamps are UTC ISO-8601 in both directions; inputs must carry an explicit `Z` or numeric offset. Every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers. contact: name: SuperX url: https://superx.so servers: - url: https://api.superx.so security: - apiKey: [] tags: - name: Identity - name: Content - name: Analytics - name: Inspiration - name: Audience - name: Contact Lists - name: Signals - name: Media - name: Scheduling - name: Tags - name: Context - name: Queue - name: Articles - name: Meta paths: /v1/articles/{id}/publish: post: tags: - Articles summary: Publish an article to X now description: > 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 and 5 publishes per day), which surface as 502 `x_publish_failed` with the failure detail. Supports `Idempotency-Key`, strongly recommended. A 504 `upstream_timeout` is AMBIGUOUS: the publish may still have completed; GET the article and check its status before retrying. operationId: publishArticle parameters: - name: id in: path required: true schema: type: string - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: false content: application/json: schema: type: object properties: account_id: type: string responses: '200': description: Published. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: type: object properties: data: type: object properties: id: type: string status: type: string enum: - published post_id: type: string nullable: true url: type: string nullable: true published_at: type: string format: date-time nullable: true example: data: id: k9GdPzR4wq2xVbY0nT1sc status: published post_id: '1790000000000000000' url: https://x.com/i/status/1790000000000000000 published_at: '2026-07-07T12:00:00.000Z' '400': $ref: '#/components/responses/InvalidParameter' '401': $ref: '#/components/responses/Unauthorized' '402': description: Post quota exceeded for the current billing period. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: post_quota_exceeded message: Post quota exceeded for the current billing period. '403': description: >- Read-only key (`insufficient_scope`), linked account (`writes_main_account_only`), missing X Premium (`x_premium_required`), a connected account needing re-authorization (`reauth_required`), or a lapsed subscription. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/LegacyErrorEnvelope' example: error: code: x_premium_required message: >- Publishing articles requires X Premium on the connected account. '404': $ref: '#/components/responses/ArticleNotFound' '409': description: >- The article's status does not allow publishing (already published, or a publish is in flight). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: article_not_editable message: This article is already published '429': $ref: '#/components/responses/RateLimited' '502': description: >- The publish failed (`x_publish_failed`, article returned to draft, quota refunded) or could not be confirmed (`x_publish_ambiguous`, check the article's status). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: x_publish_failed message: The publish failed. The article was returned to draft. '504': description: >- AMBIGUOUS timeout. The publish may still have completed. GET the article to check its status before retrying. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: upstream_timeout message: >- The publish did not respond in time and may still have completed. GET the article to check its status before retrying. components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Unique key (max 64 characters) for safe retries. Replays carry the "Idempotency-Replayed" response header set to "true". Keys are retained for 24 hours. schema: type: string maxLength: 64 headers: X-RateLimit-Limit: description: The limit of the rate window closest to exhaustion. schema: type: integer X-RateLimit-Remaining: description: Requests remaining in that window. schema: type: integer X-RateLimit-Reset: description: Unix timestamp (seconds) when that window resets. schema: type: integer responses: InvalidParameter: description: A parameter is missing, malformed, or out of range. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: invalid_parameter message: since must be a UTC ISO-8601 timestamp Unauthorized: description: >- Missing/malformed Authorization header (`unauthorized`) or an unknown/revoked key (`invalid_api_key`). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: invalid_api_key message: Unknown or revoked API key ArticleNotFound: description: No article with that id belongs to this account. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: not_found message: No article with that id belongs to this account. RateLimited: description: Rate limit exceeded (limits vary by plan). Honor Retry-After. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: rate_limited message: >- Rate limit exceeded for the Pro plan (30 requests/min). Upgrade for higher limits. retry_after: 42 schemas: ErrorEnvelope: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Stable machine-readable error code. message: type: string retry_after: type: integer description: Seconds to wait before retrying (rate-limit errors only). LegacyErrorEnvelope: type: object required: - error description: | Legacy shape used ONLY by the shared subscription middleware: a plain string `error` field. Seen on `403` when the subscription has lapsed (string starts with "subscription_required:") and on `500` when subscription verification fails (string starts with "internal_error:"). properties: error: type: string example: >- subscription_required: The SuperX API requires an active subscription securitySchemes: apiKey: type: http scheme: bearer description: >- A SuperX API key ("sxk_..."), created in the SuperX app under Account > API / MCP / CLI. Keys are server-side secrets. ````