> ## 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. # Presign an image upload > 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 endpoints. Images only: `image/jpeg`, `image/png`, `image/webp` (5 MB max each) and `image/gif` (15 MB max). The attach step re-checks the real bytes (size and magic-byte type), so a mismatched upload fails at attach time. Uploads never attached to a post are deleted after 24 hours. Needs the write scope. Quota: 100 uploads per key per day, on top of the normal write rate limits. No `Idempotency-Key` handling: a duplicate presign is just an unused upload that expires. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/media 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/media: post: tags: - Media summary: Presign an image upload description: | 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 endpoints. Images only: `image/jpeg`, `image/png`, `image/webp` (5 MB max each) and `image/gif` (15 MB max). The attach step re-checks the real bytes (size and magic-byte type), so a mismatched upload fails at attach time. Uploads never attached to a post are deleted after 24 hours. Needs the write scope. Quota: 100 uploads per key per day, on top of the normal write rate limits. No `Idempotency-Key` handling: a duplicate presign is just an unused upload that expires. operationId: createMediaUpload requestBody: required: true content: application/json: schema: type: object required: - filename - file_type - size properties: filename: type: string description: Original filename; sanitized into the object key. file_type: type: string enum: - image/jpeg - image/png - image/webp - image/gif size: type: integer description: File size in bytes. 5 MB max (15 MB for GIF). example: filename: chart.png file_type: image/png size: 48213 responses: '201': description: The registered upload and its presigned PUT URL. 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: object_key: type: string description: >- Pass this in `parts[].media` when creating or editing a post. url: type: string description: The public URL the file will have once uploaded. upload_url: type: string description: >- Presigned PUT URL. Upload the raw bytes here with `Content-Type` equal to `file_type`. expires_at: type: string format: date-time description: When the upload_url stops working (20 minutes). example: data: object_key: u123/api_1751980800000_9f3a1c2b_chart.png url: >- https://media.superx.so/u123/api_1751980800000_9f3a1c2b_chart.png upload_url: >- https:///u123/api_1751980800000_9f3a1c2b_chart.png?X-Amz-... expires_at: '2026-07-08T15:20:00.000Z' '400': description: >- Invalid parameter, unsupported type (`unsupported_media_type`; videos land here), or over the size cap (`media_too_large`). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: unsupported_media_type message: >- file_type must be one of: image/jpeg, image/png, image/webp, image/gif. Videos are not supported yet. '401': $ref: '#/components/responses/Unauthorized' '403': description: >- Read-only key (`insufficient_scope`) or a lapsed subscription (legacy string envelope). content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/LegacyErrorEnvelope' example: error: code: insufficient_scope message: >- This API key is read-only. Create a key with the write scope to use this endpoint. '429': description: >- Write rate limit (`rate_limited`) or the daily media quota (`media_quota_exceeded`, 100/day). `Retry-After` indicates the wait. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: media_quota_exceeded message: >- Daily media upload limit reached (100/day). Retry after the indicated delay. '500': $ref: '#/components/responses/InternalError' '503': description: >- Media storage is not configured (`media_not_configured`) or temporarily unavailable (`upstream_unavailable`). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: media_not_configured message: >- Media storage is not configured on this server. Try again later. components: 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 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 responses: 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 InternalError: description: >- Unexpected server error. May also use the legacy string envelope when subscription verification fails. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/LegacyErrorEnvelope' example: error: code: internal_error message: Failed to fetch posts 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. ````