openapi: 3.2.0
info:
  title: Xquik Lists API
  version: '1.0'
  description: Xquik is an independent third-party service.
  x-guidance: '## Common tasks


    **Find a tweet** - GET /x/tweets/{id}. Returns text, author, metrics, media, and creation time. Cost: $0.00015 per lookup.


    **Search tweets** - GET /x/tweets/search?q={query}&limit={n}. Supports X operators, structured filters, Tweet IDs, and status URLs. Omit mode for automatic coverage. Cost: $0.00015 per returned tweet.


    **Find a user** - GET /x/users/{id}. Accepts an ID or username. Cost: $0.00015 per lookup.


    **Check if A follows B** - GET /x/followers/check?source={a}&target={b}. Accepts usernames or profile URLs. Cost: $0.00075.


    **Get trends** - GET /trends?woeid={region}&count={n}. WOEID 1 is worldwide. Cost: $0.00045.


    **Download media** - POST /x/media/download with `tweetIds`. Fresh Tweets cost 1 credit each. Cached repeats are free.


    **Read an article** - GET /x/articles/{tweetId}. Cost: $0.00075.


    ## Pagination


    Default platform pages return `hasMore` and `nextCursor`. X pages return `has_next_page` and `next_cursor`. The 2026-04-29 contract returns `has_more` and `next_cursor`. Pass cursors through `cursor`; `after` remains compatible. Dynamic pricing counts returned items, not requests.


    Omit `mode` for automatic reads. Pass cursors unchanged. `mode=standard` remains legacy. Retry 409 responses after `Retry-After`. Restart 410 responses without a cursor.


    ## Authentication


    Eligible reads accept guest wallets. Fixed-price lookups also accept MPP. Other features require an API key or OAuth 2.1 bearer token. API keys also support `Authorization: Bearer xq_...`.


    ## Best-Practice Response Contract


    v1 remains the default. Send `xquik-api-contract: 2026-04-29` for snake_case, Unix timestamps, structured errors, unified pagination, resource objects, and prefixed IDs. Dependency failures use 424 instead of 502.'
  contact:
    name: Xquik
    url: https://xquik.com
    email: support@xquik.com
servers:
- url: https://xquik.com
security:
- apiKey: []
- oauthBearer: []
tags:
- name: Lists
  description: X List followers, members, and tweets
