openapi: 3.2.0 info: title: Xquik X Write API version: '1.0' description: "Xquik is an independent third-party service. Not affiliated with X Corp. \"Twitter\" and \"X\" are trademarks of X Corp. Look up tweets, users, and X trends. Search tweets, check follow relationships, download media, and monitor accounts. 33 paid-read endpoints accept prepaid credits without a subscription. 7 fixed-price lookups also accept direct MPP payments. Write and automation endpoints require an API key or OAuth 2.1 bearer token.\n\n## Xquik SDKs\n\nStainless generates each SDK from this OpenAPI schema. Pick a language:\n\n- TypeScript / Node.js: `npm i x-twitter-scraper` -\n [Xquik-dev/x-twitter-scraper-typescript](https://github.com/Xquik-dev/x-twitter-scraper-typescript)\n\n- Python: `pip install x-twitter-scraper` -\n [Xquik-dev/x-twitter-scraper-python](https://github.com/Xquik-dev/x-twitter-scraper-python)\n\n- Go: `go get github.com/Xquik-dev/x-twitter-scraper-go` -\n [Xquik-dev/x-twitter-scraper-go](https://github.com/Xquik-dev/x-twitter-scraper-go)\n\n- Ruby: `gem install x-twitter-scraper` -\n [Xquik-dev/x-twitter-scraper-ruby](https://github.com/Xquik-dev/x-twitter-scraper-ruby)\n\n- Java (source build; Maven Central pending) -\n [Xquik-dev/x-twitter-scraper-java](https://github.com/Xquik-dev/x-twitter-scraper-java)\n\n- Kotlin (source build; Maven Central pending) -\n [Xquik-dev/x-twitter-scraper-kotlin](https://github.com/Xquik-dev/x-twitter-scraper-kotlin)\n\n- C# / .NET: `dotnet add package XTwitterScraper` -\n [Xquik-dev/x-twitter-scraper-csharp](https://github.com/Xquik-dev/x-twitter-scraper-csharp)\n\n- PHP: `composer require xquik/x-twitter-scraper` -\n [Xquik-dev/x-twitter-scraper-php](https://github.com/Xquik-dev/x-twitter-scraper-php)\n\n- CLI: `go install github.com/Xquik-dev/x-twitter-scraper-cli/cmd/x-twitter-scraper@latest` -\n [Xquik-dev/x-twitter-scraper-cli](https://github.com/Xquik-dev/x-twitter-scraper-cli)\n\n- Terraform Provider (Terraform Registry) -\n [Xquik-dev/terraform-provider-x-twitter-scraper](https://github.com/Xquik-dev/terraform-provider-x-twitter-scraper)\n\n\nOpenClaw plugin: [Xquik-dev/tweetclaw](https://github.com/Xquik-dev/tweetclaw) (`openclaw plugins install clawhub:@xquik/tweetclaw`)." x-guidance: '## Common tasks **Find a tweet** - GET /x/tweets/{id} with a numeric tweet ID. Returns full tweet data: text, author, metrics (likes, retweets, replies, views), media URLs, and creation timestamp. Cost: $0.00015 per lookup. **Search tweets** - GET /x/tweets/search?q={query}&limit={n}. Supports X search operators, structured filters like fromUser, mediaType, minFaves, hashtags, and verifiedOnly, plus exact lookup for a pasted Tweet ID or X status URL. Plain from:user date windows are optimized for timeline completeness. Returns up to 200 tweets per page with cursor-based pagination. Cost: $0.00015 per tweet returned. **Find a user** - GET /x/users/{id} where {id} is a numeric user ID or @username. Returns profile data: name, bio, follower/following counts, verification status, join date. Cost: $0.00015 per lookup. **Check if A follows B** - GET /x/followers/check?source={a}&target={b} where source and target are usernames, @usernames, or X or Twitter profile URLs. Cost: $0.00075. **Get trending topics** - GET /trends?woeid={region}&count={n}. WOEID 1 = worldwide, 23424977 = US, 23424975 = UK, 23424969 = Turkey. Cost: $0.00045. **Download media** - POST /x/media/download with {"tweetIds": ["123", "456"]} body. Returns download URLs for images and videos. Cost: 1 credit per fresh tweet processed with media; cached repeat downloads are free. **Read an article** - GET /x/articles/{tweetId} for long-form X Articles. Returns full article HTML, cover image, and metadata. Cost: $0.00075. ## Pagination Default v1 responses keep their existing pagination fields for compatibility. Platform list endpoints return `hasMore` and `nextCursor`; X data endpoints return `has_next_page` and `next_cursor`. Send `xquik-api-contract: 2026-04-29` to receive the unified best-practice fields `has_more` and `next_cursor`. Pass the cursor back as `?cursor={cursor}`; legacy `?after={cursor}` still works. Dynamic-priced endpoints charge per item returned, not per request. ## Authentication Eligible paid read endpoints accept accountless prepaid credit wallets. Fixed-price lookups also accept direct MPP payments. Media downloads, write endpoints, and automation features require authentication. Send an Xquik API key through `x-api-key`, `Xquik-Api-Key`, or `Authorization: Bearer xq_...`. Send an OAuth 2.1 access token through `Authorization: Bearer`. ## Best-Practice Response Contract v1 keeps its original response contract by default so existing integrations do not break. Send `xquik-api-contract: 2026-04-29` to opt in to the best-practice contract: snake_case response fields, Unix timestamps in seconds, structured error objects, `has_more` and `next_cursor` pagination fields, `object` resource identifiers, and prefixed IDs where available. Dependency failures that returned 502 in default v1 return 424 in the opt-in contract. Future major API versions should make this contract the default.' contact: name: Xquik url: https://xquik.com email: support@xquik.com servers: - url: https://xquik.com security: - apiKey: [] - oauthBearer: [] tags: - name: X Write description: X write actions (tweets, likes, follows, DMs) paths: /api/v1/x/tweets: post: operationId: createTweet summary: Create tweet tags: - X Write security: - apiKey: [] - oauthBearer: [] parameters: - $ref: '#/components/parameters/WriteIdempotencyKey' requestBody: required: true description: Account and tweet content. Requires text, media, or both. content: application/json: schema: type: object required: - account properties: account: type: string description: X account (@username or account ID) example: '@elonmusk' text: type: string description: Tweet text (optional when media is provided) example: Just launched our new feature! reply_to_tweet_id: type: string example: '1234567890' community_id: type: string example: '1500000000000000000' is_note_tweet: type: boolean example: false media: type: array items: type: string maxItems: 4 description: Array of public media URLs to attach. Supports up to 4 images or exactly 1 MP4 video up to 100 MB. Each URL must be publicly reachable. Attached media adds 2 credits per started MB across all files. example: - https://example.com/video.mp4 example: account: '@elonmusk' text: Just launched our new feature! responses: '200': $ref: '#/components/responses/WriteActionCompleted' '202': $ref: '#/components/responses/WriteActionAccepted' '400': $ref: '#/components/responses/WriteInvalidInput' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AccountAuthError' '409': $ref: '#/components/responses/WriteIdempotencyConflict' '422': $ref: '#/components/responses/WriteRejected' '429': $ref: '#/components/responses/WriteRateLimited' '500': $ref: '#/components/responses/WriteError' '503': $ref: '#/components/responses/WriteTrackingUnavailable' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Create tweet. /api/v1/x/write-actions/{id}: get: operationId: getWriteActionStatus summary: Get write action status tags: - X Write security: - apiKey: [] - oauthBearer: [] parameters: - name: id in: path required: true schema: type: string description: Write action ID returned by a pending write response. responses: '200': $ref: '#/components/responses/WriteActionCompleted' '202': $ref: '#/components/responses/WriteActionAccepted' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimitExceeded' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Get write action status. /api/v1/x/tweets/{id}: delete: operationId: deleteTweet summary: Delete tweet tags: - X Write security: - apiKey: [] - oauthBearer: [] parameters: - $ref: '#/components/parameters/WriteIdempotencyKey' - name: id in: path required: true schema: type: string description: Tweet ID to delete requestBody: required: true description: Account that owns the tweet. content: application/json: schema: $ref: '#/components/schemas/XAccountBody' example: account: '@elonmusk' responses: '200': $ref: '#/components/responses/WriteActionCompleted' '202': $ref: '#/components/responses/WriteActionAccepted' '400': $ref: '#/components/responses/WriteInvalidInput' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AccountAuthError' '409': $ref: '#/components/responses/WriteIdempotencyConflict' '422': $ref: '#/components/responses/WriteRejected' '429': $ref: '#/components/responses/RateLimitedByX' '500': $ref: '#/components/responses/WriteError' '503': $ref: '#/components/responses/WriteTrackingUnavailable' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Delete tweet. /api/v1/x/tweets/{id}/like: post: operationId: likeTweet summary: Like tweet tags: - X Write security: - apiKey: [] - oauthBearer: [] parameters: - $ref: '#/components/parameters/WriteIdempotencyKey' - name: id in: path required: true schema: type: string description: Tweet ID to like requestBody: required: true description: Account to perform the like. content: application/json: schema: $ref: '#/components/schemas/XAccountBody' example: account: '@elonmusk' responses: '200': $ref: '#/components/responses/WriteActionCompleted' '202': $ref: '#/components/responses/WriteActionAccepted' '400': $ref: '#/components/responses/WriteInvalidInput' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AccountAuthError' '409': $ref: '#/components/responses/WriteIdempotencyConflict' '422': $ref: '#/components/responses/WriteRejected' '429': $ref: '#/components/responses/RateLimitedByX' '500': $ref: '#/components/responses/WriteError' '503': $ref: '#/components/responses/WriteTrackingUnavailable' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Like tweet. delete: operationId: unlikeTweet summary: Unlike tweet tags: - X Write security: - apiKey: [] - oauthBearer: [] parameters: - $ref: '#/components/parameters/WriteIdempotencyKey' - name: id in: path required: true schema: type: string description: Tweet ID to unlike requestBody: required: true description: Account that liked the tweet. content: application/json: schema: $ref: '#/components/schemas/XAccountBody' responses: '200': $ref: '#/components/responses/WriteActionCompleted' '202': $ref: '#/components/responses/WriteActionAccepted' '400': $ref: '#/components/responses/WriteInvalidInput' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AccountAuthError' '409': $ref: '#/components/responses/WriteIdempotencyConflict' '422': $ref: '#/components/responses/WriteRejected' '429': $ref: '#/components/responses/RateLimitedByX' '500': $ref: '#/components/responses/WriteError' '503': $ref: '#/components/responses/WriteTrackingUnavailable' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Unlike tweet. /api/v1/x/tweets/{id}/retweet: post: operationId: retweet summary: Retweet tags: - X Write security: - apiKey: [] - oauthBearer: [] parameters: - $ref: '#/components/parameters/WriteIdempotencyKey' - name: id in: path required: true schema: type: string description: Tweet ID to retweet requestBody: required: true description: Account to perform the retweet. content: application/json: schema: $ref: '#/components/schemas/XAccountBody' responses: '200': $ref: '#/components/responses/WriteActionCompleted' '202': $ref: '#/components/responses/WriteActionAccepted' '400': $ref: '#/components/responses/WriteInvalidInput' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AccountAuthError' '409': $ref: '#/components/responses/WriteIdempotencyConflict' '422': $ref: '#/components/responses/WriteRejected' '429': $ref: '#/components/responses/RateLimitedByX' '500': $ref: '#/components/responses/WriteError' '503': $ref: '#/components/responses/WriteTrackingUnavailable' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Retweet. delete: operationId: unretweet summary: Unretweet tags: - X Write security: - apiKey: [] - oauthBearer: [] parameters: - $ref: '#/components/parameters/WriteIdempotencyKey' - name: id in: path required: true schema: type: string description: Tweet ID to unretweet requestBody: required: true description: Account that retweeted the tweet. content: application/json: schema: $ref: '#/components/schemas/XAccountBody' responses: '200': $ref: '#/components/responses/WriteActionCompleted' '202': $ref: '#/components/responses/WriteActionAccepted' '400': $ref: '#/components/responses/WriteInvalidInput' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AccountAuthError' '409': $ref: '#/components/responses/WriteIdempotencyConflict' '422': $ref: '#/components/responses/WriteRejected' '429': $ref: '#/components/responses/RateLimitedByX' '500': $ref: '#/components/responses/WriteError' '503': $ref: '#/components/responses/WriteTrackingUnavailable' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Unretweet. /api/v1/x/users/{id}/follow: post: operationId: followUser summary: Follow user tags: - X Write security: - apiKey: [] - oauthBearer: [] parameters: - $ref: '#/components/parameters/WriteIdempotencyKey' - name: id in: path required: true schema: type: string description: User ID to follow requestBody: required: true description: Account to perform the follow. content: application/json: schema: $ref: '#/components/schemas/XAccountBody' responses: '200': $ref: '#/components/responses/WriteActionCompleted' '202': $ref: '#/components/responses/WriteActionAccepted' '400': $ref: '#/components/responses/WriteInvalidInput' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AccountAuthError' '409': $ref: '#/components/responses/WriteIdempotencyConflict' '422': $ref: '#/components/responses/WriteRejected' '429': $ref: '#/components/responses/WriteRateLimited' '500': $ref: '#/components/responses/WriteError' '503': $ref: '#/components/responses/WriteTrackingUnavailable' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Follow user. delete: operationId: unfollowUser summary: Unfollow user tags: - X Write security: - apiKey: [] - oauthBearer: [] parameters: - $ref: '#/components/parameters/WriteIdempotencyKey' - name: id in: path required: true schema: type: string description: User ID to unfollow requestBody: required: true description: Account that follows the target user. content: application/json: schema: $ref: '#/components/schemas/XAccountBody' responses: '200': $ref: '#/components/responses/WriteActionCompleted' '202': $ref: '#/components/responses/WriteActionAccepted' '400': $ref: '#/components/responses/WriteInvalidInput' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AccountAuthError' '409': $ref: '#/components/responses/WriteIdempotencyConflict' '422': $ref: '#/components/responses/WriteRejected' '429': $ref: '#/components/responses/WriteRateLimited' '500': $ref: '#/components/responses/WriteError' '503': $ref: '#/components/responses/WriteTrackingUnavailable' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Unfollow user. /api/v1/x/users/{id}/remove-follower: post: operationId: removeFollower summary: Remove follower tags: - X Write security: - apiKey: [] - oauthBearer: [] parameters: - $ref: '#/components/parameters/WriteIdempotencyKey' - name: id in: path required: true schema: type: string description: User ID to remove from your followers requestBody: required: true description: Account whose follower list should be updated. content: application/json: schema: $ref: '#/components/schemas/XAccountBody' responses: '200': $ref: '#/components/responses/WriteActionCompleted' '202': $ref: '#/components/responses/WriteActionAccepted' '400': $ref: '#/components/responses/WriteInvalidInput' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AccountAuthError' '409': $ref: '#/components/responses/WriteIdempotencyConflict' '422': $ref: '#/components/responses/WriteRejected' '429': $ref: '#/components/responses/WriteRateLimited' '500': $ref: '#/components/responses/WriteError' '503': $ref: '#/components/responses/WriteTrackingUnavailable' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Remove follower. /api/v1/x/dm/{userId}: post: operationId: sendDm summary: Send direct message tags: - X Write security: - apiKey: [] - oauthBearer: [] parameters: - $ref: '#/components/parameters/WriteIdempotencyKey' - name: userId in: path required: true schema: type: string description: Recipient user ID requestBody: required: true description: Account, message text, and an optional media attachment. content: application/json: schema: type: object required: - account - text properties: account: type: string description: X account (@username or ID) sending the DM example: '@elonmusk' text: type: string example: Example text media_ids: type: array minItems: 1 maxItems: 1 items: type: string description: Optional array containing exactly 1 uploaded media ID. example: - '1234567890123456789' example: account: '@elonmusk' text: Example text content media_ids: - '1234567890123456789' responses: '200': $ref: '#/components/responses/WriteActionCompleted' '202': $ref: '#/components/responses/WriteActionAccepted' '400': $ref: '#/components/responses/WriteInvalidInput' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AccountAuthError' '409': $ref: '#/components/responses/WriteIdempotencyConflict' '422': $ref: '#/components/responses/WriteRejected' '429': $ref: '#/components/responses/WriteRateLimited' '500': $ref: '#/components/responses/WriteError' '503': $ref: '#/components/responses/WriteTrackingUnavailable' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Send direct message. /api/v1/x/media: post: operationId: uploadMedia summary: Upload media tags: - X Write security: - apiKey: [] - oauthBearer: [] parameters: - $ref: '#/components/parameters/WriteIdempotencyKey' requestBody: required: true description: Upload media with multipart form data, or provide a JSON URL for server-side download. content: multipart/form-data: schema: type: object required: - account - file properties: account: type: string description: X account (@username or ID) uploading media example: '@elonmusk' file: type: string format: binary description: Media file to upload example: binary-content is_long_video: type: boolean description: Set true only for video/mp4 multipart uploads longer than 140 seconds. example: false example: account: '@elonmusk' file: file_value is_long_video: true application/json: schema: type: object required: - account - url properties: account: type: string description: X account (@username or ID) uploading media from URL example: '@elonmusk' url: type: string format: uri description: HTTPS URL to download and upload as media example: https://example.com/image.png example: account: '@elonmusk' url: https://example.com/image.png responses: '200': $ref: '#/components/responses/WriteActionCompleted' '202': $ref: '#/components/responses/WriteActionAccepted' '400': $ref: '#/components/responses/WriteInvalidInput' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AccountAuthError' '404': $ref: '#/components/responses/XAccountNotFound' '409': $ref: '#/components/responses/WriteIdempotencyConflict' '422': $ref: '#/components/responses/WriteRejected' '429': $ref: '#/components/responses/WriteRateLimited' '500': $ref: '#/components/responses/WriteError' '503': $ref: '#/components/responses/WriteTrackingUnavailable' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Upload media. /api/v1/x/profile: patch: operationId: updateProfile summary: Update X profile tags: - X Write security: - apiKey: [] - oauthBearer: [] parameters: - $ref: '#/components/parameters/WriteIdempotencyKey' requestBody: required: true description: Account and profile fields to update (name, bio, location, website). content: application/json: schema: type: object required: - account properties: account: type: string description: X account (@username or ID) to update profile example: '@elonmusk' name: type: string description: Display name example: Example Name description: type: string description: Bio description example: CEO of Tesla, SpaceX, and X location: type: string example: Austin, TX url: type: string description: Website URL example: https://x.com example: account: '@elonmusk' name: Example Name description: description_value location: location_value url: https://xquik.com/example responses: '200': $ref: '#/components/responses/WriteActionCompleted' '202': $ref: '#/components/responses/WriteActionAccepted' '400': $ref: '#/components/responses/WriteInvalidInput' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AccountAuthError' '404': $ref: '#/components/responses/XAccountNotFound' '409': $ref: '#/components/responses/WriteIdempotencyConflict' '422': $ref: '#/components/responses/WriteRejected' '429': $ref: '#/components/responses/WriteRateLimited' '500': $ref: '#/components/responses/WriteError' '503': $ref: '#/components/responses/WriteTrackingUnavailable' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Update X profile. /api/v1/x/profile/avatar: patch: operationId: updateAvatar summary: Update profile avatar tags: - X Write security: - apiKey: [] - oauthBearer: [] parameters: - $ref: '#/components/parameters/WriteIdempotencyKey' requestBody: required: true description: Account and avatar image file or HTTPS image URL (max 700 KB). content: multipart/form-data: schema: type: object required: - account - file properties: account: type: string description: X account (@username or ID) for avatar update example: '@elonmusk' file: type: string format: binary description: Avatar image (max 700 KB) example: binary-content example: account: '@elonmusk' file: file_value application/json: schema: type: object required: - account - url properties: account: type: string description: X account (@username or ID) receiving avatar from URL example: '@elonmusk' url: type: string format: uri description: HTTPS URL to the avatar image to download example: https://example.com/avatar.png example: account: '@elonmusk' url: https://example.com/avatar.png responses: '200': $ref: '#/components/responses/WriteActionCompleted' '202': $ref: '#/components/responses/WriteActionAccepted' '400': $ref: '#/components/responses/WriteInvalidInput' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AccountAuthError' '404': $ref: '#/components/responses/XAccountNotFound' '409': $ref: '#/components/responses/WriteIdempotencyConflict' '422': $ref: '#/components/responses/WriteRejected' '429': $ref: '#/components/responses/WriteRateLimited' '500': $ref: '#/components/responses/WriteError' '503': $ref: '#/components/responses/WriteTrackingUnavailable' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Update profile avatar. /api/v1/x/profile/banner: patch: operationId: updateBanner summary: Update profile banner tags: - X Write security: - apiKey: [] - oauthBearer: [] parameters: - $ref: '#/components/parameters/WriteIdempotencyKey' requestBody: required: true description: Account and banner image file or HTTPS image URL (max 2 MB). content: multipart/form-data: schema: type: object required: - account - file properties: account: type: string description: X account (@username or ID) for banner update example: '@elonmusk' file: type: string format: binary description: Banner image (max 2MB) example: binary-content example: account: '@elonmusk' file: file_value application/json: schema: type: object required: - account - url properties: account: type: string description: X account (@username or ID) receiving banner from URL example: '@elonmusk' url: type: string format: uri description: HTTPS URL to the banner image to download example: https://example.com/banner.png example: account: '@elonmusk' url: https://example.com/banner.png responses: '200': $ref: '#/components/responses/WriteActionCompleted' '202': $ref: '#/components/responses/WriteActionAccepted' '400': $ref: '#/components/responses/WriteInvalidInput' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AccountAuthError' '404': $ref: '#/components/responses/XAccountNotFound' '409': $ref: '#/components/responses/WriteIdempotencyConflict' '422': $ref: '#/components/responses/WriteRejected' '429': $ref: '#/components/responses/WriteRateLimited' '500': $ref: '#/components/responses/WriteError' '503': $ref: '#/components/responses/WriteTrackingUnavailable' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Update profile banner. /api/v1/x/communities: post: operationId: createCommunity summary: Create community tags: - X Write security: - apiKey: [] - oauthBearer: [] parameters: - $ref: '#/components/parameters/WriteIdempotencyKey' requestBody: required: true description: Account, community name, and optional description. content: application/json: schema: type: object required: - account - name properties: account: type: string description: X account (@username or ID) creating the community example: '@elonmusk' name: type: string description: Community name example: Example Name description: type: string description: Community description example: A community for Tesla enthusiasts example: account: '@elonmusk' name: Example Name description: A community for Tesla enthusiasts responses: '200': $ref: '#/components/responses/WriteActionCompleted' '202': $ref: '#/components/responses/WriteActionAccepted' '400': $ref: '#/components/responses/WriteInvalidInput' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AccountAuthError' '404': $ref: '#/components/responses/XAccountNotFound' '409': $ref: '#/components/responses/WriteIdempotencyConflict' '422': $ref: '#/components/responses/WriteRejected' '429': $ref: '#/components/responses/WriteRateLimited' '500': $ref: '#/components/responses/WriteError' '503': $ref: '#/components/responses/WriteTrackingUnavailable' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Create community. /api/v1/x/communities/{id}: delete: operationId: deleteCommunity summary: Delete community tags: - X Write security: - apiKey: [] - oauthBearer: [] parameters: - $ref: '#/components/parameters/WriteIdempotencyKey' - $ref: '#/components/parameters/ResourceId' requestBody: required: true description: Account and community name for deletion confirmation. content: application/json: schema: type: object required: - account - community_name properties: account: type: string description: X account (@username or ID) deleting the community example: '@elonmusk' community_name: type: string description: Community name for confirmation example: Tesla Fans example: account: '@elonmusk' community_name: Tesla Fans responses: '200': $ref: '#/components/responses/WriteActionCompleted' '202': $ref: '#/components/responses/WriteActionAccepted' '400': $ref: '#/components/responses/WriteInvalidInput' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AccountAuthError' '404': $ref: '#/components/responses/XAccountNotFound' '409': $ref: '#/components/responses/WriteIdempotencyConflict' '422': $ref: '#/components/responses/WriteRejected' '429': $ref: '#/components/responses/WriteRateLimited' '500': $ref: '#/components/responses/WriteError' '503': $ref: '#/components/responses/WriteTrackingUnavailable' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Delete community. /api/v1/x/communities/{id}/join: post: operationId: joinCommunity summary: Join community tags: - X Write security: - apiKey: [] - oauthBearer: [] parameters: - $ref: '#/components/parameters/WriteIdempotencyKey' - $ref: '#/components/parameters/ResourceId' requestBody: required: true description: Account to join the community. content: application/json: schema: $ref: '#/components/schemas/XAccountBody' responses: '200': $ref: '#/components/responses/WriteActionCompleted' '202': $ref: '#/components/responses/WriteActionAccepted' '400': $ref: '#/components/responses/WriteInvalidInput' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AccountAuthError' '404': $ref: '#/components/responses/XAccountNotFound' '409': $ref: '#/components/responses/WriteIdempotencyConflict' '422': $ref: '#/components/responses/WriteRejected' '429': $ref: '#/components/responses/WriteRateLimited' '500': $ref: '#/components/responses/WriteError' '503': $ref: '#/components/responses/WriteTrackingUnavailable' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Join community. delete: operationId: leaveCommunity summary: Leave community tags: - X Write security: - apiKey: [] - oauthBearer: [] parameters: - $ref: '#/components/parameters/WriteIdempotencyKey' - $ref: '#/components/parameters/ResourceId' requestBody: required: true description: Account to leave the community. content: application/json: schema: $ref: '#/components/schemas/XAccountBody' responses: '200': $ref: '#/components/responses/WriteActionCompleted' '202': $ref: '#/components/responses/WriteActionAccepted' '400': $ref: '#/components/responses/WriteInvalidInput' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AccountAuthError' '404': $ref: '#/components/responses/XAccountNotFound' '409': $ref: '#/components/responses/WriteIdempotencyConflict' '422': $ref: '#/components/responses/WriteRejected' '429': $ref: '#/components/responses/WriteRateLimited' '500': $ref: '#/components/responses/WriteError' '503': $ref: '#/components/responses/WriteTrackingUnavailable' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Leave community. components: responses: PaymentRequired: description: 'Payment required. Fixed-price direct MPP requests return a Machine Payments Protocol problem document and a WWW-Authenticate challenge. Authenticated X data requests return balances and explicit Stripe checkout-creation actions. Guest paid-read keys receive only the accountless guest top-up action. Direct MPP challenges also advertise the Stripe wallet action. Other authenticated endpoints return a legacy error shape. A failed request never creates checkout. Create checkout only after the user confirms a payment option. ' headers: WWW-Authenticate: description: MPP payment challenge for eligible anonymous pay-per-use requests. Authenticated credit or subscription errors omit this header. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/XWritePaymentRequired' - $ref: '#/components/schemas/AuthenticatedPaymentRequired' - $ref: '#/components/schemas/GuestPaymentRequired' - allOf: - $ref: '#/components/schemas/Error' - not: required: - payment_options example: balance: '0' dashboard: /dashboard/account error: insufficient_credits message: Insufficient credits. Top up or subscribe to continue. next_step: Ask the user to confirm a payment option before creating checkout. payment_options: credits: create_checkout: body: dollars: 10 locale: en creates: checkout_url method: POST path: /api/v1/credits/topup provider: stripe requires_authentication: true requires_user_confirmation: true response_url_field: url subscription: create_checkout: body: tier: starter creates: checkout_url method: POST path: /api/v1/subscribe provider: stripe requires_authentication: true requires_user_confirmation: true response_url_field: url required: '1' top_up_endpoint: /api/v1/credits/topup top_up_url: POST /api/v1/credits/topup application/problem+json: schema: $ref: '#/components/schemas/MppPaymentRequired' example: account_required: false challengeId: Opaque MPP challenge identifier detail: Payment is required. hint: Use a supported wallet with an offer from the WWW-Authenticate header. status: 402 title: Payment Required type: https://paymentauth.org/problems/payment-required next_step: Ask the user to confirm a USD amount before creating checkout. payment_options: guest_wallet: create_checkout: account_required: false amount_bounds: currency: usd maximum_minor: 25000 minimum_minor: 1000 body: amount_minor: 1000 currency: usd creates: checkout_url method: POST path: /api/v1/guest-wallets provider: stripe required_headers: Idempotency-Key: requires_authentication: false requires_user_confirmation: true requires_user_interaction: true response_fields: - checkout_url - api_key - status_url response_url_field: checkout_url XAccountNotFound: description: Connected X account not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: account_not_found message: X account not found. Connect it first at /dashboard/account?tab=x-accounts. WriteTrackingUnavailable: description: 'Durable tracking or the write service is temporarily unavailable. Inspect safeToRetry before creating another action. ' headers: X-Request-Id: required: true description: Correlation ID for this tracking failure. schema: type: string Retry-After: description: Recommended retry delay in seconds. schema: type: integer minimum: 1 content: application/json: schema: oneOf: - $ref: '#/components/schemas/XWriteActionError' - $ref: '#/components/schemas/XWriteAction' example: error: write_tracking_unavailable message: Write tracking unavailable. Try again. charged: false chargedCredits: '0' retryable: true safeToRetry: true success: false nextAction: type: retry RateLimitedByX: description: 'X throttled the write. Possible codes: `x_rate_limited` (short-term throttle) or `x_daily_limit` (daily cap hit). Back off and retry later. Distinct from Xquik tier-based 429. ' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: x_rate_limited message: Rate limited by X. Wait before retrying. headers: Retry-After: description: Seconds until the next permitted request. schema: example: 60 minimum: 1 type: integer WriteActionCompleted: description: Write reached a terminal state. headers: X-Request-Id: required: true description: Correlation ID for support and observability. schema: type: string Location: description: Relative URL for the durable action record. schema: type: string content: application/json: schema: $ref: '#/components/schemas/XWriteAction' example: object: x_write_action id: '12345' writeActionId: '12345' action: like status: success terminal: true retryable: false safeToRetry: false statusUrl: /api/v1/x/write-actions/12345 pollAfterMs: null charged: true chargedCredits: '10' billing: status: charged charged: true plannedCredits: '10' chargedCredits: '10' request: hash: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef payload: tweet_id: '9876543210' account: id: '42' username: example target: type: tweet id: '9876543210' targetId: '9876543210' result: type: state_change id: '9876543210' state: liked nextAction: null sendDispatched: true success: true WriteError: description: 'Write operation failed. Possible error codes include x_write_failed, x_write_ambiguous, x_duplicate_action, and x_daily_limit. Inspect the durable action, safeToRetry, and nextAction fields before retrying. ' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: x_write_failed message: Write action failed unexpectedly. Contact support if this persists. WriteActionAccepted: description: 'Write was accepted or dispatched. Poll Location after Retry-After. Never submit another write while this action remains nonterminal. ' headers: X-Request-Id: required: true description: Correlation ID for this accepted write response. schema: type: string Location: required: true description: Relative URL for polling the durable action record. schema: type: string Retry-After: required: true description: Recommended polling delay in seconds. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/XWriteAction' example: object: x_write_action id: '12346' writeActionId: '12346' action: create_tweet status: dispatching terminal: false retryable: false safeToRetry: false statusUrl: /api/v1/x/write-actions/12346 pollAfterMs: 2000 charged: false chargedCredits: '0' billing: status: pending charged: false plannedCredits: '30' chargedCredits: '0' request: hash: abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789 payload: text: Hello from Xquik account: id: '42' username: example target: null targetId: null result: null nextAction: type: poll url: /api/v1/x/write-actions/12346 afterMs: 2000 sendDispatched: true success: false NotFound: description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: not_found message: Resource not found. WriteInvalidInput: description: The write request is invalid and no action was dispatched. headers: X-Request-Id: required: true description: Correlation ID for this invalid write request. schema: type: string content: application/json: schema: $ref: '#/components/schemas/XWriteActionError' example: error: invalid_input message: Invalid input. Check request fields. charged: false chargedCredits: '0' retryable: false safeToRetry: true success: false nextAction: type: fix_request Unauthenticated: description: Unauthenticated headers: Cache-Control: description: Prevents storage of authentication responses. schema: type: string const: no-store WWW-Authenticate: description: Bearer authentication challenge. schema: type: string const: Bearer realm="xquik" content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthenticated message: Authentication required. Provide a valid API key or bearer token. RateLimitExceeded: description: 'Xquik tier rate limit exceeded. The response includes a `Retry-After` header with the number of seconds to wait before retrying. ' content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - type: object properties: retryAfter: type: integer example: 60 example: error: rate_limit_exceeded message: Too many requests. Try again later. retryAfter: 60 headers: Retry-After: description: Seconds until the next permitted request. schema: example: 60 minimum: 1 type: integer WriteRejected: description: 'X rejected the write or the media URL could not be downloaded. Possible codes: `x_content_too_long`, `x_duplicate_action`, `x_account_suspended`, `x_account_protected`, `x_dm_not_allowed`, `x_target_not_found`, `x_account_feature_required`, `x_rejected`, `media_download_failed` (URL fetch path only - body.url not HTTPS, resolves to private IP, file too large, origin error, or timeout). ' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: x_rejected message: X rejected this request. Wait a few minutes and try again. AccountAuthError: description: 'The connected X account needs reauthentication or is currently restricted (locked, suspended, or recovering). Returns an error code of `account_needs_reauth` or `account_restricted`. ' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: account_needs_reauth message: X account needs re-authentication. Re-add the account. WriteIdempotencyConflict: description: The idempotency key belongs to a different write request. headers: X-Request-Id: required: true description: Correlation ID for this idempotency conflict. schema: type: string content: application/json: schema: $ref: '#/components/schemas/XWriteActionError' example: charged: false chargedCredits: '0' error: idempotency_conflict message: Idempotency-Key was already used with a different request. safeToRetry: true retryable: false success: false nextAction: type: retry requiresNewIdempotencyKey: true WriteRateLimited: description: 'A write was throttled by Xquik''s tier or action limits (`rate_limit_exceeded`) or by X (`x_rate_limited`, `x_daily_limit`). Respect the `Retry-After` header when present, otherwise back off before retrying. ' content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - type: object properties: retryAfter: type: integer example: 60 examples: xquikLimit: summary: Xquik tier or action limit value: error: rate_limit_exceeded message: Too many requests. Try again later. retryAfter: 60 xLimit: summary: X rate limit value: error: x_rate_limited message: Rate limited by X. Wait before retrying. example: error: rate_limit_exceeded message: Too many requests. Try again later. retryAfter: 60 headers: Retry-After: description: Seconds until the next permitted request. schema: example: 60 minimum: 1 type: integer schemas: XWritePaymentRequired: allOf: - $ref: '#/components/schemas/XWriteAction' - type: object required: - error - message description: 'Durable failed write action with the applicable payment guidance. ' XWriteActionAccount: type: - object - 'null' description: Connected account selected for the write. additionalProperties: false required: - id - username properties: id: type: string username: type: string example: id: '42' username: example GuestWalletPurchaseRequest: description: User-confirmed guest wallet checkout request. type: object additionalProperties: false required: - amount_minor - currency properties: amount_minor: type: integer minimum: 1000 maximum: 25000 description: USD cents accepted for this checkout. example: 1000 currency: type: string const: usd Error: description: 'Error response. Default v1 returns a legacy string error code. Send `xquik-api-contract: 2026-04-29` to receive the structured best-practice error object. ' type: object required: - error properties: error: x-stainless-naming: python: type_name: ErrorValue java: type_name: ErrorValue example: invalid_input oneOf: - type: string title: LegacyErrorCode enum: - internal_error - account_already_connected - account_needs_reauth - account_not_found - account_required - account_restricted - api_key_limit_reached - article_not_found - dm_not_permitted - invalid_format - invalid_id - invalid_input - invalid_params - invalid_tool_type - invalid_tweet_id - invalid_tweet_url - invalid_user_id - invalid_user_ids - invalid_username - invalid_json - insufficient_credits - login_cooldown - login_failed - media_download_failed - missing_params - missing_query - monitor_already_exists - no_media - no_credits - no_subscription - not_found - payment_failed - rate_limit_exceeded - service_unavailable - style_not_found - subscription_inactive - tweet_not_found - unauthenticated - unsupported_field - user_not_found - body_too_large - checkout_unavailable - connection_challenge_expired - connection_challenge_inactive - draft_not_found - favoriters_unavailable - forbidden - guest_wallet_unavailable - guest_wallets_disabled - guest_wallets_unavailable - idempotency_conflict - idempotency_key_conflict - invalid_community_id - invalid_idempotency_key - invalid_list_id - invalid_payment_amount - invalid_range - login_rate_limited - missing_idempotency_key - missing_ids - no_cached_style - passkey_required - rate_limited - read_request_timeout - replies_incomplete - support_media_rate_limit - support_request_rate_limit - too_many_ids - unknown_field - unsupported_media_type - webhook_inactive - write_tracking_unavailable - x_write_unconfirmed - x_account_feature_required - x_account_protected - x_account_suspended - x_api_rate_limited - x_api_unavailable - x_api_unauthorized - x_auth_failure - x_content_too_long - x_daily_limit - x_dm_not_allowed - x_duplicate_action - x_login_auth_failed - x_login_challenge - x_login_denied - x_login_failed - x_login_proxy_error - x_login_rate_limited - x_login_service_unavailable - x_login_suspended - x_rate_limited - x_rejected - x_target_not_found - x_transient_error - x_user_lookup_failed - x_write_ambiguous - x_write_failed example: invalid_input - type: object title: StructuredError required: - message - type - code properties: message: type: string example: Invalid input. Check the request body. type: type: string enum: - api_error - authentication_error - billing_error - dependency_error - invalid_request_error - permission_error - rate_limit_error example: invalid_request_error code: type: string title: ErrorCode enum: - internal_error - account_already_connected - account_needs_reauth - account_not_found - account_required - account_restricted - api_key_limit_reached - article_not_found - dm_not_permitted - invalid_format - invalid_id - invalid_input - invalid_params - invalid_tool_type - invalid_tweet_id - invalid_tweet_url - invalid_user_id - invalid_user_ids - invalid_username - invalid_json - insufficient_credits - login_cooldown - login_failed - media_download_failed - missing_params - missing_query - monitor_already_exists - no_media - no_credits - no_subscription - not_found - payment_failed - rate_limit_exceeded - service_unavailable - style_not_found - subscription_inactive - tweet_not_found - unauthenticated - unsupported_field - user_not_found - body_too_large - checkout_unavailable - connection_challenge_expired - connection_challenge_inactive - draft_not_found - favoriters_unavailable - forbidden - guest_wallet_unavailable - guest_wallets_disabled - guest_wallets_unavailable - idempotency_conflict - idempotency_key_conflict - invalid_community_id - invalid_idempotency_key - invalid_list_id - invalid_payment_amount - invalid_range - login_rate_limited - missing_idempotency_key - missing_ids - no_cached_style - passkey_required - rate_limited - read_request_timeout - replies_incomplete - support_media_rate_limit - support_request_rate_limit - too_many_ids - unknown_field - unsupported_media_type - webhook_inactive - write_tracking_unavailable - x_write_unconfirmed - x_account_feature_required - x_account_protected - x_account_suspended - x_api_rate_limited - x_api_unavailable - x_api_unauthorized - x_auth_failure - x_content_too_long - x_daily_limit - x_dm_not_allowed - x_duplicate_action - x_login_auth_failed - x_login_challenge - x_login_denied - x_login_failed - x_login_proxy_error - x_login_rate_limited - x_login_service_unavailable - x_login_suspended - x_rate_limited - x_rejected - x_target_not_found - x_transient_error - x_user_lookup_failed - x_write_ambiguous - x_write_failed example: invalid_input message: type: string description: Human-readable error guidance. example: Invalid input. Check the request body. reason: type: string description: Machine-readable reason for a login cooldown. example: temporary_issue retryAfter: type: integer minimum: 1 description: Seconds until the next permitted request. example: 60 retryAfterMs: type: integer minimum: 1 description: Required wait in milliseconds. example: 60000 GuestPaymentRequired: description: 'Credit error for a paid-read guest key with only its accountless guest top-up action. ' type: object additionalProperties: false required: - balance - error - message - next_step - payment_options - required - top_up_endpoint - top_up_url properties: balance: type: string pattern: ^\d+$ example: '0' error: type: string enum: - insufficient_credits - no_credits - no_subscription - subscription_inactive example: insufficient_credits message: type: string example: Insufficient credits. Top up or subscribe to continue. next_step: type: string const: Ask the user to confirm a USD amount before creating checkout. payment_options: type: object additionalProperties: false required: - credits properties: credits: type: object additionalProperties: false required: - create_checkout properties: create_checkout: $ref: '#/components/schemas/GuestWalletTopupCheckoutAction' required: type: string pattern: ^\d+$ example: '1' top_up_endpoint: type: string const: /api/v1/guest-wallets/topups top_up_url: type: string const: POST /api/v1/guest-wallets/topups XAccountBody: description: Request body identifying an X account by username or ID. type: object required: - account properties: account: type: string description: X account identifier (@username or account ID) example: '@elonmusk' GuestWalletCreateCheckoutAction: description: Explicit direct REST action for a new guest wallet checkout. type: object additionalProperties: false required: - account_required - amount_bounds - body - creates - method - path - provider - required_headers - requires_authentication - requires_user_confirmation - requires_user_interaction - response_fields - response_url_field properties: account_required: type: boolean const: false amount_bounds: $ref: '#/components/schemas/GuestWalletAmountBounds' body: $ref: '#/components/schemas/GuestWalletPurchaseRequest' creates: type: string const: checkout_url method: type: string const: POST path: type: string const: /api/v1/guest-wallets provider: type: string const: stripe required_headers: type: object additionalProperties: false required: - Idempotency-Key properties: Idempotency-Key: type: string const: requires_authentication: type: boolean const: false requires_user_confirmation: type: boolean const: true requires_user_interaction: type: boolean const: true response_fields: type: array minItems: 3 maxItems: 3 prefixItems: - type: string const: checkout_url - type: string const: api_key - type: string const: status_url items: type: string enum: - checkout_url - api_key - status_url response_url_field: type: string const: checkout_url XWriteActionError: type: object description: Canonical pre-dispatch error with safe recovery guidance. additionalProperties: true required: - error - message - retryable - safeToRetry - charged - chargedCredits - success - nextAction properties: error: type: string example: invalid_input message: type: string example: Invalid input. Check request fields. retryable: type: boolean example: false safeToRetry: type: boolean example: true charged: type: boolean const: false chargedCredits: type: string const: '0' success: type: boolean const: false writeActionId: type: string example: '12345' statusUrl: type: string example: /api/v1/x/write-actions/12345 nextAction: $ref: '#/components/schemas/XWriteActionNextAction' allowedFields: type: array example: - account - text items: type: string fieldErrors: type: array example: - code: required message: Account is required. path: account items: type: object required: - code - message - path properties: code: type: string message: type: string path: type: string GuestWalletTopupCheckoutAction: description: Explicit direct REST action for a guest wallet top-up. type: object additionalProperties: false required: - account_required - amount_bounds - body - creates - method - path - provider - required_headers - requires_authentication - requires_user_confirmation - requires_user_interaction - response_fields - response_url_field properties: account_required: type: boolean const: false amount_bounds: $ref: '#/components/schemas/GuestWalletAmountBounds' body: $ref: '#/components/schemas/GuestWalletPurchaseRequest' creates: type: string const: checkout_url method: type: string const: POST path: type: string const: /api/v1/guest-wallets/topups provider: type: string const: stripe required_headers: type: object additionalProperties: false required: - Idempotency-Key properties: Idempotency-Key: type: string const: requires_authentication: type: boolean const: true requires_user_confirmation: type: boolean const: true requires_user_interaction: type: boolean const: true response_fields: type: array minItems: 2 maxItems: 2 prefixItems: - type: string const: checkout_url - type: string const: status_url items: type: string enum: - checkout_url - status_url response_url_field: type: string const: checkout_url XWriteActionNextAction: type: - object - 'null' description: Exact follow-up an API client or agent should perform. additionalProperties: false required: - type properties: type: type: string enum: - poll - retry - verify_result - fix_request url: type: string afterMs: type: integer minimum: 0 requiresNewIdempotencyKey: type: boolean example: type: poll url: /api/v1/x/write-actions/12345 afterMs: 2000 XWriteActionRequest: type: object description: Stable fingerprint and sanitized payload for replay checks. additionalProperties: false required: - hash - payload properties: hash: type: - string - 'null' pattern: ^[0-9a-f]{64}$ description: Stable hash of account, action, target, and payload. payload: type: - object - 'null' additionalProperties: true description: Exact sanitized payload dispatched for this action. example: hash: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef payload: tweet_id: '9876543210' XWriteAction: type: object required: - object - id - writeActionId - action - status - terminal - retryable - safeToRetry - statusUrl - pollAfterMs - charged - chargedCredits - billing - request - account - target - targetId - result - nextAction - sendDispatched - success properties: object: type: string const: x_write_action id: type: string example: '12345' writeActionId: type: string example: '12345' action: type: string example: like enum: - create_tweet - delete_tweet - like - unlike - retweet - unretweet - follow - unfollow - remove_follower - send_dm - upload_media - update_profile - update_avatar - update_banner - create_community - delete_community - join_community - leave_community status: type: string example: success enum: - accepted - dispatching - pending_confirmation - success - failed - expired terminal: type: boolean example: true retryable: type: boolean description: True only when a new attempt can reasonably succeed. example: false safeToRetry: type: boolean description: 'True only when no write was dispatched and a new idempotency key may be used. ' example: false statusUrl: type: string example: /api/v1/x/write-actions/12345 pollAfterMs: type: - integer - 'null' minimum: 0 example: null charged: type: boolean example: true chargedCredits: type: string pattern: ^\d+$ example: '10' billing: $ref: '#/components/schemas/XWriteActionBilling' request: $ref: '#/components/schemas/XWriteActionRequest' account: $ref: '#/components/schemas/XWriteActionAccount' target: $ref: '#/components/schemas/XWriteActionTarget' targetId: type: - string - 'null' example: '9876543210' result: $ref: '#/components/schemas/XWriteActionResult' nextAction: $ref: '#/components/schemas/XWriteActionNextAction' requestHash: type: string pattern: ^[0-9a-f]{64}$ example: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef requestId: type: string example: 01JZ8R7QSC9QKT0V7JX4M2A6B8 idempotent: type: boolean example: false error: type: string example: x_write_ambiguous message: type: string example: Invalid input. Check request fields. sendDispatched: type: boolean example: true sendDispatchedAt: type: string format: date-time description: Dispatch timestamp when the write reached execution. example: '2026-07-21T05:00:00Z' createdAt: type: string format: date-time example: '2026-07-21T05:00:00Z' updatedAt: type: string format: date-time example: '2026-07-21T05:00:02Z' completedAt: type: string format: date-time example: '2026-07-21T05:00:02Z' expiresAt: type: string format: date-time description: 'Deadline for resolving a non-terminal write. This is not the Idempotency-Key retention deadline. ' example: '2026-07-22T05:00:00Z' confirmedAt: type: string format: date-time example: '2026-07-21T05:00:02Z' confirmationCheckedAt: type: string format: date-time example: '2026-07-21T05:00:02Z' confirmationAttempts: type: integer minimum: 0 example: 1 tweetId: type: string description: Compatibility field for a confirmed tweet result ID. example: '9876543210' messageId: type: string description: Compatibility field for a confirmed direct message ID. example: '1234567890' mediaId: type: string description: Compatibility field for a confirmed media upload ID. example: '2345678901' mediaUrl: type: string format: uri description: Public media URL when the upload creates one. example: https://media.xquik.com/example.jpg communityId: type: string description: Compatibility field for a confirmed community ID. example: '3456789012' communityName: type: string description: Confirmed community name when available. example: Builders resultId: type: string description: Compatibility result ID for other write actions. example: '9876543210' media: type: object additionalProperties: true description: Media count, kind, size, and billing details when used. example: count: 1 kind: image details: type: object additionalProperties: true description: Structured recovery context for a failed write. example: suggestion: Poll the action status URL. success: type: boolean example: true description: 'Durable write lifecycle record. Poll statusUrl until terminal is true. Reusing the original Idempotency-Key returns this same record. Submit a new write only when safeToRetry is true, using a new key. ' XWriteActionBilling: type: object additionalProperties: false required: - status - charged - plannedCredits - chargedCredits properties: status: type: string enum: - not_charged - pending - charged - charge_failed - refunded example: charged charged: type: boolean example: true plannedCredits: type: string pattern: ^\d+$ example: '10' chargedCredits: type: string pattern: ^\d+$ example: '10' description: 'plannedCredits is the approved maximum. chargedCredits comes from the settled credit ledger. Pending or failed writes are not charged. ' example: status: charged charged: true plannedCredits: '10' chargedCredits: '10' AuthenticatedPaymentRequired: description: Authenticated credit or subscription error with confirmation-gated Stripe checkout actions. type: object additionalProperties: false required: - balance - dashboard - error - message - next_step - payment_options - required - top_up_endpoint - top_up_url properties: balance: type: string pattern: ^\d+$ description: Available credits as a decimal string. example: '0' dashboard: type: string const: /dashboard/account description: Account page for manual billing management. error: type: string enum: - insufficient_credits - no_credits - no_subscription - subscription_inactive example: insufficient_credits message: type: string example: Insufficient credits. Top up or subscribe to continue. next_step: type: string const: Ask the user to confirm a payment option before creating checkout. payment_options: type: object additionalProperties: false required: - credits - subscription properties: credits: type: object additionalProperties: false required: - create_checkout properties: create_checkout: type: object additionalProperties: false required: - body - creates - method - path - provider - requires_authentication - requires_user_confirmation - response_url_field properties: body: type: object additionalProperties: false required: - dollars - locale properties: dollars: type: integer const: 10 locale: type: string const: en creates: type: string const: checkout_url method: type: string const: POST path: type: string const: /api/v1/credits/topup provider: type: string const: stripe requires_authentication: type: boolean const: true requires_user_confirmation: type: boolean const: true response_url_field: type: string const: url subscription: type: object additionalProperties: false required: - create_checkout properties: create_checkout: type: object additionalProperties: false required: - body - creates - method - path - provider - requires_authentication - requires_user_confirmation - response_url_field properties: body: type: object additionalProperties: false required: - tier properties: tier: type: string const: starter creates: type: string const: checkout_url method: type: string const: POST path: type: string const: /api/v1/subscribe provider: type: string const: stripe requires_authentication: type: boolean const: true requires_user_confirmation: type: boolean const: true response_url_field: type: string const: url required: type: string pattern: ^\d+$ description: Credits required for the blocked request. example: '1' top_up_endpoint: type: string const: /api/v1/credits/topup top_up_url: type: string const: POST /api/v1/credits/topup XWriteActionTarget: type: - object - 'null' description: Existing X resource targeted by the write, when applicable. additionalProperties: false required: - type - id properties: type: type: string enum: - tweet - user - community id: type: string example: type: tweet id: '9876543210' MppPaymentRequired: description: Anonymous payment requirement for a direct MPP operation. The response includes an MPP challenge and an accountless Stripe action. type: object required: - account_required - detail - next_step - payment_options - status - title - type properties: account_required: type: boolean const: false challengeId: type: string description: Opaque identifier for the MPP payment challenge. example: mpp_challenge_example detail: type: string example: Payment is required. hint: type: string description: Instructions for selecting and paying an MPP offer. example: Use a supported wallet with an offer from the WWW-Authenticate header. next_step: type: string const: Ask the user to confirm a USD amount before creating checkout. payment_options: type: object additionalProperties: false required: - guest_wallet properties: guest_wallet: type: object additionalProperties: false required: - create_checkout properties: create_checkout: $ref: '#/components/schemas/GuestWalletCreateCheckoutAction' status: type: integer const: 402 title: type: string const: Payment Required type: type: string format: uri const: https://paymentauth.org/problems/payment-required GuestWalletAmountBounds: description: Accepted guest wallet purchase range in USD cents. type: object additionalProperties: false required: - currency - maximum_minor - minimum_minor properties: currency: type: string const: usd maximum_minor: type: integer const: 25000 minimum_minor: type: integer const: 1000 XWriteActionResult: type: - object - 'null' description: Confirmed result produced by the write, when available. additionalProperties: false properties: type: type: string enum: - tweet - direct_message - media - community - state_change id: type: string state: type: string example: type: state_change id: '9876543210' state: liked parameters: WriteIdempotencyKey: name: Idempotency-Key in: header required: true description: 'Generate one unique value for each intended write. Reuse it only when retrying the exact same account, action, target, and payload. A reused key returns the original action. Reusing it with different input returns 409. Replay protection remains active for at least 90 days. ' schema: type: string minLength: 1 maxLength: 255 pattern: ^[!-~]{1,255}$ ResourceId: name: id in: path required: true schema: type: string description: Resource ID returned by the matching create or list endpoint. securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: 'Xquik API key passed through the x-api-key header. Xquik-Api-Key is a vendor-prefixed alias. API keys beginning with xq_ can also use Authorization: Bearer.' oauthBearer: type: http scheme: bearer description: 'OAuth 2.1 access token passed through Authorization: Bearer. Values beginning with xq_ remain Xquik API-key credentials, not OAuth tokens.' cookieSession: type: apiKey in: cookie name: __Host-xquik_session description: Secure Xquik browser session cookie. x-service-info: categories: - data docs: homepage: https://xquik.com apiReference: https://docs.xquik.com llms: https://docs.xquik.com/llms.txt x-discovery: ownershipProofs: - dns:xquik.com