openapi.yaml

openapi: 3.1.0
info:
  title: Xquik API
  version: '1.0'
  description: >-
    Not affiliated with X Corp. Look up any tweet, user, or trend on X. Search
    tweets, check follower relationships, download media, and monitor accounts
    in real time. 33 paid-read endpoints work without a subscription through
    prepaid credits. 7 fixed-price lookups also accept direct per-call MPP
    payments. Write endpoints (post, like, retweet, follow, DM) and automation
    endpoints (bulk extractions, giveaway draws, monitors, webhooks) require an
    API key or OAuth 2.1 bearer token.


    ## Xquik SDKs


    All SDKs are auto-generated from this OpenAPI spec via Stainless and stay in
    sync release-by-release. Pick your language:


    - TypeScript / Node.js: `npm i x-twitter-scraper` -
      [Xquik-dev/x-twitter-scraper-typescript](https://github.com/Xquik-dev/x-twitter-scraper-typescript)

    - Python: `pip install x-twitter-scraper` -
      [Xquik-dev/x-twitter-scraper-python](https://github.com/Xquik-dev/x-twitter-scraper-python)

    - Go: `go get github.com/Xquik-dev/x-twitter-scraper-go` -
      [Xquik-dev/x-twitter-scraper-go](https://github.com/Xquik-dev/x-twitter-scraper-go)

    - Ruby: `gem install x-twitter-scraper` -
      [Xquik-dev/x-twitter-scraper-ruby](https://github.com/Xquik-dev/x-twitter-scraper-ruby)

    - Java (source build; Maven Central pending) -
      [Xquik-dev/x-twitter-scraper-java](https://github.com/Xquik-dev/x-twitter-scraper-java)

    - Kotlin (source build; Maven Central pending) -
      [Xquik-dev/x-twitter-scraper-kotlin](https://github.com/Xquik-dev/x-twitter-scraper-kotlin)

    - C# / .NET: `dotnet add package XTwitterScraper` -
      [Xquik-dev/x-twitter-scraper-csharp](https://github.com/Xquik-dev/x-twitter-scraper-csharp)

    - PHP: `composer require xquik/x-twitter-scraper` -
      [Xquik-dev/x-twitter-scraper-php](https://github.com/Xquik-dev/x-twitter-scraper-php)

    - CLI: `npm i -g x-twitter-scraper-cli` -
      [Xquik-dev/x-twitter-scraper-cli](https://github.com/Xquik-dev/x-twitter-scraper-cli)

    - Terraform Provider (Terraform Registry) -
      [Xquik-dev/terraform-provider-x-twitter-scraper](https://github.com/Xquik-dev/terraform-provider-x-twitter-scraper)


    OpenClaw plugin:
    [Xquik-dev/tweetclaw](https://github.com/Xquik-dev/tweetclaw) (`claw install
    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 Stripe 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/api/v1

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'

security:
  - apiKey: []
  - oauthBearer: []

tags:
  - name: API Keys
    description: API key management (session auth only)
  - name: Account
    description: Account info and settings
  - name: Articles
    description: Long-form X Article extraction
  - name: Communities
    description: X Community info, members, and tweets
  - name: Composition
    description: AI tweet composition, drafts, writing styles, and radar
  - name: Draws
    description: Giveaway draws from tweet replies
  - name: Events
    description: Activity events from monitored accounts
  - name: Extractions
    description: Bulk data extraction (23 tool types)
  - name: Guest Wallets
    description: Accountless prepaid access for paid read endpoints
  - name: Lists
    description: X List followers, members, and tweets
  - name: Media
    description: Media upload and download
  - name: Monitors
    description: Real-time X account monitoring
  - name: Subscribe
    description: Subscription, billing, and credits
  - name: Support
    description: Support ticket management
  - name: Trends
    description: Trending topics and hashtags by region
  - name: Tweets
    description: Look up, search, and analyze individual tweets
  - name: Users
    description: Look up, search, and explore user profiles and relationships
  - name: Webhooks
    description: Webhook endpoint management and delivery
  - name: X Accounts
    description: Connected X account management
  - name: X Write
    description: X write actions (tweets, likes, follows, DMs)
paths:
  # ── Account ──────────────────────────────────────────────
  /account:
    get:
      operationId: getAccount
      summary: Get account info
      tags: [Account]
      security:
        - apiKey: []
        - oauthBearer: []
      responses:
        '200':
          description: Account info
          content:
            application/json:
              schema:
                type: object
                required: [plan, monitorsUsed, monitorsAllowed, monitorBilling]
                properties:
                  plan:
                    type: string
                    enum: [active, inactive]
                    example: active
                  monitorsUsed:
                    type: integer
                    example: 3
                  monitorsAllowed:
                    type: integer
                    deprecated: true
                    x-stainless-deprecation-message:
                      Monitor slots are unlimited. Use
                      monitorBilling.unlimitedSlots instead.
                    description:
                      Deprecated. Monitor slots are unlimited, so this is always
                      Number.MAX_SAFE_INTEGER.
                    example: 9007199254740991
                  monitorBilling:
                    type: object
                    required:
                      [
                        activeDailyEstimate,
                        activeHourlyBurn,
                        creditsPerActiveMonitorDay,
                        creditsPerActiveMonitorHour,
                        eventsIncluded,
                        instantCheckIntervalSeconds,
                        unlimitedSlots,
                      ]
                    properties:
                      activeDailyEstimate:
                        type: string
                        description:
                          Estimated daily credits for currently active monitors.
                        example: '1500'
                      activeHourlyBurn:
                        type: string
                        description:
                          Credits charged each hour for currently active
                          monitors.
                        example: '63'
                      creditsPerActiveMonitorDay:
                        type: string
                        description:
                          Estimated daily credits for 1 active instant monitor.
                        example: '500'
                      creditsPerActiveMonitorHour:
                        type: string
                        description:
                          Hourly credits charged for 1 active instant monitor.
                        example: '21'
                      eventsIncluded:
                        type: boolean
                        description:
                          Webhook and event deliveries are included in monitor
                          billing.
                        example: true
                      instantCheckIntervalSeconds:
                        type: integer
                        description: Active monitors check every 1 second.
                        example: 1
                      unlimitedSlots:
                        type: boolean
                        description: Monitor slot count is unlimited.
                        example: true
                  creditInfo:
                    type: object
                    required:
                      [
                        balance,
                        lifetimePurchased,
                        lifetimeUsed,
                        autoTopupEnabled,
                        autoTopupAmountDollars,
                        autoTopupThreshold,
                      ]
                    properties:
                      balance:
                        type: string
                        description:
                          Bigint string to preserve precision above
                          Number.MAX_SAFE_INTEGER.
                        example: '50000'
                      lifetimePurchased:
                        type: string
                        description: Total purchased credits as a bigint string.
                        example: '140000'
                      lifetimeUsed:
                        type: string
                        description: Total consumed credits as a bigint string.
                        example: '90000'
                      autoTopupEnabled:
                        type: boolean
                        example: false
                      autoTopupAmountDollars:
                        type: number
                        description:
                          Dollar amount charged when automatic top-up runs.
                        example: 10
                      autoTopupThreshold:
                        type: string
                        description:
                          Bigint string threshold that triggers automatic top-up
                          when enabled.
                        example: '50000'
                    example:
                      balance: '50000'
                      lifetimePurchased: '140000'
                      lifetimeUsed: '90000'
                      autoTopupEnabled: false
                      autoTopupAmountDollars: 10
                      autoTopupThreshold: '50000'
                  xUsername:
                    type: string
                    description:
                      Linked X username, omitted when no X account is connected.
                    example: elonmusk
              example:
                plan: active
                monitorsUsed: 3
                monitorsAllowed: 9007199254740991
                monitorBilling:
                  activeDailyEstimate: '1500'
                  activeHourlyBurn: '63'
                  creditsPerActiveMonitorDay: '500'
                  creditsPerActiveMonitorHour: '21'
                  eventsIncluded: true
                  instantCheckIntervalSeconds: 1
                  unlimitedSlots: true
                creditInfo:
                  balance: '50000'
                  lifetimePurchased: '140000'
                  lifetimeUsed: '90000'
                  autoTopupEnabled: false
                  autoTopupAmountDollars: 10
                  autoTopupThreshold: '50000'
                xUsername: elonmusk
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    patch:
      operationId: updateAccount
      summary: Update account locale
      tags: [Account]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: Locale preference for the account.
        content:
          application/json:
            schema:
              type: object
              required: [locale]
              properties:
                locale:
                  type: string
                  enum: [en, tr, es]
                  example: en
            example:
              locale: en
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'

        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /account/x-identity:
    put:
      operationId: setXIdentity
      summary: Set linked X username
      tags: [Account]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: X username to link to this account.
        content:
          application/json:
            schema:
              type: object
              required: [username]
              properties:
                username:
                  type: string
                  description: X username without @
                  example: elonmusk
            example:
              username: elonmusk
      responses:
        '200':
          description: X identity linked
          content:
            application/json:
              schema:
                type: object
                required: [success, xUsername]
                properties:
                  success:
                    type: boolean
                    const: true
                  xUsername:
                    type: string
                    example: elonmusk
              example:
                success: true
                xUsername: elonmusk
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  # ── API Keys ─────────────────────────────────────────────
  /api-keys:
    get:
      operationId: listApiKeys
      summary: List API keys
      tags: [API Keys]
      security:
        - cookieSession: []
      responses:
        '200':
          description: API key list
          content:
            application/json:
              schema:
                type: object
                required: [keys]
                properties:
                  keys:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiKey'
                    example: []
              example:
                keys: []
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    post:
      operationId: createApiKey
      summary: Create API key
      tags: [API Keys]
      security:
        - cookieSession: []
      requestBody:
        required: true
        description: Optional display name for the new API key.
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: My API Key
            example:
              name: My API Key
      responses:
        '201':
          description: API key created
          content:
            application/json:
              schema:
                type: object
                required: [id, fullKey, name, prefix, createdAt]
                properties:
                  id:
                    type: string
                    example: '42'
                  fullKey:
                    type: string
                    example: xq_live_abc123def456
                  name:
                    type: string
                    example: My API Key
                  prefix:
                    type: string
                    example: xq_live_abc1
                  createdAt:
                    type: string
                    format: date-time
                    example: '2025-01-15T12:00:00Z'
              example:
                id: '42'
                fullKey: xq_live_abc123def456
                name: My API Key
                prefix: xq_live_abc1
                createdAt: '2025-01-15T12:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          description: API key limit reached
          content:
            application/json:
              schema:
                type: object
                required: [error, limit, message]
                properties:
                  error:
                    type: string
                    const: api_key_limit_reached
                    example: api_key_limit_reached
                  limit:
                    type: integer
                    example: 100
                  message:
                    type: string
                    example:
                      API key limit reached. Delete an existing key first.
              example:
                error: api_key_limit_reached
                limit: 100
                message: API key limit reached. Delete an existing key first.
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /api-keys/{id}:
    delete:
      operationId: revokeApiKey
      summary: Revoke API key
      tags: [API Keys]
      security:
        - cookieSession: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  # ── Subscribe ────────────────────────────────────────────
  /subscribe:
    post:
      operationId: subscribe
      summary: Create subscription checkout
      description: >
        Create a subscription checkout or billing-management URL only after the
        user confirms. The request never completes payment by itself.
      tags: [Subscribe]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: false
        description: Optional subscription tier to pre-select at checkout.
        content:
          application/json:
            schema:
              type: object
              properties:
                tier:
                  type: string
                  enum: [starter, pro, business]
                  description: Subscription tier to pre-select.
                  example: pro
            example:
              tier: pro
      responses:
        '200':
          description: Billing URL
          content:
            application/json:
              schema:
                type: object
                required: [url, status, message]
                properties:
                  url:
                    type: string
                    format: uri
                    example: 'https://xquik.com/billing/session'
                  status:
                    type: string
                    enum: [checkout_created, already_subscribed, payment_issue]
                    example: checkout_created
                  message:
                    type: string
                    example: Billing session created
              example:
                url: 'https://xquik.com/billing/session'
                status: checkout_created
                message: Billing session created
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  # ── Composition ──────────────────────────────────────────
  /compose:
    post:
      operationId: compose
      summary: Compose, refine, or score a tweet
      tags: [Composition]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: Workflow step, topic, goal, and optional style parameters.
        content:
          application/json:
            schema:
              type: object
              required: [step]
              properties:
                step:
                  type: string
                  enum: [compose, refine, score]
                  description: Workflow step
                  example: compose
                topic:
                  type: string
                  description: Tweet topic (compose, refine)
                  example: AI trends in 2025
                goal:
                  type: string
                  enum: [engagement, followers, authority, conversation]
                  description: Optimization goal
                  example: engagement
                draft:
                  type: string
                  description: Tweet draft text to evaluate (score)
                  example: "AI is changing everything. Here's why."
                tone:
                  type: string
                  description: Desired tone (refine)
                  example: professional
                styleUsername:
                  type: string
                  description:
                    Cached style username for voice matching (compose)
                  example: elonmusk
                additionalContext:
                  type: string
                  description: Extra context or URLs (refine)
                  example: 'https://x.com/elonmusk/status/1234567890'
                callToAction:
                  type: string
                  description: Desired call to action (refine)
                  example: Follow for more
                mediaType:
                  type: string
                  enum: [photo, video, none]
                  description: Media type (refine)
                  example: none
                hasLink:
                  type: boolean
                  description: Whether a link is attached (score)
                  example: false
                hasMedia:
                  type: boolean
                  description: Whether media is attached (score)
                  example: false
            example:
              step: compose
              topic: AI trends in 2025
              goal: engagement
      responses:
        '200':
          description: Composition result
          content:
            application/json:
              schema:
                type: object
                properties:
                  text:
                    type: string
                    description: Generated or refined tweet text
                    example:
                      'AI is reshaping every industry. Here are 5 trends to
                      watch in 2025.'
                  score:
                    type: number
                    description: Engagement score (0-100)
                    example: 78
                  feedback:
                    type: string
                    description: AI feedback on the draft
                    example: 'Strong hook. Consider adding a call to action.'
                  suggestions:
                    type: array
                    items:
                      type: string
                    description: Improvement suggestions
                    example: ['Add a thread hook', 'Include a relevant hashtag']
                additionalProperties: true
              example:
                text:
                  'AI is reshaping every industry. Here are 5 trends to watch in
                  2025.'
                score: 78
                feedback: 'Strong hook. Consider adding a call to action.'
                suggestions: ['Add a thread hook', 'Include a relevant hashtag']
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /drafts:
    get:
      operationId: listDrafts
      summary: List saved drafts
      tags: [Composition]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/Limit'
        - name: afterCursor
          in: query
          schema:
            type: string
          description: Cursor for pagination
      responses:
        '200':
          description: Draft list
          content:
            application/json:
              schema:
                type: object
                required: [drafts, hasMore]
                properties:
                  drafts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Draft'
                    example: []
                  hasMore:
                    type: boolean
                    example: false
                  nextCursor:
                    type: string
                    example: 'abc123'
              example:
                drafts: []
                hasMore: false
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    post:
      operationId: createDraft
      summary: Save a tweet draft
      tags: [Composition]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: Draft text with optional topic and optimization goal.
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text:
                  type: string
                  example: 'AI is the future of productivity'
                topic:
                  type: string
                  example: 'AI trends'
                goal:
                  type: string
                  enum: [engagement, followers, authority, conversation]
                  example: engagement
            example:
              text: 'AI is the future of productivity'
              topic: 'AI trends'
              goal: engagement
      responses:
        '201':
          description: Draft created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DraftDetail'
              example:
                id: '42'
                text: 'AI is the future of productivity'
                topic: 'AI trends'
                goal: engagement
                createdAt: '2025-01-15T12:00:00Z'
                updatedAt: '2025-01-16T09:30:00Z'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /drafts/{id}:
    get:
      operationId: getDraft
      summary: Get draft by ID
      tags: [Composition]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Draft details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DraftDetail'
              example:
                id: '42'
                text: 'AI is the future of productivity'
                topic: 'AI trends'
                goal: engagement
                createdAt: '2025-01-15T12:00:00Z'
                updatedAt: '2025-01-16T09:30:00Z'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    delete:
      operationId: deleteDraft
      summary: Delete a draft
      tags: [Composition]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /styles:
    get:
      operationId: listStyles
      summary: List cached style profiles
      tags: [Composition]
      security:
        - apiKey: []
        - oauthBearer: []
      responses:
        '200':
          description: Style profile list
          content:
            application/json:
              schema:
                type: object
                required: [styles]
                properties:
                  styles:
                    type: array
                    items:
                      $ref: '#/components/schemas/StyleProfileSummary'
                    example: []
              example:
                styles: []
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    post:
      operationId: analyzeStyle
      summary: Analyze writing style from recent tweets
      tags: [Composition]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: X username whose recent tweets define the style.
        content:
          application/json:
            schema:
              type: object
              required: [username]
              properties:
                username:
                  type: string
                  description: X username to analyze
                  example: elonmusk
            example:
              username: elonmusk
      responses:
        '200':
          description: Fresh cached style profile returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StyleProfile'
              example:
                xUsername: 'elonmusk'
                tweetCount: 50
                isOwnAccount: true
                fetchedAt: '2025-01-15T12:00:00Z'
                tweets:
                  - id: '1234567890'
                    text: 'Just launched our new feature!'
        '201':
          description: Style profile created or refreshed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StyleProfile'
              example:
                xUsername: 'elonmusk'
                tweetCount: 50
                isOwnAccount: true
                fetchedAt: '2025-01-15T12:00:00Z'
                tweets:
                  - id: '1234567890'
                    text: 'Just launched our new feature!'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'

        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /styles/compare:
    get:
      operationId: compareStyles
      summary: Compare two style profiles
      tags: [Composition]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: username1
          in: query
          required: true
          schema:
            type: string
          description: First username to compare
        - name: username2
          in: query
          required: true
          schema:
            type: string
          description: Second username to compare
      responses:
        '200':
          description: Style comparison
          content:
            application/json:
              schema:
                type: object
                required: [style1, style2]
                properties:
                  style1:
                    $ref: '#/components/schemas/StyleProfile'
                  style2:
                    $ref: '#/components/schemas/StyleProfile'
              example:
                style1:
                  xUsername: 'elonmusk'
                  tweetCount: 50
                  isOwnAccount: true
                  fetchedAt: '2025-01-15T12:00:00Z'
                  tweets:
                    - id: '1234567890'
                      text: 'Just launched our new feature!'
                style2:
                  xUsername: 'BillGates'
                  tweetCount: 40
                  isOwnAccount: false
                  fetchedAt: '2025-01-15T12:00:00Z'
                  tweets:
                    - id: '9876543210'
                      text: 'Climate change is a global challenge.'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /styles/{id}:
    get:
      operationId: getStyle
      summary: Get cached style profile
      tags: [Composition]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/StyleId'
      responses:
        '200':
          description: Style profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StyleProfile'
              example:
                xUsername: 'elonmusk'
                tweetCount: 50
                isOwnAccount: true
                fetchedAt: '2025-01-15T12:00:00Z'
                tweets:
                  - id: '1234567890'
                    text: 'Just launched our new feature!'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    put:
      operationId: saveStyle
      summary: Save style profile with custom tweets
      tags: [Composition]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/StyleId'
      requestBody:
        required: true
        description: Label and sample tweets that define the style profile.
        content:
          application/json:
            schema:
              type: object
              required: [label, tweets]
              properties:
                label:
                  type: string
                  description: Display label for the style
                  example: 'Professional Voice'
                tweets:
                  type: array
                  items:
                    type: object
                    required: [text]
                    properties:
                      text:
                        type: string
                        example:
                          'Excited to share our latest research findings.'
                  description: Array of tweet objects
                  example:
                    - text: 'Excited to share our latest research findings.'
            example:
              label: 'Professional Voice'
              tweets:
                - text: 'Excited to share our latest research findings.'
      responses:
        '200':
          description: Style profile saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StyleProfile'
              example:
                xUsername: 'elonmusk'
                tweetCount: 1
                isOwnAccount: true
                fetchedAt: '2025-01-15T12:00:00Z'
                tweets:
                  - id: '1234567890'
                    text: 'Excited to share our latest research findings.'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    delete:
      operationId: deleteStyle
      summary: Delete a style profile
      tags: [Composition]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/StyleId'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /styles/{id}/performance:
    get:
      operationId: getStylePerformance
      summary: Get engagement metrics for style tweets
      tags: [Composition]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/StyleId'
      responses:
        '200':
          description: Performance metrics
          content:
            application/json:
              schema:
                type: object
                required: [xUsername, tweetCount, tweets]
                properties:
                  xUsername:
                    type: string
                    example: elonmusk
                  tweetCount:
                    type: integer
                    example: 5
                  tweets:
                    type: array
                    items:
                      type: object
                      required: [id, text]
                      properties:
                        id:
                          type: string
                          example: '1234567890'
                        text:
                          type: string
                          example:
                            'Excited to share our latest research findings.'
                        likeCount:
                          type: integer
                          example: 120
                        retweetCount:
                          type: integer
                          example: 15
                        replyCount:
                          type: integer
                          example: 8
                        viewCount:
                          type: integer
                          example: 5000
                        createdAt:
                          type: string
                          example: '2025-01-15T12:00:00Z'
                    example:
                      - id: '1234567890'
                        text: 'Excited to share our latest research findings.'
                        likeCount: 120
                        retweetCount: 15
                        replyCount: 8
                        viewCount: 5000
                        createdAt: '2025-01-15T12:00:00Z'
              example:
                xUsername: elonmusk
                tweetCount: 5
                tweets:
                  - id: '1234567890'
                    text: 'Excited to share our latest research findings.'
                    likeCount: 120
                    retweetCount: 15
                    replyCount: 8
                    viewCount: 5000
                    createdAt: '2025-01-15T12:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /radar:
    get:
      operationId: getRadar
      summary: Get trending topics from curated sources
      tags: [Composition]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: after
          in: query
          schema:
            type: string
          description: Cursor for pagination (from prior response nextCursor).
        - name: category
          in: query
          schema:
            type: string
            enum:
              [
                general,
                tech,
                dev,
                science,
                culture,
                politics,
                business,
                entertainment,
              ]
          description: Filter by category.
        - name: hours
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 72
            default: 6
          description: Lookback window in hours (1-72, default 6).
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
          description: Number of items to return (1-100, default 50).
        - name: region
          in: query
          schema:
            type: string
            default: global
          description:
            Region filter. Use `global` or a region code such as `US`, `GB`,
            `TR`, or `ES`.
        - name: source
          in: query
          schema:
            type: string
            enum:
              [
                github,
                google_trends,
                hacker_news,
                polymarket,
                reddit,
                trustmrr,
                wikipedia,
              ]
          description:
            'Source filter. One of: github, google_trends, hacker_news,
            polymarket, reddit, trustmrr, wikipedia'
      responses:
        '200':
          description: Radar items
          content:
            application/json:
              schema:
                type: object
                required: [hasMore, items]
                properties:
                  hasMore:
                    type: boolean
                    example: false
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/RadarItem'
                    example: []
                  nextCursor:
                    type: string
                    description:
                      Opaque cursor for the next page (present only when hasMore
                      is true).
                    example: 'eyJ0IjoxNzM5OTcyODAwLCJpIjoiOTk5In0='
              example:
                hasMore: false
                items: []
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  # ── Monitors ─────────────────────────────────────────────
  /monitors:
    get:
      operationId: listMonitors
      summary: List monitors
      tags: [Monitors]
      security:
        - apiKey: []
        - oauthBearer: []
      responses:
        '200':
          description: Monitor list
          content:
            application/json:
              schema:
                type: object
                required: [monitors, total]
                properties:
                  monitors:
                    type: array
                    items:
                      $ref: '#/components/schemas/Monitor'
                    example: []
                  total:
                    type: integer
                    example: 0
              example:
                monitors: []
                total: 0
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    post:
      operationId: createMonitor
      summary: Create monitor
      description:
        Creates an instant monitor. Monitors are unlimited. Active monitors
        check every 1 second and cost 21 credits per hour. Events and webhook
        deliveries are included. Creation requires available credits for the
        first hourly charge and username lookup.
      tags: [Monitors]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: Target X username and event types to monitor.
        content:
          application/json:
            schema:
              type: object
              required: [username, eventTypes]
              properties:
                username:
                  type: string
                  description: X username (without @)
                  example: elonmusk
                eventTypes:
                  $ref: '#/components/schemas/EventTypeArray'
                  example: [tweet.new, tweet.reply]
            example:
              username: elonmusk
              eventTypes: [tweet.new, tweet.reply]
      responses:
        '201':
          description: Monitor created
          content:
            application/json:
              schema:
                type: object
                required:
                  [
                    id,
                    username,
                    xUserId,
                    eventTypes,
                    isActive,
                    createdAt,
                    nextBillingAt,
                  ]
                properties:
                  id:
                    type: string
                    example: '42'
                  username:
                    type: string
                    example: elonmusk
                  xUserId:
                    type: string
                    example: '1234567890'
                  eventTypes:
                    $ref: '#/components/schemas/EventTypeArray'
                    example: [tweet.new, tweet.reply]
                  isActive:
                    type: boolean
                    example: true
                  createdAt:
                    type: string
                    format: date-time
                    example: '2025-01-15T12:00:00Z'
                  nextBillingAt:
                    type: string
                    format: date-time
                    description:
                      Next hourly credit charge time. New active monitors are
                      due immediately.
                    example: '2025-01-15T12:00:00Z'
              example:
                id: '42'
                username: elonmusk
                xUserId: '1234567890'
                eventTypes: [tweet.new, tweet.reply]
                isActive: true
                createdAt: '2025-01-15T12:00:00Z'
                nextBillingAt: '2025-01-15T12:00:00Z'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          description: X user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'user_not_found'
                message: 'X user not found. Check the username.'
        '409':
          description: Monitor already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'monitor_already_exists'
                message: 'Monitor already exists.'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /monitors/keywords:
    get:
      operationId: listKeywordMonitors
      summary: List keyword monitors
      tags: [Monitors]
      security:
        - apiKey: []
        - oauthBearer: []
      responses:
        '200':
          description: Keyword monitor list
          content:
            application/json:
              schema:
                type: object
                required: [monitors, total]
                properties:
                  monitors:
                    type: array
                    items:
                      $ref: '#/components/schemas/KeywordMonitor'
                    example: []
                  total:
                    type: integer
                    example: 0
              example:
                monitors: []
                total: 0
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    post:
      operationId: createKeywordMonitor
      summary: Create keyword monitor
      description:
        Creates an instant keyword monitor. Keyword monitors are unlimited.
        Active monitors check every 1 second and cost 21 credits per hour.
        Events and webhook deliveries are included. Creation requires available
        credits for the first hourly charge.
      tags: [Monitors]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: Search query and event types to monitor.
        content:
          application/json:
            schema:
              type: object
              required: [query, eventTypes]
              properties:
                query:
                  type: string
                  minLength: 1
                  maxLength: 512
                  description:
                    X search query to monitor. Whitespace is normalized.
                  example: 'xquik OR "x api"'
                eventTypes:
                  $ref: '#/components/schemas/EventTypeArray'
                  example: [tweet.new]
            example:
              query: 'xquik OR "x api"'
              eventTypes: [tweet.new]
      responses:
        '201':
          description: Keyword monitor created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeywordMonitor'
              example:
                id: '21'
                query: 'xquik OR "x api"'
                eventTypes: [tweet.new]
                isActive: true
                createdAt: '2025-01-15T12:00:00Z'
                nextBillingAt: '2025-01-15T12:00:00Z'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '409':
          description: Keyword monitor already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'monitor_already_exists'
                message: 'Monitor already exists.'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /monitors/keywords/{id}:
    get:
      operationId: getKeywordMonitor
      summary: Get keyword monitor
      tags: [Monitors]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Keyword monitor details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeywordMonitor'
              example:
                id: '21'
                query: 'xquik OR "x api"'
                eventTypes: [tweet.new]
                isActive: true
                createdAt: '2025-01-15T12:00:00Z'
                nextBillingAt: '2025-01-15T13:00:00Z'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    patch:
      operationId: updateKeywordMonitor
      summary: Update keyword monitor
      tags: [Monitors]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        description: Updated event types or active status.
        content:
          application/json:
            schema:
              type: object
              properties:
                eventTypes:
                  $ref: '#/components/schemas/EventTypeArray'
                  example: [tweet.new]
                isActive:
                  type: boolean
                  example: true
            example:
              eventTypes: [tweet.new]
              isActive: true
      responses:
        '200':
          description: Keyword monitor updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeywordMonitor'
              example:
                id: '21'
                query: 'xquik OR "x api"'
                eventTypes: [tweet.new]
                isActive: true
                createdAt: '2025-01-15T12:00:00Z'
                nextBillingAt: '2025-01-15T13:00:00Z'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    delete:
      operationId: deleteKeywordMonitor
      summary: Delete keyword monitor
      tags: [Monitors]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /monitors/{id}:
    get:
      operationId: getMonitor
      summary: Get monitor
      tags: [Monitors]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Monitor details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
              example:
                id: '42'
                username: elonmusk
                xUserId: '1234567890'
                eventTypes: [tweet.new, tweet.reply]
                isActive: true
                createdAt: '2025-01-15T12:00:00Z'
                nextBillingAt: '2025-01-15T13:00:00Z'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    patch:
      operationId: updateMonitor
      summary: Update monitor
      tags: [Monitors]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        description: Event type list or active state for the account monitor.
        content:
          application/json:
            schema:
              type: object
              properties:
                eventTypes:
                  $ref: '#/components/schemas/EventTypeArray'
                  example: [tweet.new]
                isActive:
                  type: boolean
                  example: true
            example:
              eventTypes: [tweet.new]
              isActive: true
      responses:
        '200':
          description: Monitor updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
              example:
                id: '42'
                username: elonmusk
                xUserId: '1234567890'
                eventTypes: [tweet.new]
                isActive: true
                createdAt: '2025-01-15T12:00:00Z'
                nextBillingAt: '2025-01-15T13:00:00Z'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    delete:
      operationId: deleteMonitor
      summary: Delete monitor
      tags: [Monitors]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  # ── Events ───────────────────────────────────────────────
  /events:
    get:
      operationId: listEvents
      summary: List events
      tags: [Events]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/After'
        - name: monitorId
          in: query
          description: Filter events by monitor ID
          schema:
            type: string
        - name: eventType
          in: query
          description: Filter events by type
          schema:
            $ref: '#/components/schemas/EventType'
      responses:
        '200':
          description: Event list
          content:
            application/json:
              schema:
                type: object
                required: [events, hasMore]
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                    example: []
                  hasMore:
                    type: boolean
                    example: false
                  nextCursor:
                    type: string
                    example: 'abc123'
              example:
                events: []
                hasMore: false
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /events/{id}:
    get:
      operationId: getEvent
      summary: Get event
      tags: [Events]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Event details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventDetail'
              example:
                id: '42'
                type: 'tweet.new'
                username: 'elonmusk'
                monitorId: '7'
                monitorType: account
                occurredAt: '2025-01-15T12:00:00Z'
                data:
                  tweetId: '1234567890'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  # ── Extractions ──────────────────────────────────────────
  /extractions:
    get:
      operationId: listExtractions
      summary: List extraction jobs
      tags: [Extractions]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/After'
        - name: toolType
          in: query
          description: Filter by extraction tool type
          schema:
            $ref: '#/components/schemas/ExtractionToolType'
        - name: status
          in: query
          description: Filter by job status
          schema:
            type: string
            enum: [running, completed, failed]
      responses:
        '200':
          description: Extraction job list
          content:
            application/json:
              schema:
                type: object
                required: [extractions, hasMore]
                properties:
                  extractions:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExtractionJob'
                    example: []
                  hasMore:
                    type: boolean
                    example: false
                  nextCursor:
                    type: string
                    example: 'abc123'
              example:
                extractions: []
                hasMore: false
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    post:
      operationId: createExtraction
      summary: Run extraction
      tags: [Extractions]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description:
          Tool type and target identifier (tweet, user, community, list, or
          search query).
        content:
          application/json:
            schema:
              type: object
              required: [toolType]
              properties:
                toolType:
                  $ref: '#/components/schemas/ExtractionToolType'
                  example: follower_explorer
                targetTweetId:
                  type: string
                  example: '1234567890'
                targetUsername:
                  type: string
                  example: elonmusk
                targetCommunityId:
                  type: string
                  description:
                    Required for community_post_extractor & community_search.
                  example: '1500000000000000000'
                targetListId:
                  type: string
                  description:
                    Required for list_follower_explorer, list_member_extractor &
                    list_post_extractor.
                  example: '1234567890'
                targetSpaceId:
                  type: string
                  description: Required for space_explorer.
                  example: '1vOGwMdBqpwGB'
                resultsLimit:
                  type: integer
                  description:
                    Maximum number of results to extract. When set, the
                    extraction stops after reaching this limit.
                  example: 1000
                searchQuery:
                  type: string
                  description:
                    Required for tweet_search_extractor & community_search.
                  example: 'AI trends 2025'
                fromUser:
                  type: string
                  description:
                    Filter by author username (tweet_search_extractor)
                  example: nasa
                toUser:
                  type: string
                  description:
                    Filter replies sent to a username (tweet_search_extractor)
                  example: openai
                mentioning:
                  type: string
                  description:
                    Filter tweets mentioning a username (tweet_search_extractor)
                  example: example_user
                language:
                  type: string
                  description: Language code filter (tweet_search_extractor)
                  example: en
                sinceDate:
                  type: string
                  format: date
                  description: Start date YYYY-MM-DD (tweet_search_extractor)
                  example: '2025-01-01'
                untilDate:
                  type: string
                  format: date
                  description: End date YYYY-MM-DD (tweet_search_extractor)
                  example: '2025-12-31'
                mediaType:
                  type: string
                  enum: [images, videos, gifs, media, links, none]
                  description: Media type filter (tweet_search_extractor)
                  example: images
                minFaves:
                  type: integer
                  minimum: 0
                  description: Minimum likes threshold (tweet_search_extractor)
                  example: 10
                minRetweets:
                  type: integer
                  minimum: 0
                  description:
                    Minimum retweets threshold (tweet_search_extractor)
                  example: 5
                minReplies:
                  type: integer
                  minimum: 0
                  description:
                    Minimum replies threshold (tweet_search_extractor)
                  example: 3
                minQuotes:
                  type: integer
                  minimum: 0
                  description:
                    Minimum quote count threshold (tweet_search_extractor)
                  example: 2
                verifiedOnly:
                  type: boolean
                  description: Only verified authors (tweet_search_extractor)
                  example: false
                replies:
                  type: string
                  enum: [include, exclude, only]
                  description: Reply mode (tweet_search_extractor)
                  example: include
                retweets:
                  type: string
                  enum: [include, exclude, only]
                  description: Retweet mode (tweet_search_extractor)
                  example: exclude
                quotes:
                  type: string
                  enum: [include, exclude, only]
                  description: Quote mode (tweet_search_extractor)
                  example: include
                exactPhrase:
                  type: string
                  description: Exact phrase to match (tweet_search_extractor)
                  example: 'artificial intelligence'
                excludeWords:
                  type: string
                  description:
                    Words or quoted phrases to exclude. Separate with spaces,
                    commas, or lines. (tweet_search_extractor)
                  example: 'spam'
                anyWords:
                  type: string
                  description:
                    Words or quoted phrases where any one can match. Separate
                    with spaces, commas, or lines. (tweet_search_extractor)
                  example: 'ChatGPT AI model'
                hashtags:
                  type: string
                  description:
                    Hashtags separated by spaces, commas, or lines.
                    (tweet_search_extractor)
                  example: '#AI startups'
                cashtags:
                  type: string
                  description:
                    Cashtags separated by spaces, commas, or lines.
                    (tweet_search_extractor)
                  example: '$TSLA $NVDA'
                url:
                  type: string
                  description:
                    URL substring or domain filter (tweet_search_extractor)
                  example: example.com
                conversationId:
                  type: string
                  description: Conversation ID filter (tweet_search_extractor)
                  example: '1234567890'
                inReplyToTweetId:
                  type: string
                  description:
                    Only replies to this tweet ID (tweet_search_extractor)
                  example: '1234567890'
                quotesOfTweetId:
                  type: string
                  description:
                    Only quotes of this tweet ID (tweet_search_extractor)
                  example: '1234567890'
                retweetsOfTweetId:
                  type: string
                  description:
                    Only retweets of this tweet ID (tweet_search_extractor)
                  example: '1234567890'
                listId:
                  type: string
                  description: Search within a list ID (tweet_search_extractor)
                  example: '1234567890'
                place:
                  type: string
                  description: Search within a place ID (tweet_search_extractor)
                  example: '96683cc9126741d1'
                placeCountry:
                  type: string
                  description:
                    Search within a country code (tweet_search_extractor)
                  example: US
                pointRadius:
                  type: string
                  description:
                    Geo point radius, e.g. -73.99 40.73 25mi
                    (tweet_search_extractor)
                  example: '-73.99 40.73 25mi'
                boundingBox:
                  type: string
                  description:
                    Geo bounding box, e.g. -74.1 40.6 -73.9 40.8
                    (tweet_search_extractor)
                  example: '-74.1 40.6 -73.9 40.8'
                advancedQuery:
                  type: string
                  description:
                    Raw advanced search query appended as-is
                    (tweet_search_extractor)
                  example: 'min_faves:100'
            example:
              toolType: follower_explorer
              targetUsername: elonmusk
      responses:
        '202':
          description: Extraction started
          content:
            application/json:
              schema:
                type: object
                required: [id, toolType, status]
                properties:
                  id:
                    type: string
                    example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
                  toolType:
                    $ref: '#/components/schemas/ExtractionToolType'
                    example: follower_explorer
                  status:
                    type: string
                    const: running
                    example: running
              example:
                id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
                toolType: follower_explorer
                status: running
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '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'

  /extractions/estimate:
    post:
      operationId: estimateExtraction
      summary: Estimate extraction cost
      tags: [Extractions]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description:
          Same parameters as a real extraction; returns estimated credit cost
          without running the job.
        content:
          application/json:
            schema:
              type: object
              required: [toolType]
              properties:
                toolType:
                  $ref: '#/components/schemas/ExtractionToolType'
                  example: follower_explorer
                targetTweetId:
                  type: string
                  example: '1234567890'
                targetUsername:
                  type: string
                  example: elonmusk
                targetCommunityId:
                  type: string
                  description:
                    Required for community_post_extractor & community_search.
                  example: '1500000000000000000'
                targetListId:
                  type: string
                  description:
                    Required for list_follower_explorer, list_member_extractor &
                    list_post_extractor.
                  example: '1234567890'
                targetSpaceId:
                  type: string
                  description: Required for space_explorer.
                  example: '1vOGwMdBqpwGB'
                resultsLimit:
                  type: integer
                  description:
                    Maximum number of results to estimate. When set, the
                    estimate caps projected results to this value.
                  example: 1000
                searchQuery:
                  type: string
                  description:
                    Required for tweet_search_extractor & community_search.
                  example: 'AI trends 2025'
                fromUser:
                  type: string
                  description:
                    Estimate only tweets from this author username
                    (tweet_search_extractor)
                  example: nasa
                toUser:
                  type: string
                  description:
                    Estimate replies sent to this username
                    (tweet_search_extractor)
                  example: openai
                mentioning:
                  type: string
                  description:
                    Estimate tweets mentioning this username
                    (tweet_search_extractor)
                  example: example_user
                language:
                  type: string
                  description:
                    Language code used for estimate filtering
                    (tweet_search_extractor)
                  example: en
                sinceDate:
                  type: string
                  format: date
                  description:
                    Estimate start date in YYYY-MM-DD format
                    (tweet_search_extractor)
                  example: '2025-01-01'
                untilDate:
                  type: string
                  format: date
                  description:
                    Estimate end date in YYYY-MM-DD format
                    (tweet_search_extractor)
                  example: '2025-12-31'
                mediaType:
                  type: string
                  enum: [images, videos, gifs, media, links, none]
                  description:
                    Media type used for estimate filtering
                    (tweet_search_extractor)
                  example: images
                minFaves:
                  type: integer
                  minimum: 0
                  description:
                    Minimum likes threshold for estimated results
                    (tweet_search_extractor)
                  example: 10
                minRetweets:
                  type: integer
                  minimum: 0
                  description:
                    Minimum retweets threshold for estimated results
                    (tweet_search_extractor)
                  example: 5
                minReplies:
                  type: integer
                  minimum: 0
                  description:
                    Minimum replies threshold for estimated results
                    (tweet_search_extractor)
                  example: 3
                minQuotes:
                  type: integer
                  minimum: 0
                  description:
                    Minimum quote count threshold for estimated results
                    (tweet_search_extractor)
                  example: 2
                verifiedOnly:
                  type: boolean
                  description:
                    Estimate only verified authors (tweet_search_extractor)
                  example: false
                replies:
                  type: string
                  enum: [include, exclude, only]
                  description:
                    Reply mode used for estimation (tweet_search_extractor)
                  example: include
                retweets:
                  type: string
                  enum: [include, exclude, only]
                  description:
                    Retweet mode used for estimation (tweet_search_extractor)
                  example: exclude
                quotes:
                  type: string
                  enum: [include, exclude, only]
                  description:
                    Quote mode used for estimation (tweet_search_extractor)
                  example: include
                exactPhrase:
                  type: string
                  description: Exact phrase filter for search estimation
                  example: 'artificial intelligence'
                excludeWords:
                  type: string
                  description:
                    Words or quoted phrases excluded from estimated results.
                    Separate with spaces, commas, or lines.
                  example: 'spam'
                anyWords:
                  type: string
                  description:
                    Alternative words or quoted phrases for estimated results.
                    Separate with spaces, commas, or lines.
                  example: 'ChatGPT AI model'
                hashtags:
                  type: string
                  description:
                    Hashtags applied to the estimate, separated by spaces,
                    commas, or lines.
                  example: '#AI startups'
                cashtags:
                  type: string
                  description:
                    Cashtags applied to the estimate, separated by spaces,
                    commas, or lines.
                  example: '$TSLA $NVDA'
                url:
                  type: string
                  description:
                    URL substring or domain filter used for estimation
                    (tweet_search_extractor)
                  example: example.com
                conversationId:
                  type: string
                  description:
                    Conversation ID filter used for estimation
                    (tweet_search_extractor)
                  example: '1234567890'
                inReplyToTweetId:
                  type: string
                  description:
                    Estimate only replies to this tweet ID
                    (tweet_search_extractor)
                  example: '1234567890'
                quotesOfTweetId:
                  type: string
                  description:
                    Estimate only quotes of this tweet ID
                    (tweet_search_extractor)
                  example: '1234567890'
                retweetsOfTweetId:
                  type: string
                  description:
                    Estimate only retweets of this tweet ID
                    (tweet_search_extractor)
                  example: '1234567890'
                listId:
                  type: string
                  description:
                    Estimate search results within this list ID
                    (tweet_search_extractor)
                  example: '1234567890'
                place:
                  type: string
                  description:
                    Estimate search results within this place ID
                    (tweet_search_extractor)
                  example: '96683cc9126741d1'
                placeCountry:
                  type: string
                  description:
                    Estimate search results within this country code
                    (tweet_search_extractor)
                  example: US
                pointRadius:
                  type: string
                  description:
                    Geo point radius used for estimation, e.g. -73.99 40.73 25mi
                    (tweet_search_extractor)
                  example: '-73.99 40.73 25mi'
                boundingBox:
                  type: string
                  description:
                    Geo bounding box used for estimation, e.g. -74.1 40.6 -73.9
                    40.8 (tweet_search_extractor)
                  example: '-74.1 40.6 -73.9 40.8'
                advancedQuery:
                  type: string
                  description:
                    Raw advanced query string appended to the estimate
                    (tweet_search_extractor)
                  example: 'min_faves:100'
            example:
              toolType: follower_explorer
              targetUsername: elonmusk
      responses:
        '200':
          description: Extraction estimate
          content:
            application/json:
              schema:
                type: object
                required:
                  [
                    estimatedResults,
                    creditsRequired,
                    creditsAvailable,
                    allowed,
                    source,
                  ]
                properties:
                  estimatedResults:
                    type: integer
                    example: 500
                  creditsRequired:
                    type: string
                    example: '500'
                  creditsAvailable:
                    type: string
                    example: '50000'
                  allowed:
                    type: boolean
                    example: true
                  source:
                    type: string
                    enum:
                      [
                        followers,
                        following,
                        paginationCap,
                        posts,
                        quoteCount,
                        replyCount,
                        resultsLimit,
                        retweetCount,
                        unknown,
                      ]
                    example: 'replyCount'
                  resolvedXUserId:
                    type: string
                    example: '123456'
              example:
                estimatedResults: 500
                creditsRequired: '500'
                creditsAvailable: '50000'
                allowed: true
                source: 'replyCount'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /extractions/{id}:
    get:
      operationId: getExtraction
      summary: Get extraction results
      tags: [Extractions]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Extraction public ID (UUID)
        - name: limit
          in: query
          description: Maximum number of results to return (1-1000, default 100)
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - $ref: '#/components/parameters/After'
      responses:
        '200':
          description: Extraction job with results
          content:
            application/json:
              schema:
                type: object
                required: [job, results, hasMore]
                properties:
                  job:
                    type: object
                    additionalProperties: true
                    x-stainless-any: true
                    description:
                      Extraction job metadata - shape varies by tool type (JSON)
                    x-stainless-terraform-type: string
                    example:
                      id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
                      toolType: follower_explorer
                      status: completed
                  results:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                    example: []
                  hasMore:
                    type: boolean
                    example: false
                  nextCursor:
                    type: string
                    example: 'abc123'
              example:
                job:
                  id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
                  toolType: follower_explorer
                  status: completed
                results: []
                hasMore: false
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /extractions/{id}/export:
    get:
      operationId: exportExtraction
      summary: Export extraction results
      tags: [Extractions]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Extraction public ID
        - name: format
          in: query
          required: true
          description: Export file format
          schema:
            type: string
            enum: [csv, json, md, md-document, pdf, txt, xlsx]
      responses:
        '200':
          description: Exported file
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  # ── Draws ────────────────────────────────────────────────
  /draws:
    get:
      operationId: listDraws
      summary: List draws
      tags: [Draws]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/After'
      responses:
        '200':
          description: Draw list
          content:
            application/json:
              schema:
                type: object
                required: [draws, hasMore]
                properties:
                  draws:
                    type: array
                    items:
                      $ref: '#/components/schemas/DrawListItem'
                    example: []
                  hasMore:
                    type: boolean
                    example: false
                  nextCursor:
                    type: string
                    example: 'abc123'
              example:
                draws: []
                hasMore: false
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    post:
      operationId: createDraw
      summary: Run giveaway draw
      description:
        Runs a giveaway draw from a source tweet. The draw first checks the
        minimum credits needed to inspect the source tweet and at least one
        candidate. Remaining credits cap how many replies and retweeters can be
        inspected before filters and winner selection run.
      tags: [Draws]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description:
          Tweet URL, winner count, and optional eligibility filters (retweet,
          follow, keywords, hashtags, account age).
        content:
          application/json:
            schema:
              type: object
              required: [tweetUrl]
              properties:
                tweetUrl:
                  type: string
                  format: uri
                  example: 'https://x.com/elonmusk/status/1234567890'
                winnerCount:
                  type: integer
                  default: 1
                  example: 3
                backupCount:
                  type: integer
                  example: 2
                uniqueAuthorsOnly:
                  type: boolean
                  example: true
                mustRetweet:
                  type: boolean
                  example: true
                mustFollowUsername:
                  type: string
                  example: elonmusk
                filterMinFollowers:
                  type: integer
                  example: 50
                filterAccountAgeDays:
                  type: integer
                  example: 30
                filterLanguage:
                  type: string
                  example: en
                requiredHashtags:
                  type: array
                  items:
                    type: string
                  example: ['#giveaway']
                requiredKeywords:
                  type: array
                  items:
                    type: string
                  example: ['entered']
                requiredMentions:
                  type: array
                  items:
                    type: string
                  example: ['@elonmusk']
            example:
              tweetUrl: 'https://x.com/elonmusk/status/1234567890'
              winnerCount: 3
              mustRetweet: true
      responses:
        '201':
          description: Draw completed
          content:
            application/json:
              schema:
                type: object
                required: [id, tweetId, totalEntries, validEntries, winners]
                properties:
                  id:
                    type: string
                    example: 'f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345'
                  tweetId:
                    type: string
                    example: '1234567890'
                  totalEntries:
                    type: integer
                    description:
                      Candidate entries inspected for this draw after the
                      credit-derived cap. This may be lower than the source
                      tweet's full reply count.
                    example: 250
                  validEntries:
                    type: integer
                    description:
                      Entries from the inspected candidate set that passed all
                      filters. This is not necessarily every valid reply on the
                      source tweet when credits cap inspection.
                    example: 200
                  winners:
                    type: array
                    items:
                      $ref: '#/components/schemas/Winner'
                    example: []
              example:
                id: 'f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345'
                tweetId: '1234567890'
                totalEntries: 250
                validEntries: 200
                winners: []
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          description:
            Insufficient usable credits. Draws can fail before execution when
            the available balance cannot cover the minimum draw cost. A draw can
            also fail after execution when its final computed cost cannot be
            deducted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'insufficient_credits'
                message: 'Insufficient credits'
        '404':
          $ref: '#/components/responses/NotFound'
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'

  /draws/{id}:
    get:
      operationId: getDraw
      summary: Get draw details
      tags: [Draws]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/DrawId'
      responses:
        '200':
          description: Draw with winners
          content:
            application/json:
              schema:
                type: object
                required: [draw, winners]
                properties:
                  draw:
                    $ref: '#/components/schemas/DrawDetail'
                    example:
                      id: 'f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345'
                      tweetUrl: 'https://x.com/elonmusk/status/1234567890'
                      tweetId: '1234567890'
                      tweetText: 'Giving away 3 Tesla Model 3s!'
                      tweetAuthorUsername: 'elonmusk'
                      status: 'completed'
                      totalEntries: 250
                      validEntries: 200
                      tweetLikeCount: 50000
                      tweetRetweetCount: 25000
                      tweetReplyCount: 10000
                      tweetQuoteCount: 5000
                      createdAt: '2025-01-15T12:00:00Z'
                  winners:
                    type: array
                    items:
                      $ref: '#/components/schemas/Winner'
                    example: []
              example:
                draw:
                  id: 'f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345'
                  tweetUrl: 'https://x.com/elonmusk/status/1234567890'
                  tweetId: '1234567890'
                  tweetText: 'Giving away 3 Tesla Model 3s!'
                  tweetAuthorUsername: 'elonmusk'
                  status: 'completed'
                  totalEntries: 250
                  validEntries: 200
                  tweetLikeCount: 50000
                  tweetRetweetCount: 25000
                  tweetReplyCount: 10000
                  tweetQuoteCount: 5000
                  createdAt: '2025-01-15T12:00:00Z'
                winners: []
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /draws/{id}/export:
    get:
      operationId: exportDraw
      summary: Export draw data
      tags: [Draws]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/DrawId'
        - name: format
          in: query
          required: true
          description: Export output format
          schema:
            type: string
            enum: [csv, json, md, md-document, pdf, txt, xlsx]
        - name: type
          in: query
          schema:
            type: string
            enum: [winners, entries]
            default: winners
          description: Export winners or all entries
      responses:
        '200':
          description: Exported draw file
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  # ── Webhooks ─────────────────────────────────────────────
  /webhooks:
    get:
      operationId: listWebhooks
      summary: List webhooks
      tags: [Webhooks]
      security:
        - apiKey: []
        - oauthBearer: []
      responses:
        '200':
          description: Webhook list
          content:
            application/json:
              schema:
                type: object
                required: [webhooks]
                properties:
                  webhooks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
                    example: []
              example:
                webhooks: []
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    post:
      operationId: createWebhook
      summary: Create webhook
      tags: [Webhooks]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: HTTPS callback URL and event types to subscribe to.
        content:
          application/json:
            schema:
              type: object
              required: [url, eventTypes]
              properties:
                url:
                  type: string
                  format: uri
                  description: HTTPS URL
                  example: 'https://example.com/webhook'
                eventTypes:
                  $ref: '#/components/schemas/EventTypeArray'
                  example: [tweet.new, tweet.reply]
            example:
              url: 'https://example.com/webhook'
              eventTypes: [tweet.new, tweet.reply]
      responses:
        '201':
          description: Webhook created
          content:
            application/json:
              schema:
                type: object
                required: [id, url, secret, eventTypes, createdAt]
                properties:
                  id:
                    type: string
                    example: '42'
                  url:
                    type: string
                    format: uri
                    example: 'https://example.com/webhook'
                  secret:
                    type: string
                    description:
                      Plaintext HMAC signing secret returned only at creation.
                    example: 'a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2'
                  eventTypes:
                    $ref: '#/components/schemas/EventTypeArray'
                    example: [tweet.new, tweet.reply]
                  createdAt:
                    type: string
                    format: date-time
                    example: '2025-01-15T12:00:00Z'
              example:
                id: '42'
                url: 'https://example.com/webhook'
                secret: 'a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2'
                eventTypes: [tweet.new, tweet.reply]
                createdAt: '2025-01-15T12:00:00Z'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /webhooks/{id}:
    patch:
      operationId: updateWebhook
      summary: Update webhook
      tags: [Webhooks]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        description: Updated URL, event types, or active status.
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                  example: 'https://example.com/webhook'
                eventTypes:
                  $ref: '#/components/schemas/EventTypeArray'
                  example: [tweet.new]
                isActive:
                  type: boolean
                  example: true
            example:
              url: 'https://example.com/webhook'
              isActive: true
      responses:
        '200':
          description: Webhook updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
              example:
                id: '42'
                url: 'https://example.com/webhook'
                eventTypes: [tweet.new]
                isActive: true
                consecutiveFailures: 0
                deliveryStatus: active
                failureHardCap: 200
                createdAt: '2025-01-15T12:00:00Z'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    delete:
      operationId: deleteWebhook
      summary: Deactivate webhook
      tags: [Webhooks]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /webhooks/{id}/deliveries:
    get:
      operationId: listWebhookDeliveries
      summary: List webhook deliveries
      tags: [Webhooks]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Delivery list
          content:
            application/json:
              schema:
                type: object
                required: [deliveries]
                properties:
                  deliveries:
                    type: array
                    items:
                      $ref: '#/components/schemas/Delivery'
                    example: []
              example:
                deliveries: []
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /webhooks/{id}/test:
    post:
      operationId: testWebhook
      summary: Test webhook endpoint
      tags: [Webhooks]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Test result
          content:
            application/json:
              schema:
                type: object
                required: [success, statusCode]
                properties:
                  success:
                    type: boolean
                    example: true
                  statusCode:
                    type: integer
                    example: 200
                  error:
                    type: string
                    example: ''
              example:
                success: true
                statusCode: 200
        '400':
          description: Invalid webhook ID or test delivery failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'webhook_test_failed'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /webhooks/{id}/resume:
    post:
      operationId: resumeWebhook
      summary: Test and resume webhook endpoint
      tags: [Webhooks]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Webhook resumed after a successful test delivery
          content:
            application/json:
              schema:
                type: object
                required: [success, statusCode, webhook]
                properties:
                  success:
                    type: boolean
                    example: true
                  statusCode:
                    type: integer
                    example: 200
                  webhook:
                    $ref: '#/components/schemas/Webhook'
              example:
                success: true
                statusCode: 200
                webhook:
                  id: '42'
                  url: 'https://example.com/webhook'
                  eventTypes: [tweet.new]
                  isActive: true
                  consecutiveFailures: 0
                  deliveryStatus: active
                  failureHardCap: 200
                  createdAt: '2025-01-15T12:00:00Z'
        '400':
          description: Webhook test failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'Connection timed out'
                statusCode: 0
                success: false
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  # ── X API (reads) ────────────────────────────────────────
  /x/tweets:
    get:
      operationId: getBatchTweets
      summary: Get multiple tweets by IDs
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: ids
          in: query
          required: true
          schema:
            type: string
          description: Comma-separated tweet IDs (max 100)
      responses:
        '200':
          description: List of tweets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
              example:
                tweets:
                  - id: '1234567890'
                    text: 'Just launched our new feature!'
                    createdAt: '2025-01-15T12:00:00Z'
                    likeCount: 42
                    retweetCount: 5
                    replyCount: 3
                    quoteCount: 1
                    viewCount: 1500
                    bookmarkCount: 2
                    author:
                      id: '9876543210'
                      username: 'elonmusk'
                      name: 'Elon Musk'
                      verified: true
                has_next_page: true
                next_cursor: 'DAACCgACGRElMJcAAA'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'
    post:
      operationId: createTweet
      summary: Create tweet
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      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'
                attachment_url:
                  type: string
                  example: 'https://x.com/elonmusk/status/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':
          description: Tweet created
          content:
            application/json:
              schema:
                type: object
                required: [tweetId, success, charged, chargedCredits]
                properties:
                  tweetId:
                    type: string
                    example: '1234567890'
                  success:
                    type: boolean
                    const: true
                    example: true
                  charged:
                    type: boolean
                    example: true
                  chargedCredits:
                    type: string
                    description:
                      Credits charged for this tweet. Text-only tweets and
                      replies cost 30 credits; attached media adds 2 credits per
                      started MB.
                    example: '32'
                  writeActionId:
                    type: string
                    example: '42'
              example:
                tweetId: '1234567890'
                success: true
                charged: true
                chargedCredits: '32'
        '202':
          description:
            Write was dispatched but final confirmation is still pending. Do not
            retry-send the same write. Poll the write action status instead.
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - status
                  - writeActionId
                  - charged
                  - chargedCredits
                  - retryable
                properties:
                  error:
                    type: string
                    const: x_write_unconfirmed
                  status:
                    type: string
                    const: pending_confirmation
                  writeActionId:
                    type: string
                    example: '42'
                  charged:
                    type: boolean
                    const: false
                  chargedCredits:
                    type: string
                    example: '0'
                  retryable:
                    type: boolean
                    const: false
                  message:
                    type: string
                    example:
                      Action may have completed, but confirmation is still
                      pending.
              example:
                error: x_write_unconfirmed
                status: pending_confirmation
                writeActionId: '42'
                charged: false
                chargedCredits: '0'
                retryable: false
                message:
                  Action may have completed, but confirmation is still pending.
        '400':
          description: Invalid input or unsupported field
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                InvalidInput:
                  summary: Invalid input
                  value:
                    error: invalid_input
                    message: Either text or media is required
                UnsupportedField:
                  summary: Unsupported field on POST /x/tweets
                  value:
                    error: unsupported_field
                    message:
                      media_ids is not supported on POST /x/tweets. Pass media
                      as an array of public image or MP4 video URLs.
                    retryable: false
                    details:
                      action: create_tweet
                      suggestion:
                        Use the media field with public URLs instead of
                        media_ids. Send up to 4 images or exactly 1 MP4 video.
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /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':
          description: Write action status
          content:
            application/json:
              schema:
                type: object
                required:
                  - writeActionId
                  - action
                  - status
                  - charged
                  - chargedCredits
                  - media
                  - sendDispatched
                  - retryable
                  - createdAt
                properties:
                  writeActionId:
                    type: string
                    example: '42'
                  action:
                    type: string
                    example: create_tweet
                  status:
                    type: string
                    enum: [success, failed, pending_confirmation]
                    example: pending_confirmation
                  tweetId:
                    type: string
                    example: '1234567890'
                  messageId:
                    type: string
                    example: '1234567890'
                  targetId:
                    type: [string, 'null']
                    example: '1234567890'
                  charged:
                    type: boolean
                    example: false
                  chargedCredits:
                    type: string
                    example: '32'
                  media:
                    type: object
                    required: [count, credits, kind, totalBytes]
                    properties:
                      count:
                        type: integer
                        example: 1
                      credits:
                        type: string
                        example: '2'
                      kind:
                        type: string
                        enum: [none, image, video]
                        example: video
                      totalBytes:
                        type: string
                        example: '834921'
                  sendDispatched:
                    type: boolean
                    example: true
                  retryable:
                    type: boolean
                    const: false
                    example: false
                  confirmationAttempts:
                    type: integer
                    example: 2
                  confirmationSource:
                    type: [string, 'null']
                    example: read_confirmation
                  createdAt:
                    type: string
                    format: date-time
                    example: '2026-05-08T20:00:00.000Z'
                  sendDispatchedAt:
                    type: string
                    format: date-time
                    example: '2026-05-08T20:00:01.000Z'
                  confirmationCheckedAt:
                    type: string
                    format: date-time
                    example: '2026-05-08T20:00:05.000Z'
                  confirmedAt:
                    type: string
                    format: date-time
                    example: '2026-05-08T20:00:06.000Z'
                  message:
                    type: string
                    example: Confirmation is still pending.
              example:
                writeActionId: '42'
                action: create_tweet
                status: pending_confirmation
                charged: false
                chargedCredits: '0'
                media:
                  count: 0
                  credits: '0'
                  kind: none
                  totalBytes: '0'
                sendDispatched: true
                retryable: false
                confirmationAttempts: 2
                confirmationSource: null
                createdAt: '2026-05-08T20:00:00.000Z'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /x/trends:
    get:
      operationId: getXTrends
      summary: Get trending hashtags and topics from X by region
      tags:
        - Trends
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        offers:
          - amount: '450'
            currency: '0x20c000000000000000000000b9537d11c60e8b50'
            intent: charge
            method: tempo
      parameters:
        - name: woeid
          in: query
          schema:
            type: integer
            default: 1
          description:
            'Region WOEID (1=Worldwide, 23424977=US, 23424975=UK,
            23424969=Turkey)'
        - name: count
          in: query
          description: Number of trending topics to return (1-50, default 30)
          schema:
            type: integer
            default: 30
            minimum: 1
            maximum: 50
      responses:
        '200':
          description: List of trending topics
          content:
            application/json:
              schema:
                type: object
                required: [trends, count, woeid]
                properties:
                  trends:
                    type: array
                    items:
                      type: object
                      required: [name]
                      properties:
                        name:
                          type: string
                          example: '#AI'
                        description:
                          type: string
                          example: 'Artificial intelligence discussions'
                        query:
                          type: string
                          example: '%23AI'
                        rank:
                          type: integer
                          example: 1
                    example:
                      - name: '#AI'
                        description: 'Artificial intelligence discussions'
                        query: '%23AI'
                        rank: 1
                  count:
                    type: integer
                    example: 30
                  woeid:
                    type: integer
                    example: 1
              example:
                trends:
                  - name: '#AI'
                    description: 'Artificial intelligence discussions'
                    query: '%23AI'
                    rank: 1
                count: 30
                woeid: 1
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/tweets/search:
    get:
      operationId: searchTweets
      summary:
        Search tweets by query, Tweet ID, X status URL, or account date window
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Search query (keywords, #hashtags, from:user, "exact phrases", since:YYYY-MM-DD, until:YYYY-MM-DD, min_faves:N). A plain Tweet ID or X status URL returns the exact tweet when available. Plain from:user date windows are optimized for timeline completeness. Add keywords when ranked search semantics matter more than account timeline completeness.
        - name: queryType
          in: query
          required: false
          schema:
            type: string
            enum: [Latest, Top]
            default: Latest
          description:
            Sort order - Latest (chronological) or Top (engagement-ranked)
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor from previous response
        - name: sinceTime
          in: query
          schema:
            type: string
          description: ISO 8601 timestamp - only return tweets after this time
        - name: untilTime
          in: query
          schema:
            type: string
          description: ISO 8601 timestamp - only return tweets before this time
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
            maximum: 200
          description: >
            Max tweets to return (server paginates internally). Omit for single
            page (~20). This is an upper bound for paid authenticated calls:
            remaining credits can reduce the returned page size, and zero
            affordable results returns 402 insufficient_credits.
        - $ref: '#/components/parameters/TweetFilterFromUser'
        - $ref: '#/components/parameters/TweetFilterToUser'
        - $ref: '#/components/parameters/TweetFilterMentioning'
        - $ref: '#/components/parameters/TweetFilterLanguage'
        - $ref: '#/components/parameters/TweetFilterSinceDate'
        - $ref: '#/components/parameters/TweetFilterUntilDate'
        - $ref: '#/components/parameters/TweetFilterMediaType'
        - $ref: '#/components/parameters/TweetFilterMinFaves'
        - $ref: '#/components/parameters/TweetFilterMinRetweets'
        - $ref: '#/components/parameters/TweetFilterMinReplies'
        - $ref: '#/components/parameters/TweetFilterMinQuotes'
        - $ref: '#/components/parameters/TweetFilterVerifiedOnly'
        - $ref: '#/components/parameters/TweetFilterReplies'
        - $ref: '#/components/parameters/TweetFilterRetweets'
        - $ref: '#/components/parameters/TweetFilterQuotes'
        - $ref: '#/components/parameters/TweetFilterExactPhrase'
        - $ref: '#/components/parameters/TweetFilterExcludeWords'
        - $ref: '#/components/parameters/TweetFilterAnyWords'
        - $ref: '#/components/parameters/TweetFilterHashtags'
        - $ref: '#/components/parameters/TweetFilterCashtags'
        - $ref: '#/components/parameters/TweetFilterUrl'
        - $ref: '#/components/parameters/TweetFilterConversationId'
        - $ref: '#/components/parameters/TweetFilterInReplyToTweetId'
        - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId'
        - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId'
        - $ref: '#/components/parameters/TweetSearchListId'
        - $ref: '#/components/parameters/TweetSearchPlace'
        - $ref: '#/components/parameters/TweetSearchPlaceCountry'
        - $ref: '#/components/parameters/TweetSearchPointRadius'
        - $ref: '#/components/parameters/TweetSearchBoundingBox'
        - $ref: '#/components/parameters/TweetSearchAdvancedQuery'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
              example:
                tweets:
                  - id: '1234567890'
                    text: 'Just launched our new feature!'
                    createdAt: '2025-01-15T12:00:00Z'
                    likeCount: 42
                    retweetCount: 5
                    replyCount: 3
                    quoteCount: 1
                    viewCount: 1500
                    bookmarkCount: 2
                    author:
                      id: '9876543210'
                      username: 'elonmusk'
                      name: 'Elon Musk'
                      verified: true
                has_next_page: true
                next_cursor: 'DAACCgACGRElMJcAAA'
        '400':
          description: Missing query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'missing_query'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/articles/{tweetId}:
    get:
      operationId: getArticle
      summary: Get full X Article content with cover image and metadata
      description:
        Retrieve the full content of an X Article (long-form post) by numeric
        tweet ID. Returns article_not_found when the tweet is valid but is not
        an X Article.
      tags:
        - Articles
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        offers:
          - amount: '750'
            currency: '0x20c000000000000000000000b9537d11c60e8b50'
            intent: charge
            method: tempo
      parameters:
        - name: tweetId
          in: path
          required: true
          schema:
            type: string
          description:
            Numeric tweet ID of the article, 15-20 digits. If you have a tweet
            URL, use the final status ID.
      responses:
        '200':
          description: Article with author
          content:
            application/json:
              schema:
                type: object
                required: [article]
                properties:
                  article:
                    type: object
                    properties:
                      title:
                        type: string
                        example: 'The Future of AI'
                      previewText:
                        type: string
                        example: 'A deep dive into the latest AI trends...'
                      coverImageUrl:
                        type: string
                        example: 'https://pbs.twimg.com/media/example.jpg'
                      bodyText:
                        type: string
                        description: Plain text joined from all article blocks
                        example: 'This is the first paragraph of the article.'
                      contents:
                        type: array
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              description:
                                'Block type: paragraph, header-one, header-two,
                                header-three, header-four, header-five,
                                header-six, unordered-list-item,
                                ordered-list-item, blockquote, code-block,
                                media, divider'
                              example: 'paragraph'
                            text:
                              type: string
                              example:
                                'This is the first paragraph of the article.'
                            url:
                              type: string
                              description: Media URL for media blocks
                              example: 'https://pbs.twimg.com/media/example.jpg'
                            previewUrl:
                              type: string
                              description: Preview image URL for media blocks
                              example: 'https://pbs.twimg.com/media/example.jpg'
                            width:
                              type: integer
                              example: 1200
                            height:
                              type: integer
                              example: 675
                            inlineStyleRanges:
                              type: array
                              description: Inline text formatting ranges
                              items:
                                type: object
                                properties:
                                  offset:
                                    type: integer
                                    example: 0
                                  length:
                                    type: integer
                                    example: 8
                                  style:
                                    type: string
                                    example: 'BOLD'
                      createdAt:
                        type: string
                        example: '2025-01-15T12:00:00Z'
                      likeCount:
                        type: integer
                        example: 150
                      replyCount:
                        type: integer
                        example: 23
                      quoteCount:
                        type: integer
                        example: 8
                      viewCount:
                        type: integer
                        example: 5000
                  author:
                    $ref: '#/components/schemas/ArticleAuthor'
              example:
                article:
                  title: 'The Future of AI'
                  previewText: 'A deep dive into the latest AI trends...'
                  coverImageUrl: 'https://pbs.twimg.com/media/example.jpg'
                  contents:
                    - type: 'paragraph'
                      text: 'This is the first paragraph of the article.'
                  createdAt: '2025-01-15T12:00:00Z'
                  likeCount: 150
                  replyCount: 23
                  quoteCount: 8
                  viewCount: 5000
                author:
                  id: '9876543210'
                  name: 'Elon Musk'
                  username: 'elonmusk'
                  profilePicture: 'https://pbs.twimg.com/profile_images/example.jpg'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          description: Article not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'article_not_found'
                message: 'Article not found. Use an X Article tweet ID.'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/tweets/{id}:
    get:
      operationId: lookupTweet
      summary: Get tweet with full text, author, metrics and media
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        offers:
          - amount: '150'
            currency: '0x20c000000000000000000000b9537d11c60e8b50'
            intent: charge
            method: tempo
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Numeric tweet ID, 15-20 digits
      responses:
        '200':
          description: Tweet with author
          content:
            application/json:
              schema:
                type: object
                required: [tweet]
                properties:
                  tweet:
                    $ref: '#/components/schemas/TweetDetail'
                  author:
                    $ref: '#/components/schemas/TweetAuthor'
              example:
                tweet:
                  id: '1234567890'
                  text: 'Just launched our new feature!'
                  createdAt: '2025-01-15T12:00:00Z'
                  retweetCount: 5
                  replyCount: 3
                  likeCount: 42
                  quoteCount: 1
                  viewCount: 1500
                  bookmarkCount: 2
                author:
                  id: '9876543210'
                  username: 'elonmusk'
                  followers: 150000000
                  verified: true
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          description: Tweet not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'tweet_not_found'
                message: 'Tweet not found. Check the tweet ID.'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'
    delete:
      operationId: deleteTweet
      summary: Delete tweet
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - 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/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/tweets/{id}/like:
    post:
      operationId: likeTweet
      summary: Like tweet
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - 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/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'
    delete:
      operationId: unlikeTweet
      summary: Unlike tweet
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - 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/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/tweets/{id}/retweet:
    post:
      operationId: retweet
      summary: Retweet
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - 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/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'
    delete:
      operationId: unretweet
      summary: Unretweet
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - 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/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/users/batch:
    get:
      operationId: getBatchUsers
      summary: Look up multiple users by IDs in one call
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: ids
          in: query
          required: true
          schema:
            type: string
          description:
            Comma-separated numeric user IDs (1-100 values). Duplicate IDs are
            ignored while preserving first-seen order.
      responses:
        '200':
          description:
            Matched users plus reconciliation metadata for unavailable IDs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchUsers'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/users/search:
    get:
      operationId: searchUsers
      summary: Search users by name or username
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: User search query
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for user search
      responses:
        '200':
          description: User search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/users/{id}:
    get:
      operationId: getUser
      summary: Get user profile with follower counts and verification
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        offers:
          - amount: '150'
            currency: '0x20c000000000000000000000b9537d11c60e8b50'
            intent: charge
            method: tempo
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: X username (without @) or user ID
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
              example:
                id: '9876543210'
                username: elonmusk
                name: Elon Musk
                description: CEO of Tesla, SpaceX, and X
                followers: 150000000
                following: 500
                verified: true
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'user_not_found'
                message: 'X user not found. Check the username.'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/users/{id}/follow:
    post:
      operationId: followUser
      summary: Follow user
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - 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/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'
    delete:
      operationId: unfollowUser
      summary: Unfollow user
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - 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/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/users/{id}/remove-follower:
    post:
      operationId: removeFollower
      summary: Remove follower
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - 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/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/followers/check:
    get:
      operationId: checkFollow
      summary: Check if one user follows another
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        offers:
          - amount: '750'
            currency: '0x20c000000000000000000000b9537d11c60e8b50'
            intent: charge
            method: tempo
      parameters:
        - name: source
          in: query
          required: true
          schema:
            type: string
          description: Source username, @username, or X or Twitter profile URL
        - name: target
          in: query
          required: true
          schema:
            type: string
          description: Target username, @username, or X or Twitter profile URL
      responses:
        '200':
          description: Follow check result
          content:
            application/json:
              schema:
                type: object
                required:
                  [isFollowing, isFollowedBy, sourceUsername, targetUsername]
                properties:
                  isFollowing:
                    type: boolean
                    example: true
                  isFollowedBy:
                    type: boolean
                    example: false
                  sourceUsername:
                    type: string
                    example: 'elonmusk'
                  targetUsername:
                    type: string
                    example: 'jack'
              example:
                isFollowing: true
                isFollowedBy: false
                sourceUsername: 'elonmusk'
                targetUsername: 'jack'
        '400':
          description: Missing or invalid params
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'missing_params'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/dm/{userId}:
    post:
      operationId: sendDm
      summary: Send direct message
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - 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':
          description: DM sent
          content:
            application/json:
              schema:
                type: object
                required: [messageId, success]
                properties:
                  messageId:
                    type: string
                    example: '1234567890123456789'
                  success:
                    type: boolean
                    const: true
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/media:
    post:
      operationId: uploadMedia
      summary: Upload media
      tags: [Media]
      security:
        - apiKey: []
        - oauthBearer: []
      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':
          description: Media uploaded
          content:
            application/json:
              schema:
                type: object
                required: [mediaId, mediaUrl, success]
                properties:
                  mediaId:
                    type: string
                    example: '1234567890123456789'
                  mediaUrl:
                    type: string
                    format: uri
                    description: Public media URL for tweet `media` arrays.
                    example: 'https://media.xquik.com/uploads/1234567890123456789.png'
                  success:
                    type: boolean
                    const: true
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '404':
          $ref: '#/components/responses/XAccountNotFound'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/media/download:
    post:
      operationId: downloadMedia
      summary: Download images and videos from tweets
      tags:
        - Media
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description:
          Single tweet URL/ID, accepted aliases, or array of up to 50 tweet
          URLs/IDs for bulk download. When `tweetIds` contains at least one
          string value, bulk mode is used.
        content:
          application/json:
            schema:
              type: object
              properties:
                tweetInput:
                  type: string
                  description: Tweet URL or ID (single tweet)
                  example: 'https://x.com/elonmusk/status/1234567890'
                tweetId:
                  type: string
                  description: Numeric tweet ID alias for tweetInput
                  example: '1234567890'
                tweetUrl:
                  type: string
                  description: Tweet URL alias for tweetInput
                  example: 'https://x.com/elonmusk/status/1234567890'
                tweetIds:
                  type: array
                  items:
                    type: string
                  maxItems: 50
                  description:
                    Array of tweet URLs or IDs (bulk, max 50 string items)
                  example: ['1234567890', '1234567891']
            example:
              tweetInput: 'https://x.com/elonmusk/status/1234567890'
      responses:
        '200':
          description:
            'Media download result. Single: tweetId + galleryUrl + cacheHit.
            Bulk: galleryUrl + totalTweets + totalMedia.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  tweetId:
                    type: string
                    example: '1234567890'
                  galleryUrl:
                    type: string
                    example: 'https://xquik.com/gallery/abc123'
                  cacheHit:
                    type: boolean
                    example: false
                  totalTweets:
                    type: integer
                    example: 2
                  totalMedia:
                    type: integer
                    example: 5
              example:
                tweetId: '1234567890'
                galleryUrl: 'https://xquik.com/gallery/abc123'
                cacheHit: false
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          description: Tweet media source not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'tweet_not_found'
                message: 'Tweet not found.'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/profile:
    patch:
      operationId: updateProfile
      summary: Update X profile
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      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/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '404':
          $ref: '#/components/responses/XAccountNotFound'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/profile/avatar:
    patch:
      operationId: updateAvatar
      summary: Update profile avatar
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      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/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '404':
          $ref: '#/components/responses/XAccountNotFound'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/profile/banner:
    patch:
      operationId: updateBanner
      summary: Update profile banner
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      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/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '404':
          $ref: '#/components/responses/XAccountNotFound'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/communities:
    post:
      operationId: createCommunity
      summary: Create community
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      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':
          description: Community created
          content:
            application/json:
              schema:
                type: object
                required: [communityId, success]
                properties:
                  communityId:
                    type: string
                    example: '1500000000000000000'
                  communityName:
                    type: string
                    example: 'Tesla Fans'
                  success:
                    type: boolean
                    const: true
                    example: true
              example:
                communityId: '1500000000000000000'
                communityName: 'Tesla Fans'
                success: true
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '404':
          $ref: '#/components/responses/XAccountNotFound'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/communities/{id}:
    delete:
      operationId: deleteCommunity
      summary: Delete community
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $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/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '404':
          $ref: '#/components/responses/XAccountNotFound'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/communities/{id}/join:
    post:
      operationId: joinCommunity
      summary: Join community
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $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/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '404':
          $ref: '#/components/responses/XAccountNotFound'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'
    delete:
      operationId: leaveCommunity
      summary: Leave community
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $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/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '404':
          $ref: '#/components/responses/XAccountNotFound'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  # ── X Accounts ───────────────────────────────────────────
  /x/accounts:
    get:
      operationId: listXAccounts
      summary: List connected X accounts
      tags: [X Accounts]
      security:
        - apiKey: []
        - oauthBearer: []
      responses:
        '200':
          description: X account list
          content:
            application/json:
              schema:
                type: object
                required: [accounts]
                properties:
                  accounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/XAccount'
                    example:
                      - id: '42'
                        xUserId: '9876543210'
                        xUsername: 'elonmusk'
                        status: 'active'
                        health: 'healthy'
                        createdAt: '2025-01-15T12:00:00Z'
                        updatedAt: '2025-03-10T08:30:00Z'
              example:
                accounts:
                  - id: '42'
                    xUserId: '9876543210'
                    xUsername: 'elonmusk'
                    status: 'active'
                    health: 'healthy'
                    createdAt: '2025-01-15T12:00:00Z'
                    updatedAt: '2025-03-10T08:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    post:
      operationId: connectXAccount
      summary: Connect X account
      tags: [X Accounts]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description:
          X credentials (username, email, password) and optional 2FA secret.
        content:
          application/json:
            schema:
              type: object
              required: [username, email, password]
              properties:
                username:
                  type: string
                  description: X username
                  example: 'your_x_username'
                email:
                  type: string
                  description: Account email
                  example: 'account@example.invalid'
                password:
                  type: string
                  description: Account password
                  example: '<ACCOUNT_PASSWORD>'
                totp_secret:
                  type: string
                  description: TOTP secret for 2FA
                  example: '<TOTP_SECRET>'
            example:
              username: 'your_x_username'
              email: 'account@example.invalid'
              password: '<ACCOUNT_PASSWORD>'
              totp_secret: '<TOTP_SECRET>'
      responses:
        '201':
          description: X account connected after verification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SanitizedXAccount'
        '202':
          description: Additional email verification code required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/XAccountConnectionChallenge'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '409':
          $ref: '#/components/responses/ConnectAlreadyConnected'
        '422':
          $ref: '#/components/responses/ConnectLoginFailed'
        '429':
          $ref: '#/components/responses/ConnectRateLimitExceeded'
        '502':
          $ref: '#/components/responses/ConnectUserLookupFailed'
        '503':
          $ref: '#/components/responses/ConnectServiceUnavailable'

  /x/account-connection-challenges/{id}/submit:
    post:
      operationId: submitXAccountConnectionChallenge
      summary: Submit X account email verification code
      tags: [X Accounts]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        description: Email verification code requested during account connect.
        content:
          application/json:
            schema:
              type: object
              required: [email_code]
              properties:
                email_code:
                  type: string
                  description: Code sent to the account email.
                  example: '<EMAIL_VERIFICATION_CODE>'
            example:
              email_code: '<EMAIL_VERIFICATION_CODE>'
      responses:
        '201':
          description: X account connected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SanitizedXAccount'
        '202':
          description: Email verification code required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/XAccountConnectionChallenge'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/ConnectAlreadyConnected'
        '410':
          description: Verification code expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/ConnectLoginFailed'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '503':
          $ref: '#/components/responses/ConnectServiceUnavailable'

  /x/accounts/{id}:
    get:
      operationId: getXAccount
      summary: Get X account details
      tags: [X Accounts]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: X account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/XAccountDetail'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    delete:
      operationId: disconnectXAccount
      summary: Disconnect X account
      tags: [X Accounts]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /x/accounts/{id}/reauth:
    post:
      operationId: reauthXAccount
      summary: Re-authenticate X account
      tags: [X Accounts]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        description: Updated password and optional fields for re-authentication.
        content:
          application/json:
            schema:
              type: object
              required: [password]
              properties:
                password:
                  type: string
                  description: Updated account password
                  example: '<ACCOUNT_PASSWORD>'
                totp_secret:
                  type: string
                  description: TOTP secret for 2FA re-authentication
                  example: '<TOTP_SECRET>'
                email:
                  type: string
                  description: Email for the X account (updates stored email)
                  example: 'account@example.invalid'
            example:
              password: '<ACCOUNT_PASSWORD>'
              totp_secret: '<TOTP_SECRET>'
              email: 'account@example.invalid'
      responses:
        '200':
          description: Re-authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SanitizedXAccount'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/ReauthAccountNotFound'
        '422':
          $ref: '#/components/responses/ConnectLoginFailed'
        '429':
          $ref: '#/components/responses/ConnectLoginCooldown'
        '503':
          $ref: '#/components/responses/ConnectServiceUnavailable'

  /x/accounts/bulk-retry:
    post:
      operationId: bulkRetryXAccounts
      summary: Bulk retry temporarily failed X accounts
      description: >
        Clears loginFailedAt and loginFailureReason for all accounts with
        transient or automated failure reasons, making them eligible for retry
        on next use.
      tags: [X Accounts]
      security:
        - apiKey: []
        - oauthBearer: []
      responses:
        '200':
          description: Accounts cleared for retry
          content:
            application/json:
              schema:
                type: object
                required: [cleared]
                properties:
                  cleared:
                    type: integer
                    description: Number of accounts cleared
                    example: 3
              example:
                cleared: 3
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  # ── Trends ───────────────────────────────────────────────
  /trends:
    get:
      operationId: getTrends
      summary: Get trending hashtags and topics by region (alias)
      tags:
        - Trends
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        offers:
          - amount: '450'
            currency: '0x20c000000000000000000000b9537d11c60e8b50'
            intent: charge
            method: tempo
      parameters:
        - name: woeid
          in: query
          schema:
            type: integer
            default: 1
          description:
            'Region Yahoo WOEID code (1=Worldwide, 23424977=US, 23424975=UK,
            23424969=Turkey)'
        - name: count
          in: query
          description: Number of trending topics returned (1-50, default 30)
          schema:
            type: integer
            default: 30
            minimum: 1
            maximum: 50
      responses:
        '200':
          description: Trending topics
          content:
            application/json:
              schema:
                type: object
                required: [trends, total, woeid]
                properties:
                  trends:
                    type: array
                    items:
                      type: object
                      required: [name]
                      properties:
                        name:
                          type: string
                          example: '#AI'
                        description:
                          type: string
                          example: 'Artificial intelligence discussions'
                        query:
                          type: string
                          example: '%23AI'
                        rank:
                          type: integer
                          example: 1
                    example:
                      - name: '#AI'
                        rank: 1
                  total:
                    type: integer
                    example: 30
                  woeid:
                    type: integer
                    example: 1
              example:
                trends:
                  - name: '#AI'
                    description: 'Artificial intelligence discussions'
                    query: '%23AI'
                    rank: 1
                total: 30
                woeid: 1
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

  # ── Support Tickets ─────────────────────────────────────
  /support/tickets:
    post:
      operationId: createTicket
      summary: Create a support ticket
      tags: [Support]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: Ticket subject and message body.
        content:
          application/json:
            schema:
              type: object
              required: [subject, body]
              properties:
                subject:
                  type: string
                  maxLength: 500
                  example: 'Cannot connect X account'
                body:
                  type: string
                  maxLength: 10000
                  title: TicketContent
                  example: 'I am unable to connect my X account. Please help.'
            example:
              subject: 'Cannot connect X account'
              body: 'I am unable to connect my X account. Please help.'
      responses:
        '201':
          description: Ticket created
          content:
            application/json:
              schema:
                type: object
                properties:
                  publicId:
                    type: string
                    example: 'tkt_a1b2c3d4e5f6a1b2c3d4e5f6'
              example:
                publicId: 'tkt_a1b2c3d4e5f6a1b2c3d4e5f6'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    get:
      operationId: listTickets
      summary: List user's support tickets
      tags: [Support]
      security:
        - apiKey: []
        - oauthBearer: []
      responses:
        '200':
          description: List of tickets
          content:
            application/json:
              schema:
                type: object
                properties:
                  tickets:
                    type: array
                    items:
                      type: object
                      properties:
                        publicId:
                          type: string
                          example: 'tkt_a1b2c3d4e5f6a1b2c3d4e5f6'
                        subject:
                          type: string
                          example: 'Cannot connect X account'
                        status:
                          type: string
                          example: 'open'
                        messageCount:
                          type: integer
                          example: 2
                        createdAt:
                          type: string
                          format: date-time
                          example: '2025-01-15T12:00:00Z'
                        updatedAt:
                          type: string
                          format: date-time
                          example: '2025-01-16T09:30:00Z'
                    example:
                      - publicId: 'tkt_a1b2c3d4e5f6a1b2c3d4e5f6'
                        subject: 'Cannot connect X account'
                        status: 'open'
              example:
                tickets:
                  - publicId: 'tkt_a1b2c3d4e5f6a1b2c3d4e5f6'
                    subject: 'Cannot connect X account'
                    status: 'open'
                    messageCount: 2
                    createdAt: '2025-01-15T12:00:00Z'
                    updatedAt: '2025-01-16T09:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /support/tickets/{id}:
    get:
      operationId: getTicket
      summary: Get ticket with all messages
      tags: [Support]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Support ticket public ID
          example: 'tkt_a1b2c3d4e5f6a1b2c3d4e5f6'
      responses:
        '200':
          description: Ticket detail
          content:
            application/json:
              schema:
                type: object
                properties:
                  publicId:
                    type: string
                    example: 'tkt_a1b2c3d4e5f6a1b2c3d4e5f6'
                  subject:
                    type: string
                    example: 'Cannot connect X account'
                  status:
                    type: string
                    example: 'open'
                  createdAt:
                    type: string
                    format: date-time
                    example: '2025-01-15T12:00:00Z'
                  updatedAt:
                    type: string
                    format: date-time
                    example: '2025-01-16T09:30:00Z'
                  messages:
                    type: array
                    items:
                      type: object
                      properties:
                        body:
                          type: string
                          example: 'I am unable to connect my X account.'
                        sender:
                          type: string
                          example: 'user'
                        createdAt:
                          type: string
                          format: date-time
                          example: '2025-01-15T12:00:00Z'
                    example:
                      - body: 'I am unable to connect my X account.'
                        sender: 'user'
                        createdAt: '2025-01-15T12:00:00Z'
              example:
                publicId: 'tkt_a1b2c3d4e5f6a1b2c3d4e5f6'
                subject: 'Cannot connect X account'
                status: 'open'
                messages:
                  - body: 'I am unable to connect my X account.'
                    sender: 'user'
                    createdAt: '2025-01-15T12:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    patch:
      operationId: updateTicketStatus
      summary: Update ticket status
      tags: [Support]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Support ticket public ID to update
          example: 'tkt_a1b2c3d4e5f6a1b2c3d4e5f6'
      requestBody:
        required: true
        description: New ticket status (open, resolved, or closed).
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status:
                  type: string
                  enum: [open, resolved, closed]
                  example: 'resolved'
            example:
              status: 'resolved'
      responses:
        '200':
          description: Status updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  publicId:
                    type: string
                    example: 'tkt_a1b2c3d4e5f6a1b2c3d4e5f6'
                  status:
                    type: string
                    example: 'resolved'
              example:
                publicId: 'tkt_a1b2c3d4e5f6a1b2c3d4e5f6'
                status: 'resolved'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /support/tickets/{id}/messages:
    post:
      operationId: addTicketMessage
      summary: Reply to a support ticket
      tags: [Support]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Support ticket public ID for the reply
          example: 'tkt_a1b2c3d4e5f6a1b2c3d4e5f6'
      requestBody:
        required: true
        description: Reply message body (max 10,000 characters).
        content:
          application/json:
            schema:
              type: object
              required: [body]
              properties:
                body:
                  type: string
                  maxLength: 10000
                  title: MessageContent
                  example: 'Thank you for the update.'
            example:
              body: 'Thank you for the update.'
      responses:
        '201':
          description: Message added
          content:
            application/json:
              schema:
                type: object
                properties:
                  publicId:
                    type: string
                    example: 'tkt_a1b2c3d4e5f6a1b2c3d4e5f6'
              example:
                publicId: 'tkt_a1b2c3d4e5f6a1b2c3d4e5f6'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /guest-wallets:
    post:
      operationId: createGuestWallet
      summary: Create an accountless prepaid wallet checkout
      description: >
        Create a one-use Stripe-hosted checkout after the user explicitly
        confirms a $10-$250 USD amount. This request creates no charge by
        itself. The user opens checkout_url on Stripe. This endpoint returns the
        paid-read API key without requiring an Xquik account, email, dashboard,
        or Xquik web page. An idempotent replay returns the same key.
      tags: [Guest Wallets]
      security: []
      parameters:
        - $ref: '#/components/parameters/GuestIdempotencyKey'
      requestBody:
        required: true
        description: Confirmed USD amount in cents.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GuestWalletPurchaseRequest'
            example:
              amount_minor: 1000
              currency: usd
      responses:
        '201':
          description: >
            Stripe-hosted checkout, guest API key, and API status URL.
          headers:
            Cache-Control:
              description: Prevents storage of the secret-bearing response.
              schema:
                type: string
                const: no-store, private
            Idempotent-Replayed:
              description: Present as true when replaying the same request.
              schema:
                type: string
                const: 'true'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuestWalletCreateResponse'
              example:
                account_required: false
                amount: { amount_minor: 1000, currency: usd }
                api_key: xq_example_returned_once
                authorization: { header: Authorization, scheme: Bearer }
                checkout_url: https://buy.stripe.com/example
                credential_notice:
                  Store api_key and the Idempotency-Key securely before sharing
                  checkout_url. No email recovery is available.
                credits: '66666'
                expires_at: '2026-07-13T13:00:00.000Z'
                instructions:
                  Give checkout_url to the user. They must complete payment on
                  Stripe. Never submit payment for them. After payment, poll
                  status_url every poll_after_seconds until
                  latest_purchase.status is no longer pending.
                poll_after_seconds: 2
                purchase_id: gp_example
                requires_user_interaction: true
                status: pending
                status_url: https://xquik.com/api/v1/guest-wallets/status
                wallet_id: gw_example
        '400':
          $ref: '#/components/responses/InvalidInput'
        '409':
          description: Idempotency-Key was reused with a different request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: Checkout expired or can no longer be used.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Request body is too large.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: Content-Type must be application/json.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '423':
          description: Guest wallet is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '503':
          description: Guest wallet checkout is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /guest-wallets/topups:
    post:
      operationId: topUpGuestWallet
      summary: Create another guest wallet checkout
      description: >
        Create a one-use Stripe-hosted checkout for an existing paid-read guest
        key after the user explicitly confirms a $10-$250 USD amount. The key
        remains the same. This request creates no charge by itself and never
        redirects through an Xquik web page.
      tags: [Guest Wallets]
      security:
        - apiKey: []
      parameters:
        - $ref: '#/components/parameters/GuestIdempotencyKey'
      requestBody:
        required: true
        description: Confirmed USD amount in cents.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GuestWalletPurchaseRequest'
            example:
              amount_minor: 1000
              currency: usd
      responses:
        '201':
          description: Stripe-hosted checkout and API status URL.
          headers:
            Cache-Control:
              description: Prevents storage of the secret-bearing response.
              schema:
                type: string
                const: no-store, private
            Idempotent-Replayed:
              description: Present as true when replaying the same request.
              schema:
                type: string
                const: 'true'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuestWalletTopupResponse'
              example:
                account_required: false
                amount: { amount_minor: 1000, currency: usd }
                checkout_url: https://buy.stripe.com/example
                credits: '66666'
                expires_at: '2026-07-13T13:00:00.000Z'
                instructions:
                  Give checkout_url to the user. They must complete payment on
                  Stripe. Never submit payment for them. After payment, poll
                  status_url every poll_after_seconds until
                  latest_purchase.status is no longer pending.
                poll_after_seconds: 2
                purchase_id: gp_example
                requires_user_interaction: true
                status: pending
                status_url: https://xquik.com/api/v1/guest-wallets/status
                wallet_id: gw_example
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '409':
          description: Idempotency-Key was reused with a different request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: Checkout expired or can no longer be used.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Request body is too large.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: Content-Type must be application/json.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '423':
          description: Guest wallet is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '503':
          description: Guest wallet checkout is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /guest-wallets/status:
    get:
      operationId: getGuestWalletStatus
      summary: Get guest wallet and payment status
      description: >
        Poll after Stripe payment. Use usable to decide whether paid reads can
        run. An active wallet can remain usable while a top-up is pending. A new
        wallet becomes usable only after verified webhook fulfillment. Send the
        guest key as Authorization: Bearer.
      tags: [Guest Wallets]
      security:
        - apiKey: []
      responses:
        '200':
          description: Guest wallet status without exposing the API key.
          headers:
            Cache-Control:
              description: Prevents storage of wallet status.
              schema:
                type: string
                const: no-store, private
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuestWalletStatusResponse'
              example:
                balance: '66666'
                latest_purchase:
                  amount: { amount_minor: 1000, currency: usd }
                  checkout_url: null
                  credits: '66666'
                  expires_at: '2026-07-13T13:00:00.000Z'
                  purchase_id: gp_example
                  status: paid
                poll_after_seconds: null
                scope: paid_reads
                status: active
                top_up:
                  method: POST
                  path: /api/v1/guest-wallets/topups
                usable: true
                wallet_id: gw_example
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /credits:
    get:
      operationId: getCredits
      summary: Get credits balance
      tags:
        - Subscribe
      security:
        - apiKey: []
        - oauthBearer: []
      responses:
        '200':
          description: Credits balance and usage
          content:
            application/json:
              schema:
                type: object
                required:
                  [
                    auto_topup_amount_dollars,
                    auto_topup_enabled,
                    auto_topup_threshold,
                    balance,
                    lifetime_purchased,
                    lifetime_used,
                  ]
                properties:
                  auto_topup_amount_dollars:
                    type: number
                    description:
                      Configured dollar amount for each automatic top-up.
                    example: 10
                  auto_topup_enabled:
                    type: boolean
                    example: false
                  auto_topup_threshold:
                    type: string
                    description:
                      Credit balance threshold that triggers automatic top-up
                      when enabled, represented as a bigint string.
                    example: '50000'
                  balance:
                    type: string
                    description:
                      Current credit balance as a bigint string to preserve
                      precision above Number.MAX_SAFE_INTEGER.
                    example: '50000'
                  lifetime_purchased:
                    type: string
                    description: Lifetime purchased credits as a bigint string.
                    example: '200000'
                  lifetime_used:
                    type: string
                    description: Lifetime consumed credits as a bigint string.
                    example: '150000'
              example:
                auto_topup_amount_dollars: 10
                auto_topup_enabled: false
                auto_topup_threshold: '50000'
                balance: '50000'
                lifetime_purchased: '200000'
                lifetime_used: '150000'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /credits/topup:
    post:
      operationId: topUpCredits
      summary: Create credit top-up checkout
      description: >
        Create a Stripe Checkout session only after the user confirms. The
        request never completes payment or adds credits by itself.
      tags:
        - Subscribe
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: Confirmed dollar amount for the credit top-up checkout.
        content:
          application/json:
            schema:
              type: object
              required: [dollars]
              properties:
                dollars:
                  type: integer
                  description: Amount to top up in US dollars. Minimum 10.
                  minimum: 10
                  example: 10
                locale:
                  type: string
                  description: Optional checkout locale. Defaults to en.
                  example: en
            example:
              dollars: 10
      responses:
        '200':
          description: Top-up payment links
          content:
            application/json:
              schema:
                type: object
                required: [url, redirect_url]
                properties:
                  redirect_url:
                    type: string
                    format: uri
                    description:
                      Stable first-party Xquik redirect URL for the active
                      Stripe Checkout session.
                    example: 'https://xquik.com/api/v1/credits/topup/redirect?session_id=cs_test_123'
                  url:
                    type: string
                    format: uri
                    description:
                      Same stable first-party Xquik redirect URL as
                      redirect_url. The response never exposes a raw Stripe
                      Checkout URL.
                    example: 'https://xquik.com/api/v1/credits/topup/redirect?session_id=cs_test_123'
              example:
                redirect_url: 'https://xquik.com/api/v1/credits/topup/redirect?session_id=cs_test_123'
                url: 'https://xquik.com/api/v1/credits/topup/redirect?session_id=cs_test_123'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /credits/topup/redirect:
    get:
      operationId: redirectCreditTopupCheckout
      summary: Redirect to an active top-up payment page
      tags:
        - Subscribe
      security: []
      parameters:
        - name: session_id
          in: query
          required: true
          schema:
            type: string
          description: Billing session ID returned by the top-up billing flow.
      responses:
        '303':
          description: Redirects to the active payment page.
          headers:
            Location:
              description: Payment page URL.
              schema:
                type: string
                format: uri
        '400':
          $ref: '#/components/responses/InvalidInput'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          description: Top-up payment session is no longer active.
        '502':
          description: Payment page lookup failed.
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
                    example: missing_url
  /credits/topup/status:
    get:
      operationId: getCreditTopupStatus
      summary: Get top-up billing status
      tags:
        - Subscribe
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: session_id
          in: query
          required: true
          schema:
            type: string
          description: Billing session ID returned by the top-up billing flow.
      responses:
        '200':
          description: Top-up billing status
          content:
            application/json:
              schema:
                type: object
                required: [status]
                properties:
                  amount_dollars:
                    anyOf:
                      - type: integer
                        minimum: 10
                      - type: 'null'
                    description: Dollar amount requested for the top-up.
                    example: 25
                  credits:
                    type: string
                    description: Bigint string credit amount granted or pending.
                    example: '166666'
                  status:
                    type: string
                    enum: [paid, processing, failed, expired]
                    example: paid
              example:
                amount_dollars: 25
                credits: '166666'
                status: paid
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /credits/quick-topup:
    post:
      operationId: quickTopUpCredits
      summary: Instantly charge saved card for credits
      tags:
        - Subscribe
      security:
        - cookieSession: []
      requestBody:
        required: true
        description: Dollar amount to charge the saved payment method.
        content:
          application/json:
            schema:
              type: object
              required: [dollars]
              properties:
                dollars:
                  type: number
                  description: Dollar amount for the top-up
                  minimum: 10
                  maximum: 500
                  example: 25
            example:
              dollars: 25
      responses:
        '200':
          description: Quick top-up result
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    required: [outcome, balance, credits]
                    properties:
                      outcome:
                        type: string
                        const: charged
                      balance:
                        type: string
                        description: Updated credit balance as a bigint string.
                        example: '1450'
                      credits:
                        type: string
                        description:
                          Credits added by this top-up as a bigint string.
                        example: '1000'
                  - type: object
                    required: [outcome, clientSecret]
                    properties:
                      outcome:
                        type: string
                        const: requires_action
                      clientSecret:
                        type: string
                        description:
                          Payment client secret for completing authentication.
                        example: pi_3abc_secret_xyz
                  - type: object
                    required: [outcome]
                    properties:
                      outcome:
                        type: string
                        const: no_payment_method
              examples:
                charged:
                  summary: Payment succeeded
                  value:
                    outcome: charged
                    balance: '1450'
                    credits: '1000'
                requiresAction:
                  summary: Additional authentication required
                  value:
                    outcome: requires_action
                    clientSecret: pi_3abc_secret_xyz
                noPaymentMethod:
                  summary: No saved payment method
                  value:
                    outcome: no_payment_method
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /x/tweets/{id}/favoriters:
    get:
      operationId: getTweetFavoriters
      summary: List visible users who liked a tweet
      description: >
        Returns liker profiles that X makes visible for the post. X can withhold
        liker identities even when the post reports likes. In that case this
        endpoint returns 424 `favoriters_unavailable` instead of a misleading
        empty success.
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Tweet ID to get favoriters
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for favoriters
        - $ref: '#/components/parameters/FollowerPageSize'
      responses:
        '200':
          description: Visible users who liked the tweet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/FavoritersUnavailable'

  /x/users/{id}/tweets:
    get:
      operationId: getUserTweets
      summary: List recent tweets posted by a user
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: X user ID or username
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for user tweets
        - $ref: '#/components/parameters/ResultPageSize'
        - name: includeReplies
          in: query
          schema:
            type: boolean
            default: false
          description: Include reply tweets
        - name: includeParentTweet
          in: query
          schema:
            type: boolean
            default: false
          description: Include parent tweet for replies
        - $ref: '#/components/parameters/TweetFilterFromUser'
        - $ref: '#/components/parameters/TweetFilterToUser'
        - $ref: '#/components/parameters/TweetFilterMentioning'
        - $ref: '#/components/parameters/TweetFilterLanguage'
        - $ref: '#/components/parameters/TweetFilterSinceDate'
        - $ref: '#/components/parameters/TweetFilterUntilDate'
        - $ref: '#/components/parameters/TweetFilterMediaType'
        - $ref: '#/components/parameters/TweetFilterMinFaves'
        - $ref: '#/components/parameters/TweetFilterMinRetweets'
        - $ref: '#/components/parameters/TweetFilterMinReplies'
        - $ref: '#/components/parameters/TweetFilterMinQuotes'
        - $ref: '#/components/parameters/TweetFilterVerifiedOnly'
        - $ref: '#/components/parameters/TweetFilterReplies'
        - $ref: '#/components/parameters/TweetFilterRetweets'
        - $ref: '#/components/parameters/TweetFilterQuotes'
        - $ref: '#/components/parameters/TweetFilterExactPhrase'
        - $ref: '#/components/parameters/TweetFilterExcludeWords'
        - $ref: '#/components/parameters/TweetFilterAnyWords'
        - $ref: '#/components/parameters/TweetFilterHashtags'
        - $ref: '#/components/parameters/TweetFilterCashtags'
        - $ref: '#/components/parameters/TweetFilterUrl'
        - $ref: '#/components/parameters/TweetFilterConversationId'
        - $ref: '#/components/parameters/TweetFilterInReplyToTweetId'
        - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId'
        - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId'
      responses:
        '200':
          description: User tweets list
          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'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/users/{id}/replies:
    get:
      operationId: getUserReplies
      summary: List a user's With Replies timeline
      description: Returns the user's timeline with replies included by default.
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: X user ID or username
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for user replies
        - $ref: '#/components/parameters/ResultPageSize'
        - name: includeParentTweet
          in: query
          schema:
            type: boolean
            default: false
          description: Include parent tweet for replies
        - $ref: '#/components/parameters/TweetFilterFromUser'
        - $ref: '#/components/parameters/TweetFilterToUser'
        - $ref: '#/components/parameters/TweetFilterMentioning'
        - $ref: '#/components/parameters/TweetFilterLanguage'
        - $ref: '#/components/parameters/TweetFilterSinceDate'
        - $ref: '#/components/parameters/TweetFilterUntilDate'
        - $ref: '#/components/parameters/TweetFilterMediaType'
        - $ref: '#/components/parameters/TweetFilterMinFaves'
        - $ref: '#/components/parameters/TweetFilterMinRetweets'
        - $ref: '#/components/parameters/TweetFilterMinReplies'
        - $ref: '#/components/parameters/TweetFilterMinQuotes'
        - $ref: '#/components/parameters/TweetFilterVerifiedOnly'
        - $ref: '#/components/parameters/TweetFilterReplies'
        - $ref: '#/components/parameters/TweetFilterRetweets'
        - $ref: '#/components/parameters/TweetFilterQuotes'
        - $ref: '#/components/parameters/TweetFilterExactPhrase'
        - $ref: '#/components/parameters/TweetFilterExcludeWords'
        - $ref: '#/components/parameters/TweetFilterAnyWords'
        - $ref: '#/components/parameters/TweetFilterHashtags'
        - $ref: '#/components/parameters/TweetFilterCashtags'
        - $ref: '#/components/parameters/TweetFilterUrl'
        - $ref: '#/components/parameters/TweetFilterConversationId'
        - $ref: '#/components/parameters/TweetFilterInReplyToTweetId'
        - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId'
        - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId'
      responses:
        '200':
          description: User timeline with replies
          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'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/users/{id}/likes:
    get:
      operationId: getUserLikes
      summary: List tweets liked by a user
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: User ID or username
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for liked tweets
        - $ref: '#/components/parameters/ResultPageSize'
        - $ref: '#/components/parameters/TweetFilterFromUser'
        - $ref: '#/components/parameters/TweetFilterToUser'
        - $ref: '#/components/parameters/TweetFilterMentioning'
        - $ref: '#/components/parameters/TweetFilterLanguage'
        - $ref: '#/components/parameters/TweetFilterSinceDate'
        - $ref: '#/components/parameters/TweetFilterUntilDate'
        - $ref: '#/components/parameters/TweetFilterMediaType'
        - $ref: '#/components/parameters/TweetFilterMinFaves'
        - $ref: '#/components/parameters/TweetFilterMinRetweets'
        - $ref: '#/components/parameters/TweetFilterMinReplies'
        - $ref: '#/components/parameters/TweetFilterMinQuotes'
        - $ref: '#/components/parameters/TweetFilterVerifiedOnly'
        - $ref: '#/components/parameters/TweetFilterReplies'
        - $ref: '#/components/parameters/TweetFilterRetweets'
        - $ref: '#/components/parameters/TweetFilterQuotes'
        - $ref: '#/components/parameters/TweetFilterExactPhrase'
        - $ref: '#/components/parameters/TweetFilterExcludeWords'
        - $ref: '#/components/parameters/TweetFilterAnyWords'
        - $ref: '#/components/parameters/TweetFilterHashtags'
        - $ref: '#/components/parameters/TweetFilterCashtags'
        - $ref: '#/components/parameters/TweetFilterUrl'
        - $ref: '#/components/parameters/TweetFilterConversationId'
        - $ref: '#/components/parameters/TweetFilterInReplyToTweetId'
        - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId'
        - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId'
      responses:
        '200':
          description: List of liked 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'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/users/{id}/media:
    get:
      operationId: getUserMedia
      summary: List media tweets posted by a user
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: User ID or username for media lookup
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for media tweets
        - $ref: '#/components/parameters/ResultPageSize'
        - $ref: '#/components/parameters/TweetFilterFromUser'
        - $ref: '#/components/parameters/TweetFilterToUser'
        - $ref: '#/components/parameters/TweetFilterMentioning'
        - $ref: '#/components/parameters/TweetFilterLanguage'
        - $ref: '#/components/parameters/TweetFilterSinceDate'
        - $ref: '#/components/parameters/TweetFilterUntilDate'
        - $ref: '#/components/parameters/TweetFilterMediaType'
        - $ref: '#/components/parameters/TweetFilterMinFaves'
        - $ref: '#/components/parameters/TweetFilterMinRetweets'
        - $ref: '#/components/parameters/TweetFilterMinReplies'
        - $ref: '#/components/parameters/TweetFilterMinQuotes'
        - $ref: '#/components/parameters/TweetFilterVerifiedOnly'
        - $ref: '#/components/parameters/TweetFilterReplies'
        - $ref: '#/components/parameters/TweetFilterRetweets'
        - $ref: '#/components/parameters/TweetFilterQuotes'
        - $ref: '#/components/parameters/TweetFilterExactPhrase'
        - $ref: '#/components/parameters/TweetFilterExcludeWords'
        - $ref: '#/components/parameters/TweetFilterAnyWords'
        - $ref: '#/components/parameters/TweetFilterHashtags'
        - $ref: '#/components/parameters/TweetFilterCashtags'
        - $ref: '#/components/parameters/TweetFilterUrl'
        - $ref: '#/components/parameters/TweetFilterConversationId'
        - $ref: '#/components/parameters/TweetFilterInReplyToTweetId'
        - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId'
        - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId'
      responses:
        '200':
          description: List of media 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'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/users/{id}/followers-you-know:
    get:
      operationId: getFollowersYouKnow
      summary: List mutual followers between you and a user
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: User ID for followers-you-know lookup
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for followers-you-know
        - $ref: '#/components/parameters/FollowerPageSize'
      responses:
        '200':
          description: List of mutual followers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/bookmarks:
    get:
      operationId: getBookmarks
      summary: Get bookmarked tweets
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: folderId
          in: query
          schema:
            type: string
          description: Optional bookmark folder ID
        - name: cursor
          in: query
          schema:
            type: string
            example: 'DAACCgACGRElMJcAAA'
          description: Pagination cursor for bookmarks
      responses:
        '200':
          description: List of bookmarked tweets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/bookmarks/folders:
    get:
      operationId: getBookmarkFolders
      summary: Get bookmark folders
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
      responses:
        '200':
          description: List of bookmark folders
          content:
            application/json:
              schema:
                type: object
                required: [folders, has_next_page, next_cursor]
                properties:
                  folders:
                    type: array
                    items:
                      type: object
                      required: [id, name]
                      properties:
                        id:
                          type: string
                          example: '1234567890'
                        name:
                          type: string
                          example: 'Read Later'
                    example:
                      - id: '1234567890'
                        name: 'Read Later'
                  has_next_page:
                    type: boolean
                    description:
                      Always false for the current bookmark folder route
                    example: false
                  next_cursor:
                    type: string
                    description:
                      Always empty for the current bookmark folder route
                    example: ''
              example:
                folders:
                  - id: '1234567890'
                    name: 'Read Later'
                has_next_page: false
                next_cursor: ''
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/notifications:
    get:
      operationId: getNotifications
      summary: Get notifications
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum: [All, Verified, Mentions]
            default: All
          description:
            Notification type filter. Unrecognized values fall back to All.
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for notifications
      responses:
        '200':
          description: List of notifications
          content:
            application/json:
              schema:
                type: object
                required: [notifications, has_next_page, next_cursor]
                properties:
                  notifications:
                    type: array
                    items:
                      type: object
                      required: [id]
                      properties:
                        id:
                          type: string
                          example: '1234567890'
                        type:
                          type: string
                          example: 'like'
                        message:
                          type: string
                          example: 'elonmusk liked your tweet'
                        timestamp:
                          type: string
                          example: '2025-01-15T12:00:00Z'
                    example:
                      - id: '1234567890'
                        type: 'like'
                        message: 'elonmusk liked your tweet'
                        timestamp: '2025-01-15T12:00:00Z'
                  has_next_page:
                    type: boolean
                    example: true
                  next_cursor:
                    type: string
                    example: 'DAACCgACGRElMJcAAA'
              example:
                notifications:
                  - id: '1234567890'
                    type: 'like'
                    message: 'elonmusk liked your tweet'
                    timestamp: '2025-01-15T12:00:00Z'
                has_next_page: true
                next_cursor: 'DAACCgACGRElMJcAAA'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/timeline:
    get:
      operationId: getTimeline
      summary: Get home timeline
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: seenTweetIds
          in: query
          schema:
            type: string
          description:
            Comma-separated tweet IDs to exclude from results. Empty entries are
            ignored.
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for timeline
      responses:
        '200':
          description: List of timeline tweets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/dm/{userId}/history:
    get:
      operationId: getDmHistory
      summary: Get DM conversation history
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: Target user ID
        - name: account
          in: query
          required: true
          schema:
            type: string
          description: >
            X handle (without the `@` prefix) of the connected X account used to
            read the conversation. The account must be a participant in the
            conversation.
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for DM history
        - name: maxId
          in: query
          schema:
            type: string
          description: Legacy pagination cursor (backward compat)
      responses:
        '200':
          description: List of DM messages
          content:
            application/json:
              schema:
                type: object
                required: [messages, has_next_page, next_cursor]
                properties:
                  messages:
                    type: array
                    items:
                      type: object
                      required: [id, senderId, receiverId]
                      properties:
                        id:
                          type: string
                          example: '1234567890123456789'
                        text:
                          type: string
                          example: 'Hey, how are you?'
                        senderId:
                          type: string
                          example: '9876543210'
                        receiverId:
                          type: string
                          example: '1234567890'
                        createdAt:
                          type: string
                          example: '2025-01-15T12:00:00Z'
                        mediaUrl:
                          type: string
                          example: 'https://pbs.twimg.com/dm_media/abc.jpg'
                          description: >
                            URL of attached media (image, GIF, or video).
                            Omitted when the message has no media attachment.
                    example:
                      - id: '1234567890123456789'
                        text: 'Hey, how are you?'
                        senderId: '9876543210'
                        receiverId: '1234567890'
                  has_next_page:
                    type: boolean
                    example: true
                  next_cursor:
                    type: string
                    example: 'DAACCgACGRElMJcAAA'
              example:
                messages:
                  - id: '1234567890123456789'
                    text: 'Hey, how are you?'
                    senderId: '9876543210'
                    receiverId: '1234567890'
                has_next_page: true
                next_cursor: 'DAACCgACGRElMJcAAA'
        '400':
          description: >
            Invalid input. Either `invalid_user_id` (path user ID is empty or
            invalid) or `account_required` (the `account` query parameter was
            missing or empty).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalidUserId:
                  summary: Invalid user ID
                  value:
                    error: invalid_user_id
                accountRequired:
                  summary: Account query parameter missing
                  value:
                    error: account_required
                    message: >-
                      Provide ?account=<x_handle> for a connected X account. DM
                      history requires a connected participant account.
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          description: >
            DM read forbidden. Either the connected account is not a participant
            in this conversation (`dm_not_permitted`), the account is suspended,
            locked, or otherwise restricted (`account_restricted`), or the
            account session needs to be re-authenticated
            (`account_needs_reauth`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                dmNotPermitted:
                  summary: Account is not a conversation participant
                  value:
                    error: dm_not_permitted
                    message: >-
                      X rejected the DM read. The connected account is not a
                      participant in this conversation, or it needs
                      reauthentication. Reconnect the account on the dashboard
                      and try again.
                accountRestricted:
                  summary: Connected account is restricted
                  value:
                    error: account_restricted
                accountNeedsReauth:
                  summary: Connected account needs reauthentication
                  value:
                    error: account_needs_reauth
        '404':
          description: Connected X account not found for the authenticated user.
          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.
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'

  /x/communities/{id}/info:
    get:
      operationId: getCommunityInfo
      summary: Get community name, description and member count
      tags:
        - Communities
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        offers:
          - amount: '150'
            currency: '0x20c000000000000000000000b9537d11c60e8b50'
            intent: charge
            method: tempo
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Community ID
      responses:
        '200':
          description: Community details
          content:
            application/json:
              schema:
                type: object
                required: [community]
                properties:
                  community:
                    type: object
                    description: Community info object
                    example:
                      id: '1500000000000000000'
                      name: 'Tesla Fans'
                    properties:
                      id:
                        type: string
                        description: Unique community identifier
                      name:
                        type: string
                        description: Display name of the community
                      description:
                        type: string
                        description: About text for the community
                      banner_url:
                        type: string
                        description: Community banner image URL
                      created_at:
                        type: string
                        description: Community creation timestamp
                      join_policy:
                        type: string
                        description: Join policy (open or restricted)
                      invites_policy:
                        type: string
                        description: Invitation policy
                      is_member:
                        type: boolean
                        description:
                          Whether the authenticated viewer is a member
                      is_nsfw:
                        type: boolean
                        description: Whether the community is marked sensitive
                      role:
                        type: string
                        description: Authenticated viewer's community role
                      creator:
                        type: object
                        required: [id, username, verified]
                        properties:
                          id:
                            type: string
                          username:
                            type: string
                          verified:
                            type: boolean
                          name:
                            type: string
                      member_count:
                        type: integer
                        description: Total member count
                      moderator_count:
                        type: integer
                        description: Total moderator count
                      primary_topic:
                        type: object
                        description: Primary topic
                        properties:
                          id:
                            type: string
                          name:
                            type: string
                      rules:
                        type: array
                        description: Community rules
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            description:
                              type: string
                    required: [id]
              example:
                community:
                  id: '1500000000000000000'
                  name: 'Tesla Fans'
                  description: 'A community for Tesla enthusiasts'
                  banner_url: 'https://xquik.com/example'
                  created_at: '2025-01-15T12:00:00Z'
                  join_policy: 'open'
                  member_count: 10000
                  moderator_count: 5
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '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'

  /x/communities/{id}/members:
    get:
      operationId: getCommunityMembers
      summary: List members of a community
      tags:
        - Communities
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Community ID for member lookup
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor
        - name: pageSize
          in: query
          schema:
            type: integer
            minimum: 20
            maximum: 200
            default: 20
          description: >
            Items per page (20-200, default 20). This is an upper bound for paid
            authenticated calls: remaining credits can reduce the returned page
            size, and zero affordable results returns 402 insufficient_credits.
      responses:
        '200':
          description: List of community 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'

  /x/communities/{id}/moderators:
    get:
      operationId: getCommunityModerators
      summary: List moderators of a community
      tags:
        - Communities
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Community ID for moderator lookup
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for community moderators
      responses:
        '200':
          description: List of community moderators
          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'

  /x/communities/{id}/tweets:
    get:
      operationId: getCommunityTweets
      summary: List tweets posted in a community
      tags:
        - Communities
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Community ID for tweet lookup
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for community tweets
        - $ref: '#/components/parameters/ResultPageSize'
      responses:
        '200':
          description: List of community 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'

  /x/communities/search:
    get:
      operationId: searchCommunities
      summary: Search tweets within an X Community by keyword
      description:
        Returns tweets, not community records. Requires a Community ID.
      tags:
        - Communities
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: communityId
          in: query
          required: true
          schema:
            type: string
            pattern: '^\d+$'
          description: Numeric ID of the community whose posts to search
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Search query
        - name: queryType
          in: query
          schema:
            type: string
            enum: [Latest, Top]
            default: Latest
          description: Sort order (Latest or Top)
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for community search
        - $ref: '#/components/parameters/ResultPageSize'
      responses:
        '200':
          description: Tweet search results from the selected X Community
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'

  /x/communities/tweets:
    get:
      operationId: getAllCommunityTweets
      summary: Search tweets within an X Community
      description: Requires a Community ID and keyword query.
      tags:
        - Communities
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: communityId
          in: query
          required: true
          schema:
            type: string
            pattern: '^\d+$'
          description: Numeric ID of the community to search
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Keyword query within the selected community
        - name: queryType
          in: query
          schema:
            type: string
            enum: [Latest, Top]
            default: Latest
          description: Sort order for community results (Latest or Top)
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for community results
        - $ref: '#/components/parameters/ResultPageSize'
      responses:
        '200':
          description: Paginated matching tweets from the selected community
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'

  /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'
      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'

  /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)
      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'

  /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'

  /x/tweets/{id}/quotes:
    get:
      operationId: getTweetQuotes
      summary: List quote tweets of a tweet
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Numeric tweet ID to get quotes, 15-20 digits
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for quote tweets
        - $ref: '#/components/parameters/ResultPageSize'
        - name: sinceTime
          in: query
          schema:
            type: string
          description: Unix timestamp - return quotes posted after this time
        - name: untilTime
          in: query
          schema:
            type: string
          description: Unix timestamp - return quotes posted before this time
        - name: includeReplies
          in: query
          schema:
            type: boolean
          description: Include reply quotes (default false)
        - $ref: '#/components/parameters/TweetFilterFromUser'
        - $ref: '#/components/parameters/TweetFilterToUser'
        - $ref: '#/components/parameters/TweetFilterMentioning'
        - $ref: '#/components/parameters/TweetFilterLanguage'
        - $ref: '#/components/parameters/TweetFilterSinceDate'
        - $ref: '#/components/parameters/TweetFilterUntilDate'
        - $ref: '#/components/parameters/TweetFilterMediaType'
        - $ref: '#/components/parameters/TweetFilterMinFaves'
        - $ref: '#/components/parameters/TweetFilterMinRetweets'
        - $ref: '#/components/parameters/TweetFilterMinReplies'
        - $ref: '#/components/parameters/TweetFilterMinQuotes'
        - $ref: '#/components/parameters/TweetFilterVerifiedOnly'
        - $ref: '#/components/parameters/TweetFilterReplies'
        - $ref: '#/components/parameters/TweetFilterRetweets'
        - $ref: '#/components/parameters/TweetFilterQuotes'
        - $ref: '#/components/parameters/TweetFilterExactPhrase'
        - $ref: '#/components/parameters/TweetFilterExcludeWords'
        - $ref: '#/components/parameters/TweetFilterAnyWords'
        - $ref: '#/components/parameters/TweetFilterHashtags'
        - $ref: '#/components/parameters/TweetFilterCashtags'
        - $ref: '#/components/parameters/TweetFilterUrl'
        - $ref: '#/components/parameters/TweetFilterConversationId'
        - $ref: '#/components/parameters/TweetFilterInReplyToTweetId'
        - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId'
        - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId'
      responses:
        '200':
          description: List of quote tweets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/tweets/{id}/replies:
    get:
      operationId: getTweetReplies
      summary: List replies to a tweet
      description: >
        Returns visible replies. For an unfiltered first page, Xquik compares a
        terminal page with the post's reported reply count. If the page is
        visibly incomplete, the endpoint returns 424 `replies_incomplete`
        instead of presenting partial coverage as complete. Use tweet search
        with a `conversation_id:{id}` query as the broader fallback.
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Tweet ID to get replies
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for tweet replies
        - $ref: '#/components/parameters/ResultPageSize'
        - name: sinceTime
          in: query
          schema:
            type: string
          description: Unix timestamp - return replies posted after this time
        - name: untilTime
          in: query
          schema:
            type: string
          description: Unix timestamp - return replies posted before this time
        - $ref: '#/components/parameters/TweetFilterFromUser'
        - $ref: '#/components/parameters/TweetFilterToUser'
        - $ref: '#/components/parameters/TweetFilterMentioning'
        - $ref: '#/components/parameters/TweetFilterLanguage'
        - $ref: '#/components/parameters/TweetFilterSinceDate'
        - $ref: '#/components/parameters/TweetFilterUntilDate'
        - $ref: '#/components/parameters/TweetFilterMediaType'
        - $ref: '#/components/parameters/TweetFilterMinFaves'
        - $ref: '#/components/parameters/TweetFilterMinRetweets'
        - $ref: '#/components/parameters/TweetFilterMinReplies'
        - $ref: '#/components/parameters/TweetFilterMinQuotes'
        - $ref: '#/components/parameters/TweetFilterVerifiedOnly'
        - $ref: '#/components/parameters/TweetFilterReplies'
        - $ref: '#/components/parameters/TweetFilterRetweets'
        - $ref: '#/components/parameters/TweetFilterQuotes'
        - $ref: '#/components/parameters/TweetFilterExactPhrase'
        - $ref: '#/components/parameters/TweetFilterExcludeWords'
        - $ref: '#/components/parameters/TweetFilterAnyWords'
        - $ref: '#/components/parameters/TweetFilterHashtags'
        - $ref: '#/components/parameters/TweetFilterCashtags'
        - $ref: '#/components/parameters/TweetFilterUrl'
        - $ref: '#/components/parameters/TweetFilterConversationId'
        - $ref: '#/components/parameters/TweetFilterInReplyToTweetId'
        - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId'
        - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId'
      responses:
        '200':
          description: List of replies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/RepliesIncomplete'

  /x/tweets/{id}/retweeters:
    get:
      operationId: getTweetRetweeters
      summary: List users who retweeted a tweet
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Tweet ID to get retweeters
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for retweeters
        - $ref: '#/components/parameters/FollowerPageSize'
      responses:
        '200':
          description: List of retweeters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/tweets/{id}/thread:
    get:
      operationId: getTweetThread
      summary: Get full conversation thread for a tweet
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Tweet ID to get thread context
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for thread tweets
        - $ref: '#/components/parameters/ResultPageSize'
      responses:
        '200':
          description: Thread tweets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/users/{id}/followers:
    get:
      operationId: getUserFollowers
      summary: List followers of a user
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: User ID or username
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for followers list
        - name: after
          in: query
          deprecated: true
          schema:
            type: string
          description: Legacy cursor alias. Prefer cursor.
        - $ref: '#/components/parameters/FollowerPageSize'
        - name: limit
          in: query
          deprecated: true
          schema:
            type: integer
          description:
            Legacy integer page size alias for following lists. Prefer pageSize.
      responses:
        '200':
          description: List of user 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'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/users/{id}/following:
    get:
      operationId: getUserFollowing
      summary: List accounts a user follows
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: User ID or username for following lookup
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for following list
        - name: after
          in: query
          deprecated: true
          schema:
            type: string
          description: Legacy cursor alias. Prefer cursor.
        - $ref: '#/components/parameters/FollowerPageSize'
        - name: limit
          in: query
          deprecated: true
          schema:
            type: integer
          description: Legacy page size alias. Prefer pageSize.
      responses:
        '200':
          description: List of following
          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'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/users/{id}/mentions:
    get:
      operationId: getUserMentions
      summary: List tweets mentioning a user
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: User ID or username for mentions lookup
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for mentions
        - $ref: '#/components/parameters/ResultPageSize'
        - name: sinceTime
          in: query
          schema:
            type: string
          description: Unix timestamp - return mentions after this time
        - name: untilTime
          in: query
          schema:
            type: string
          description: Unix timestamp - return mentions before this time
        - $ref: '#/components/parameters/TweetFilterFromUser'
        - $ref: '#/components/parameters/TweetFilterToUser'
        - $ref: '#/components/parameters/TweetFilterMentioning'
        - $ref: '#/components/parameters/TweetFilterLanguage'
        - $ref: '#/components/parameters/TweetFilterSinceDate'
        - $ref: '#/components/parameters/TweetFilterUntilDate'
        - $ref: '#/components/parameters/TweetFilterMediaType'
        - $ref: '#/components/parameters/TweetFilterMinFaves'
        - $ref: '#/components/parameters/TweetFilterMinRetweets'
        - $ref: '#/components/parameters/TweetFilterMinReplies'
        - $ref: '#/components/parameters/TweetFilterMinQuotes'
        - $ref: '#/components/parameters/TweetFilterVerifiedOnly'
        - $ref: '#/components/parameters/TweetFilterReplies'
        - $ref: '#/components/parameters/TweetFilterRetweets'
        - $ref: '#/components/parameters/TweetFilterQuotes'
        - $ref: '#/components/parameters/TweetFilterExactPhrase'
        - $ref: '#/components/parameters/TweetFilterExcludeWords'
        - $ref: '#/components/parameters/TweetFilterAnyWords'
        - $ref: '#/components/parameters/TweetFilterHashtags'
        - $ref: '#/components/parameters/TweetFilterCashtags'
        - $ref: '#/components/parameters/TweetFilterUrl'
        - $ref: '#/components/parameters/TweetFilterConversationId'
        - $ref: '#/components/parameters/TweetFilterInReplyToTweetId'
        - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId'
        - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId'
      responses:
        '200':
          description: List of mentions
          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'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

  /x/users/{id}/verified-followers:
    get:
      operationId: getUserVerifiedFollowers
      summary: List verified followers of a user
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: User ID or username for verified followers
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for verified followers
        - $ref: '#/components/parameters/FollowerPageSize'
      responses:
        '200':
          description: List of verified 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'
        '502':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '424':
          $ref: '#/components/responses/XApiError'

components:
  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.

  parameters:
    GuestIdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: >
        Generate a cryptographically random UUID v4. Reuse it only to retry the
        same wallet and amount request. Initial wallet creation can recover the
        API key from this value, so store it as a secret and never log it.
      schema:
        type: string
        minLength: 36
        maxLength: 36
        pattern: '^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$'
    ResourceId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Resource ID returned by the matching create or list endpoint.
    DrawId:
      name: id
      in: path
      required: true
      schema:
        type: string
        example: 'f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345'
      description: Draw public ID returned by create and list draw responses.
    Limit:
      name: limit
      in: query
      description: >
        Maximum number of items to return (1-100, default 50). For paid
        per-result endpoints, the returned count may be lower when remaining
        credits cannot cover the requested page. If zero paid results are
        affordable, the endpoint returns 402 insufficient_credits.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    ResultPageSize:
      name: pageSize
      in: query
      description: >
        Maximum items requested from this page (1-100, default 20). The response
        can contain fewer items because the source returned fewer, filters
        removed items, or remaining credits cover fewer results. Keep requesting
        next_cursor while has_next_page is true, even when a page is empty. The
        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).
        The response can contain fewer profiles because the source returned
        fewer or remaining credits cover fewer results. Keep requesting
        next_cursor while has_next_page is true. The deprecated limit and count
        aliases remain accepted.
      schema:
        type: integer
        minimum: 20
        maximum: 200
        default: 200
    After:
      name: cursor
      in: query
      schema:
        type: string
      description: Cursor for keyset pagination from prior response next_cursor
    StyleId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Style profile ID or X username
    TweetFilterFromUser:
      name: fromUser
      in: query
      schema:
        type: string
      description: Filter by author username.
    TweetFilterToUser:
      name: toUser
      in: query
      schema:
        type: string
      description: Filter replies sent to a username.
    TweetFilterMentioning:
      name: mentioning
      in: query
      schema:
        type: string
      description: Filter tweets mentioning a username.
    TweetFilterLanguage:
      name: language
      in: query
      schema:
        type: string
      description: Language code filter, e.g. en or tr.
    TweetFilterSinceDate:
      name: sinceDate
      in: query
      schema:
        type: string
        format: date
      description: Start date in YYYY-MM-DD format.
    TweetFilterUntilDate:
      name: untilDate
      in: query
      schema:
        type: string
        format: date
      description: End date in YYYY-MM-DD format.
    TweetFilterMediaType:
      name: mediaType
      in: query
      schema:
        type: string
        enum: [images, videos, gifs, media, links, none]
      description: Filter by media type.
    TweetFilterMinFaves:
      name: minFaves
      in: query
      schema:
        type: integer
        minimum: 0
      description: Minimum likes threshold.
    TweetFilterMinRetweets:
      name: minRetweets
      in: query
      schema:
        type: integer
        minimum: 0
      description: Minimum retweets threshold.
    TweetFilterMinReplies:
      name: minReplies
      in: query
      schema:
        type: integer
        minimum: 0
      description: Minimum replies threshold.
    TweetFilterMinQuotes:
      name: minQuotes
      in: query
      schema:
        type: integer
        minimum: 0
      description: Minimum quote count threshold.
    TweetFilterVerifiedOnly:
      name: verifiedOnly
      in: query
      schema:
        type: boolean
      description: Only return tweets from verified authors.
    TweetFilterReplies:
      name: replies
      in: query
      schema:
        type: string
        enum: [include, exclude, only]
      description: Reply mode.
    TweetFilterRetweets:
      name: retweets
      in: query
      schema:
        type: string
        enum: [include, exclude, only]
      description: Retweet mode.
    TweetFilterQuotes:
      name: quotes
      in: query
      schema:
        type: string
        enum: [include, exclude, only]
      description: Quote mode.
    TweetFilterExactPhrase:
      name: exactPhrase
      in: query
      schema:
        type: string
      description: Exact phrase to match.
    TweetFilterExcludeWords:
      name: excludeWords
      in: query
      schema:
        type: string
      description:
        Words or quoted phrases to exclude. Separate with spaces, commas, or
        lines.
    TweetFilterAnyWords:
      name: anyWords
      in: query
      schema:
        type: string
      description:
        Words or quoted phrases where any one can match. Separate with spaces,
        commas, or lines.
    TweetFilterHashtags:
      name: hashtags
      in: query
      schema:
        type: string
      description: Hashtags separated by spaces, commas, or lines.
    TweetFilterCashtags:
      name: cashtags
      in: query
      schema:
        type: string
      description: Cashtags separated by spaces, commas, or lines.
    TweetFilterUrl:
      name: url
      in: query
      schema:
        type: string
      description: URL substring or domain filter.
    TweetFilterConversationId:
      name: conversationId
      in: query
      schema:
        type: string
      description: Conversation ID filter.
    TweetFilterInReplyToTweetId:
      name: inReplyToTweetId
      in: query
      schema:
        type: string
      description: Only replies to this tweet ID.
    TweetFilterQuotesOfTweetId:
      name: quotesOfTweetId
      in: query
      schema:
        type: string
      description: Only quotes of this tweet ID.
    TweetFilterRetweetsOfTweetId:
      name: retweetsOfTweetId
      in: query
      schema:
        type: string
      description: Only retweets of this tweet ID.
    TweetSearchListId:
      name: listId
      in: query
      schema:
        type: string
      description: Search within a list ID.
    TweetSearchPlace:
      name: place
      in: query
      schema:
        type: string
      description: Search within a place ID.
    TweetSearchPlaceCountry:
      name: placeCountry
      in: query
      schema:
        type: string
      description: Search within a country code.
    TweetSearchPointRadius:
      name: pointRadius
      in: query
      schema:
        type: string
      description: Geo point radius, e.g. -73.99 40.73 25mi.
    TweetSearchBoundingBox:
      name: boundingBox
      in: query
      schema:
        type: string
      description: Geo bounding box, e.g. -74.1 40.6 -73.9 40.8.
    TweetSearchAdvancedQuery:
      name: advancedQuery
      in: query
      schema:
        type: string
      description: Raw advanced search query appended as-is.

  responses:
    Success:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required: [success]
            properties:
              success:
                type: boolean
                const: true
                example: true
          example:
            success: true
    NoContent:
      description: Deleted
    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.'
    AnonymousGuestAuthenticationRequired:
      description: >
        Authentication required for a non-MPP paid read. The Bearer challenge
        requests authentication and is not a Payment challenge. Requests without
        credentials advertise accountless Stripe checkout, but create no
        checkout. Explicit invalid credentials return the plain error shape.
        Call an advertised action only after explicit user confirmation.
      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
    InvalidInput:
      description: Invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'invalid_input'
            message: 'Invalid input. Check the request body.'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'not_found'
            message: 'Resource not found.'
    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/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
    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.'
    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.'
    WriteError:
      description: >
        Write operation failed. Possible error codes include x_write_failed,
        x_write_ambiguous, x_duplicate_action, x_daily_limit (429 - account
        reached daily posting limit, wait 24 hours), and x_write_unconfirmed
        (202 - action may have completed but could not be confirmed, verify
        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.'
    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.'
    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.'
    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.'
    TransientError:
      description: >
        A transient upstream issue occurred. Safe to retry with exponential
        backoff. Returns error code `x_transient_error`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'x_transient_error'
            message: 'X is temporarily unavailable. Retry after a short delay.'
    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.'
    FavoritersUnavailable:
      description: >
        X reports likes for the post but does not expose the corresponding user
        identities. Returns error code `favoriters_unavailable`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'favoriters_unavailable'
            message:
              'Users who liked this post are unavailable. Use retweeters or
              replies instead.'
    RepliesIncomplete:
      description: >
        The direct replies page ended before the post's reported reply count.
        Returns error code `replies_incomplete` so verification workflows do not
        treat partial coverage as exhaustive.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'replies_incomplete'
            message:
              'Replies are incomplete. Use tweet search with a conversation_id
              filter.'
    ConnectAlreadyConnected:
      description: >
        The specified X account is already connected to this Xquik account.
        Returns error code `account_already_connected`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'account_already_connected'
            message: 'This X account is already connected.'
    ConnectLoginFailed:
      description: >
        Could not authenticate with X. The provided credentials (username,
        password, or TOTP secret) were rejected. Returns error code
        `login_failed`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'login_failed'
            message: 'Login failed. Check credentials and try again.'
    ConnectLoginCooldown:
      description: >
        A prior login attempt triggered a cooldown. Response includes `reason`,
        `retryAfterMs`, and a `Retry-After` header in seconds. Returns error
        code `login_cooldown`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'login_cooldown'
            message: 'Login is temporarily paused'
    ConnectRateLimitExceeded:
      description: >
        Too many requests. Either the generous connection safety limit was
        exceeded (`rate_limit_exceeded`, `retryAfter` seconds, `Retry-After:
        900` header) or a prior login attempt triggered a cooldown
        (`login_cooldown`, `reason`, `retryAfterMs`, `Retry-After` header in
        seconds).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'rate_limit_exceeded'
            message: 'Too many requests. Retry later.'
    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
    ConnectUserLookupFailed:
      description: >
        The X username could not be resolved. Verify the handle is correct and
        the account exists. Default v1 returns 502. The best-practice response
        contract returns 424. Error code: `x_user_lookup_failed`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'x_user_lookup_failed'
            message: 'X username lookup failed. Try again later.'
    ConnectServiceUnavailable:
      description: >
        The X connection service is temporarily unavailable. Retry after a short
        delay. Returns error code `service_unavailable`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'service_unavailable'
            message: 'Service temporarily unavailable. Try again later.'
    ReauthAccountNotFound:
      description: >
        No X account with this ID belongs to the authenticated user. Returns
        error code `account_not_found`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'account_not_found'
            message: 'X account not found.'

  schemas:
    PaginatedTweets:
      description: >
        Paginated tweet results. The item count can be lower than pageSize when
        the source returns fewer tweets, filters remove tweets, or remaining
        credits cover fewer results. Follow next_cursor while has_next_page is
        true. An empty page can still have has_next_page true after filtering.
        Zero affordable results returns 402 insufficient_credits.
      type: object
      required: [tweets, has_next_page, next_cursor]
      properties:
        tweets:
          type: array
          items:
            $ref: '#/components/schemas/SearchTweet'
          example:
            - id: '1234567890'
              text: 'Just launched our new feature!'
              retweetCount: 5
              replyCount: 3
              likeCount: 42
              quoteCount: 1
              viewCount: 1500
              bookmarkCount: 2
        has_next_page:
          type: boolean
          example: true
        next_cursor:
          type: string
          example: 'DAACCgACGRElMJcAAA'
    PaginatedUsers:
      description: >
        Paginated user profiles. The item count can be lower than pageSize when
        the source returns fewer profiles or remaining credits cover fewer
        results. Follow next_cursor while has_next_page is true. A relationship
        can naturally contain fewer profiles than requested. Zero affordable
        results returns 402 insufficient_credits.
      type: object
      required: [users, has_next_page, next_cursor]
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserProfile'
          example:
            - id: '9876543210'
              username: 'elonmusk'
              name: 'Elon Musk'
        has_next_page:
          type: boolean
          example: true
        next_cursor:
          type: string
          example: 'DAACCgACGRElMJcAAA'
    BatchUsers:
      description: >
        Batch user lookup results. Duplicate requested IDs are ignored while
        preserving first-seen order. unavailable_ids identifies processed IDs
        with no returned profile. unprocessed_ids identifies IDs skipped when
        available credits limit processing.
      type: object
      required:
        [
          users,
          has_next_page,
          next_cursor,
          requested_count,
          processed_count,
          returned_count,
          unavailable_ids,
          unprocessed_ids,
        ]
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserProfile'
        has_next_page:
          type: boolean
          const: false
          description: Batch lookups never paginate.
        next_cursor:
          type: string
          description: Empty because batch lookups never paginate.
          maxLength: 0
          example: ''
        requested_count:
          type: integer
          minimum: 0
          maximum: 100
          description: Number of unique IDs requested.
        processed_count:
          type: integer
          minimum: 0
          maximum: 100
          description: Number of requested IDs included in the lookup.
        returned_count:
          type: integer
          minimum: 0
          maximum: 100
          description: Number of user profiles returned and charged.
        unavailable_ids:
          type: array
          description:
            Processed IDs with no returned profile, in first-seen request order.
          items:
            type: string
            pattern: '^\d+$'
        unprocessed_ids:
          type: array
          description:
            Requested IDs skipped because available credits limited processing.
            Retry these IDs after adding credits.
          items:
            type: string
            pattern: '^\d+$'
    GuestWalletAmount:
      description: Confirmed USD amount for a guest wallet purchase.
      type: object
      additionalProperties: false
      required: [amount_minor, currency]
      properties:
        amount_minor:
          type: integer
          minimum: 1000
          maximum: 25000
          description: USD amount in cents. Accepted range is $10-$250.
          example: 1000
        currency:
          type: string
          const: usd
    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
    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: Confirmed USD amount in cents.
          example: 1000
        currency:
          type: string
          const: usd
    GuestWalletCheckoutResponse:
      description: Pending Stripe checkout and guest wallet purchase details.
      type: object
      additionalProperties: false
      required:
        - account_required
        - amount
        - checkout_url
        - credits
        - expires_at
        - instructions
        - poll_after_seconds
        - purchase_id
        - requires_user_interaction
        - status
        - status_url
        - wallet_id
      properties:
        account_required:
          type: boolean
          const: false
        amount:
          $ref: '#/components/schemas/GuestWalletAmount'
        api_key:
          type: string
          format: password
          description: >
            Paid-read bearer credential returned only by initial creation. Store
            it as a secret. Never place it in a URL or log.
          example: xq_example_returned_once
        authorization:
          type: object
          additionalProperties: false
          required: [header, scheme]
          properties:
            header:
              type: string
              enum: [Authorization]
              example: Authorization
            scheme:
              type: string
              enum: [Bearer]
              example: Bearer
        checkout_url:
          type: string
          format: uri
          pattern: '^https://buy\.stripe\.com/'
          description: Raw Stripe-hosted checkout URL for user interaction.
          example: https://buy.stripe.com/example
        credits:
          type: string
          pattern: '^\d+$'
          description: Credits granted after verified payment.
          example: '66666'
        credential_notice:
          type: string
          const:
            Store api_key and the Idempotency-Key securely before sharing
            checkout_url. No email recovery is available.
        expires_at:
          type: string
          format: date-time
          description: Time when the pending checkout expires.
          example: '2026-07-13T13:00:00.000Z'
        instructions:
          type: string
          const:
            Give checkout_url to the user. They must complete payment on Stripe.
            Never submit payment for them. After payment, poll status_url every
            poll_after_seconds until latest_purchase.status is no longer
            pending.
        poll_after_seconds:
          type: integer
          const: 2
          description: Wait at least this long before polling status_url.
        purchase_id:
          type: string
          pattern: '^gp_[A-Za-z0-9_-]+$'
          example: gp_example
        requires_user_interaction:
          type: boolean
          const: true
        status:
          type: string
          enum: [creating, pending, paid, expired, failed, refunded, disputed]
          example: pending
        status_url:
          type: string
          format: uri
          const: https://xquik.com/api/v1/guest-wallets/status
        wallet_id:
          type: string
          pattern: '^gw_[A-Za-z0-9_-]+$'
          example: gw_example
    GuestWalletCreateResponse:
      description: Initial guest wallet response containing the one-time key.
      allOf:
        - $ref: '#/components/schemas/GuestWalletCheckoutResponse'
        - type: object
          required: [api_key, authorization, credential_notice]
    GuestWalletTopupResponse:
      description: Existing guest wallet top-up response without a new key.
      allOf:
        - $ref: '#/components/schemas/GuestWalletCheckoutResponse'
        - not:
            anyOf:
              - type: object
                properties:
                  api_key:
                    type: string
                required: [api_key]
              - type: object
                properties:
                  authorization:
                    type: object
                required: [authorization]
    GuestWalletPurchaseStatus:
      description: Latest guest wallet purchase fulfillment state.
      type: object
      additionalProperties: false
      required: [amount, checkout_url, credits, expires_at, purchase_id, status]
      properties:
        amount:
          $ref: '#/components/schemas/GuestWalletAmount'
        checkout_url:
          anyOf:
            - type: string
              format: uri
              pattern: '^https://buy\.stripe\.com/'
            - type: 'null'
          description: Present only while the purchase is pending.
          example: null
        credits:
          type: string
          pattern: '^\d+$'
          example: '66666'
        expires_at:
          type: string
          format: date-time
          example: '2026-07-13T13:00:00.000Z'
        purchase_id:
          type: string
          pattern: '^gp_[A-Za-z0-9_-]+$'
          example: gp_example
        status:
          type: string
          enum: [creating, pending, paid, expired, failed, refunded, disputed]
          example: paid
    GuestWalletStatusResponse:
      description: Current balance, usability, and latest guest purchase state.
      type: object
      additionalProperties: false
      required:
        - balance
        - latest_purchase
        - poll_after_seconds
        - scope
        - status
        - top_up
        - usable
        - wallet_id
      properties:
        balance:
          type: string
          pattern: '^\d+$'
          example: '66666'
        latest_purchase:
          description: Latest purchase state. This does not determine usability.
          anyOf:
            - $ref: '#/components/schemas/GuestWalletPurchaseStatus'
            - type: 'null'
          example:
            amount: { amount_minor: 1000, currency: usd }
            checkout_url: null
            credits: '66666'
            expires_at: '2026-07-13T13:00:00.000Z'
            purchase_id: gp_example
            status: paid
        poll_after_seconds:
          description: Polling delay while payment is pending. Null means stop.
          anyOf:
            - type: integer
              const: 2
            - type: 'null'
        scope:
          type: string
          const: paid_reads
        status:
          type: string
          description: >
            Combined wallet and pending-checkout state. A pending top-up can
            coexist with usable true. Terminal expired or failed states require
            a new guest wallet.
          enum: [active, pending, expired, failed, frozen, closed]
          example: active
        top_up:
          description: Top-up action when usable and no checkout is pending.
          anyOf:
            - type: object
              additionalProperties: false
              required: [method, path]
              properties:
                method:
                  type: string
                  const: POST
                path:
                  type: string
                  const: /api/v1/guest-wallets/topups
            - type: 'null'
        usable:
          type: boolean
          description: Authoritative paid-read readiness. Use instead of status.
          example: true
        wallet_id:
          type: string
          pattern: '^gw_[A-Za-z0-9_-]+$'
          example: gw_example
    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: <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
    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: <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
    AnonymousGuestAuthenticationRequired:
      description: >
        Authentication error for a non-MPP anonymous paid read. The response
        also advertises optional accountless Stripe 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
          example: Authentication required.
        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'
    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
    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
    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
    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
                - 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
                - x_write_unconfirmed
              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
                    - 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
                    - x_write_unconfirmed
                  example: invalid_input
    EventType:
      description: Type of monitor event fired when account activity occurs.
      type: string
      enum:
        - tweet.new
        - tweet.reply
        - tweet.retweet
        - tweet.quote
        - tweet.media
        - tweet.link
        - tweet.poll
        - tweet.mention
        - tweet.hashtag
        - tweet.longform
        - profile.avatar.changed
        - profile.banner.changed
        - profile.name.changed
        - profile.username.changed
        - profile.bio.changed
        - profile.location.changed
        - profile.url.changed
        - profile.verified.changed
        - profile.protected.changed
        - profile.pinned_tweet.changed
        - profile.unavailable.changed
      example: 'tweet.new'

    EventTypeArray:
      description: Array of event types to subscribe to.
      type: array
      items:
        $ref: '#/components/schemas/EventType'
      minItems: 1
      example: ['tweet.new', 'tweet.reply']

    ExtractionToolType:
      description: Identifier for the extraction tool used to run a job.
      type: string
      example: 'follower_explorer'
      enum:
        - article_extractor
        - community_extractor
        - community_moderator_explorer
        - community_post_extractor
        - community_search
        - favoriters
        - follower_explorer
        - following_explorer
        - list_follower_explorer
        - list_member_extractor
        - list_post_extractor
        - mention_extractor
        - people_search
        - post_extractor
        - quote_extractor
        - reply_extractor
        - repost_extractor
        - space_explorer
        - thread_extractor
        - tweet_search_extractor
        - user_likes
        - user_media
        - verified_follower_explorer

    ApiKey:
      description: API key metadata returned when listing keys.
      type: object
      required: [id, name, prefix, isActive, createdAt]
      properties:
        id:
          type: string
        name:
          type: string
        prefix:
          type: string
        isActive:
          type: boolean
        createdAt:
          type: string
          format: date-time
        lastUsedAt:
          type: string
          format: date-time

    Monitor:
      description: Account monitor that tracks activity for a given X user.
      type: object
      required:
        [id, username, xUserId, eventTypes, isActive, createdAt, nextBillingAt]
      properties:
        id:
          type: string
          example: '42'
        username:
          type: string
          example: 'elonmusk'
        xUserId:
          type: string
          example: '9876543210'
        eventTypes:
          $ref: '#/components/schemas/EventTypeArray'
          example: ['tweet.new', 'tweet.reply']
        isActive:
          type: boolean
          example: true
        createdAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'
        nextBillingAt:
          type: string
          format: date-time
          description: Next hourly credit charge time for this account monitor.
          example: '2025-01-15T12:00:00Z'

    KeywordMonitor:
      description: Keyword monitor that tracks matching public X activity.
      type: object
      required: [id, query, eventTypes, isActive, createdAt, nextBillingAt]
      properties:
        id:
          type: string
          example: '21'
        query:
          type: string
          example: 'xquik OR "x api"'
        eventTypes:
          $ref: '#/components/schemas/EventTypeArray'
          example: ['tweet.new']
        isActive:
          type: boolean
          example: true
        createdAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'
        nextBillingAt:
          type: string
          format: date-time
          description:
            Next hourly credit charge time for this keyword query monitor.
          example: '2025-01-15T12:00:00Z'

    Event:
      description:
        Monitor event summary with source metadata and occurrence time.
      type: object
      required: [id, type, monitorId, monitorType, occurredAt, data]
      properties:
        id:
          type: string
        type:
          $ref: '#/components/schemas/EventType'
        username:
          type: string
          description: Account username, present for account monitor events.
        query:
          type: string
          description: Keyword query, present for keyword monitor events.
        monitorId:
          type: string
          description:
            Account monitor ID for account events, or keyword monitor ID for
            keyword events.
        monitorType:
          type: string
          enum: [account, keyword]
          description: Source monitor type.
        keywordMonitorId:
          type: string
          description: Keyword monitor ID, present for keyword monitor events.
        occurredAt:
          type: string
          format: date-time
        data:
          type: object
          additionalProperties: true

    EventDetail:
      description:
        Full monitor event including payload data and optional X event ID.
      type: object
      required: [id, type, monitorId, monitorType, occurredAt, data]
      properties:
        id:
          type: string
          example: '42'
        type:
          $ref: '#/components/schemas/EventType'
          example: 'tweet.new'
        username:
          type: string
          description: Account username for this detailed monitor event.
          example: 'elonmusk'
        query:
          type: string
          description: Keyword query for this detailed monitor event.
          example: 'xquik OR "x api"'
        monitorId:
          type: string
          description: Monitor ID associated with this detailed event payload.
          example: '10'
        monitorType:
          type: string
          enum: [account, keyword]
          description: Source monitor type for this detailed event.
          example: account
        keywordMonitorId:
          type: string
          description: Keyword monitor ID included on detailed keyword events.
          example: '21'
        occurredAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'
        data:
          type: object
          additionalProperties: true
          x-stainless-any: true
          description: Event payload - shape varies by event type (JSON)
          x-stainless-terraform-type: string
          example:
            tweetId: '1234567890'
        xEventId:
          type: string
          example: '1234567890'

    ExtractionJob:
      description: Extraction job tracking status, tool type, and result count.
      type: object
      required: [id, toolType, status, totalResults, createdAt]
      properties:
        id:
          type: string
        toolType:
          $ref: '#/components/schemas/ExtractionToolType'
        status:
          type: string
          enum: [running, completed, failed]
        totalResults:
          type: integer
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time

    DrawListItem:
      description: Giveaway draw summary with entry counts and status.
      type: object
      required: [id, tweetUrl, status, totalEntries, validEntries, createdAt]
      properties:
        id:
          type: string
          description: Draw public ID for detail responses.
          example: 'f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345'
        tweetUrl:
          type: string
          format: uri
        status:
          type: string
        totalEntries:
          type: integer
        validEntries:
          type: integer
        createdAt:
          type: string
          format: date-time
        drawnAt:
          type: string
          format: date-time

    DrawDetail:
      description: Full giveaway draw with tweet metrics, entries, and timing.
      type: object
      required:
        - id
        - tweetUrl
        - tweetId
        - tweetText
        - tweetAuthorUsername
        - status
        - totalEntries
        - validEntries
        - tweetLikeCount
        - tweetRetweetCount
        - tweetReplyCount
        - tweetQuoteCount
        - createdAt
      properties:
        id:
          type: string
          description: Draw public ID.
          example: 'f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345'
        tweetUrl:
          type: string
          format: uri
        tweetId:
          type: string
        tweetText:
          type: string
        tweetAuthorUsername:
          type: string
        status:
          type: string
        totalEntries:
          type: integer
        validEntries:
          type: integer
        tweetLikeCount:
          type: integer
        tweetRetweetCount:
          type: integer
        tweetReplyCount:
          type: integer
        tweetQuoteCount:
          type: integer
        createdAt:
          type: string
          format: date-time
        drawnAt:
          type: string
          format: date-time

    Winner:
      description: Giveaway draw winner with position and backup flag.
      type: object
      required: [authorUsername, tweetId, position, isBackup]
      properties:
        authorUsername:
          type: string
        tweetId:
          type: string
        position:
          type: integer
        isBackup:
          type: boolean

    Webhook:
      description: Webhook endpoint registered to receive event deliveries.
      type: object
      required:
        - id
        - url
        - eventTypes
        - isActive
        - consecutiveFailures
        - deliveryStatus
        - failureHardCap
        - createdAt
      properties:
        id:
          type: string
          example: '42'
        url:
          type: string
          format: uri
          example: 'https://example.com/webhooks/xquik'
        eventTypes:
          $ref: '#/components/schemas/EventTypeArray'
          example: ['tweet.new', 'tweet.reply']
        isActive:
          type: boolean
          example: true
        consecutiveFailures:
          type: integer
          description:
            Consecutive failed delivery attempts since the last success.
          example: 0
        deliveryStatus:
          type: string
          enum: [active, paused, needs_attention]
          description:
            Endpoint delivery state. needs_attention means delivery stopped
            after repeated failures.
          example: active
        failureHardCap:
          type: integer
          description: Consecutive delivery failures that pause the endpoint.
          example: 200
        createdAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'

    Delivery:
      description: Webhook delivery attempt record with status and retry count.
      type: object
      required: [id, streamEventId, status, attempts, createdAt]
      properties:
        id:
          type: string
        streamEventId:
          type: string
        status:
          type: string
        attempts:
          type: integer
        createdAt:
          type: string
          format: date-time
        deliveredAt:
          type: string
          format: date-time
        lastStatusCode:
          type: integer
        lastError:
          type: string

    ArticleAuthor:
      description: X Article author profile fields returned when available.
      type: object
      required: [id, name, username]
      properties:
        id:
          type: string
          example: '9876543210'
        name:
          type: string
          example: 'Elon Musk'
        username:
          type: string
          example: elonmusk
        description:
          type: string
        location:
          type: string
        url:
          type: string
        createdAt:
          type: string
        followersCount:
          type: integer
        followingCount:
          type: integer
        statusesCount:
          type: integer
        mediaCount:
          type: integer
        favouritesCount:
          type: integer
        profilePicture:
          type: string
        profileBannerUrl:
          type: string
        isBlueVerified:
          type: boolean
        isVerified:
          type: boolean
        isTranslator:
          type: boolean
        protected:
          type: boolean
        canDm:
          type: boolean

    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
        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

    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'
        entities:
          type: object
          additionalProperties: true
          x-stainless-any: true
          x-stainless-terraform-type: string
        media:
          type: array
          items:
            $ref: '#/components/schemas/TweetMedia'
        author:
          $ref: '#/components/schemas/UserProfile'

    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.
              example: true
        aiGenerated:
          type: object
          properties:
            detectionSource:
              type: string
              description: Source of the AI-generated media disclosure.
              example: UserDeclared
            canEdit:
              type: boolean
              description: Whether the disclosure can be edited on X.
              example: true
            hasAiGeneratedMedia:
              type: boolean
              description:
                True when X labels the tweet as containing AI-generated media.
              example: true

    TweetDetail:
      description:
        Full tweet with text, engagement metrics, media, and metadata. 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
          example: '1234567890'
        text:
          type: string
          example: 'Just launched our new feature!'
        createdAt:
          type: string
          example: '2025-01-15T12:00:00Z'
        isNoteTweet:
          type: boolean
          description:
            Whether this is a Note Tweet (long-form post, up to 25,000
            characters)
          example: false
        isReply:
          type: boolean
          description: Whether this tweet is a reply to another tweet
          example: false
        isLimitedReply:
          type: boolean
          description: Whether replies are limited for this tweet
          example: false
        isQuoteStatus:
          type: boolean
          description: Whether this tweet quotes another tweet
          example: false
        conversationId:
          type: string
          description: ID of the root tweet in the conversation thread
          example: '1234567890'
        source:
          type: string
          description: Client application used to post this tweet
          example: 'Twitter Web App'
        type:
          type: string
          description: Tweet result type
          example: tweet
        url:
          type: string
          description: Tweet permalink URL
          example: 'https://x.com/example_user/status/1234567890'
        lang:
          type: string
          description: Tweet language code
          example: en
        inReplyToId:
          type: string
          description: Tweet ID being replied to
          example: '1234567890'
        inReplyToUserId:
          type: string
          description: User ID being replied to
          example: '9876543210'
        inReplyToUsername:
          type: string
          description: Username being replied to
          example: example_user
        displayTextRange:
          type: array
          items:
            type: integer
          description: Start and end offsets for rendered tweet text
          example: [0, 31]
        contentDisclosure:
          $ref: '#/components/schemas/ContentDisclosure'
        entities:
          type: object
          additionalProperties: true
          x-stainless-any: true
          x-stainless-terraform-type: string
          description:
            Parsed entities from the tweet text (URLs, mentions, hashtags,
            media)
        quoted_tweet:
          $ref: '#/components/schemas/EmbeddedTweet'
        retweeted_tweet:
          $ref: '#/components/schemas/EmbeddedTweet'
        author:
          $ref: '#/components/schemas/TweetAuthor'
        media:
          type: array
          items:
            $ref: '#/components/schemas/TweetMedia'
          description: Attached media items, omitted when the tweet has no media
        retweetCount:
          type: integer
          example: 5
        replyCount:
          type: integer
          example: 3
        likeCount:
          type: integer
          example: 42
        quoteCount:
          type: integer
          example: 1
        viewCount:
          type: integer
          example: 1500
        bookmarkCount:
          type: integer
          example: 2

    TweetAuthor:
      description:
        Tweet author profile. The lookup route always includes follower count
        and verification state. Other profile fields appear when available.
      allOf:
        - $ref: '#/components/schemas/UserProfile'
        - title: TweetAuthorRequirements
          type: object
          required: [followers, verified]

    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
          example: '1234567890'
        text:
          type: string
          example: 'Just launched our new feature!'
        type:
          type: string
          example: 'tweet'
        createdAt:
          type: string
          example: '2025-01-15T12:00:00Z'
        isNoteTweet:
          type: boolean
          description:
            True for Note Tweets (long-form content, up to 25,000 characters)
          example: false
        isReply:
          type: boolean
          description: True when this search result is a reply
          example: false
        isQuoteStatus:
          type: boolean
          description: True when this search result quotes another tweet
          example: false
        isLimitedReply:
          type: boolean
          description: Whether the tweet has limited reply permissions
          example: false
        inReplyToId:
          type: string
          description: Tweet ID being replied to
          example: '1234567890'
        inReplyToUserId:
          type: string
          description: User ID being replied to
          example: '9876543210'
        inReplyToUsername:
          type: string
          description: Username being replied to
          example: 'example_user'
        conversationId:
          type: string
          description: Root tweet ID for the search result conversation
          example: '1234567890'
        source:
          type: string
          description: Client application used to post the tweet
          example: 'Twitter Web App'
        displayTextRange:
          type: array
          items:
            type: integer
          description: Start and end offsets for rendered tweet text
          example: [0, 31]
        contentDisclosure:
          $ref: '#/components/schemas/ContentDisclosure'
        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: Tweet permalink URL
          example: 'https://x.com/example_user/status/1234567890'
        lang:
          type: string
          description: Tweet language code
          example: 'en'
        likeCount:
          type: integer
          example: 42
        retweetCount:
          type: integer
          example: 5
        replyCount:
          type: integer
          example: 3
        quoteCount:
          type: integer
          example: 1
        viewCount:
          type: integer
          example: 1500
        bookmarkCount:
          type: integer
          example: 2
        author:
          $ref: '#/components/schemas/UserProfile'

    UserProfile:
      description:
        X user profile with bio, follower counts, and verification status.
      type: object
      required: [id, username, name]
      properties:
        id:
          type: string
          example: '9876543210'
        username:
          type: string
          example: 'elonmusk'
        name:
          type: string
          example: 'Elon Musk'
        description:
          type: string
          example: 'CEO of Tesla, SpaceX, and X'
        followers:
          type: integer
          example: 150000000
        following:
          type: integer
          example: 500
        verified:
          type: boolean
          example: true
        isBlueVerified:
          type: boolean
          description: Whether X shows a blue verification badge
          example: true
        isVerified:
          type: boolean
          description: Whether X marks the profile as verified
          example: true
        profilePicture:
          type: string
          example: 'https://pbs.twimg.com/profile_images/example.jpg'
        coverPicture:
          type: string
          example: 'https://pbs.twimg.com/profile_banners/example.jpg'
        profileBannerUrl:
          type: string
          description: Original X profile banner field when available
          example: 'https://pbs.twimg.com/profile_banners/example.jpg'
        location:
          type: string
          example: 'Austin, TX'
        createdAt:
          type: string
          example: '2009-06-02T20:12:29Z'
        statusesCount:
          type: integer
          example: 35000
        mediaCount:
          type: integer
          example: 1200
        canDm:
          type: boolean
          example: false
        protected:
          type: boolean
          description: Whether the profile protects its posts
          example: false
        url:
          type: string
          example: 'https://xquik.com'
        favouritesCount:
          type: integer
          example: 18000
        hasCustomTimelines:
          type: boolean
          example: true
        isTranslator:
          type: boolean
          example: false
        withheldInCountries:
          type: array
          items:
            type: string
          example: ['DE']
        possiblySensitive:
          type: boolean
          example: false
        pinnedTweetIds:
          type: array
          items:
            type: string
          example: ['1234567890']
        isAutomated:
          type: boolean
          example: false
        automatedBy:
          type: string
          example: 'example_user'
        unavailable:
          type: boolean
          example: false
        unavailableReason:
          type: string
          example: 'suspended'
        verifiedType:
          type: string
          example: 'Business'
        communityRole:
          type: string
          description: Community role when returned by community member reads
          example: Member
        viewerFollowedBy:
          type: boolean
          description: Whether this profile follows the authenticated viewer
          example: false
        viewerFollowing:
          type: boolean
          description: Whether the authenticated viewer follows this profile
          example: true
        profile_bio:
          type: object
          additionalProperties: true
          x-stainless-any: true
          x-stainless-terraform-type: string
          description: Structured profile bio with entity annotations
          example:
            description: CEO of Tesla, SpaceX, and X
            entities:
              urls: []

    # ── New schemas ──────────────────────────────────────────
    Draft:
      description: Saved tweet draft with optional topic and goal.
      type: object
      required: [id, text, createdAt]
      properties:
        id:
          type: string
          example: '42'
        text:
          type: string
          example: 'Draft tweet about AI trends'
        topic:
          type: string
          example: 'Technology'
        goal:
          type: string
          example: 'Engagement'
        createdAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'

    DraftDetail:
      description: Full tweet draft including update timestamp.
      type: object
      required: [id, text, createdAt, updatedAt]
      properties:
        id:
          type: string
          example: '42'
        text:
          type: string
          example: 'Draft tweet about AI trends'
        topic:
          type: string
          example: 'Technology'
        goal:
          type: string
          example: 'Engagement'
        createdAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'
        updatedAt:
          type: string
          format: date-time
          example: '2025-01-16T09:30:00Z'

    StyleProfileSummary:
      description: Style profile summary with tweet count and ownership flag.
      type: object
      required: [xUsername, tweetCount, isOwnAccount, fetchedAt]
      properties:
        xUsername:
          type: string
          example: 'elonmusk'
        tweetCount:
          type: integer
          example: 50
        isOwnAccount:
          type: boolean
          example: true
        fetchedAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'

    StyleProfile:
      description:
        Full style profile with sampled tweets used for tone analysis.
      type: object
      required: [xUsername, tweetCount, isOwnAccount, fetchedAt, tweets]
      properties:
        xUsername:
          type: string
          example: 'elonmusk'
        tweetCount:
          type: integer
          example: 50
        isOwnAccount:
          type: boolean
          example: true
        fetchedAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'
        tweets:
          type: array
          items:
            type: object
            required: [id, text]
            properties:
              id:
                type: string
                example: '1234567890'
              text:
                type: string
                example: 'Just launched our new feature!'
              createdAt:
                type: string
                example: '2025-01-15T12:00:00Z'
              authorUsername:
                type: string
                example: 'elonmusk'
          example:
            - id: '1234567890'
              text: 'Just launched our new feature!'

    RadarItem:
      description:
        Trending topic with score, category, source, region, language, and
        source-specific metadata.
      type: object
      required:
        - id
        - sourceId
        - title
        - score
        - category
        - source
        - region
        - language
        - metadata
        - publishedAt
        - createdAt
      properties:
        id:
          type: string
          description: Radar item identifier.
          example: '4712'
        sourceId:
          type: string
          description: Source-specific identifier used for deduplication.
          example: 'trustmrr_acme'
        title:
          type: string
          example: 'AI Revolution in 2025'
        url:
          type: string
          example: 'https://example.com/article/ai-revolution'
        score:
          type: number
          example: 95.5
        category:
          type: string
          enum:
            [
              general,
              tech,
              dev,
              science,
              culture,
              politics,
              business,
              entertainment,
            ]
          example: 'tech'
        source:
          type: string
          enum:
            [
              github,
              google_trends,
              hacker_news,
              polymarket,
              reddit,
              trustmrr,
              wikipedia,
            ]
          example: 'trustmrr'
        region:
          type: string
          example: 'global'
        language:
          type: string
          example: 'en'
        metadata:
          type: object
          description: |
            Source-specific fields. Shape varies per source:
            - reddit: { subreddit: string, author: string }
            - github: { starsToday: number }
            - hacker_news: { points: number, numberComments: number }
            - google_trends: { approxTraffic: number }
            - polymarket: { volume24hr: number }
            - wikipedia: { views: number }
            - trustmrr: { mrr, growthPercent, last30Days, total, customers, activeSubscriptions, onSale, xHandle?, category?, askingPrice?, country?, growthMrrPercent?, multiple?, paymentProvider?, rank? }
          additionalProperties: true
        publishedAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'
        createdAt:
          type: string
          format: date-time
          example: '2025-01-15T12:01:00Z'
        description:
          type: string
          example: 'AI is transforming every industry'
        imageUrl:
          type: string
          example: 'https://example.com/images/ai.jpg'

    XAccount:
      description:
        Linked X account summary with connection status, health, and timestamp
        metadata.
      type: object
      required: [id, xUserId, xUsername, status, health, createdAt, updatedAt]
      properties:
        id:
          type: string
          example: '42'
        xUserId:
          type: string
          example: '9876543210'
        xUsername:
          type: string
          example: 'elonmusk'
        status:
          type: string
          example: 'active'
        health:
          type: string
          description: >
            Derived connection health. `healthy` = session active. `needsReauth`
            = user must submit fresh credentials. `locked` = X locked the
            account; unlock on x.com first. `suspended` = X banned the account.
            `recovering` = past cooldown, will auto-retry on next use.
            `temporaryIssue` = temporary connection problem; retry shortly.
          enum:
            [
              healthy,
              locked,
              needsReauth,
              recovering,
              suspended,
              temporaryIssue,
            ]
          example: 'healthy'
        createdAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'
        updatedAt:
          type: string
          format: date-time
          example: '2025-03-10T08:30:00Z'
        cookiesObtainedAt:
          type: string
          format: date-time
          example: '2025-03-10T08:30:00Z'

    XAccountConnectionChallenge:
      description:
        Resumable account connection challenge. Submit the email code to finish
        the same connection attempt.
      type: object
      required: [object, id, status, expiresAt, message, username]
      properties:
        object:
          type: string
          enum: [x_account_connection_challenge]
          example: 'x_account_connection_challenge'
        id:
          type: string
          example: 'xch_8vGd8Y9JvH6dV0xA'
        status:
          type: string
          enum: [requires_email_code]
          example: 'requires_email_code'
        expiresAt:
          type: string
          format: date-time
          example: '2026-05-08T12:10:00Z'
        message:
          type: string
          example: 'Enter the email verification code to continue.'
        username:
          type: string
          example: 'elonmusk'

    XAccountDetail:
      description:
        Connected X account details with health and timestamp metadata.
      type: object
      required: [id, xUserId, xUsername, status, health, createdAt]
      properties:
        id:
          type: string
          example: '42'
        xUserId:
          type: string
          example: '9876543210'
        xUsername:
          type: string
          example: 'elonmusk'
        status:
          type: string
          example: 'active'
        health:
          type: string
          enum:
            [
              healthy,
              locked,
              needsReauth,
              recovering,
              suspended,
              temporaryIssue,
            ]
          example: 'healthy'
        createdAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'
        updatedAt:
          type: string
          format: date-time
          example: '2025-03-10T08:30:00Z'
        cookiesObtainedAt:
          type: string
          format: date-time
          example: '2025-03-10T08:30:00Z'

    SanitizedXAccount:
      description: Sanitized X account summary returned by connect and reauth.
      type: object
      required: [id, xUserId, xUsername, status, health, createdAt]
      properties:
        id:
          type: string
          example: '42'
        xUserId:
          type: string
          example: '9876543210'
        xUsername:
          type: string
          example: 'elonmusk'
        status:
          type: string
          example: 'active'
        health:
          type: string
          enum:
            [
              healthy,
              locked,
              needsReauth,
              recovering,
              suspended,
              temporaryIssue,
            ]
          example: 'healthy'
        createdAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'
    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'