paths:
  /api/v1/x/lists/{id}/followers:
    get:
      operationId: getListFollowers
      summary: List followers of an X List
      tags:
      - Lists
      security:
      - apiKey: []
      - oauthBearer: []
      - {}
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: List ID
      - name: cursor
        in: query
        schema:
          type: string
        description: Pagination cursor for list followers
      - $ref: '#/components/parameters/FollowerPageSize'
      - $ref: '#/components/parameters/UserFilterMinFollowers'
      - $ref: '#/components/parameters/UserFilterMaxFollowers'
      - $ref: '#/components/parameters/UserFilterMinFollowing'
      - $ref: '#/components/parameters/UserFilterMaxFollowing'
      - $ref: '#/components/parameters/UserFilterMinStatuses'
      - $ref: '#/components/parameters/UserFilterMaxStatuses'
      - $ref: '#/components/parameters/UserFilterMinAccountAgeDays'
      - $ref: '#/components/parameters/UserFilterVerifiedOnly'
      - $ref: '#/components/parameters/UserFilterVerifiedType'
      - $ref: '#/components/parameters/UserFilterHasWebsite'
      - $ref: '#/components/parameters/UserFilterHasLocation'
      - $ref: '#/components/parameters/UserFilterBioContains'
      - $ref: '#/components/parameters/UserFilterLocationContains'
      - $ref: '#/components/parameters/UserFilterUsernameContains'
      responses:
        '200':
          description: List of followers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        default:
          $ref: '#/components/responses/UnexpectedError'
      description: List followers of an X List.
  /api/v1/x/lists/{id}/members:
    get:
      operationId: getListMembers
      summary: List members of an X List
      tags:
      - Lists
      security:
      - apiKey: []
      - oauthBearer: []
      - {}
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: List ID for member lookup
      - name: cursor
        in: query
        schema:
          type: string
        description: Pagination cursor for list members
      - name: pageSize
        in: query
        schema:
          type: integer
          minimum: 20
          maximum: 200
          default: 20
        description: Members per page (20-200, default 20)
      - $ref: '#/components/parameters/UserFilterMinFollowers'
      - $ref: '#/components/parameters/UserFilterMaxFollowers'
      - $ref: '#/components/parameters/UserFilterMinFollowing'
      - $ref: '#/components/parameters/UserFilterMaxFollowing'
      - $ref: '#/components/parameters/UserFilterMinStatuses'
      - $ref: '#/components/parameters/UserFilterMaxStatuses'
      - $ref: '#/components/parameters/UserFilterMinAccountAgeDays'
      - $ref: '#/components/parameters/UserFilterVerifiedOnly'
      - $ref: '#/components/parameters/UserFilterVerifiedType'
      - $ref: '#/components/parameters/UserFilterHasWebsite'
      - $ref: '#/components/parameters/UserFilterHasLocation'
      - $ref: '#/components/parameters/UserFilterBioContains'
      - $ref: '#/components/parameters/UserFilterLocationContains'
      - $ref: '#/components/parameters/UserFilterUsernameContains'
      responses:
        '200':
          description: List of members
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        default:
          $ref: '#/components/responses/UnexpectedError'
      description: List members of an X List.
  /api/v1/x/lists/{id}/tweets:
    get:
      operationId: getListTweets
      summary: List tweets from an X List
      tags:
      - Lists
      security:
      - apiKey: []
      - oauthBearer: []
      - {}
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: List ID for tweet lookup
      - name: cursor
        in: query
        schema:
          type: string
        description: Pagination cursor for list tweets
      - $ref: '#/components/parameters/ResultPageSize'
      - name: sinceTime
        in: query
        schema:
          type: string
        description: Unix timestamp - filter after
      - name: untilTime
        in: query
        schema:
          type: string
        description: Unix timestamp - filter before
      - name: includeReplies
        in: query
        schema:
          type: boolean
        description: Include replies (default false)
      responses:
        '200':
          description: List tweets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        default:
          $ref: '#/components/responses/UnexpectedError'
      description: List tweets from an X List.
