> ## 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. # Search the inspiration media index > 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. Media file URLs are not exposed through the API; open `source_url` for the original post. Owner-scoped, so there is no `account_id`. Omit `q` to BROWSE the newest media instead of searching; `meta.mode` reports which ran, and only `search` results carry a `score`. Unlike the app there is no personalisation: the app fills an empty search box from the signed-in person's profile and click history, which an owner-scoped key has no equivalent of. There is NO pagination: the index returns at most 120 items per query, and `limit` only trims that. Ask for the 120 and filter on your side rather than looking for a page parameter. Counts as a read and costs no enrichment units. The media index has two caps of its own, per account: a burst of 20 refilling one every 3 seconds, and 500 FRESH searches per UTC day. Repeats of a recent identical search are served from a short-lived cache and do not count against the daily cap. Both return `429 rate_limited` with `Retry-After`. ## OpenAPI ````yaml /api-reference/openapi.yaml get /v1/inspiration/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: Datasets description: | The audience collections Ask SuperX builds in the app: the repliers, quoters or reposters of a post, the members of an X list, your own posts or replies, or a research brief. Collect a new one with `POST /v1/datasets` (a big collection answers 202 and finishes in the background), read it, export it, or copy the people in it into a contact list you created. Datasets are kept for 30 days, and the ones Ask SuperX builds in the app show up here too. - name: Engage description: | The account's saved Engage feeds and the candidate posts in them, for an agent to score and a person to act on. Read-only by design. These endpoints return feed candidates for a person to review; replies are written and sent by a person in the SuperX app, which is why there is no reply endpoint here. Sending spammy, automated, or AI-generated replies that read as inauthentic may get your X account suspended under X's inauthentic-behavior rules and your SuperX account terminated. AI suggestions must be reviewed and meaningfully edited before they are sent, and you are solely responsible for what you post. Reply activity is logged and may be audited. - name: X Lookups description: | Read any public post, its top replies, any public profile, or an account's latest posts LIVE from X, rather than from SuperX's stored data. These are owner-scoped, so none of them take an `account_id`: nothing about a public lookup is per-X-account. They cost the tighter live-enrichment allowance and share a daily allowance of 300 live lookups with Ask SuperX inside the app, so use them for what you actually need rather than to sweep. Repeat lookups within 15 minutes may be served from a short-lived server-side cache. - name: Tools description: | The composer helpers from the SuperX app, over the API: rewrite a post, edit one selected piece of it, apply one preset rewrite, check a claim, or compare two versions. Every one of them returns TEXT and writes nothing. Nothing here is posted, scheduled or sent; save what you keep with `POST /v1/posts/draft` or `POST /v1/scheduled-posts`. They cost AI credits, measured from the models' real cost, and spend no live-data allowance. - name: Media - name: Workers description: | The posts the account's Workers have written, and the three things a person does with one: save it as a draft, schedule it, or dismiss it. A Worker is a scheduled AI writer set up in the SuperX app. Creating, editing and running one stays in the app, so there is no create or run endpoint here. What a run produces lands in the app's "To review" queue and is read with `GET /v1/workers/suggestions`. NOTHING HERE POSTS TO X. Drafting or scheduling a suggestion writes a post the user can see in the app and on `GET /v1/scheduled-posts`, exactly like the app's own buttons. AI output must be reviewed and meaningfully edited by a person before it goes out, so show the text to the user and confirm the time before you schedule anything. - name: Scheduling - name: Tags - name: Context - name: Queue - name: DMs description: | Queue direct messages into the account's own DM pipeline, and read or cancel what is waiting. NOTHING HERE SENDS A MESSAGE. `POST /v1/dm/campaigns` enqueues; the SuperX app's scheduler is what sends, within the account's daily and monthly DM limits, so the create response is counts, not deliveries. Unsent messages can be cancelled until the scheduler picks them up. You are responsible for the messages you queue. Unsolicited or automated bulk DMs may get an X account suspended under X's rules and a SuperX account terminated, so confirm the recipient list and the exact wording with the person on whose behalf you are queueing. - name: Articles - name: Meta paths: /v1/inspiration/media: get: tags: - Inspiration summary: Search the inspiration media index description: | 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. Media file URLs are not exposed through the API; open `source_url` for the original post. Owner-scoped, so there is no `account_id`. Omit `q` to BROWSE the newest media instead of searching; `meta.mode` reports which ran, and only `search` results carry a `score`. Unlike the app there is no personalisation: the app fills an empty search box from the signed-in person's profile and click history, which an owner-scoped key has no equivalent of. There is NO pagination: the index returns at most 120 items per query, and `limit` only trims that. Ask for the 120 and filter on your side rather than looking for a page parameter. Counts as a read and costs no enrichment units. The media index has two caps of its own, per account: a burst of 20 refilling one every 3 seconds, and 500 FRESH searches per UTC day. Repeats of a recent identical search are served from a short-lived cache and do not count against the daily cap. Both return `429 rate_limited` with `Retry-After`. operationId: searchInspirationMedia parameters: - name: q in: query description: >- What to search for (max 300 characters). Omit to browse the newest media. schema: type: string maxLength: 300 - name: platforms in: query description: | Comma-separated platforms to include. Default: `instagram,youtube,x,threads`. schema: type: string example: youtube,instagram - name: time_filter in: query description: How recent the media must be. schema: type: string enum: - all - 24h - 7d - 30d default: all - name: media_type in: query description: Media kind. schema: type: string enum: - all - video - image default: all - name: content_type in: query description: | Free-text content-type label as stored in the index (max 50 characters). There is no enumerated list: a label the index does not use returns zero items and still counts against the daily search cap, so leave it off unless you know the label. schema: type: string maxLength: 50 - name: limit in: query description: Items to return (1-120). 120 is everything one query can return. schema: type: integer minimum: 1 maximum: 120 default: 20 responses: '200': description: Matching media items. 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: array items: $ref: '#/components/schemas/MediaItem' meta: type: object properties: mode: type: string enum: - search - browse description: >- search = ranked against your query, browse = newest first. total: type: integer description: Items the index returned before the `limit` slice. example: data: - id: ig_3421887766 platform: instagram title: 3 hooks that made this reel go to 2M caption: The first second is everything. summary: >- Creator breaks down three opening lines and why each one holds attention. content_type: educational source_url: https://instagram.com/p/Cxyz123 author_username: hookschool author_url: https://instagram.com/hookschool posted_at: '2026-08-28T12:11:00.000Z' like_count: 48211 view_count: 2041882 comment_count: 611 share_count: 2044 engagement_tier: high score: 0.7412 meta: mode: search total: 120 '400': $ref: '#/components/responses/InvalidParameter' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/SubscriptionRequired' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/UpstreamUnavailable' 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: MediaItem: type: object description: One item from the cross-platform inspiration media index. properties: id: type: string platform: type: string enum: - x - instagram - youtube - threads - reddit - linkedin title: type: string caption: type: string nullable: true summary: type: string nullable: true description: A short description of what the media shows. content_type: type: string nullable: true source_url: type: string nullable: true description: | The original post on its own platform, and the ONLY link returned here. The media files themselves (thumbnail, video) are not exposed through the API; open `source_url` for the post. author_username: type: string nullable: true author_url: type: string nullable: true posted_at: type: string format: date-time nullable: true like_count: type: integer view_count: type: integer comment_count: type: integer share_count: type: integer engagement_tier: type: string nullable: true score: type: number description: | Relevance against your query, 0 to 1, higher is closer. Present in `search` mode only (never when browsing). 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: 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 SubscriptionRequired: description: | Subscription lapsed. NOTE the legacy body shape: `error` is a plain string here, not the `{ code, message }` object. Read-only keys on write endpoints instead get the object envelope with code `insufficient_scope`. content: application/json: schema: oneOf: - $ref: '#/components/schemas/LegacyErrorEnvelope' - $ref: '#/components/schemas/ErrorEnvelope' example: error: >- subscription_required: The SuperX API requires an active subscription 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 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 UpstreamUnavailable: description: >- The scheduling service is temporarily unreachable. Safe to retry; reuse your Idempotency-Key on POST. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: upstream_unavailable message: >- The scheduling service is temporarily unavailable. Retry with the same Idempotency-Key. 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. ````