components:
  schemas:
    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.
    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
    TweetNote:
      description: Complete Note Tweet content and rich-text metadata.
      type: object
      required:
      - text
      properties:
        id:
          type: string
        text:
          type: string
        isExpandable:
          type: boolean
        entities:
          type: object
          additionalProperties: true
          x-stainless-any: true
          x-stainless-terraform-type: string
        richtextTags:
          type: array
          items:
            type: object
            required:
            - fromIndex
            - toIndex
            - types
            properties:
              fromIndex:
                type: integer
              toIndex:
                type: integer
              types:
                type: array
                items:
                  type: string
    XWritePaymentRequired:
      allOf:
      - $ref: '#/components/schemas/XWriteAction'
      - type: object
        required:
        - error
        - message
      description: 'Durable failed write action with the applicable payment guidance.

        '
    UserProfile:
      description: X user profile with bio, follower counts, and verification status.
      type: object
      required:
      - id
      - username
      - name
      properties:
        id:
          type: string
        username:
          type: string
        name:
          type: string
        description:
          type: string
        followers:
          type: integer
        following:
          type: integer
        verified:
          type: boolean
        isBlueVerified:
          type: boolean
          description: Whether X shows a blue verification badge
        isVerified:
          type: boolean
          description: Whether X marks the profile as verified
        profilePicture:
          type: string
        coverPicture:
          type: string
        profileBannerUrl:
          type: string
          description: Original X profile banner field when available
        location:
          type: string
        createdAt:
          type: string
        statusesCount:
          type: integer
        mediaCount:
          type: integer
        protected:
          type: boolean
          description: Whether the profile protects its posts
        url:
          type: string
        favouritesCount:
          type: integer
        hasCustomTimelines:
          type: boolean
        isTranslator:
          type: boolean
        withheldInCountries:
          type: array
          items:
            type: string
        possiblySensitive:
          type: boolean
        pinnedTweetIds:
          type: array
          items:
            type: string
        isAutomated:
          type: boolean
        automatedBy:
          type: string
        unavailable:
          type: boolean
        unavailableReason:
          type: string
        verifiedType:
          type: string
        affiliatesHighlightedLabel:
          $ref: '#/components/schemas/UserAffiliateLabel'
        businessAccountAffiliatesCount:
          type: integer
        creatorSubscriptionsCount:
          type: integer
        hasGraduatedAccess:
          type: boolean
        hasHiddenSubscriptionsOnProfile:
          type: boolean
        highlightsInfo:
          $ref: '#/components/schemas/UserHighlightsInfo'
        identityVerification:
          $ref: '#/components/schemas/UserIdentityVerification'
        isProfileTranslatable:
          type: boolean
        parodyCommentaryFanLabel:
          type: string
        profileDescriptionLanguage:
          type: string
        profileImageShape:
          type: string
        profileInterstitialType:
          type: string
        profileSortEnabled:
          type: boolean
        profileTranslatorType:
          type: string
        superFollowEligible:
          type: boolean
        communityRole:
          type: string
          description: Community role when returned by community member reads
        profile_bio:
          type: object
          additionalProperties: true
          x-stainless-any: true
          x-stainless-terraform-type: string
          description: Structured profile bio with entity annotations
    TweetCard:
      description: Public card metadata attached to a tweet.
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        url:
          type: string
        bindingValues:
          type: object
          additionalProperties: true
          x-stainless-any: true
          x-stainless-terraform-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
          deprecated: true
          const: stripe
        required_headers:
          type: object
          additionalProperties: false
          required:
          - Idempotency-Key
          properties:
            Idempotency-Key:
              type: string
              const: <cryptographically random UUID v4>
        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
    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.
        currency:
          type: string
          const: usd
    SearchTweet:
      description: Tweet returned from search results with inline author info. A zero metric can mean X did not report the count.
      type: object
      required:
      - id
      - text
      - retweetCount
      - replyCount
      - likeCount
      - quoteCount
      - viewCount
      - bookmarkCount
      properties:
        id:
          type: string
        text:
          type: string
        type:
          type: string
        createdAt:
          type: string
        isNoteTweet:
          type: boolean
          description: True for Note Tweets (long-form content, up to 25,000 characters)
        isReply:
          type: boolean
          description: True when this search result is a reply
        isQuoteStatus:
          type: boolean
          description: True when this search result quotes another tweet
        isLimitedReply:
          type: boolean
          description: Whether the tweet has limited reply permissions
        inReplyToId:
          type: string
          description: ID of the tweet this result replies to.
        inReplyToUserId:
          type: string
          description: ID of the user this result replies to.
        inReplyToUsername:
          type: string
          description: Username this result replies to.
        conversationId:
          type: string
          description: Root tweet ID for the search result conversation
        source:
          type: string
          description: Client application used to post the tweet
        displayTextRange:
          type: array
          items:
            type: integer
          description: Rendered text's start and end offsets.
        contentDisclosure:
          $ref: '#/components/schemas/ContentDisclosure'
        article:
          $ref: '#/components/schemas/TweetArticleMetadata'
        card:
          $ref: '#/components/schemas/TweetCard'
        communityNote:
          $ref: '#/components/schemas/TweetCommunityNote'
        edit:
          $ref: '#/components/schemas/TweetEdit'
        isTranslatable:
          type: boolean
        noteTweet:
          $ref: '#/components/schemas/TweetNote'
        place:
          $ref: '#/components/schemas/TweetPlace'
        possiblySensitive:
          type: boolean
        previousCounts:
          $ref: '#/components/schemas/TweetPreviousCounts'
        viewState:
          type: string
        entities:
          type: object
          additionalProperties: true
          description: Parsed search-result entities including URLs, mentions, hashtags, and media markers
        quoted_tweet:
          $ref: '#/components/schemas/EmbeddedTweet'
        retweeted_tweet:
          $ref: '#/components/schemas/EmbeddedTweet'
        media:
          type: array
          items:
            $ref: '#/components/schemas/TweetMedia'
          description: Search-result media attachments, omitted when no media is present
        url:
          type: string
          description: Search result permalink.
        lang:
          type: string
          description: Search result language code.
        likeCount:
          type: integer
        retweetCount:
          type: integer
        replyCount:
          type: integer
        quoteCount:
          type: integer
        viewCount:
          type: integer
        bookmarkCount:
          type: integer
        author:
          $ref: '#/components/schemas/UserProfile'
    UserHighlightsInfo:
      description: Profile highlight availability and count metadata.
      type: object
      properties:
        canHighlightTweets:
          type: boolean
        highlightedTweets:
          type: string
    EmbeddedTweet:
      description: 'Quoted or retweeted tweet context. Every object includes id, text, and engagement metrics. A zero metric can mean X did not report the count. Author, media, and conversation fields appear when available.

        '
      type: object
      required:
      - id
      - text
      - retweetCount
      - replyCount
      - likeCount
      - quoteCount
      - viewCount
      - bookmarkCount
      properties:
        id:
          type: string
        text:
          type: string
        type:
          type: string
        createdAt:
          type: string
        url:
          type: string
        lang:
          type: string
        retweetCount:
          type: integer
        replyCount:
          type: integer
        likeCount:
          type: integer
        quoteCount:
          type: integer
        viewCount:
          type: integer
        bookmarkCount:
          type: integer
        isReply:
          type: boolean
        isLimitedReply:
          type: boolean
        isNoteTweet:
          type: boolean
        isQuoteStatus:
          type: boolean
        inReplyToId:
          type: string
        inReplyToUserId:
          type: string
        inReplyToUsername:
          type: string
        conversationId:
          type: string
        source:
          type: string
        displayTextRange:
          type: array
          items:
            type: integer
        contentDisclosure:
          $ref: '#/components/schemas/ContentDisclosure'
        article:
          $ref: '#/components/schemas/TweetArticleMetadata'
        card:
          $ref: '#/components/schemas/TweetCard'
        communityNote:
          $ref: '#/components/schemas/TweetCommunityNote'
        edit:
          $ref: '#/components/schemas/TweetEdit'
        isTranslatable:
          type: boolean
        noteTweet:
          $ref: '#/components/schemas/TweetNote'
        place:
          $ref: '#/components/schemas/TweetPlace'
        possiblySensitive:
          type: boolean
        previousCounts:
          $ref: '#/components/schemas/TweetPreviousCounts'
        viewState:
          type: string
        entities:
          type: object
          additionalProperties: true
          x-stainless-any: true
          x-stainless-terraform-type: string
        quoted_tweet:
          $ref: '#/components/schemas/EmbeddedTweet'
        retweeted_tweet:
          $ref: '#/components/schemas/EmbeddedTweet'
        media:
          type: array
          items:
            $ref: '#/components/schemas/TweetMedia'
        author:
          $ref: '#/components/schemas/UserProfile'
    TweetArticleMetadata:
      description: Article metadata attached to a tweet.
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        previewText:
          type: string
        coverMediaUrl:
          type: string
    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
          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
            - closed
            - 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
            - monitor_profile_unavailable
            - 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
            - coverage_cursor_gone
            - coverage_cursor_unavailable
            - draft_not_found
            - expired
            - favoriters_unavailable
            - forbidden
            - guest_wallet_unavailable
            - guest_wallets_disabled
            - guest_wallets_unavailable
            - idempotency_conflict
            - idempotency_key_conflict
            - invalid_community_id
            - invalid_complete_replies_request
            - invalid_coverage_cursor
            - invalid_coverage_request
            - invalid_idempotency_key
            - invalid_list_id
            - invalid_output_options
            - invalid_payment_amount
            - invalid_range
            - invalid_reply_options
            - login_rate_limited
            - login_service_unavailable
            - missing_idempotency_key
            - missing_ids
            - missing_url
            - no_cached_style
            - passkey_required
            - rate_limited
            - read_request_timeout
            - replies_incomplete
            - support_media_rate_limit
            - support_request_rate_limit
            - too_many_ids
            - too_many_tweets
            - 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
          - type: object
            title: StructuredError
            required:
            - message
            - type
            - code
            properties:
              message:
                type: string
              type:
                type: string
                enum:
                - api_error
                - authentication_error
                - billing_error
                - dependency_error
                - invalid_request_error
                - permission_error
                - rate_limit_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
                - closed
                - 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
                - monitor_profile_unavailable
                - 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
                - coverage_cursor_gone
                - coverage_cursor_unavailable
                - draft_not_found
                - expired
                - favoriters_unavailable
                - forbidden
                - guest_wallet_unavailable
                - guest_wallets_disabled
                - guest_wallets_unavailable
                - idempotency_conflict
                - idempotency_key_conflict
                - invalid_community_id
                - invalid_complete_replies_request
                - invalid_coverage_cursor
                - invalid_coverage_request
                - invalid_idempotency_key
                - invalid_list_id
                - invalid_output_options
                - invalid_payment_amount
                - invalid_range
                - invalid_reply_options
                - login_rate_limited
                - login_service_unavailable
                - missing_idempotency_key
                - missing_ids
                - missing_url
                - no_cached_style
                - passkey_required
                - rate_limited
                - read_request_timeout
                - replies_incomplete
                - support_media_rate_limit
                - support_request_rate_limit
                - too_many_ids
                - too_many_tweets
                - 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
        message:
          type: string
          description: Human-readable error guidance.
        reason:
          type: string
          description: Machine-readable reason for a login cooldown.
        retryAfter:
          type: integer
          minimum: 1
          description: Seconds until the next permitted request.
        retryAfterMs:
          type: integer
          minimum: 1
          description: Required wait in milliseconds.
    ContentDisclosure:
      description: Content disclosure metadata shown by X when a tweet is labeled as paid partnership content or AI-generated media.
      type: object
      properties:
        advertising:
          type: object
          properties:
            isPaidPromotion:
              type: boolean
              description: True when X labels the tweet as paid promotion content.
        aiGenerated:
          type: object
          properties:
            detectionSource:
              type: string
              description: Source of the AI-generated media disclosure.
            hasAiGeneratedMedia:
              type: boolean
              description: True when X labels the tweet as containing AI-generated media.
    PaginatedTweets:
      description: 'No-mode search, user Tweet, user reply, and direct reply reads use automatic coverage. Shape, filters, aliases, and billing stay compatible. Unprefixed cursors remain legacy. Follow next_cursor while has_next_page is true. An empty filtered page can still have has_next_page true.

        '
      type: object
      required:
      - tweets
      - has_next_page
      - next_cursor
      properties:
        tweets:
          type: array
          items:
            $ref: '#/components/schemas/SearchTweet'
        has_next_page:
          type: boolean
        next_cursor:
          type: string
    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
          deprecated: true
          const: stripe
        required_headers:
          type: object
          additionalProperties: false
          required:
          - Idempotency-Key
          properties:
            Idempotency-Key:
              type: string
              const: <cryptographically random UUID v4>
        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
    MppPaymentRequired:
      description: Anonymous payment requirement for a direct MPP operation. The response includes an MPP challenge and an accountless checkout 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.
        detail:
          type: string
        hint:
          type: string
          description: Instructions for selecting and paying an MPP offer.
        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
    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
    UserAffiliateLabel:
      description: Organization affiliation label shown on an X profile.
      type: object
      properties:
        badgeUrl:
          type: string
        description:
          type: string
        url:
          type: string
        urlType:
          type: string
        userLabelDisplayType:
          type: string
        userLabelType:
          type: string
    AnonymousGuestAuthenticationRequired:
      description: 'Authentication error for a non-MPP anonymous paid read. The response also offers an optional accountless checkout after confirmation.

        '
      type: object
      additionalProperties: false
      required:
      - account_required
      - error
      - message
      - next_step
      - payment_options
      properties:
        account_required:
          type: boolean
          const: false
        error:
          type: string
          const: unauthenticated
        message:
          type: string
        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'
    TweetPlace:
      description: Public place metadata attached to a tweet.
      type: object
      properties:
        boundingBox:
          type: object
          additionalProperties: true
          x-stainless-any: true
          x-stainless-terraform-type: string
        country:
          type: string
        countryCode:
          type: string
        fullName:
          type: string
        id:
          type: string
        name:
          type: string
        placeType:
          type: string
        url:
          type: string
    TweetMedia:
      description: Normalized media attached to a tweet.
      type: object
      required:
      - mediaUrl
      - type
      - url
      properties:
        mediaUrl:
          type: string
          description: Media preview URL
        type:
          type: string
          enum:
          - photo
          - video
          - animated_gif
        url:
          type: string
          description: X media link from the tweet
        allowDownload:
          type: boolean
          description: Whether X permits direct media download.
        altText:
          type: string
          description: Accessibility text supplied for the media.
        aspectRatio:
          type: array
          description: Video aspect ratio as width and height.
          items:
            type: integer
        availabilityStatus:
          type: string
          description: Media availability state reported by X.
        displayUrl:
          type: string
          description: Display-friendly media URL reported by X.
        durationMillis:
          type: integer
          description: Video duration in milliseconds.
        expandedUrl:
          type: string
          description: Expanded X media URL.
        faceRects:
          type: object
          description: Face-aware crop rectangles grouped by media size.
          additionalProperties:
            type: array
            items:
              type: object
              required:
              - x
              - y
              - w
              - h
              properties:
                x:
                  type: integer
                y:
                  type: integer
                w:
                  type: integer
                h:
                  type: integer
        focusRects:
          type: array
          description: Suggested image crops reported by X.
          items:
            type: object
            required:
            - x
            - y
            - w
            - h
            properties:
              x:
                type: integer
              y:
                type: integer
              w:
                type: integer
              h:
                type: integer
        height:
          type: integer
          description: Original media height.
        id:
          type: string
          description: X media entity ID.
        indices:
          type: array
          description: Media entity offsets in the tweet text.
          items:
            type: integer
        mediaKey:
          type: string
          description: Stable X media key.
        monetizable:
          type: boolean
          description: Whether X reports the media as monetizable.
        sizes:
          type: object
          description: Named media renditions and resize modes.
          additionalProperties:
            type: object
            required:
            - w
            - h
            - resize
            properties:
              w:
                type: integer
              h:
                type: integer
              resize:
                type: string
        videoVariants:
          type: array
          description: Available video encodings, ordered as returned
          items:
            type: object
            required:
            - contentType
            - url
            properties:
              bitrate:
                type: integer
              contentType:
                type: string
              url:
                type: string
        width:
          type: integer
          description: Original media width.
    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
    XWriteActionBilling:
      type: object
      additionalProperties: false
      required:
      - status
      - charged
      - plannedCredits
      - chargedCredits
      properties:
        status:
          type: string
          enum:
          - not_charged
          - pending
          - charged
          - charge_failed
          - refunded
        charged:
          type: boolean
        plannedCredits:
          type: string
          pattern: ^\d+$
        chargedCredits:
          type: string
          pattern: ^\d+$
      description: 'plannedCredits is the approved maximum. chargedCredits comes from the settled credit ledger. Pending or failed writes are not charged.

        '
    PaginatedUsers:
      description: 'Paginated user profiles. No-mode follower, following, and verified follower requests merge independent views automatically. Response fields, page size, aliases, filters, and per-returned-profile billing stay unchanged. Existing unprefixed cursors retain legacy behavior. Follow next_cursor while has_next_page is true.

        '
      type: object
      required:
      - users
      - has_next_page
      - next_cursor
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserProfile'
        has_next_page:
          type: boolean
        next_cursor:
          type: string
    TweetPreviousCounts:
      description: Engagement counts retained from a prior tweet edit.
      type: object
      properties:
        bookmarkCount:
          type: integer
        likeCount:
          type: integer
        quoteCount:
          type: integer
        replyCount:
          type: integer
        retweetCount:
          type: integer
    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+$
        error:
          type: string
          enum:
          - insufficient_credits
          - no_credits
          - no_subscription
          - subscription_inactive
        message:
          type: string
        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+$
        top_up_endpoint:
          type: string
          const: /api/v1/guest-wallets/topups
        top_up_url:
          type: string
          const: POST /api/v1/guest-wallets/topups
    AuthenticatedPaymentRequired:
      description: Authenticated credit or subscription error with confirmation-gated hosted 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.
        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
        message:
          type: string
        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
                      deprecated: true
                      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
                      deprecated: true
                      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.
        top_up_endpoint:
          type: string
          const: /api/v1/credits/topup
        top_up_url:
          type: string
          const: POST /api/v1/credits/topup
    UserIdentityVerification:
      description: Identity verification metadata displayed by X.
      type: object
      properties:
        description:
          type: string
        isIdentityVerified:
          type: boolean
        verifiedSinceMsec:
          type: string
    TweetEdit:
      description: Edit history metadata returned by X.
      type: object
      properties:
        editTweetIds:
          type: array
          items:
            type: string
        editableUntilMsecs:
          type: string
    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
        writeActionId:
          type: string
        action:
          type: string
          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
          enum:
          - accepted
          - dispatching
          - pending_confirmation
          - success
          - failed
          - expired
        terminal:
          type: boolean
        retryable:
          type: boolean
          description: True only when a new attempt can reasonably succeed.
        safeToRetry:
          type: boolean
          description: 'True only when no write was dispatched and a new idempotency key may be used.

            '
        statusUrl:
          type: string
        pollAfterMs:
          type:
          - integer
          - 'null'
          minimum: 0
        charged:
          type: boolean
        chargedCredits:
          type: string
          pattern: ^\d+$
        billing:
          $ref: '#/components/schemas/XWriteActionBilling'
        request:
          $ref: '#/components/schemas/XWriteActionRequest'
        account:
          $ref: '#/components/schemas/XWriteActionAccount'
        target:
          $ref: '#/components/schemas/XWriteActionTarget'
        targetId:
          type:
          - string
          - 'null'
        result:
          $ref: '#/components/schemas/XWriteActionResult'
        nextAction:
          $ref: '#/components/schemas/XWriteActionNextAction'
        requestHash:
          type: string
          pattern: ^[0-9a-f]{64}$
        requestId:
          type: string
        idempotent:
          type: boolean
        error:
          type: string
        message:
          type: string
        sendDispatched:
          type: boolean
        sendDispatchedAt:
          type: string
          format: date-time
          description: Dispatch timestamp when the write reached execution.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
          description: 'Deadline for resolving a non-terminal write. This is not the Idempotency-Key retention deadline.

            '
        confirmedAt:
          type: string
          format: date-time
        confirmationCheckedAt:
          type: string
          format: date-time
        confirmationAttempts:
          type: integer
          minimum: 0
        tweetId:
          type: string
          description: Compatibility field for a confirmed tweet result ID.
        messageId:
          type: string
          description: Compatibility field for a confirmed direct message ID.
        mediaId:
          type: string
          description: Compatibility field for a confirmed media upload ID.
        mediaUrl:
          type: string
          format: uri
          description: Public media URL when the upload creates one.
        communityId:
          type: string
          description: Compatibility field for a confirmed community ID.
        communityName:
          type: string
          description: Confirmed community name when available.
        resultId:
          type: string
          description: Compatibility result ID for other write actions.
        media:
          type: object
          additionalProperties: true
          description: Media count, kind, size, and billing details when used.
        details:
          type: object
          additionalProperties: true
          description: Structured recovery context for a failed write.
        success:
          type: boolean
      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.

        '
    XWriteActionAccount:
      type:
      - object
      - 'null'
      description: Connected account selected for the write.
      additionalProperties: false
      required:
      - id
      - username
      properties:
        id:
          type: string
        username:
          type: string
    TweetCommunityNote:
      description: Community Note presentation metadata returned by X.
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        shortTitle:
          type: string
        subtitle:
          type: string
        footer:
          type: string
        destinationUrl:
          type: string
        visualStyle:
          type: string
    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
  parameters:
    UserFilterMaxFollowers:
      name: maxFollowers
      in: query
      schema:
        type: integer
        minimum: 0
      description: Maximum follower count. Missing counts pass this maximum.
    UserFilterUsernameContains:
      name: usernameContains
      in: query
      schema:
        type: string
      description: Match a username substring, ignoring case.
    UserFilterMinStatuses:
      name: minStatuses
      in: query
      schema:
        type: integer
        minimum: 0
      description: Minimum post count. minPosts is also accepted.
    UserFilterHasLocation:
      name: hasLocation
      in: query
      schema:
        type: boolean
      description: Only return profiles with a location.
    UserFilterHasWebsite:
      name: hasWebsite
      in: query
      schema:
        type: boolean
      description: Only return profiles with a website.
    UserFilterVerifiedOnly:
      name: verifiedOnly
      in: query
      schema:
        type: boolean
      description: Only return verified profiles.
    UserFilterMinAccountAgeDays:
      name: minAccountAgeDays
      in: query
      schema:
        type: integer
        minimum: 0
      description: Minimum account age in whole days.
    ResultPageSize:
      name: pageSize
      in: query
      description: 'Maximum page items (1-100, default 20). Source, filters, or credits can reduce results. Continue while has_next_page is true. Deprecated limit and count aliases remain accepted.

        '
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    FollowerPageSize:
      name: pageSize
      in: query
      description: 'Maximum user profiles requested from this page (20-200, default 200). Source, filters, or credits can return fewer profiles. Keep requesting next_cursor while has_next_page is true. Deprecated aliases remain accepted.

        '
      schema:
        type: integer
        minimum: 20
        maximum: 200
        default: 200
    UserFilterMinFollowers:
      name: minFollowers
      in: query
      schema:
        type: integer
        minimum: 0
      description: Minimum follower count. Filtering happens before billing.
    UserFilterLocationContains:
      name: locationContains
      in: query
      schema:
        type: string
      description: Match a location substring, ignoring case.
    UserFilterMinFollowing:
      name: minFollowing
      in: query
      schema:
        type: integer
        minimum: 0
      description: Minimum following count.
    UserFilterBioContains:
      name: bioContains
      in: query
      schema:
        type: string
      description: 'Match any comma-separated or line-separated bio term, ignoring case.

        '
    UserFilterVerifiedType:
      name: verifiedType
      in: query
      schema:
        type: string
      description: Match the verification type exactly, ignoring case.
    UserFilterMaxStatuses:
      name: maxStatuses
      in: query
      schema:
        type: integer
        minimum: 0
      description: Maximum post count. maxPosts is also accepted.
    UserFilterMaxFollowing:
      name: maxFollowing
      in: query
      schema:
        type: integer
        minimum: 0
      description: Maximum following count.
  responses:
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: not_found
            message: Resource not found.
    PaymentRequired:
      description: 'Payment required. MPP reads return a problem document and `WWW-Authenticate`. Authenticated reads return balances and checkout actions. Guest keys receive only the guest top-up action. Other endpoints may use legacy errors. A failed request never creates checkout. Require user confirmation before creating one.

        '
      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: <cryptographically random UUID v4>
                  requires_authentication: false
                  requires_user_confirmation: true
                  requires_user_interaction: true
                  response_fields:
                  - checkout_url
                  - api_key
                  - status_url
                  response_url_field: checkout_url
    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
    AnonymousGuestAuthenticationRequired:
      description: 'Authentication required for a non-MPP paid read. The challenge requests Bearer authentication, not payment. Missing credentials advertise guest checkout without creating it. Invalid credentials return a plain error. Require user confirmation before calling an advertised action.

        '
      headers:
        Cache-Control:
          description: Prevents storage of the guest checkout action.
          schema:
            type: string
            const: no-store
        WWW-Authenticate:
          description: Bearer authentication challenge, not a Payment challenge.
          schema:
            type: string
            const: Bearer realm="xquik"
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/AnonymousGuestAuthenticationRequired'
            - allOf:
              - $ref: '#/components/schemas/Error'
              - not:
                  required:
                  - payment_options
          example:
            account_required: false
            error: unauthenticated
            message: Authentication 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: <cryptographically random UUID v4>
                  requires_authentication: false
                  requires_user_confirmation: true
                  requires_user_interaction: true
                  response_fields:
                  - checkout_url
                  - api_key
                  - status_url
                  response_url_field: checkout_url
    XApiError:
      description: 'Dependency unavailable, unauthorized, or rate limited. Default v1 returns 502. The best-practice response contract returns 424 for transparent dependency failures.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: x_api_unavailable
            message: X data source temporarily unavailable. Try again later.
    UnexpectedError:
      content:
        application/json:
          example:
            error: internal_error
            message: Unexpected error. Try again.
          schema:
            $ref: '#/components/schemas/Error'
      description: Unexpected error.
    InvalidInput:
      description: Invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: invalid_input
            message: Invalid input. Check the request body.
  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