openapi: "3.1.0"
info:
  title: "Xquik API"
  version: "1.0"
  description: "Xquik is an independent third-party service. Not affiliated with X
    Corp. \"Twitter\" and \"X\" are trademarks of X Corp. Read and automate X.
    Paid reads accept credits. Some lookups accept MPP. Writes require API key
    or OAuth 2.1.


    ## Client Libraries


    See the current [SDK, CLI, and Terraform
    guides](https://docs.xquik.com/sdks) and [TweetClaw
    setup](https://docs.xquik.com/guides/tweetclaw)."
  x-guidance: "## Common tasks


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


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


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


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


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


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


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


    ## Pagination


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


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


    ## Authentication


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


    ## Best-Practice Response Contract


    v1 remains the default. Send `xquik-api-contract: 2026-04-29` for
    snake_case, Unix timestamps, structured errors, unified pagination, resource
    objects, and prefixed IDs. Dependency failures use 424 instead of 502."
  contact:
    name: "Xquik"
    url: "https://xquik.com"
    email: "support@xquik.com"
servers:
  - url: "https://xquik.com"
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: "X account monitoring with 1-second checks"
  - 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:
  /api/v1/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: "Rounded daily estimate for 1 active monitor."
                        example: "500"
                      creditsPerActiveMonitorHour:
                        type: "string"
                        description: "Hourly credits charged for 1 active 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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get account info."
    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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Update account locale."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Set linked X username."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List API keys."
    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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Create API key."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Revoke API key."
  /api/v1/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.\n"
      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"
        default:
          $ref: "#/components/responses/UnexpectedError"
  /api/v1/compose:
    post:
      operationId: "compose"
      summary: "Build, refine, or check a post draft"
      description: "Run one step of Xquik's three-step writing workflow. Compose
        returns questions, editorial rules, and source-specific Radar
        recommendations. Refine returns goal-specific guidance. Score applies
        deterministic text checks. It does not predict reach or expose X ranking
        weights.\n"
      tags:
        - "Composition"
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: "Send exactly one workflow step and its required fields."
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/ComposePrepareRequest"
                - $ref: "#/components/schemas/ComposeRefineRequest"
                - $ref: "#/components/schemas/ComposeScoreRequest"
            example:
              step: "compose"
              topic: "PostgreSQL query planning"
              goal: "engagement"
      responses:
        "200":
          description: "Result for the requested workflow step"
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ComposePrepareResult"
                  - $ref: "#/components/schemas/ComposeRefineResult"
                  - $ref: "#/components/schemas/ComposeScoreResult"
              example:
                checklist:
                  - factor: "No external links in body"
                    passed: true
                  - factor: "No hashtags"
                    passed: true
                  - factor: "No excessive capitalization"
                    passed: true
                  - factor: "Length between 50 and 280 characters"
                    passed: true
                  - factor: "No excessive punctuation"
                    passed: true
                  - factor: "No emojis"
                    passed: true
                  - factor: "No em dashes or double dashes"
                    passed: true
                  - factor: "Sufficient substance"
                    passed: true
                  - factor: "Link-in-reply strategy"
                    passed: true
                nextStep: "All 9 checks passed. Get an account from GET /api/v1/x/accounts. Then
                  send the draft to POST /api/v1/x/tweets. The intentUrl also
                  supports one-click posting.\n"
                passed: true
                passedCount: 9
                topSuggestion: "All Xquik editorial checks passed."
                totalChecks: 9
                intentUrl: "https://x.com/intent/tweet?text=PostgreSQL%2018%20reduced%20query%2\
                  0latency"
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        default:
          $ref: "#/components/responses/UnexpectedError"
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List saved drafts."
    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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Save a tweet draft."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get draft by ID."
    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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Delete a draft."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List cached style profiles."
    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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Analyze writing style from recent tweets."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Compare two style profiles."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get cached style profile."
    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: "professional voice"
                tweetCount: 1
                isOwnAccount: false
                fetchedAt: "2026-08-02T18:30:00.000Z"
                tweets:
                  - id: "0"
                    text: "Excited to share our latest research findings."
                    authorUsername: "professional voice"
                    createdAt: "2026-08-02T18:30:00.000Z"
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Save style profile with custom tweets."
    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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Delete a style profile."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get engagement metrics for style tweets."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get trending topics from curated sources."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List monitors."
    post:
      operationId: "createMonitor"
      summary: "Create monitor"
      description: "Creates an account 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":
          $ref: "#/components/responses/UserNotFound"
        "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"
        default:
          $ref: "#/components/responses/UnexpectedError"
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List keyword monitors."
    post:
      operationId: "createKeywordMonitor"
      summary: "Create keyword monitor"
      description: "Creates a 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"
        default:
          $ref: "#/components/responses/UnexpectedError"
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get keyword monitor."
    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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Update keyword monitor."
    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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Delete keyword monitor."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get monitor."
    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"
        "409":
          description: "The monitored X account is still unavailable"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "monitor_profile_unavailable"
                message: "X account unavailable. Restore it before resuming."
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Update monitor."
    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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Delete monitor."
  /api/v1/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: "Account monitor ID."
          schema:
            type: "string"
        - name: "keywordMonitorId"
          in: "query"
          description: "Keyword 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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List events."
  /api/v1/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"
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get event."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List extraction jobs."
    post:
      operationId: "createExtraction"
      summary: "Run extraction"
      tags:
        - "Extractions"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: "dry_run"
          in: "query"
          description: "Estimate cost without creating an extraction."
          schema:
            type: "boolean"
            default: false
          example: true
      requestBody:
        required: true
        description: "Tool type and target identifier (tweet, user, community, list, or
          search query)."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExtractionRequest"
            example:
              toolType: "follower_explorer"
              targetUsername: "elonmusk"
      responses:
        "200":
          description: "Dry-run estimate"
          content:
            application/json:
              schema:
                type: "object"
                required:
                  - "allowed"
                  - "creditsAvailable"
                  - "creditsRequired"
                  - "estimatedResults"
                  - "source"
                properties:
                  allowed:
                    type: "boolean"
                  creditsAvailable:
                    type: "string"
                  creditsRequired:
                    type: "string"
                  estimatedResults:
                    type: "integer"
                  resolvedXUserId:
                    type: "string"
                  source:
                    type: "string"
              example:
                allowed: true
                creditsAvailable: "10000"
                creditsRequired: "1000"
                estimatedResults: 1000
                source: "profile"
        "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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Run extraction."
  /api/v1/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:
              $ref: "#/components/schemas/ExtractionRequest"
            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"
                      - "collection"
                      - "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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Estimate extraction cost."
  /api/v1/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"
        - name: "outputMode"
          in: "query"
          description: "Select compact, full, or raw-compatible result fields."
          schema:
            type: "string"
            enum:
              - "compact"
              - "full"
              - "raw"
            default: "full"
        - name: "outputPreset"
          in: "query"
          description: "Keep enrichment nested or merge it into each result."
          schema:
            type: "string"
            enum:
              - "nested"
              - "flat"
            default: "nested"
        - name: "fieldStyle"
          in: "query"
          description: "Preserve source keys or convert result field names."
          schema:
            type: "string"
            enum:
              - "source"
              - "camelCase"
              - "snake_case"
            default: "source"
        - name: "includeRaw"
          in: "query"
          deprecated: true
          description: "Use outputMode=raw instead."
          schema:
            type: "boolean"
            default: false
      responses:
        "200":
          description: "Extraction job with results"
          content:
            application/json:
              schema:
                type: "object"
                required:
                  - "job"
                  - "results"
                  - "hasMore"
                properties:
                  job:
                    $ref: "#/components/schemas/PublicMetadata"
                    description: "Extraction job metadata - shape varies by tool type (JSON)"
                    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
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get extraction results."
  /api/v1/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"
        - name: "minFollowers"
          in: "query"
          schema:
            type: "integer"
          description: "Minimum follower count."
        - name: "maxFollowers"
          in: "query"
          schema:
            type: "integer"
          description: "Maximum follower count."
        - name: "minFollowing"
          in: "query"
          schema:
            type: "integer"
          description: "Minimum following count."
        - name: "maxFollowing"
          in: "query"
          schema:
            type: "integer"
          description: "Maximum following count."
        - name: "minPosts"
          in: "query"
          schema:
            type: "integer"
          description: "Minimum post count."
        - name: "maxPosts"
          in: "query"
          schema:
            type: "integer"
          description: "Maximum post count."
        - name: "minLikes"
          in: "query"
          schema:
            type: "integer"
          description: "Minimum like count."
        - name: "minReplies"
          in: "query"
          schema:
            type: "integer"
          description: "Minimum reply count."
        - name: "minRetweets"
          in: "query"
          schema:
            type: "integer"
          description: "Minimum repost count."
        - name: "minViews"
          in: "query"
          schema:
            type: "integer"
          description: "Minimum view count."
        - name: "hasDescription"
          in: "query"
          schema:
            type: "boolean"
          description: "Require a non-empty description."
        - name: "hasLocation"
          in: "query"
          schema:
            type: "boolean"
          description: "Require a non-empty location."
        - name: "hasMedia"
          in: "query"
          schema:
            type: "boolean"
          description: "Require media."
        - name: "verified"
          in: "query"
          schema:
            type: "boolean"
          description: "Filter by verified status."
        - name: "lang"
          in: "query"
          schema:
            type: "string"
          description: "Filter by language code."
        - name: "search"
          in: "query"
          schema:
            type: "string"
          description: "Search exported result text."
        - name: "sinceDate"
          in: "query"
          schema:
            type: "string"
            format: "date"
          description: "Include results on or after this date."
        - name: "untilDate"
          in: "query"
          schema:
            type: "string"
            format: "date"
          description: "Include results on or before this date."
      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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Export extraction results."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List draws."
    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"
        default:
          $ref: "#/components/responses/UnexpectedError"
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get draw details."
  /api/v1/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. PDF entry exports include up to 10,000 rows.
            Other entry formats include up to 100,000 rows."
          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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Export draw data."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List webhooks."
    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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Create webhook."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Update webhook."
    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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Deactivate webhook."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List webhook deliveries."
  /api/v1/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":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Test webhook endpoint."
  /api/v1/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:
                type: "object"
                additionalProperties: false
                required:
                  - "error"
                  - "statusCode"
                  - "success"
                properties:
                  error:
                    type: "string"
                    description: "Delivery failure returned by the webhook sender."
                    example: "Connection timed out"
                  statusCode:
                    type: "integer"
                    description: "Webhook response status, or 0 before a response."
                    example: 0
                  success:
                    type: "boolean"
                    const: false
              example:
                error: "Connection timed out"
                statusCode: 0
                success: false
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Test and resume webhook endpoint."
  /api/v1/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: "Requested tweets in request order. Partial successful reads
            recheck unresolved IDs once."
          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: false
                next_cursor: ""
        "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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get multiple tweets by IDs."
    post:
      operationId: "createTweet"
      x-write-action: "create_tweet"
      summary: "Create tweet"
      tags:
        - "X Write"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/WriteIdempotencyKey"
      requestBody:
        required: true
        description: "Account and tweet content. Requires text, media, or both."
        content:
          application/json:
            schema:
              type: "object"
              required:
                - "account"
              properties:
                account:
                  type: "string"
                  description: "X account (@username or account ID)"
                  example: "@elonmusk"
                text:
                  type: "string"
                  description: "Tweet text (optional when media is provided)"
                  example: "Just launched our new feature!"
                reply_to_tweet_id:
                  type: "string"
                  example: "1234567890"
                community_id:
                  type: "string"
                  example: "1500000000000000000"
                is_note_tweet:
                  type: "boolean"
                  example: false
                media:
                  type: "array"
                  items:
                    type: "string"
                  maxItems: 4
                  description: "Array of public media URLs to attach. Supports up to 4 images or
                    exactly 1 MP4 video up to 100 MB. Each URL must be publicly
                    reachable. Attached media adds 2 credits per started MB
                    across all files."
                  example:
                    - "https://example.com/video.mp4"
            example:
              account: "@elonmusk"
              text: "Just launched our new feature!"
      responses:
        "200":
          $ref: "#/components/responses/WriteActionCompleted"
        "202":
          $ref: "#/components/responses/WriteActionAccepted"
        "400":
          $ref: "#/components/responses/WriteInvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/AccountAuthError"
        "409":
          $ref: "#/components/responses/WriteIdempotencyConflict"
        "422":
          $ref: "#/components/responses/WriteRejected"
        "429":
          $ref: "#/components/responses/WriteRateLimited"
        "500":
          $ref: "#/components/responses/WriteError"
        "503":
          $ref: "#/components/responses/WriteTrackingUnavailable"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Create tweet."
  /api/v1/x/write-actions/{id}:
    get:
      operationId: "getWriteActionStatus"
      summary: "Get write action status"
      tags:
        - "X Write"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "Write action ID returned by a pending write response."
      responses:
        "200":
          $ref: "#/components/responses/WriteActionCompleted"
        "202":
          $ref: "#/components/responses/WriteActionAccepted"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get write action status."
  /api/v1/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"
                        promotedContent:
                          type:
                            - "string"
                            - "null"
                          description: "Promotion identifier from X. Null for organic trends."
                        rank:
                          type: "integer"
                          example: 1
                        tweetVolume:
                          type:
                            - "integer"
                            - "null"
                          description: "Approximate public post volume when X supplies it."
                          example: 250000
                        url:
                          type: "string"
                          format: "uri"
                          description: "X search URL for the trend."
                    example:
                      - name: "#AI"
                        description: "Artificial intelligence discussions"
                        promotedContent: null
                        query: "%23AI"
                        rank: 1
                        tweetVolume: 250000
                        url: "https://x.com/search?q=%23AI"
                  count:
                    type: "integer"
                    example: 30
                  woeid:
                    type: "integer"
                    example: 1
              example:
                trends:
                  - name: "#AI"
                    description: "Artificial intelligence discussions"
                    promotedContent: null
                    query: "%23AI"
                    rank: 1
                    tweetVolume: 250000
                    url: "https://x.com/search?q=%23AI"
                count: 30
                woeid: 1
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get trending hashtags and topics from X by region."
  /api/v1/x/tweets/search:
    get:
      operationId: "searchTweets"
      summary: "Search tweets by query, Tweet ID, X status URL, or account date window"
      description: "No-mode search maximizes coverage. New cursorless `Latest`
        sessions return rows newest-first across cursor pages. Existing cursors
        preserve their established ordering.\n"
      tags:
        - "Tweets"
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: "q"
          in: "query"
          required: true
          schema:
            type: "string"
          description: "Query, Tweet ID, or status URL. Valid inline bounds apply per page."
        - name: "queryType"
          in: "query"
          required: false
          schema:
            type: "string"
            enum:
              - "Latest"
              - "Top"
            default: "Latest"
          description: "Sort order - Latest (chronological) or Top (engagement-ranked)"
        - $ref: "#/components/parameters/AutomaticCoverageMode"
        - $ref: "#/components/parameters/AutomaticCoverageCursor"
        - name: "sinceTime"
          in: "query"
          schema:
            type: "string"
          description: "Inclusive ISO bound."
        - name: "untilTime"
          in: "query"
          schema:
            type: "string"
          description: "Exclusive ISO bound."
        - name: "limit"
          in: "query"
          required: false
          schema:
            type: "integer"
            minimum: 1
            maximum: 10000
          description: "Result upper bound. Omit it for the existing 20-row page size.
            Explicit coverage defaults to 2000 and allows 10000. For paid
            requests, remaining credits can reduce results. Zero affordable
            results returns 402.\n"
        - $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/TweetFilterMinViews"
        - $ref: "#/components/parameters/TweetFilterMinBookmarks"
        - $ref: "#/components/parameters/TweetFilterMaxFaves"
        - $ref: "#/components/parameters/TweetFilterMaxRetweets"
        - $ref: "#/components/parameters/TweetFilterMaxReplies"
        - $ref: "#/components/parameters/TweetFilterMaxQuotes"
        - $ref: "#/components/parameters/TweetFilterBlueVerifiedOnly"
        - $ref: "#/components/parameters/TweetFilterCardName"
        - $ref: "#/components/parameters/TweetFilterSource"
        - $ref: "#/components/parameters/TweetFilterExcludeSource"
        - $ref: "#/components/parameters/TweetFilterGeocode"
        - $ref: "#/components/parameters/TweetFilterSinceId"
        - $ref: "#/components/parameters/TweetFilterMaxId"
        - $ref: "#/components/parameters/TweetFilterNear"
        - $ref: "#/components/parameters/TweetFilterWithin"
        - $ref: "#/components/parameters/TweetFilterWithinTime"
        - $ref: "#/components/parameters/TweetFilterNativeRetweets"
        - $ref: "#/components/parameters/TweetFilterSafe"
        - $ref: "#/components/parameters/TweetFilterNews"
        - $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:
                oneOf:
                  - $ref: "#/components/schemas/PaginatedTweets"
                  - $ref: "#/components/schemas/TweetSearchCoverageResponse"
              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"
        "409":
          $ref: "#/components/responses/CoverageCursorUnavailable"
        "410":
          $ref: "#/components/responses/CursorGone"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        "503":
          $ref: "#/components/responses/MaximumCoverageBusy"
        default:
          $ref: "#/components/responses/UnexpectedError"
  /api/v1/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."
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
  /api/v1/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:
                      id: "9876543210"
                      username: "elonmusk"
                      name: "Elon Musk"
                      followers: 150000000
                      verified: true
              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"
                  name: "Elon Musk"
                  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."
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get tweet with full text, author, metrics and media."
    delete:
      operationId: "deleteTweet"
      x-write-action: "delete_tweet"
      summary: "Delete tweet"
      tags:
        - "X Write"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/WriteIdempotencyKey"
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "Tweet ID to delete"
      requestBody:
        required: true
        description: "Account that owns the tweet."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XAccountBody"
            example:
              account: "@elonmusk"
      responses:
        "200":
          $ref: "#/components/responses/WriteActionCompleted"
        "202":
          $ref: "#/components/responses/WriteActionAccepted"
        "400":
          $ref: "#/components/responses/WriteInvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/AccountAuthError"
        "409":
          $ref: "#/components/responses/WriteIdempotencyConflict"
        "422":
          $ref: "#/components/responses/WriteRejected"
        "429":
          $ref: "#/components/responses/RateLimitedByX"
        "500":
          $ref: "#/components/responses/WriteError"
        "503":
          $ref: "#/components/responses/WriteTrackingUnavailable"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Delete tweet."
  /api/v1/x/tweets/{id}/like:
    post:
      operationId: "likeTweet"
      x-write-action: "like"
      summary: "Like tweet"
      tags:
        - "X Write"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/WriteIdempotencyKey"
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "Tweet ID to like"
      requestBody:
        required: true
        description: "Account to perform the like."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XAccountBody"
            example:
              account: "@elonmusk"
      responses:
        "200":
          $ref: "#/components/responses/WriteActionCompleted"
        "202":
          $ref: "#/components/responses/WriteActionAccepted"
        "400":
          $ref: "#/components/responses/WriteInvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/AccountAuthError"
        "409":
          $ref: "#/components/responses/WriteIdempotencyConflict"
        "422":
          $ref: "#/components/responses/WriteRejected"
        "429":
          $ref: "#/components/responses/RateLimitedByX"
        "500":
          $ref: "#/components/responses/WriteError"
        "503":
          $ref: "#/components/responses/WriteTrackingUnavailable"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Like tweet."
    delete:
      operationId: "unlikeTweet"
      x-write-action: "unlike"
      summary: "Unlike tweet"
      tags:
        - "X Write"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/WriteIdempotencyKey"
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "Tweet ID to unlike"
      requestBody:
        required: true
        description: "Account that liked the tweet."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XAccountBody"
      responses:
        "200":
          $ref: "#/components/responses/WriteActionCompleted"
        "202":
          $ref: "#/components/responses/WriteActionAccepted"
        "400":
          $ref: "#/components/responses/WriteInvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/AccountAuthError"
        "409":
          $ref: "#/components/responses/WriteIdempotencyConflict"
        "422":
          $ref: "#/components/responses/WriteRejected"
        "429":
          $ref: "#/components/responses/RateLimitedByX"
        "500":
          $ref: "#/components/responses/WriteError"
        "503":
          $ref: "#/components/responses/WriteTrackingUnavailable"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Unlike tweet."
  /api/v1/x/tweets/{id}/retweet:
    post:
      operationId: "retweet"
      x-write-action: "retweet"
      summary: "Retweet"
      tags:
        - "X Write"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/WriteIdempotencyKey"
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "Tweet ID to retweet"
      requestBody:
        required: true
        description: "Account to perform the retweet."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XAccountBody"
      responses:
        "200":
          $ref: "#/components/responses/WriteActionCompleted"
        "202":
          $ref: "#/components/responses/WriteActionAccepted"
        "400":
          $ref: "#/components/responses/WriteInvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/AccountAuthError"
        "409":
          $ref: "#/components/responses/WriteIdempotencyConflict"
        "422":
          $ref: "#/components/responses/WriteRejected"
        "429":
          $ref: "#/components/responses/RateLimitedByX"
        "500":
          $ref: "#/components/responses/WriteError"
        "503":
          $ref: "#/components/responses/WriteTrackingUnavailable"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Retweet."
    delete:
      operationId: "unretweet"
      x-write-action: "unretweet"
      summary: "Unretweet"
      tags:
        - "X Write"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/WriteIdempotencyKey"
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "Tweet ID to unretweet"
      requestBody:
        required: true
        description: "Account that retweeted the tweet."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XAccountBody"
      responses:
        "200":
          $ref: "#/components/responses/WriteActionCompleted"
        "202":
          $ref: "#/components/responses/WriteActionAccepted"
        "400":
          $ref: "#/components/responses/WriteInvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/AccountAuthError"
        "409":
          $ref: "#/components/responses/WriteIdempotencyConflict"
        "422":
          $ref: "#/components/responses/WriteRejected"
        "429":
          $ref: "#/components/responses/RateLimitedByX"
        "500":
          $ref: "#/components/responses/WriteError"
        "503":
          $ref: "#/components/responses/WriteTrackingUnavailable"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Unretweet."
  /api/v1/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"
              example:
                users:
                  - id: "9876543210"
                    username: "elonmusk"
                    name: "Elon Musk"
                has_next_page: false
                next_cursor: ""
                requested_count: 2
                processed_count: 2
                returned_count: 1
                unavailable_ids:
                  - "1234567890"
                unprocessed_ids: []
        "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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Look up multiple users by IDs in one call."
  /api/v1/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"
        - $ref: "#/components/parameters/ResultPageSize"
        - $ref: "#/components/parameters/UserFilterMinFollowers"
        - $ref: "#/components/parameters/UserFilterMaxFollowers"
        - $ref: "#/components/parameters/UserFilterMinFollowing"
        - $ref: "#/components/parameters/UserFilterMaxFollowing"
        - $ref: "#/components/parameters/UserFilterMinStatuses"
        - $ref: "#/components/parameters/UserFilterMaxStatuses"
        - $ref: "#/components/parameters/UserFilterMinAccountAgeDays"
        - $ref: "#/components/parameters/UserFilterVerifiedOnly"
        - $ref: "#/components/parameters/UserFilterVerifiedType"
        - $ref: "#/components/parameters/UserFilterHasWebsite"
        - $ref: "#/components/parameters/UserFilterHasLocation"
        - $ref: "#/components/parameters/UserFilterBioContains"
        - $ref: "#/components/parameters/UserFilterLocationContains"
        - $ref: "#/components/parameters/UserFilterUsernameContains"
      responses:
        "200":
          description: "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"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Search users by name or username."
  /api/v1/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":
          $ref: "#/components/responses/UserNotFound"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get user profile with follower counts and verification."
  /api/v1/x/users/{id}/follow:
    post:
      operationId: "followUser"
      x-write-action: "follow"
      summary: "Follow user"
      tags:
        - "X Write"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/WriteIdempotencyKey"
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "User ID to follow"
      requestBody:
        required: true
        description: "Account to perform the follow."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XAccountBody"
      responses:
        "200":
          $ref: "#/components/responses/WriteActionCompleted"
        "202":
          $ref: "#/components/responses/WriteActionAccepted"
        "400":
          $ref: "#/components/responses/WriteInvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/AccountAuthError"
        "409":
          $ref: "#/components/responses/WriteIdempotencyConflict"
        "422":
          $ref: "#/components/responses/WriteRejected"
        "429":
          $ref: "#/components/responses/WriteRateLimited"
        "500":
          $ref: "#/components/responses/WriteError"
        "503":
          $ref: "#/components/responses/WriteTrackingUnavailable"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Follow user."
    delete:
      operationId: "unfollowUser"
      x-write-action: "unfollow"
      summary: "Unfollow user"
      tags:
        - "X Write"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/WriteIdempotencyKey"
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "User ID to unfollow"
      requestBody:
        required: true
        description: "Account that follows the target user."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XAccountBody"
      responses:
        "200":
          $ref: "#/components/responses/WriteActionCompleted"
        "202":
          $ref: "#/components/responses/WriteActionAccepted"
        "400":
          $ref: "#/components/responses/WriteInvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/AccountAuthError"
        "409":
          $ref: "#/components/responses/WriteIdempotencyConflict"
        "422":
          $ref: "#/components/responses/WriteRejected"
        "429":
          $ref: "#/components/responses/WriteRateLimited"
        "500":
          $ref: "#/components/responses/WriteError"
        "503":
          $ref: "#/components/responses/WriteTrackingUnavailable"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Unfollow user."
  /api/v1/x/users/{id}/remove-follower:
    post:
      operationId: "removeFollower"
      x-write-action: "remove_follower"
      summary: "Remove follower"
      tags:
        - "X Write"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/WriteIdempotencyKey"
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "User ID to remove from your followers"
      requestBody:
        required: true
        description: "Account whose follower list should be updated."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XAccountBody"
      responses:
        "200":
          $ref: "#/components/responses/WriteActionCompleted"
        "202":
          $ref: "#/components/responses/WriteActionAccepted"
        "400":
          $ref: "#/components/responses/WriteInvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/AccountAuthError"
        "409":
          $ref: "#/components/responses/WriteIdempotencyConflict"
        "422":
          $ref: "#/components/responses/WriteRejected"
        "429":
          $ref: "#/components/responses/WriteRateLimited"
        "500":
          $ref: "#/components/responses/WriteError"
        "503":
          $ref: "#/components/responses/WriteTrackingUnavailable"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Remove follower."
  /api/v1/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"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Check if one user follows another."
  /api/v1/x/dm/{userId}:
    post:
      operationId: "sendDm"
      x-write-action: "send_dm"
      summary: "Send direct message"
      tags:
        - "X Write"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/WriteIdempotencyKey"
        - name: "userId"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "Recipient user ID"
      requestBody:
        required: true
        description: "Account, message text, and an optional media attachment."
        content:
          application/json:
            schema:
              type: "object"
              required:
                - "account"
                - "text"
              properties:
                account:
                  type: "string"
                  description: "X account (@username or ID) sending the DM"
                  example: "@elonmusk"
                text:
                  type: "string"
                  example: "Example text"
                media_ids:
                  type: "array"
                  minItems: 1
                  maxItems: 1
                  items:
                    type: "string"
                  description: "Optional array containing exactly 1 uploaded media ID."
                  example:
                    - "1234567890123456789"
            example:
              account: "@elonmusk"
              text: "Example text content"
              media_ids:
                - "1234567890123456789"
      responses:
        "200":
          $ref: "#/components/responses/WriteActionCompleted"
        "202":
          $ref: "#/components/responses/WriteActionAccepted"
        "400":
          $ref: "#/components/responses/WriteInvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/AccountAuthError"
        "409":
          $ref: "#/components/responses/WriteIdempotencyConflict"
        "422":
          $ref: "#/components/responses/WriteRejected"
        "429":
          $ref: "#/components/responses/WriteRateLimited"
        "500":
          $ref: "#/components/responses/WriteError"
        "503":
          $ref: "#/components/responses/WriteTrackingUnavailable"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Send direct message."
  /api/v1/x/media:
    post:
      operationId: "uploadMedia"
      x-write-action: "upload_media"
      summary: "Upload media"
      tags:
        - "X Write"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/WriteIdempotencyKey"
      requestBody:
        required: true
        description: "Upload media with multipart form data, or provide a JSON URL for
          server-side download."
        content:
          multipart/form-data:
            schema:
              type: "object"
              required:
                - "account"
                - "file"
              properties:
                account:
                  type: "string"
                  description: "X account (@username or ID) uploading media"
                  example: "@elonmusk"
                file:
                  type: "string"
                  format: "binary"
                  description: "Media file to upload"
                  example: "binary-content"
                is_long_video:
                  type: "boolean"
                  description: "Set true only for video/mp4 multipart uploads longer than 140
                    seconds."
                  example: false
            example:
              account: "@elonmusk"
              file: "file_value"
              is_long_video: true
          application/json:
            schema:
              type: "object"
              required:
                - "account"
                - "url"
              properties:
                account:
                  type: "string"
                  description: "X account (@username or ID) uploading media from URL"
                  example: "@elonmusk"
                url:
                  type: "string"
                  format: "uri"
                  description: "HTTPS URL to download and upload as media"
                  example: "https://example.com/image.png"
            example:
              account: "@elonmusk"
              url: "https://example.com/image.png"
      responses:
        "200":
          $ref: "#/components/responses/WriteActionCompleted"
        "202":
          $ref: "#/components/responses/WriteActionAccepted"
        "400":
          $ref: "#/components/responses/WriteInvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/AccountAuthError"
        "404":
          $ref: "#/components/responses/XAccountNotFound"
        "409":
          $ref: "#/components/responses/WriteIdempotencyConflict"
        "422":
          $ref: "#/components/responses/WriteRejected"
        "429":
          $ref: "#/components/responses/WriteRateLimited"
        "500":
          $ref: "#/components/responses/WriteError"
        "503":
          $ref: "#/components/responses/WriteTrackingUnavailable"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Upload media."
  /api/v1/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."
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Download images and videos from tweets."
  /api/v1/x/profile:
    patch:
      operationId: "updateProfile"
      x-write-action: "update_profile"
      summary: "Update X profile"
      tags:
        - "X Write"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/WriteIdempotencyKey"
      requestBody:
        required: true
        description: "Account and profile fields to update (name, bio, location, website)."
        content:
          application/json:
            schema:
              type: "object"
              required:
                - "account"
              properties:
                account:
                  type: "string"
                  description: "X account (@username or ID) to update profile"
                  example: "@elonmusk"
                name:
                  type: "string"
                  description: "Display name"
                  example: "Example Name"
                description:
                  type: "string"
                  description: "Bio description"
                  example: "CEO of Tesla, SpaceX, and X"
                location:
                  type: "string"
                  example: "Austin, TX"
                url:
                  type: "string"
                  description: "Website URL"
                  example: "https://x.com"
            example:
              account: "@elonmusk"
              name: "Example Name"
              description: "description_value"
              location: "location_value"
              url: "https://xquik.com/example"
      responses:
        "200":
          $ref: "#/components/responses/WriteActionCompleted"
        "202":
          $ref: "#/components/responses/WriteActionAccepted"
        "400":
          $ref: "#/components/responses/WriteInvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/AccountAuthError"
        "404":
          $ref: "#/components/responses/XAccountNotFound"
        "409":
          $ref: "#/components/responses/WriteIdempotencyConflict"
        "422":
          $ref: "#/components/responses/WriteRejected"
        "429":
          $ref: "#/components/responses/WriteRateLimited"
        "500":
          $ref: "#/components/responses/WriteError"
        "503":
          $ref: "#/components/responses/WriteTrackingUnavailable"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Update X profile."
  /api/v1/x/profile/avatar:
    patch:
      operationId: "updateAvatar"
      x-write-action: "update_avatar"
      summary: "Update profile avatar"
      tags:
        - "X Write"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/WriteIdempotencyKey"
      requestBody:
        required: true
        description: "Account and avatar image file or HTTPS image URL (max 700 KB)."
        content:
          multipart/form-data:
            schema:
              type: "object"
              required:
                - "account"
                - "file"
              properties:
                account:
                  type: "string"
                  description: "X account (@username or ID) for avatar update"
                  example: "@elonmusk"
                file:
                  type: "string"
                  format: "binary"
                  description: "Avatar image (max 700 KB)"
                  example: "binary-content"
            example:
              account: "@elonmusk"
              file: "file_value"
          application/json:
            schema:
              type: "object"
              required:
                - "account"
                - "url"
              properties:
                account:
                  type: "string"
                  description: "X account (@username or ID) receiving avatar from URL"
                  example: "@elonmusk"
                url:
                  type: "string"
                  format: "uri"
                  description: "HTTPS URL to the avatar image to download"
                  example: "https://example.com/avatar.png"
            example:
              account: "@elonmusk"
              url: "https://example.com/avatar.png"
      responses:
        "200":
          $ref: "#/components/responses/WriteActionCompleted"
        "202":
          $ref: "#/components/responses/WriteActionAccepted"
        "400":
          $ref: "#/components/responses/WriteInvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/AccountAuthError"
        "404":
          $ref: "#/components/responses/XAccountNotFound"
        "409":
          $ref: "#/components/responses/WriteIdempotencyConflict"
        "422":
          $ref: "#/components/responses/WriteRejected"
        "429":
          $ref: "#/components/responses/WriteRateLimited"
        "500":
          $ref: "#/components/responses/WriteError"
        "503":
          $ref: "#/components/responses/WriteTrackingUnavailable"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Update profile avatar."
  /api/v1/x/profile/banner:
    patch:
      operationId: "updateBanner"
      x-write-action: "update_banner"
      summary: "Update profile banner"
      tags:
        - "X Write"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/WriteIdempotencyKey"
      requestBody:
        required: true
        description: "Account and banner image file or HTTPS image URL (max 2 MB)."
        content:
          multipart/form-data:
            schema:
              type: "object"
              required:
                - "account"
                - "file"
              properties:
                account:
                  type: "string"
                  description: "X account (@username or ID) for banner update"
                  example: "@elonmusk"
                file:
                  type: "string"
                  format: "binary"
                  description: "Banner image (max 2MB)"
                  example: "binary-content"
            example:
              account: "@elonmusk"
              file: "file_value"
          application/json:
            schema:
              type: "object"
              required:
                - "account"
                - "url"
              properties:
                account:
                  type: "string"
                  description: "X account (@username or ID) receiving banner from URL"
                  example: "@elonmusk"
                url:
                  type: "string"
                  format: "uri"
                  description: "HTTPS URL to the banner image to download"
                  example: "https://example.com/banner.png"
            example:
              account: "@elonmusk"
              url: "https://example.com/banner.png"
      responses:
        "200":
          $ref: "#/components/responses/WriteActionCompleted"
        "202":
          $ref: "#/components/responses/WriteActionAccepted"
        "400":
          $ref: "#/components/responses/WriteInvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/AccountAuthError"
        "404":
          $ref: "#/components/responses/XAccountNotFound"
        "409":
          $ref: "#/components/responses/WriteIdempotencyConflict"
        "422":
          $ref: "#/components/responses/WriteRejected"
        "429":
          $ref: "#/components/responses/WriteRateLimited"
        "500":
          $ref: "#/components/responses/WriteError"
        "503":
          $ref: "#/components/responses/WriteTrackingUnavailable"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Update profile banner."
  /api/v1/x/communities:
    post:
      operationId: "createCommunity"
      x-write-action: "create_community"
      summary: "Create community"
      tags:
        - "X Write"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/WriteIdempotencyKey"
      requestBody:
        required: true
        description: "Account, community name, and optional description."
        content:
          application/json:
            schema:
              type: "object"
              required:
                - "account"
                - "name"
              properties:
                account:
                  type: "string"
                  description: "X account (@username or ID) creating the community"
                  example: "@elonmusk"
                name:
                  type: "string"
                  description: "Community name"
                  example: "Example Name"
                description:
                  type: "string"
                  description: "Community description"
                  example: "A community for Tesla enthusiasts"
            example:
              account: "@elonmusk"
              name: "Example Name"
              description: "A community for Tesla enthusiasts"
      responses:
        "200":
          $ref: "#/components/responses/WriteActionCompleted"
        "202":
          $ref: "#/components/responses/WriteActionAccepted"
        "400":
          $ref: "#/components/responses/WriteInvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/AccountAuthError"
        "404":
          $ref: "#/components/responses/XAccountNotFound"
        "409":
          $ref: "#/components/responses/WriteIdempotencyConflict"
        "422":
          $ref: "#/components/responses/WriteRejected"
        "429":
          $ref: "#/components/responses/WriteRateLimited"
        "500":
          $ref: "#/components/responses/WriteError"
        "503":
          $ref: "#/components/responses/WriteTrackingUnavailable"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Create community."
  /api/v1/x/communities/{id}:
    delete:
      operationId: "deleteCommunity"
      x-write-action: "delete_community"
      summary: "Delete community"
      tags:
        - "X Write"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/WriteIdempotencyKey"
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        description: "Account and community name for deletion confirmation."
        content:
          application/json:
            schema:
              type: "object"
              required:
                - "account"
                - "community_name"
              properties:
                account:
                  type: "string"
                  description: "X account (@username or ID) deleting the community"
                  example: "@elonmusk"
                community_name:
                  type: "string"
                  description: "Community name for confirmation"
                  example: "Tesla Fans"
            example:
              account: "@elonmusk"
              community_name: "Tesla Fans"
      responses:
        "200":
          $ref: "#/components/responses/WriteActionCompleted"
        "202":
          $ref: "#/components/responses/WriteActionAccepted"
        "400":
          $ref: "#/components/responses/WriteInvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/AccountAuthError"
        "404":
          $ref: "#/components/responses/XAccountNotFound"
        "409":
          $ref: "#/components/responses/WriteIdempotencyConflict"
        "422":
          $ref: "#/components/responses/WriteRejected"
        "429":
          $ref: "#/components/responses/WriteRateLimited"
        "500":
          $ref: "#/components/responses/WriteError"
        "503":
          $ref: "#/components/responses/WriteTrackingUnavailable"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Delete community."
  /api/v1/x/communities/{id}/join:
    post:
      operationId: "joinCommunity"
      x-write-action: "join_community"
      summary: "Join community"
      tags:
        - "X Write"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/WriteIdempotencyKey"
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        description: "Account to join the community."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XAccountBody"
      responses:
        "200":
          $ref: "#/components/responses/WriteActionCompleted"
        "202":
          $ref: "#/components/responses/WriteActionAccepted"
        "400":
          $ref: "#/components/responses/WriteInvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/AccountAuthError"
        "404":
          $ref: "#/components/responses/XAccountNotFound"
        "409":
          $ref: "#/components/responses/WriteIdempotencyConflict"
        "422":
          $ref: "#/components/responses/WriteRejected"
        "429":
          $ref: "#/components/responses/WriteRateLimited"
        "500":
          $ref: "#/components/responses/WriteError"
        "503":
          $ref: "#/components/responses/WriteTrackingUnavailable"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Join community."
    delete:
      operationId: "leaveCommunity"
      x-write-action: "leave_community"
      summary: "Leave community"
      tags:
        - "X Write"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/WriteIdempotencyKey"
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        description: "Account to leave the community."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XAccountBody"
      responses:
        "200":
          $ref: "#/components/responses/WriteActionCompleted"
        "202":
          $ref: "#/components/responses/WriteActionAccepted"
        "400":
          $ref: "#/components/responses/WriteInvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/AccountAuthError"
        "404":
          $ref: "#/components/responses/XAccountNotFound"
        "409":
          $ref: "#/components/responses/WriteIdempotencyConflict"
        "422":
          $ref: "#/components/responses/WriteRejected"
        "429":
          $ref: "#/components/responses/WriteRateLimited"
        "500":
          $ref: "#/components/responses/WriteError"
        "503":
          $ref: "#/components/responses/WriteTrackingUnavailable"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Leave community."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List connected X accounts."
    post:
      operationId: "connectXAccount"
      summary: "Connect X account"
      tags:
        - "X Accounts"
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: "X credentials (username, email, password) and the Authenticator
          App 2FA secret required for a durable connection."
        content:
          application/json:
            schema:
              type: "object"
              required:
                - "username"
                - "email"
                - "password"
                - "totp_secret"
              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: "Authenticator App TOTP secret required for durable login"
                  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:
                type: "object"
                allOf:
                  - $ref: "#/components/schemas/SanitizedXAccount"
                x-stainless-override-schema:
                  x-stainless-naming:
                    csharp:
                      type_name: "AccountCreateResponse"
                  oneOf:
                    - $ref: "#/components/schemas/SanitizedXAccount"
                    - $ref: "#/components/schemas/XAccountConnectionContinuation"
        "202":
          description: "Connection continues or needs an email code"
          headers:
            Cache-Control:
              description: "Prevents caching. Present when the response status is `pending`."
              schema:
                type: "string"
                const: "no-store"
            Location:
              description: "Status URL. Present when the response status is `pending`."
              schema:
                type: "string"
                example: "/api/v1/x/account-connection-attempts/xatt_0123456789abcdef0123456789\
                  abcdef"
            Retry-After:
              description: "Seconds before checking again. Present when the response status is
                `pending`."
              schema:
                type: "integer"
                minimum: 0
                example: 3
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/XAccountConnectionContinuation"
        "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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Connect X account."
  /api/v1/x/account-connection-attempts/{id}:
    get:
      operationId: "getXAccountConnectionAttempt"
      summary: "Get X account connection status"
      tags:
        - "X Accounts"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/ConnectionAttemptId"
      responses:
        "200":
          description: "Current X account connection status"
          headers:
            Cache-Control:
              description: "Prevents caching of connection status."
              schema:
                type: "string"
                const: "no-store"
            Retry-After:
              description: "Seconds before checking again. Present when the response status is
                `pending`."
              schema:
                type: "integer"
                minimum: 0
                example: 3
          content:
            application/json:
              schema:
                x-stainless-naming:
                  csharp:
                    type_name: "AccountConnectionAttemptRetrieveResponse"
                oneOf:
                  - $ref: "#/components/schemas/XAccountConnectionAttemptPending"
                  - $ref: "#/components/schemas/XAccountConnectionAttemptSuccess"
                  - $ref: "#/components/schemas/XAccountConnectionAttemptFailed"
                  - $ref: "#/components/schemas/XAccountConnectionChallenge"
                discriminator:
                  propertyName: "status"
                  mapping:
                    pending: "#/components/schemas/XAccountConnectionAttemptPending"
                    success: "#/components/schemas/XAccountConnectionAttemptSuccess"
                    failed: "#/components/schemas/XAccountConnectionAttemptFailed"
                    requires_email_code: "#/components/schemas/XAccountConnectionChallenge"
              example:
                object: "x_account_connection_attempt"
                id: "xatt_0123456789abcdef0123456789abcdef"
                status: "pending"
                pollAfterMs: 3000
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get X account connection status."
  /api/v1/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":
          description: "Verification challenge is no longer active"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "connection_challenge_inactive"
                message: "Connection challenge is no longer active."
        "410":
          description: "Verification code expired"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "connection_challenge_expired"
                message: "Verification code expired. Start again."
        "422":
          $ref: "#/components/responses/ConnectLoginFailed"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "503":
          $ref: "#/components/responses/ConnectServiceUnavailable"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Submit X account email verification code."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get X account details."
    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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Disconnect X account."
  /api/v1/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: "Replacement Authenticator App TOTP secret. Omit it to reuse the
                    saved secret."
                  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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Re-authenticate X account."
  /api/v1/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.\n"
      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"
        default:
          $ref: "#/components/responses/UnexpectedError"
  /api/v1/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"
                        promotedContent:
                          type:
                            - "string"
                            - "null"
                          description: "Promotion identifier from X. Null for organic trends."
                        rank:
                          type: "integer"
                          example: 1
                        tweetVolume:
                          type:
                            - "integer"
                            - "null"
                          description: "Approximate public post volume when X supplies it."
                          example: 250000
                        url:
                          type: "string"
                          format: "uri"
                          description: "X search URL for the trend."
                    example:
                      - name: "#AI"
                        rank: 1
                  total:
                    type: "integer"
                    example: 30
                  woeid:
                    type: "integer"
                    example: 1
              example:
                trends:
                  - name: "#AI"
                    description: "Artificial intelligence discussions"
                    promotedContent: null
                    query: "%23AI"
                    rank: 1
                    tweetVolume: 250000
                    url: "https://x.com/search?q=%23AI"
                total: 30
                woeid: 1
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get trending hashtags and topics by region (alias)."
  /api/v1/support/attachments/{id}:
    get:
      operationId: "downloadSupportAttachment"
      summary: "Download support ticket media"
      description: "Streams an authenticated user's support image or video. Video
        requests support one standard byte range for seeking and resumable
        playback.\n"
      tags:
        - "Support"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "Support attachment public ID"
          example: "att_a1b2c3d4e5f6a1b2c3d4e5f6"
        - name: "Range"
          in: "header"
          required: false
          schema:
            type: "string"
            pattern: "^bytes=(?:[0-9]+-[0-9]*|-[0-9]+)$"
          description: "Optional single byte range"
          example: "bytes=0-1048575"
      responses:
        "200":
          description: "Complete image or video bytes"
          content:
            application/octet-stream:
              schema:
                type: "string"
                format: "binary"
        "206":
          description: "Requested partial video bytes"
          content:
            application/octet-stream:
              schema:
                type: "string"
                format: "binary"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "404":
          $ref: "#/components/responses/NotFound"
        "416":
          description: "Invalid or unsatisfiable byte range"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "invalid_range"
                message: "Use one valid byte range."
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        default:
          $ref: "#/components/responses/UnexpectedError"
  /api/v1/support/tickets:
    post:
      operationId: "createTicket"
      summary: "Create a support ticket"
      tags:
        - "Support"
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: "#/components/parameters/SupportIdempotencyKey"
      requestBody:
        required: true
        description: "Ticket subject and message body."
        content:
          application/json:
            schema:
              type: "object"
              required:
                - "subject"
                - "body"
              properties:
                subject:
                  type: "string"
                  minLength: 1
                  maxLength: 500
                  pattern: ".*\\S.*"
                  example: "Cannot connect X account"
                body:
                  type: "string"
                  minLength: 1
                  maxLength: 10000
                  pattern: ".*\\S.*"
                  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."
          multipart/form-data:
            example:
              subject: "Cannot connect X account"
              body: "I am unable to connect my X account."
              attachments:
                - "screen.png"
            schema:
              type: "object"
              required:
                - "subject"
              anyOf:
                - required:
                    - "body"
                - required:
                    - "attachments"
              properties:
                subject:
                  type: "string"
                  minLength: 1
                  maxLength: 500
                  pattern: ".*\\S.*"
                  example: "Cannot connect X account"
                body:
                  type: "string"
                  minLength: 1
                  maxLength: 10000
                  pattern: ".*\\S.*"
                  example: "I am unable to connect my X account."
                attachments:
                  type: "array"
                  minItems: 1
                  maxItems: 4
                  example:
                    - "screen.png"
                  items:
                    type: "string"
                    format: "binary"
      responses:
        "200":
          description: "Original ticket replayed after a safe retry"
          headers:
            Idempotency-Replayed:
              description: "Present as true when replaying the same request."
              schema:
                type: "string"
                const: "true"
          content:
            application/json:
              schema:
                type: "object"
                required:
                  - "publicId"
                  - "attachments"
                properties:
                  publicId:
                    type: "string"
                    example: "tkt_a1b2c3d4e5f6a1b2c3d4e5f6"
                  attachments:
                    type: "array"
                    example: []
                    items:
                      $ref: "#/components/schemas/SupportAttachmentReceipt"
              example:
                publicId: "tkt_a1b2c3d4e5f6a1b2c3d4e5f6"
                attachments: []
        "201":
          description: "Ticket created"
          content:
            application/json:
              schema:
                type: "object"
                required:
                  - "publicId"
                  - "attachments"
                properties:
                  publicId:
                    type: "string"
                    example: "tkt_a1b2c3d4e5f6a1b2c3d4e5f6"
                  attachments:
                    type: "array"
                    example: []
                    items:
                      $ref: "#/components/schemas/SupportAttachmentReceipt"
              example:
                publicId: "tkt_a1b2c3d4e5f6a1b2c3d4e5f6"
                attachments: []
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "409":
          description: "Idempotency-Key was reused with different content."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "idempotency_key_conflict"
                message: "Reuse this Idempotency-Key only with the original request."
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Create a support ticket."
    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"
                required:
                  - "tickets"
                properties:
                  tickets:
                    type: "array"
                    items:
                      type: "object"
                      required:
                        - "publicId"
                        - "subject"
                        - "status"
                        - "messageCount"
                        - "createdAt"
                        - "updatedAt"
                      properties:
                        publicId:
                          type: "string"
                          example: "tkt_a1b2c3d4e5f6a1b2c3d4e5f6"
                        subject:
                          type: "string"
                          example: "Cannot connect X account"
                        status:
                          type: "string"
                          enum:
                            - "open"
                            - "in_progress"
                            - "resolved"
                            - "closed"
                          example: "open"
                        messageCount:
                          type: "integer"
                          minimum: 1
                          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"
                        messageCount: 2
                        createdAt: "2025-01-15T12:00:00Z"
                        updatedAt: "2025-01-16T09:30:00Z"
              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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List user's support tickets."
  /api/v1/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"
                required:
                  - "publicId"
                  - "subject"
                  - "status"
                  - "createdAt"
                  - "updatedAt"
                  - "messages"
                properties:
                  publicId:
                    type: "string"
                    example: "tkt_a1b2c3d4e5f6a1b2c3d4e5f6"
                  subject:
                    type: "string"
                    example: "Cannot connect X account"
                  status:
                    type: "string"
                    enum:
                      - "open"
                      - "in_progress"
                      - "resolved"
                      - "closed"
                    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"
                      required:
                        - "body"
                        - "sender"
                        - "createdAt"
                        - "attachments"
                      properties:
                        body:
                          type: "string"
                          example: "I am unable to connect my X account."
                        sender:
                          type: "string"
                          enum:
                            - "user"
                            - "support"
                            - "system"
                          example: "user"
                        createdAt:
                          type: "string"
                          format: "date-time"
                          example: "2025-01-15T12:00:00Z"
                        attachments:
                          type: "array"
                          items:
                            $ref: "#/components/schemas/SupportAttachment"
                    example:
                      - body: "I am unable to connect my X account."
                        sender: "user"
                        createdAt: "2025-01-15T12:00:00Z"
                        attachments: []
              example:
                publicId: "tkt_a1b2c3d4e5f6a1b2c3d4e5f6"
                subject: "Cannot connect X account"
                status: "open"
                createdAt: "2025-01-15T12:00:00Z"
                updatedAt: "2025-01-16T09:30:00Z"
                messages:
                  - body: "I am unable to connect my X account."
                    sender: "user"
                    createdAt: "2025-01-15T12:00:00Z"
                    attachments: []
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get ticket with all messages."
    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"
                required:
                  - "publicId"
                  - "status"
                properties:
                  publicId:
                    type: "string"
                    example: "tkt_a1b2c3d4e5f6a1b2c3d4e5f6"
                  status:
                    type: "string"
                    enum:
                      - "open"
                      - "resolved"
                      - "closed"
                    example: "resolved"
              example:
                publicId: "tkt_a1b2c3d4e5f6a1b2c3d4e5f6"
                status: "resolved"
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Update ticket status."
  /api/v1/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"
        - $ref: "#/components/parameters/SupportIdempotencyKey"
      requestBody:
        required: true
        description: "Reply message body (max 10,000 characters)."
        content:
          application/json:
            schema:
              type: "object"
              required:
                - "body"
              properties:
                body:
                  type: "string"
                  minLength: 1
                  maxLength: 10000
                  pattern: ".*\\S.*"
                  title: "MessageContent"
                  example: "Thank you for the update."
            example:
              body: "Thank you for the update."
          multipart/form-data:
            example:
              body: "Thank you for the update."
              attachments:
                - "details.png"
            schema:
              type: "object"
              anyOf:
                - required:
                    - "body"
                - required:
                    - "attachments"
              properties:
                body:
                  type: "string"
                  minLength: 1
                  maxLength: 10000
                  pattern: ".*\\S.*"
                  example: "Thank you for the update."
                attachments:
                  type: "array"
                  minItems: 1
                  maxItems: 4
                  example:
                    - "details.png"
                  items:
                    type: "string"
                    format: "binary"
      responses:
        "200":
          description: "Original message replayed after a safe retry"
          headers:
            Idempotency-Replayed:
              description: "Set to true when this message replays."
              schema:
                type: "string"
                const: "true"
          content:
            application/json:
              schema:
                type: "object"
                required:
                  - "publicId"
                  - "attachments"
                properties:
                  publicId:
                    type: "string"
                    example: "tkt_a1b2c3d4e5f6a1b2c3d4e5f6"
                  attachments:
                    type: "array"
                    example: []
                    items:
                      $ref: "#/components/schemas/SupportAttachmentReceipt"
              example:
                publicId: "tkt_a1b2c3d4e5f6a1b2c3d4e5f6"
                attachments: []
        "201":
          description: "Message added"
          content:
            application/json:
              schema:
                type: "object"
                required:
                  - "publicId"
                  - "attachments"
                properties:
                  publicId:
                    type: "string"
                    example: "tkt_a1b2c3d4e5f6a1b2c3d4e5f6"
                  attachments:
                    type: "array"
                    example: []
                    items:
                      $ref: "#/components/schemas/SupportAttachmentReceipt"
              example:
                publicId: "tkt_a1b2c3d4e5f6a1b2c3d4e5f6"
                attachments: []
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "Reply key was reused with different message content."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "idempotency_key_conflict"
                message: "Reuse this Idempotency-Key only with the original request."
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Reply to a support ticket."
  /api/v1/guest-wallets:
    post:
      operationId: "createGuestWallet"
      summary: "Create an accountless prepaid wallet checkout"
      description: "Create a one-use hosted checkout after the user confirms $10-$250
        USD. The request creates no charge. It returns a paid-read API key
        without an Xquik account. Idempotent replays return the same key.\n"
      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: "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: "Set to true when this wallet creation replays."
              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://checkout.example/guest/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 the
                  hosted checkout page. 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"
              example:
                error: "idempotency_conflict"
                message: "Reuse this Idempotency-Key only with the original request."
        "410":
          description: "Checkout expired or can no longer be used."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "checkout_unavailable"
                message: "Checkout unavailable. Retry with a new Idempotency-Key."
        "413":
          description: "Request body is too large."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "body_too_large"
                message: "Request body is too large."
        "415":
          description: "Content-Type must be application/json."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "unsupported_media_type"
                message: "Send Content-Type: application/json."
        "423":
          description: "Guest wallet is unavailable."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "guest_wallet_unavailable"
                message: "Guest wallet unavailable. Create a new wallet or contact support."
        "429":
          $ref: "#/components/responses/GuestWalletRateLimited"
        "503":
          description: "Guest wallet checkout is unavailable."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "guest_wallets_unavailable"
                message: "Guest wallet checkout is temporarily unavailable."
        default:
          $ref: "#/components/responses/UnexpectedError"
  /api/v1/guest-wallets/topups:
    post:
      operationId: "topUpGuestWallet"
      summary: "Create another guest wallet checkout"
      description: "Create a one-use hosted checkout after the user confirms a
        $10-$250 USD amount for an existing paid-read guest key. The key remains
        the same. This request creates no charge and never redirects through
        Xquik.\n"
      tags:
        - "Guest Wallets"
      security:
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/GuestIdempotencyKey"
      requestBody:
        required: true
        description: "Confirmed top-up amount in USD cents."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GuestWalletPurchaseRequest"
            example:
              amount_minor: 1000
              currency: "usd"
      responses:
        "201":
          description: "Hosted checkout and API status URL."
          headers:
            Cache-Control:
              description: "Prevents caching the top-up checkout response."
              schema:
                type: "string"
                const: "no-store, private"
            Idempotent-Replayed:
              description: "Set to true when this top-up replays."
              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://checkout.example/guest/example"
                credits: "66666"
                expires_at: "2026-07-13T13:00:00.000Z"
                instructions: "Give checkout_url to the user. They must complete payment on the
                  hosted checkout page. 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: "Top-up key was reused with a different request."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "idempotency_conflict"
                message: "Reuse this Idempotency-Key only with the original request."
        "410":
          description: "Top-up checkout expired or became unavailable."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "checkout_unavailable"
                message: "Checkout unavailable. Retry with a new Idempotency-Key."
        "413":
          description: "Top-up request body is too large."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "body_too_large"
                message: "Request body is too large."
        "415":
          description: "Top-up requires Content-Type application/json."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "unsupported_media_type"
                message: "Send Content-Type: application/json."
        "423":
          description: "Guest wallet cannot accept a top-up."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "guest_wallet_unavailable"
                message: "Guest wallet unavailable. Create a new wallet or contact support."
        "429":
          $ref: "#/components/responses/GuestWalletRateLimited"
        "503":
          description: "Guest wallet top-up checkout is unavailable."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "guest_wallets_unavailable"
                message: "Guest wallet checkout is temporarily unavailable."
        default:
          $ref: "#/components/responses/UnexpectedError"
  /api/v1/guest-wallets/status:
    get:
      operationId: "getGuestWalletStatus"
      summary: "Get guest wallet and payment status"
      description: "Poll after 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 payment is verified. Send the guest key
        as Authorization: Bearer.\n"
      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/GuestWalletRateLimited"
        default:
          $ref: "#/components/responses/UnexpectedError"
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get credits balance."
  /api/v1/credits/topup:
    post:
      operationId: "topUpCredits"
      summary: "Create credit top-up checkout"
      description: "Create a hosted checkout only after the user confirms. The request
        never completes payment or adds credits.\n"
      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 checkouts"
          content:
            application/json:
              schema:
                type: "object"
                required:
                  - "url"
                  - "redirect_url"
                properties:
                  redirect_url:
                    type: "string"
                    format: "uri"
                    description: "Stable Xquik redirect URL for the active checkout."
                    example: "https://xquik.com/api/v1/credits/topup/redirect?session_id=checkout_e\
                      xample"
                  url:
                    type: "string"
                    format: "uri"
                    description: "Same stable Xquik redirect URL as redirect_url. The response never
                      exposes the hosted checkout URL.\n"
                    example: "https://xquik.com/api/v1/credits/topup/redirect?session_id=checkout_e\
                      xample"
              example:
                redirect_url: "https://xquik.com/api/v1/credits/topup/redirect?session_id=check\
                  out_example"
                url: "https://xquik.com/api/v1/credits/topup/redirect?session_id=checkout_examp\
                  le"
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        default:
          $ref: "#/components/responses/UnexpectedError"
  /api/v1/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: "Top-up session ID to inspect."
      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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get top-up billing status."
  /api/v1/credits/quick-topup:
    post:
      operationId: "quickTopUpCredits"
      summary: "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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Charge saved card for credits."
  /api/v1/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.\n"
      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"
        - $ref: "#/components/parameters/UserFilterMinFollowers"
        - $ref: "#/components/parameters/UserFilterMaxFollowers"
        - $ref: "#/components/parameters/UserFilterMinFollowing"
        - $ref: "#/components/parameters/UserFilterMaxFollowing"
        - $ref: "#/components/parameters/UserFilterMinStatuses"
        - $ref: "#/components/parameters/UserFilterMaxStatuses"
        - $ref: "#/components/parameters/UserFilterMinAccountAgeDays"
        - $ref: "#/components/parameters/UserFilterVerifiedOnly"
        - $ref: "#/components/parameters/UserFilterVerifiedType"
        - $ref: "#/components/parameters/UserFilterHasWebsite"
        - $ref: "#/components/parameters/UserFilterHasLocation"
        - $ref: "#/components/parameters/UserFilterBioContains"
        - $ref: "#/components/parameters/UserFilterLocationContains"
        - $ref: "#/components/parameters/UserFilterUsernameContains"
      responses:
        "200":
          description: "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"
        "424":
          $ref: "#/components/responses/FavoritersUnavailable"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
  /api/v1/x/users/{id}/tweets:
    get:
      operationId: "getUserTweets"
      summary: "List recent tweets posted by a user"
      description: "Omit mode for automatic maximum coverage. Pass next_cursor
        unchanged. Unprefixed cursors use legacy pagination. Shape and billing
        stay the same.\n"
      tags:
        - "Users"
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "X user ID or username"
        - $ref: "#/components/parameters/AutomaticCoverageCursor"
        - $ref: "#/components/parameters/AutomaticTweetPageSize"
        - 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/TweetFilterMinViews"
        - $ref: "#/components/parameters/TweetFilterMinBookmarks"
        - $ref: "#/components/parameters/TweetFilterMaxFaves"
        - $ref: "#/components/parameters/TweetFilterMaxRetweets"
        - $ref: "#/components/parameters/TweetFilterMaxReplies"
        - $ref: "#/components/parameters/TweetFilterMaxQuotes"
        - $ref: "#/components/parameters/TweetFilterBlueVerifiedOnly"
        - $ref: "#/components/parameters/TweetFilterCardName"
        - $ref: "#/components/parameters/TweetFilterSource"
        - $ref: "#/components/parameters/TweetFilterExcludeSource"
        - $ref: "#/components/parameters/TweetFilterGeocode"
        - $ref: "#/components/parameters/TweetFilterSinceId"
        - $ref: "#/components/parameters/TweetFilterMaxId"
        - $ref: "#/components/parameters/TweetFilterNear"
        - $ref: "#/components/parameters/TweetFilterWithin"
        - $ref: "#/components/parameters/TweetFilterWithinTime"
        - $ref: "#/components/parameters/TweetFilterNativeRetweets"
        - $ref: "#/components/parameters/TweetFilterSafe"
        - $ref: "#/components/parameters/TweetFilterNews"
        - $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/UserNotFound"
        "409":
          $ref: "#/components/responses/CoverageCursorUnavailable"
        "410":
          $ref: "#/components/responses/CursorGone"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        "503":
          $ref: "#/components/responses/MaximumCoverageBusy"
        default:
          $ref: "#/components/responses/UnexpectedError"
  /api/v1/x/users/{id}/replies:
    get:
      operationId: "getUserReplies"
      summary: "List a user's With Replies timeline"
      description: "Returns target-authored posts and replies. Omit mode for automatic
        maximum coverage. Pass next_cursor unchanged. Unprefixed cursors stay
        legacy. Excludes other-author context."
      tags:
        - "Users"
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "Target user ID or username for the replies timeline."
        - $ref: "#/components/parameters/AutomaticCoverageCursor"
        - $ref: "#/components/parameters/AutomaticTweetPageSize"
        - name: "includeParentTweet"
          in: "query"
          schema:
            type: "boolean"
            default: false
          description: "Include each reply's parent tweet."
        - $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/TweetFilterMinViews"
        - $ref: "#/components/parameters/TweetFilterMinBookmarks"
        - $ref: "#/components/parameters/TweetFilterMaxFaves"
        - $ref: "#/components/parameters/TweetFilterMaxRetweets"
        - $ref: "#/components/parameters/TweetFilterMaxReplies"
        - $ref: "#/components/parameters/TweetFilterMaxQuotes"
        - $ref: "#/components/parameters/TweetFilterBlueVerifiedOnly"
        - $ref: "#/components/parameters/TweetFilterCardName"
        - $ref: "#/components/parameters/TweetFilterSource"
        - $ref: "#/components/parameters/TweetFilterExcludeSource"
        - $ref: "#/components/parameters/TweetFilterGeocode"
        - $ref: "#/components/parameters/TweetFilterSinceId"
        - $ref: "#/components/parameters/TweetFilterMaxId"
        - $ref: "#/components/parameters/TweetFilterNear"
        - $ref: "#/components/parameters/TweetFilterWithin"
        - $ref: "#/components/parameters/TweetFilterWithinTime"
        - $ref: "#/components/parameters/TweetFilterNativeRetweets"
        - $ref: "#/components/parameters/TweetFilterSafe"
        - $ref: "#/components/parameters/TweetFilterNews"
        - $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/UserNotFound"
        "409":
          $ref: "#/components/responses/CoverageCursorUnavailable"
        "410":
          $ref: "#/components/responses/CursorGone"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        "503":
          $ref: "#/components/responses/MaximumCoverageBusy"
        default:
          $ref: "#/components/responses/UnexpectedError"
  /api/v1/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/TweetFilterMinViews"
        - $ref: "#/components/parameters/TweetFilterMinBookmarks"
        - $ref: "#/components/parameters/TweetFilterMaxFaves"
        - $ref: "#/components/parameters/TweetFilterMaxRetweets"
        - $ref: "#/components/parameters/TweetFilterMaxReplies"
        - $ref: "#/components/parameters/TweetFilterMaxQuotes"
        - $ref: "#/components/parameters/TweetFilterBlueVerifiedOnly"
        - $ref: "#/components/parameters/TweetFilterCardName"
        - $ref: "#/components/parameters/TweetFilterSource"
        - $ref: "#/components/parameters/TweetFilterExcludeSource"
        - $ref: "#/components/parameters/TweetFilterGeocode"
        - $ref: "#/components/parameters/TweetFilterSinceId"
        - $ref: "#/components/parameters/TweetFilterMaxId"
        - $ref: "#/components/parameters/TweetFilterNear"
        - $ref: "#/components/parameters/TweetFilterWithin"
        - $ref: "#/components/parameters/TweetFilterWithinTime"
        - $ref: "#/components/parameters/TweetFilterNativeRetweets"
        - $ref: "#/components/parameters/TweetFilterSafe"
        - $ref: "#/components/parameters/TweetFilterNews"
        - $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/UserNotFound"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List tweets liked by a user."
  /api/v1/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/TweetFilterMinViews"
        - $ref: "#/components/parameters/TweetFilterMinBookmarks"
        - $ref: "#/components/parameters/TweetFilterMaxFaves"
        - $ref: "#/components/parameters/TweetFilterMaxRetweets"
        - $ref: "#/components/parameters/TweetFilterMaxReplies"
        - $ref: "#/components/parameters/TweetFilterMaxQuotes"
        - $ref: "#/components/parameters/TweetFilterBlueVerifiedOnly"
        - $ref: "#/components/parameters/TweetFilterCardName"
        - $ref: "#/components/parameters/TweetFilterSource"
        - $ref: "#/components/parameters/TweetFilterExcludeSource"
        - $ref: "#/components/parameters/TweetFilterGeocode"
        - $ref: "#/components/parameters/TweetFilterSinceId"
        - $ref: "#/components/parameters/TweetFilterMaxId"
        - $ref: "#/components/parameters/TweetFilterNear"
        - $ref: "#/components/parameters/TweetFilterWithin"
        - $ref: "#/components/parameters/TweetFilterWithinTime"
        - $ref: "#/components/parameters/TweetFilterNativeRetweets"
        - $ref: "#/components/parameters/TweetFilterSafe"
        - $ref: "#/components/parameters/TweetFilterNews"
        - $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/UserNotFound"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List media tweets posted by a user."
  /api/v1/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"
        - $ref: "#/components/parameters/UserFilterMinFollowers"
        - $ref: "#/components/parameters/UserFilterMaxFollowers"
        - $ref: "#/components/parameters/UserFilterMinFollowing"
        - $ref: "#/components/parameters/UserFilterMaxFollowing"
        - $ref: "#/components/parameters/UserFilterMinStatuses"
        - $ref: "#/components/parameters/UserFilterMaxStatuses"
        - $ref: "#/components/parameters/UserFilterMinAccountAgeDays"
        - $ref: "#/components/parameters/UserFilterVerifiedOnly"
        - $ref: "#/components/parameters/UserFilterVerifiedType"
        - $ref: "#/components/parameters/UserFilterHasWebsite"
        - $ref: "#/components/parameters/UserFilterHasLocation"
        - $ref: "#/components/parameters/UserFilterBioContains"
        - $ref: "#/components/parameters/UserFilterLocationContains"
        - $ref: "#/components/parameters/UserFilterUsernameContains"
      responses:
        "200":
          description: "List of 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"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List mutual followers between you and a user."
  /api/v1/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"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get bookmarked tweets."
  /api/v1/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"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get bookmark folders."
  /api/v1/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"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get notifications."
  /api/v1/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"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get home timeline."
  /api/v1/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.\n"
        - 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.\n"
                    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).\n"
          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`).\n"
          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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get DM conversation history."
  /api/v1/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_nsfw:
                        type: "boolean"
                        description: "Whether the community is marked sensitive"
                      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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get community name, description and member count."
  /api/v1/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.\n"
        - $ref: "#/components/parameters/UserFilterMinFollowers"
        - $ref: "#/components/parameters/UserFilterMaxFollowers"
        - $ref: "#/components/parameters/UserFilterMinFollowing"
        - $ref: "#/components/parameters/UserFilterMaxFollowing"
        - $ref: "#/components/parameters/UserFilterMinStatuses"
        - $ref: "#/components/parameters/UserFilterMaxStatuses"
        - $ref: "#/components/parameters/UserFilterMinAccountAgeDays"
        - $ref: "#/components/parameters/UserFilterVerifiedOnly"
        - $ref: "#/components/parameters/UserFilterVerifiedType"
        - $ref: "#/components/parameters/UserFilterHasWebsite"
        - $ref: "#/components/parameters/UserFilterHasLocation"
        - $ref: "#/components/parameters/UserFilterBioContains"
        - $ref: "#/components/parameters/UserFilterLocationContains"
        - $ref: "#/components/parameters/UserFilterUsernameContains"
      responses:
        "200":
          description: "List of 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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List members of a community."
  /api/v1/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"
        - $ref: "#/components/parameters/UserFilterMinFollowers"
        - $ref: "#/components/parameters/UserFilterMaxFollowers"
        - $ref: "#/components/parameters/UserFilterMinFollowing"
        - $ref: "#/components/parameters/UserFilterMaxFollowing"
        - $ref: "#/components/parameters/UserFilterMinStatuses"
        - $ref: "#/components/parameters/UserFilterMaxStatuses"
        - $ref: "#/components/parameters/UserFilterMinAccountAgeDays"
        - $ref: "#/components/parameters/UserFilterVerifiedOnly"
        - $ref: "#/components/parameters/UserFilterVerifiedType"
        - $ref: "#/components/parameters/UserFilterHasWebsite"
        - $ref: "#/components/parameters/UserFilterHasLocation"
        - $ref: "#/components/parameters/UserFilterBioContains"
        - $ref: "#/components/parameters/UserFilterLocationContains"
        - $ref: "#/components/parameters/UserFilterUsernameContains"
      responses:
        "200":
          description: "List of 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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List moderators of a community."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List tweets posted in a community."
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
  /api/v1/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"
        default:
          $ref: "#/components/responses/UnexpectedError"
  /api/v1/x/lists/{id}/followers:
    get:
      operationId: "getListFollowers"
      summary: "List followers of an X List"
      tags:
        - "Lists"
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "List ID"
        - name: "cursor"
          in: "query"
          schema:
            type: "string"
          description: "Pagination cursor for list followers"
        - $ref: "#/components/parameters/FollowerPageSize"
        - $ref: "#/components/parameters/UserFilterMinFollowers"
        - $ref: "#/components/parameters/UserFilterMaxFollowers"
        - $ref: "#/components/parameters/UserFilterMinFollowing"
        - $ref: "#/components/parameters/UserFilterMaxFollowing"
        - $ref: "#/components/parameters/UserFilterMinStatuses"
        - $ref: "#/components/parameters/UserFilterMaxStatuses"
        - $ref: "#/components/parameters/UserFilterMinAccountAgeDays"
        - $ref: "#/components/parameters/UserFilterVerifiedOnly"
        - $ref: "#/components/parameters/UserFilterVerifiedType"
        - $ref: "#/components/parameters/UserFilterHasWebsite"
        - $ref: "#/components/parameters/UserFilterHasLocation"
        - $ref: "#/components/parameters/UserFilterBioContains"
        - $ref: "#/components/parameters/UserFilterLocationContains"
        - $ref: "#/components/parameters/UserFilterUsernameContains"
      responses:
        "200":
          description: "List of followers"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedUsers"
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/AnonymousGuestAuthenticationRequired"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "404":
          $ref: "#/components/responses/NotFound"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List followers of an X List."
  /api/v1/x/lists/{id}/members:
    get:
      operationId: "getListMembers"
      summary: "List members of an X List"
      tags:
        - "Lists"
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "List ID for member lookup"
        - name: "cursor"
          in: "query"
          schema:
            type: "string"
          description: "Pagination cursor for list members"
        - name: "pageSize"
          in: "query"
          schema:
            type: "integer"
            minimum: 20
            maximum: 200
            default: 20
          description: "Members per page (20-200, default 20)"
        - $ref: "#/components/parameters/UserFilterMinFollowers"
        - $ref: "#/components/parameters/UserFilterMaxFollowers"
        - $ref: "#/components/parameters/UserFilterMinFollowing"
        - $ref: "#/components/parameters/UserFilterMaxFollowing"
        - $ref: "#/components/parameters/UserFilterMinStatuses"
        - $ref: "#/components/parameters/UserFilterMaxStatuses"
        - $ref: "#/components/parameters/UserFilterMinAccountAgeDays"
        - $ref: "#/components/parameters/UserFilterVerifiedOnly"
        - $ref: "#/components/parameters/UserFilterVerifiedType"
        - $ref: "#/components/parameters/UserFilterHasWebsite"
        - $ref: "#/components/parameters/UserFilterHasLocation"
        - $ref: "#/components/parameters/UserFilterBioContains"
        - $ref: "#/components/parameters/UserFilterLocationContains"
        - $ref: "#/components/parameters/UserFilterUsernameContains"
      responses:
        "200":
          description: "List of members"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedUsers"
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/AnonymousGuestAuthenticationRequired"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "404":
          $ref: "#/components/responses/NotFound"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List members of an X List."
  /api/v1/x/lists/{id}/tweets:
    get:
      operationId: "getListTweets"
      summary: "List tweets from an X List"
      tags:
        - "Lists"
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "List ID for tweet lookup"
        - name: "cursor"
          in: "query"
          schema:
            type: "string"
          description: "Pagination cursor for list tweets"
        - $ref: "#/components/parameters/ResultPageSize"
        - name: "sinceTime"
          in: "query"
          schema:
            type: "string"
          description: "Unix timestamp - filter after"
        - name: "untilTime"
          in: "query"
          schema:
            type: "string"
          description: "Unix timestamp - filter before"
        - name: "includeReplies"
          in: "query"
          schema:
            type: "boolean"
          description: "Include replies (default false)"
      responses:
        "200":
          description: "List tweets"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedTweets"
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/AnonymousGuestAuthenticationRequired"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "404":
          $ref: "#/components/responses/NotFound"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List tweets from an X List."
  /api/v1/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"
        - $ref: "#/components/parameters/AutomaticCoverageCursor"
        - name: "mode"
          in: "query"
          schema:
            type: "string"
            enum:
              - "standard"
          description: "Optional legacy pagination override."
        - $ref: "#/components/parameters/AutomaticTweetPageSize"
        - 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/TweetFilterMinViews"
        - $ref: "#/components/parameters/TweetFilterMinBookmarks"
        - $ref: "#/components/parameters/TweetFilterMaxFaves"
        - $ref: "#/components/parameters/TweetFilterMaxRetweets"
        - $ref: "#/components/parameters/TweetFilterMaxReplies"
        - $ref: "#/components/parameters/TweetFilterMaxQuotes"
        - $ref: "#/components/parameters/TweetFilterBlueVerifiedOnly"
        - $ref: "#/components/parameters/TweetFilterCardName"
        - $ref: "#/components/parameters/TweetFilterSource"
        - $ref: "#/components/parameters/TweetFilterExcludeSource"
        - $ref: "#/components/parameters/TweetFilterGeocode"
        - $ref: "#/components/parameters/TweetFilterSinceId"
        - $ref: "#/components/parameters/TweetFilterMaxId"
        - $ref: "#/components/parameters/TweetFilterNear"
        - $ref: "#/components/parameters/TweetFilterWithin"
        - $ref: "#/components/parameters/TweetFilterWithinTime"
        - $ref: "#/components/parameters/TweetFilterNativeRetweets"
        - $ref: "#/components/parameters/TweetFilterSafe"
        - $ref: "#/components/parameters/TweetFilterNews"
        - $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"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List quote tweets of a tweet."
  /api/v1/x/tweets/{id}/replies:
    get:
      operationId: "getTweetReplies"
      summary: "List replies to a tweet"
      description: "Returns direct replies. Omit mode for automatic maximum coverage
        with resumable pagination. Complete mode returns nested replies,
        diagnostics, and 424 when direct coverage stays below 80%.\n"
      tags:
        - "Tweets"
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      parameters:
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "Tweet ID to get replies"
        - $ref: "#/components/parameters/AutomaticCoverageCursor"
        - name: "mode"
          in: "query"
          schema:
            type: "string"
            enum:
              - "standard"
              - "complete"
          description: "Optional advanced override. Omit mode for automatic maximum direct
            reply coverage with pagination. Standard keeps legacy pagination.
            Complete returns direct and nested replies with diagnostics, scope,
            depth, sorting, and original-post controls.\n"
        - name: "limit"
          in: "query"
          schema:
            type: "integer"
            minimum: 1
            maximum: 25000
          description: "With mode=complete, maximum combined direct and nested reply rows
            (1-25000, default 25000). Automatic pages accept 1-300. Standard
            pages accept 1-100. Prefer pageSize outside complete mode.\n"
        - $ref: "#/components/parameters/AutomaticTweetPageSize"
        - name: "scope"
          in: "query"
          schema:
            type: "string"
            enum:
              - "all"
              - "direct"
              - "nested"
            default: "all"
          description: "Select all replies, direct replies, or nested replies."
        - name: "maxDepth"
          in: "query"
          schema:
            type: "integer"
            minimum: 1
          description: "Maximum reply depth from the source post."
        - name: "sort"
          in: "query"
          schema:
            type: "string"
            enum:
              - "relevance"
              - "latest"
              - "oldest"
              - "likes"
            default: "relevance"
          description: "Sort the selected replies before applying limit."
        - name: "excludeOriginalAuthor"
          in: "query"
          schema:
            type: "boolean"
            default: false
          description: "Exclude replies written by the source-post author."
        - name: "includeOriginalPost"
          in: "query"
          schema:
            type: "boolean"
            default: false
          description: "Include the source post and count it toward limit."
        - name: "hasMediaOnly"
          in: "query"
          schema:
            type: "boolean"
            default: false
          description: "Only return replies containing media."
        - 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/TweetFilterMinViews"
        - $ref: "#/components/parameters/TweetFilterMinBookmarks"
        - $ref: "#/components/parameters/TweetFilterMaxFaves"
        - $ref: "#/components/parameters/TweetFilterMaxRetweets"
        - $ref: "#/components/parameters/TweetFilterMaxReplies"
        - $ref: "#/components/parameters/TweetFilterMaxQuotes"
        - $ref: "#/components/parameters/TweetFilterBlueVerifiedOnly"
        - $ref: "#/components/parameters/TweetFilterCardName"
        - $ref: "#/components/parameters/TweetFilterSource"
        - $ref: "#/components/parameters/TweetFilterExcludeSource"
        - $ref: "#/components/parameters/TweetFilterGeocode"
        - $ref: "#/components/parameters/TweetFilterSinceId"
        - $ref: "#/components/parameters/TweetFilterMaxId"
        - $ref: "#/components/parameters/TweetFilterNear"
        - $ref: "#/components/parameters/TweetFilterWithin"
        - $ref: "#/components/parameters/TweetFilterWithinTime"
        - $ref: "#/components/parameters/TweetFilterNativeRetweets"
        - $ref: "#/components/parameters/TweetFilterSafe"
        - $ref: "#/components/parameters/TweetFilterNews"
        - $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/TweetReplies"
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/AnonymousGuestAuthenticationRequired"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "409":
          $ref: "#/components/responses/CoverageCursorUnavailable"
        "410":
          $ref: "#/components/responses/CursorGone"
        "424":
          $ref: "#/components/responses/RepliesIncomplete"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        "503":
          $ref: "#/components/responses/MaximumCoverageBusy"
        default:
          $ref: "#/components/responses/UnexpectedError"
  /api/v1/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"
        - $ref: "#/components/parameters/UserFilterMinFollowers"
        - $ref: "#/components/parameters/UserFilterMaxFollowers"
        - $ref: "#/components/parameters/UserFilterMinFollowing"
        - $ref: "#/components/parameters/UserFilterMaxFollowing"
        - $ref: "#/components/parameters/UserFilterMinStatuses"
        - $ref: "#/components/parameters/UserFilterMaxStatuses"
        - $ref: "#/components/parameters/UserFilterMinAccountAgeDays"
        - $ref: "#/components/parameters/UserFilterVerifiedOnly"
        - $ref: "#/components/parameters/UserFilterVerifiedType"
        - $ref: "#/components/parameters/UserFilterHasWebsite"
        - $ref: "#/components/parameters/UserFilterHasLocation"
        - $ref: "#/components/parameters/UserFilterBioContains"
        - $ref: "#/components/parameters/UserFilterLocationContains"
        - $ref: "#/components/parameters/UserFilterUsernameContains"
      responses:
        "200":
          description: "List of retweeters"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedUsers"
        "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"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List users who retweeted a tweet."
  /api/v1/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"
        - $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/TweetFilterMinViews"
        - $ref: "#/components/parameters/TweetFilterMinBookmarks"
        - $ref: "#/components/parameters/TweetFilterMaxFaves"
        - $ref: "#/components/parameters/TweetFilterMaxRetweets"
        - $ref: "#/components/parameters/TweetFilterMaxReplies"
        - $ref: "#/components/parameters/TweetFilterMaxQuotes"
        - $ref: "#/components/parameters/TweetFilterBlueVerifiedOnly"
        - $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: "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"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "Get full conversation thread for a tweet."
  /api/v1/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: "Target user ID or username for follower lookup."
        - $ref: "#/components/parameters/AutomaticCoverageCursor"
        - $ref: "#/components/parameters/AutomaticCoverageMode"
        - name: "after"
          in: "query"
          deprecated: true
          schema:
            type: "string"
          description: "Legacy cursor alias. Prefer cursor."
        - $ref: "#/components/parameters/AutomaticFollowerPageSize"
        - $ref: "#/components/parameters/UserFilterMinFollowers"
        - $ref: "#/components/parameters/UserFilterMaxFollowers"
        - $ref: "#/components/parameters/UserFilterMinFollowing"
        - $ref: "#/components/parameters/UserFilterMaxFollowing"
        - $ref: "#/components/parameters/UserFilterMinStatuses"
        - $ref: "#/components/parameters/UserFilterMaxStatuses"
        - $ref: "#/components/parameters/UserFilterMinAccountAgeDays"
        - $ref: "#/components/parameters/UserFilterVerifiedOnly"
        - $ref: "#/components/parameters/UserFilterVerifiedType"
        - $ref: "#/components/parameters/UserFilterHasWebsite"
        - $ref: "#/components/parameters/UserFilterHasLocation"
        - $ref: "#/components/parameters/UserFilterBioContains"
        - $ref: "#/components/parameters/UserFilterLocationContains"
        - $ref: "#/components/parameters/UserFilterUsernameContains"
        - name: "limit"
          in: "query"
          schema:
            type: "integer"
            minimum: 1
            maximum: 10000
          description: "Legacy page-size alias outside explicit coverage mode. Coverage
            accepts 1-10000. Prefer pageSize.\n"
      responses:
        "200":
          description: "List of user followers"
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/PaginatedUsers"
                  - $ref: "#/components/schemas/UserListCoverageResponse"
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/AnonymousGuestAuthenticationRequired"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "404":
          $ref: "#/components/responses/UserNotFound"
        "409":
          $ref: "#/components/responses/CoverageCursorUnavailable"
        "410":
          $ref: "#/components/responses/CursorGone"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        "503":
          $ref: "#/components/responses/MaximumCoverageBusy"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List followers of a user."
  /api/v1/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"
        - $ref: "#/components/parameters/AutomaticCoverageCursor"
        - $ref: "#/components/parameters/AutomaticCoverageMode"
        - name: "after"
          in: "query"
          deprecated: true
          schema:
            type: "string"
          description: "Deprecated following cursor alias. Prefer cursor."
        - $ref: "#/components/parameters/AutomaticFollowerPageSize"
        - $ref: "#/components/parameters/UserFilterMinFollowers"
        - $ref: "#/components/parameters/UserFilterMaxFollowers"
        - $ref: "#/components/parameters/UserFilterMinFollowing"
        - $ref: "#/components/parameters/UserFilterMaxFollowing"
        - $ref: "#/components/parameters/UserFilterMinStatuses"
        - $ref: "#/components/parameters/UserFilterMaxStatuses"
        - $ref: "#/components/parameters/UserFilterMinAccountAgeDays"
        - $ref: "#/components/parameters/UserFilterVerifiedOnly"
        - $ref: "#/components/parameters/UserFilterVerifiedType"
        - $ref: "#/components/parameters/UserFilterHasWebsite"
        - $ref: "#/components/parameters/UserFilterHasLocation"
        - $ref: "#/components/parameters/UserFilterBioContains"
        - $ref: "#/components/parameters/UserFilterLocationContains"
        - $ref: "#/components/parameters/UserFilterUsernameContains"
        - name: "limit"
          in: "query"
          schema:
            type: "integer"
            minimum: 1
            maximum: 10000
          description: "Legacy page-size alias outside explicit coverage mode. Coverage
            accepts 1-10000. Prefer pageSize.\n"
      responses:
        "200":
          description: "List of following"
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/PaginatedUsers"
                  - $ref: "#/components/schemas/UserListCoverageResponse"
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/AnonymousGuestAuthenticationRequired"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "404":
          $ref: "#/components/responses/UserNotFound"
        "409":
          $ref: "#/components/responses/CoverageCursorUnavailable"
        "410":
          $ref: "#/components/responses/CursorGone"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        "503":
          $ref: "#/components/responses/MaximumCoverageBusy"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List accounts a user follows."
  /api/v1/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/TweetFilterMinViews"
        - $ref: "#/components/parameters/TweetFilterMinBookmarks"
        - $ref: "#/components/parameters/TweetFilterMaxFaves"
        - $ref: "#/components/parameters/TweetFilterMaxRetweets"
        - $ref: "#/components/parameters/TweetFilterMaxReplies"
        - $ref: "#/components/parameters/TweetFilterMaxQuotes"
        - $ref: "#/components/parameters/TweetFilterBlueVerifiedOnly"
        - $ref: "#/components/parameters/TweetFilterCardName"
        - $ref: "#/components/parameters/TweetFilterSource"
        - $ref: "#/components/parameters/TweetFilterExcludeSource"
        - $ref: "#/components/parameters/TweetFilterGeocode"
        - $ref: "#/components/parameters/TweetFilterSinceId"
        - $ref: "#/components/parameters/TweetFilterMaxId"
        - $ref: "#/components/parameters/TweetFilterNear"
        - $ref: "#/components/parameters/TweetFilterWithin"
        - $ref: "#/components/parameters/TweetFilterWithinTime"
        - $ref: "#/components/parameters/TweetFilterNativeRetweets"
        - $ref: "#/components/parameters/TweetFilterSafe"
        - $ref: "#/components/parameters/TweetFilterNews"
        - $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/UserNotFound"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List tweets mentioning a user."
  /api/v1/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"
        - $ref: "#/components/parameters/AutomaticCoverageCursor"
        - $ref: "#/components/parameters/AutomaticCoverageMode"
        - name: "after"
          in: "query"
          deprecated: true
          schema:
            type: "string"
          description: "Legacy cursor alias. Prefer cursor."
        - $ref: "#/components/parameters/AutomaticFollowerPageSize"
        - $ref: "#/components/parameters/UserFilterMinFollowers"
        - $ref: "#/components/parameters/UserFilterMaxFollowers"
        - $ref: "#/components/parameters/UserFilterMinFollowing"
        - $ref: "#/components/parameters/UserFilterMaxFollowing"
        - $ref: "#/components/parameters/UserFilterMinStatuses"
        - $ref: "#/components/parameters/UserFilterMaxStatuses"
        - $ref: "#/components/parameters/UserFilterMinAccountAgeDays"
        - $ref: "#/components/parameters/UserFilterVerifiedOnly"
        - $ref: "#/components/parameters/UserFilterVerifiedType"
        - $ref: "#/components/parameters/UserFilterHasWebsite"
        - $ref: "#/components/parameters/UserFilterHasLocation"
        - $ref: "#/components/parameters/UserFilterBioContains"
        - $ref: "#/components/parameters/UserFilterLocationContains"
        - $ref: "#/components/parameters/UserFilterUsernameContains"
        - name: "limit"
          in: "query"
          schema:
            type: "integer"
            minimum: 1
            maximum: 10000
          description: "Legacy page-size alias outside explicit coverage mode. Coverage
            accepts 1-10000. Prefer pageSize.\n"
      responses:
        "200":
          description: "List of verified followers"
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/PaginatedUsers"
                  - $ref: "#/components/schemas/UserListCoverageResponse"
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/AnonymousGuestAuthenticationRequired"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "404":
          $ref: "#/components/responses/UserNotFound"
        "409":
          $ref: "#/components/responses/CoverageCursorUnavailable"
        "410":
          $ref: "#/components/responses/CursorGone"
        "424":
          $ref: "#/components/responses/XApiError"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "502":
          $ref: "#/components/responses/XApiError"
        "503":
          $ref: "#/components/responses/MaximumCoverageBusy"
        default:
          $ref: "#/components/responses/UnexpectedError"
      description: "List verified followers of a user."
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:
    WriteIdempotencyKey:
      name: "Idempotency-Key"
      in: "header"
      required: true
      description: "Generate one unique value for each intended write. Reuse it only
        when retrying the exact same account, action, target, and payload. A
        reused key returns the original action. Reusing it with different input
        returns 409. Replay protection remains active for at least 90 days.\n"
      schema:
        type: "string"
        minLength: 1
        maxLength: 255
        pattern: "^[!-~]{1,255}$"
    SupportIdempotencyKey:
      name: "Idempotency-Key"
      in: "header"
      required: false
      description: "Generate one random value per ticket or reply. Reuse it only when
        retrying identical text and attachments. Never log this value.\n"
      schema:
        type: "string"
        minLength: 8
        maxLength: 128
        pattern: "^[A-Za-z0-9._:-]{8,128}$"
    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.\n"
      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."
    ConnectionAttemptId:
      name: "id"
      in: "path"
      required: true
      description: "Connection attempt ID returned by `POST /x/accounts`."
      schema:
        type: "string"
        pattern: "^xatt_[0-9a-f]{32}$"
        example: "xatt_0123456789abcdef0123456789abcdef"
    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.\n"
      schema:
        type: "integer"
        minimum: 1
        maximum: 100
        default: 50
    ResultPageSize:
      name: "pageSize"
      in: "query"
      description: "Maximum page items (1-100, default 20). Source, filters, or
        credits can reduce results. Continue while has_next_page is true.
        Deprecated limit and count aliases remain accepted.\n"
      schema:
        type: "integer"
        minimum: 1
        maximum: 100
        default: 20
    AutomaticCoverageCursor:
      name: "cursor"
      in: "query"
      schema:
        type: "string"
      description: "Cursor from the previous response. Xquik cursors resume automatic
        coverage. Existing unprefixed cursors keep legacy standard behavior.\n"
    AutomaticCoverageMode:
      name: "mode"
      in: "query"
      schema:
        type: "string"
        enum:
          - "standard"
          - "coverage"
      description: "Omit mode for resumable maximum coverage. Standard keeps legacy
        pagination. Coverage returns diagnostics once and rejects cursors.\n"
    AutomaticTweetPageSize:
      name: "pageSize"
      in: "query"
      description: "Automatic pages accept 1-300 Tweets. Standard pages keep 1-100.
        Default 20. Continue while has_next_page is true. Deprecated aliases
        remain accepted.\n"
      schema:
        type: "integer"
        minimum: 1
        maximum: 300
        default: 20
    FollowerPageSize:
      name: "pageSize"
      in: "query"
      description: "Maximum user profiles requested from this page (20-200, default
        200). Source, filters, or credits can return fewer profiles. Keep
        requesting next_cursor while has_next_page is true. Deprecated aliases
        remain accepted.\n"
      schema:
        type: "integer"
        minimum: 20
        maximum: 200
        default: 200
    AutomaticFollowerPageSize:
      name: "pageSize"
      in: "query"
      description: "Maximum user profiles: automatic 300; standard 200. Sources return
        fewer profiles. Continue with has_next_page.\n"
      schema:
        type: "integer"
        minimum: 20
        maximum: 300
        default: 200
    UserFilterMinFollowers:
      name: "minFollowers"
      in: "query"
      schema:
        type: "integer"
        minimum: 0
      description: "Minimum follower count. Filtering happens before billing."
    UserFilterMaxFollowers:
      name: "maxFollowers"
      in: "query"
      schema:
        type: "integer"
        minimum: 0
      description: "Maximum follower count. Missing counts pass this maximum."
    UserFilterMinFollowing:
      name: "minFollowing"
      in: "query"
      schema:
        type: "integer"
        minimum: 0
      description: "Minimum following count."
    UserFilterMaxFollowing:
      name: "maxFollowing"
      in: "query"
      schema:
        type: "integer"
        minimum: 0
      description: "Maximum following count."
    UserFilterMinStatuses:
      name: "minStatuses"
      in: "query"
      schema:
        type: "integer"
        minimum: 0
      description: "Minimum post count. minPosts is also accepted."
    UserFilterMaxStatuses:
      name: "maxStatuses"
      in: "query"
      schema:
        type: "integer"
        minimum: 0
      description: "Maximum post count. maxPosts is also accepted."
    UserFilterMinAccountAgeDays:
      name: "minAccountAgeDays"
      in: "query"
      schema:
        type: "integer"
        minimum: 0
      description: "Minimum account age in whole days."
    UserFilterVerifiedOnly:
      name: "verifiedOnly"
      in: "query"
      schema:
        type: "boolean"
      description: "Only return verified profiles."
    UserFilterVerifiedType:
      name: "verifiedType"
      in: "query"
      schema:
        type: "string"
      description: "Match the verification type exactly, ignoring case."
    UserFilterHasWebsite:
      name: "hasWebsite"
      in: "query"
      schema:
        type: "boolean"
      description: "Only return profiles with a website."
    UserFilterHasLocation:
      name: "hasLocation"
      in: "query"
      schema:
        type: "boolean"
      description: "Only return profiles with a location."
    UserFilterBioContains:
      name: "bioContains"
      in: "query"
      schema:
        type: "string"
      description: "Match any comma-separated or line-separated bio term, ignoring case.\n"
    UserFilterLocationContains:
      name: "locationContains"
      in: "query"
      schema:
        type: "string"
      description: "Match a location substring, ignoring case."
    UserFilterUsernameContains:
      name: "usernameContains"
      in: "query"
      schema:
        type: "string"
      description: "Match a username substring, ignoring case."
    After:
      name: "cursor"
      in: "query"
      schema:
        type: "string"
      description: "Previous nextCursor."
    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. minLikes is also accepted."
    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."
    TweetFilterMinViews:
      name: "minViews"
      in: "query"
      schema:
        type: "integer"
        minimum: 0
      description: "Minimum view count threshold."
    TweetFilterMinBookmarks:
      name: "minBookmarks"
      in: "query"
      schema:
        type: "integer"
        minimum: 0
      description: "Minimum bookmark count threshold."
    TweetFilterMaxFaves:
      name: "maxFaves"
      in: "query"
      schema:
        type: "integer"
        minimum: 0
      description: "Maximum likes threshold. maxLikes is also accepted."
    TweetFilterMaxRetweets:
      name: "maxRetweets"
      in: "query"
      schema:
        type: "integer"
        minimum: 0
      description: "Maximum retweets threshold."
    TweetFilterMaxReplies:
      name: "maxReplies"
      in: "query"
      schema:
        type: "integer"
        minimum: 0
      description: "Maximum replies threshold."
    TweetFilterMaxQuotes:
      name: "maxQuotes"
      in: "query"
      schema:
        type: "integer"
        minimum: 0
      description: "Maximum quotes threshold."
    TweetFilterBlueVerifiedOnly:
      name: "blueVerifiedOnly"
      in: "query"
      schema:
        type: "boolean"
      description: "Only return tweets from Blue-verified authors."
    TweetFilterCardName:
      name: "cardName"
      in: "query"
      schema:
        type: "string"
      description: "Match the Tweet card name."
    TweetFilterSource:
      name: "source"
      in: "query"
      schema:
        type: "string"
      description: "Match the source application."
    TweetFilterExcludeSource:
      name: "excludeSource"
      in: "query"
      schema:
        type: "string"
      description: "Exclude a source application."
    TweetFilterGeocode:
      name: "geocode"
      in: "query"
      schema:
        type: "string"
      description: "Match latitude, longitude, and radius."
    TweetFilterSinceId:
      name: "sinceId"
      in: "query"
      schema:
        type: "string"
      description: "Return Tweets newer than this Tweet ID."
    TweetFilterMaxId:
      name: "maxId"
      in: "query"
      schema:
        type: "string"
      description: "Return Tweets older than this Tweet ID."
    TweetFilterNear:
      name: "near"
      in: "query"
      schema:
        type: "string"
      description: "Match a place name."
    TweetFilterWithin:
      name: "within"
      in: "query"
      schema:
        type: "string"
      description: "Set the radius for the near filter."
    TweetFilterWithinTime:
      name: "withinTime"
      in: "query"
      schema:
        type: "string"
      description: "Match Tweets inside a recent time window."
    TweetFilterNativeRetweets:
      name: "nativeRetweets"
      in: "query"
      schema:
        type: "boolean"
      description: "Only return native reposts."
    TweetFilterSafe:
      name: "safe"
      in: "query"
      schema:
        type: "boolean"
      description: "Enable the safe-search filter."
    TweetFilterNews:
      name: "news"
      in: "query"
      schema:
        type: "boolean"
      description: "Only return news results."
    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:
    WriteActionCompleted:
      description: "Write reached a terminal state."
      headers:
        X-Request-Id:
          required: true
          description: "Correlation ID for support and observability."
          schema:
            type: "string"
        Location:
          description: "Relative URL for the durable action record."
          schema:
            type: "string"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/XWriteAction"
          example:
            object: "x_write_action"
            id: "12345"
            writeActionId: "12345"
            action: "like"
            status: "success"
            terminal: true
            retryable: false
            safeToRetry: false
            statusUrl: "/api/v1/x/write-actions/12345"
            pollAfterMs: null
            charged: true
            chargedCredits: "10"
            billing:
              status: "charged"
              charged: true
              plannedCredits: "10"
              chargedCredits: "10"
            request:
              hash: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
              payload:
                tweet_id: "9876543210"
            account:
              id: "42"
              username: "example"
            target:
              type: "tweet"
              id: "9876543210"
            targetId: "9876543210"
            result:
              type: "state_change"
              id: "9876543210"
              state: "liked"
            nextAction: null
            sendDispatched: true
            success: true
    WriteActionAccepted:
      description: "Write was accepted or dispatched. Poll Location after Retry-After.
        Never submit another write while this action remains nonterminal.\n"
      headers:
        X-Request-Id:
          required: true
          description: "Correlation ID for this accepted write response."
          schema:
            type: "string"
        Location:
          required: true
          description: "Relative URL for polling the durable action record."
          schema:
            type: "string"
        Retry-After:
          required: true
          description: "Recommended polling delay in seconds."
          schema:
            type: "integer"
            minimum: 1
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/XWriteAction"
          example:
            object: "x_write_action"
            id: "12346"
            writeActionId: "12346"
            action: "create_tweet"
            status: "dispatching"
            terminal: false
            retryable: false
            safeToRetry: false
            statusUrl: "/api/v1/x/write-actions/12346"
            pollAfterMs: 2000
            charged: false
            chargedCredits: "0"
            billing:
              status: "pending"
              charged: false
              plannedCredits: "30"
              chargedCredits: "0"
            request:
              hash: "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
              payload:
                text: "Hello from Xquik"
            account:
              id: "42"
              username: "example"
            target: null
            targetId: null
            result: null
            nextAction:
              type: "poll"
              url: "/api/v1/x/write-actions/12346"
              afterMs: 2000
            sendDispatched: true
            success: false
    WriteIdempotencyConflict:
      description: "The idempotency key belongs to a different write request."
      headers:
        X-Request-Id:
          required: true
          description: "Correlation ID for this idempotency conflict."
          schema:
            type: "string"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/XWriteActionError"
          example:
            charged: false
            chargedCredits: "0"
            error: "idempotency_conflict"
            message: "Idempotency-Key was already used with a different request."
            safeToRetry: true
            retryable: false
            success: false
            nextAction:
              type: "retry"
              requiresNewIdempotencyKey: true
    WriteInvalidInput:
      description: "The write request is invalid and no action was dispatched."
      headers:
        X-Request-Id:
          required: true
          description: "Correlation ID for this invalid write request."
          schema:
            type: "string"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/XWriteActionError"
          example:
            error: "invalid_input"
            message: "Invalid input. Check request fields."
            charged: false
            chargedCredits: "0"
            retryable: false
            safeToRetry: true
            success: false
            nextAction:
              type: "fix_request"
    WriteTrackingUnavailable:
      description: "Durable tracking or the write service is temporarily unavailable.
        Inspect safeToRetry before creating another action.\n"
      headers:
        X-Request-Id:
          required: true
          description: "Correlation ID for this tracking failure."
          schema:
            type: "string"
        Retry-After:
          description: "Recommended retry delay in seconds."
          schema:
            type: "integer"
            minimum: 1
      content:
        application/json:
          schema:
            oneOf:
              - $ref: "#/components/schemas/XWriteActionError"
              - $ref: "#/components/schemas/XWriteAction"
          example:
            error: "write_tracking_unavailable"
            message: "Write tracking unavailable. Try again."
            charged: false
            chargedCredits: "0"
            retryable: true
            safeToRetry: true
            success: false
            nextAction:
              type: "retry"
    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: "Non-MPP paid reads require Bearer authentication. Missing
        credentials advertise guest checkout without creating it. Invalid
        credentials return a plain error. Confirm before calling an advertised
        action.\n"
      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."
    UserNotFound:
      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."
    PaymentRequired:
      description: "Payment required. MPP reads include `WWW-Authenticate`.
        Authenticated reads include balances and checkout. Guest keys expose
        guest top-up only. A failed request never creates checkout. Confirm
        first.\n"
      headers:
        WWW-Authenticate:
          description: "MPP payment challenge for eligible anonymous pay-per-use requests.
            Authenticated credit or subscription errors omit this header."
          schema:
            type: "string"
      content:
        application/json:
          schema:
            oneOf:
              - $ref: "#/components/schemas/XWritePaymentRequired"
              - $ref: "#/components/schemas/AuthenticatedPaymentRequired"
              - $ref: "#/components/schemas/GuestPaymentRequired"
              - allOf:
                  - $ref: "#/components/schemas/Error"
                  - not:
                      required:
                        - "payment_options"
          example:
            balance: "0"
            dashboard: "/dashboard/account"
            error: "insufficient_credits"
            message: "Insufficient credits. Top up or subscribe to continue."
            next_step: "Ask the user to confirm a payment option before creating checkout."
            payment_options:
              credits:
                create_checkout:
                  body:
                    dollars: 10
                    locale: "en"
                  creates: "checkout_url"
                  method: "POST"
                  path: "/api/v1/credits/topup"
                  provider: "stripe"
                  requires_authentication: true
                  requires_user_confirmation: true
                  response_url_field: "url"
              subscription:
                create_checkout:
                  body:
                    tier: "starter"
                  creates: "checkout_url"
                  method: "POST"
                  path: "/api/v1/subscribe"
                  provider: "stripe"
                  requires_authentication: true
                  requires_user_confirmation: true
                  response_url_field: "url"
            required: "1"
            top_up_endpoint: "/api/v1/credits/topup"
            top_up_url: "POST /api/v1/credits/topup"
        application/problem+json:
          schema:
            $ref: "#/components/schemas/MppPaymentRequired"
          example:
            account_required: false
            challengeId: "Opaque MPP challenge identifier"
            detail: "Payment is required."
            hint: "Use a supported wallet with an offer from the WWW-Authenticate header."
            status: 402
            title: "Payment Required"
            type: "https://paymentauth.org/problems/payment-required"
            next_step: "Ask the user to confirm a USD amount before creating checkout."
            payment_options:
              guest_wallet:
                create_checkout:
                  account_required: false
                  amount_bounds:
                    currency: "usd"
                    maximum_minor: 25000
                    minimum_minor: 1000
                  body:
                    amount_minor: 1000
                    currency: "usd"
                  creates: "checkout_url"
                  method: "POST"
                  path: "/api/v1/guest-wallets"
                  provider: "stripe"
                  required_headers:
                    Idempotency-Key: "<cryptographically random UUID v4>"
                  requires_authentication: false
                  requires_user_confirmation: true
                  requires_user_interaction: true
                  response_fields:
                    - "checkout_url"
                    - "api_key"
                    - "status_url"
                  response_url_field: "checkout_url"
    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`.\n"
      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, and
        x_daily_limit. Inspect the durable action, safeToRetry, and nextAction
        fields before retrying.\n"
      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 download. Read Error.code for the exact
        reason. Media failures cover URL, size, origin, and timeout.\n"
      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.\n"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: "x_rate_limited"
            message: "Rate limited by X. Wait before retrying."
      headers:
        Retry-After:
          description: "Seconds until the next permitted request."
          schema:
            example: 60
            minimum: 1
            type: "integer"
    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.\n"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/Error"
              - type: "object"
                properties:
                  retryAfter:
                    type: "integer"
                    example: 60
          examples:
            xquikLimit:
              summary: "Xquik tier or action limit"
              value:
                error: "rate_limit_exceeded"
                message: "Too many requests. Try again later."
                retryAfter: 60
            xLimit:
              summary: "X rate limit"
              value:
                error: "x_rate_limited"
                message: "Rate limited by X. Wait before retrying."
          example:
            error: "rate_limit_exceeded"
            message: "Too many requests. Try again later."
            retryAfter: 60
      headers:
        Retry-After:
          description: "Seconds until the next permitted request."
          schema:
            example: 60
            minimum: 1
            type: "integer"
    XApiError:
      description: "Dependency unavailable, unauthorized, or rate limited. Default v1
        returns 502. The best-practice response contract returns 424 for
        transparent dependency failures.\n"
      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`.\n"
      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."
    CoverageCursorUnavailable:
      description: "Cursor is in use. Retry `coverage_cursor_unavailable` later."
      headers:
        Retry-After:
          required: true
          schema:
            type: "integer"
            minimum: 1
          description: "Seconds to wait."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: "coverage_cursor_unavailable"
            message: "Cursor busy. Retry after the indicated delay."
    CursorGone:
      description: "Restart without the `coverage_cursor_gone` cursor."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: "coverage_cursor_gone"
            message: "Cursor finished, expired, or superseded. Restart pagination without
              cursor."
    MaximumCoverageBusy:
      description: "Automatic or explicit maximum coverage is temporarily busy."
      headers:
        Retry-After:
          schema:
            type: "integer"
            minimum: 1
          description: "Seconds to wait before retrying."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: "x_api_unavailable"
            message: "Maximum coverage is busy. Retry shortly."
    RepliesIncomplete:
      description: "Incomplete replies"
      content:
        application/json:
          schema:
            anyOf:
              - $ref: "#/components/schemas/Error"
              - $ref: "#/components/schemas/IncompleteTweetReplies"
          example:
            error: "replies_incomplete"
            message: "Replies are incomplete. Retry complete mode later."
            tweets: []
            has_next_page: false
            next_cursor: ""
            nested_replies: []
            diagnostic:
              complete: false
              reportedReplyCount: 100
              targetDirectReplies: 80
              uniqueDirectReplies: 42
              coveragePercentage: 42
              nestedReplyCount: 5
              pagesAttempted: 12
              strategiesAttempted: []
              duplicateCount: 3
              cursorFailures: 0
              repeatedCursorCount: 0
              emptyFalseProgressPages: 1
              malformedCount: 0
              unrelatedCount: 2
              missingResponseModulesOrFields: []
              recommendedFallback: "Retry complete mode later. X did not expose enough direct
                replies."
              richness:
                totalReplies: 42
                text: 42
                author: 40
                createdAt: 42
                language: 38
                url: 42
                entities: 20
                media: 5
                article: 0
                card: 2
                communityNote: 0
                quotedOrRepostedTweet: 1
                engagementCounts: 42
              responseTruncated: false
    ConnectAlreadyConnected:
      description: "The specified X account is already connected to this Xquik
        account. Returns error code `account_already_connected`.\n"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: "account_already_connected"
            message: "This X account is already connected."
    ConnectLoginFailed:
      description: "Login requires new credentials or account verification. Cooldowns
        include `retryAfterMs` and `Retry-After`. Codes are `login_failed` or
        `passkey_required`.\n"
      headers:
        Retry-After:
          description: "Cooldown duration in seconds, when retrying must wait."
          schema:
            type: "integer"
            minimum: 1
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: "login_failed"
            message: "Login failed. Check credentials and try again."
            retryAfterMs: 300000
    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`.\n"
      headers:
        Retry-After:
          description: "Cooldown duration in seconds."
          required: true
          schema:
            type: "integer"
            minimum: 1
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: "login_cooldown"
            message: "Login is temporarily paused"
            reason: "temporary_issue"
            retryAfterMs: 60000
    ConnectRateLimitExceeded:
      description: "Too many requests. `rate_limit_exceeded` includes `retryAfter` and
        `Retry-After`. `login_cooldown` also includes `reason` and
        `retryAfterMs`.\n"
      headers:
        Retry-After:
          description: "Required wait in seconds."
          required: true
          schema:
            type: "integer"
            minimum: 1
      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.\n"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/Error"
              - type: "object"
                properties:
                  retryAfter:
                    type: "integer"
                    example: 60
          example:
            error: "rate_limit_exceeded"
            message: "Too many requests. Try again later."
            retryAfter: 60
      headers:
        Retry-After:
          description: "Seconds until the next permitted request."
          schema:
            example: 60
            minimum: 1
            type: "integer"
    GuestWalletRateLimited:
      description: "Guest wallet request limit exceeded."
      headers:
        Retry-After:
          description: "Seconds before the next guest wallet request."
          required: true
          schema:
            type: "integer"
            minimum: 1
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: "rate_limited"
            message: "Try again later."
    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`.\n"
      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`.\n"
      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`.\n"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: "account_not_found"
            message: "X account not found."
    UnexpectedError:
      content:
        application/json:
          example:
            error: "internal_error"
            message: "Unexpected error. Try again."
          schema:
            $ref: "#/components/schemas/Error"
      description: "Unexpected error."
  schemas:
    ComposePrepareRequest:
      type: "object"
      required:
        - "step"
        - "topic"
      properties:
        step:
          type: "string"
          const: "compose"
        topic:
          type: "string"
          minLength: 1
          description: "Subject for the post."
          example: "PostgreSQL query planning"
        goal:
          type: "string"
          enum:
            - "engagement"
            - "followers"
            - "authority"
            - "conversation"
          default: "engagement"
          description: "Editorial goal used to order the rules and questions."
        styleUsername:
          type: "string"
          minLength: 1
          description: "Username from a style analysis saved to this account."
      additionalProperties: true
    ComposeRefineRequest:
      type: "object"
      required:
        - "step"
        - "topic"
        - "goal"
        - "tone"
      properties:
        step:
          type: "string"
          const: "refine"
        topic:
          type: "string"
          minLength: 1
          description: "Subject for the post."
        goal:
          type: "string"
          enum:
            - "engagement"
            - "followers"
            - "authority"
            - "conversation"
          description: "Editorial goal for the guidance."
        tone:
          type: "string"
          minLength: 1
          description: "Requested writing tone."
          example: "professional"
        mediaType:
          type: "string"
          enum:
            - "photo"
            - "video"
            - "none"
          description: "Planned media type."
        callToAction:
          type: "string"
          minLength: 1
          description: "Specific action the draft should request."
        additionalContext:
          type: "string"
          minLength: 1
          description: "Audience, constraints, sources, or other writing context."
      additionalProperties: true
    ComposeScoreRequest:
      type: "object"
      required:
        - "step"
        - "draft"
      properties:
        step:
          type: "string"
          const: "score"
        draft:
          type: "string"
          minLength: 1
          description: "Full post text for deterministic editorial checks."
        hasLink:
          type: "boolean"
          description: "True when a separate link card is attached."
          default: false
        hasMedia:
          type: "boolean"
          deprecated: true
          x-stainless-deprecation-message: "Ignored. Remove this field. Use hasLink for a separate link card."
          description: "Accepted for backward compatibility. Text checks ignore this
            field.\n"
      additionalProperties: true
    ComposeContentRule:
      type: "object"
      required:
        - "rule"
      properties:
        rule:
          type: "string"
      additionalProperties: false
    ComposeRadarRecommendation:
      type: "object"
      required:
        - "endpoint"
        - "guidance"
        - "source"
        - "useFor"
      properties:
        endpoint:
          type: "string"
          description: "Radar endpoint for this source."
        guidance:
          type: "string"
          description: "Source-specific drafting guidance."
        source:
          type: "string"
          enum:
            - "reddit"
            - "github"
            - "trustmrr"
            - "hacker_news"
            - "google_trends"
            - "wikipedia"
            - "polymarket"
        useFor:
          type: "string"
          description: "Current-topic research this source supports."
      additionalProperties: false
    ComposeSignalLabel:
      type: "object"
      required:
        - "action"
        - "multiplier"
      properties:
        action:
          type: "string"
          description: "Human-readable published signal name."
        multiplier:
          type: "string"
          const: "Production weight not published by X"
      additionalProperties: false
    ComposeScorerSignal:
      type: "object"
      required:
        - "context"
        - "signal"
        - "weight"
      properties:
        context:
          type: "string"
          description: "Signal direction and publication limit."
        signal:
          type: "string"
          description: "Signal name from X's public ranking repository."
        weight:
          type: "null"
          description: "X does not publish the production weight."
      additionalProperties: false
    ComposeSavedStyle:
      type: "object"
      required:
        - "tweetCount"
        - "username"
      properties:
        tweetCount:
          type: "integer"
          minimum: 0
        username:
          type: "string"
      additionalProperties: false
    ComposePrepareResult:
      type: "object"
      required:
        - "contentRules"
        - "engagementMultipliers"
        - "engagementVelocity"
        - "followUpQuestions"
        - "intentUrl"
        - "nextStep"
        - "radarRecommendations"
        - "scorerWeights"
        - "source"
        - "topPenalties"
      properties:
        contentRules:
          type: "array"
          minItems: 18
          maxItems: 18
          items:
            $ref: "#/components/schemas/ComposeContentRule"
          description: "Xquik editorial heuristics, ordered for the goal."
        engagementMultipliers:
          type: "array"
          minItems: 19
          maxItems: 19
          items:
            $ref: "#/components/schemas/ComposeSignalLabel"
          description: "Published engagement signal names. Production multipliers are not
            published.\n"
        engagementVelocity:
          type: "string"
          description: "Publication limit for timing and decay claims."
        followUpQuestions:
          type: "array"
          minItems: 4
          maxItems: 4
          items:
            type: "string"
        intentUrl:
          type: "string"
          format: "uri"
          description: "X post intent seeded with the topic."
        nextStep:
          type: "string"
        radarRecommendations:
          type: "array"
          minItems: 7
          maxItems: 7
          items:
            $ref: "#/components/schemas/ComposeRadarRecommendation"
          description: "Sources and guidance for researching a fresh post angle."
        scorerWeights:
          type: "array"
          minItems: 19
          maxItems: 19
          items:
            $ref: "#/components/schemas/ComposeScorerSignal"
          description: "Published signal names with unpublished weights as null."
        source:
          type: "string"
          description: "Signal source and evidence limits."
        topPenalties:
          type: "array"
          minItems: 4
          maxItems: 4
          items:
            type: "string"
          description: "Negative engagement predictions in the public model."
        savedStyles:
          type: "array"
          items:
            $ref: "#/components/schemas/ComposeSavedStyle"
          description: "Style analyses saved to the account."
        styleTweets:
          type: "array"
          items:
            type: "string"
          description: "Cached examples for the requested style username."
        styleNote:
          type: "string"
          description: "Next action when no cached style is available."
      additionalProperties: false
    ComposeExamplePattern:
      type: "object"
      required:
        - "description"
        - "pattern"
      properties:
        description:
          type: "string"
        pattern:
          type: "string"
      additionalProperties: false
    ComposeRefineResult:
      type: "object"
      required:
        - "compositionGuidance"
        - "examplePatterns"
        - "intentUrl"
        - "nextStep"
      properties:
        compositionGuidance:
          type: "array"
          items:
            type: "string"
          description: "Goal, tone, media, and editorial guidance."
        examplePatterns:
          type: "array"
          minItems: 3
          maxItems: 3
          items:
            $ref: "#/components/schemas/ComposeExamplePattern"
        intentUrl:
          type: "string"
          format: "uri"
          description: "X post intent seeded with the topic."
        nextStep:
          type: "string"
      additionalProperties: false
    ComposeScoreCheck:
      type: "object"
      required:
        - "factor"
        - "passed"
      properties:
        factor:
          type: "string"
        passed:
          type: "boolean"
        suggestion:
          type: "string"
          description: "Present only when the check fails."
      additionalProperties: false
    ComposeScoreResult:
      type: "object"
      required:
        - "checklist"
        - "nextStep"
        - "passed"
        - "passedCount"
        - "topSuggestion"
        - "totalChecks"
      properties:
        checklist:
          type: "array"
          minItems: 9
          maxItems: 9
          items:
            $ref: "#/components/schemas/ComposeScoreCheck"
          description: "Deterministic editorial checks. Not a reach prediction."
        intentUrl:
          type: "string"
          format: "uri"
          description: "Present only when every check passes."
        nextStep:
          type: "string"
        passed:
          type: "boolean"
        passedCount:
          type: "integer"
          minimum: 0
          maximum: 9
        topSuggestion:
          type: "string"
        totalChecks:
          type: "integer"
          const: 9
      additionalProperties: false
    XWriteActionBilling:
      type: "object"
      additionalProperties: false
      required:
        - "status"
        - "charged"
        - "plannedCredits"
        - "chargedCredits"
      properties:
        status:
          type: "string"
          enum:
            - "not_charged"
            - "pending"
            - "charged"
            - "charge_failed"
            - "refunded"
          example: "charged"
        charged:
          type: "boolean"
          example: true
        plannedCredits:
          type: "string"
          pattern: "^\\d+$"
          example: "10"
        chargedCredits:
          type: "string"
          pattern: "^\\d+$"
          example: "10"
      description: "plannedCredits is the approved maximum. chargedCredits comes from
        the settled credit ledger. Pending or failed writes are not charged.\n"
      example:
        status: "charged"
        charged: true
        plannedCredits: "10"
        chargedCredits: "10"
    XWriteActionAccount:
      type:
        - "object"
        - "null"
      description: "Connected account selected for the write."
      additionalProperties: false
      required:
        - "id"
        - "username"
      properties:
        id:
          type: "string"
        username:
          type: "string"
      example:
        id: "42"
        username: "example"
    XWriteActionTarget:
      type:
        - "object"
        - "null"
      description: "Existing X resource targeted by the write, when applicable."
      additionalProperties: false
      required:
        - "type"
        - "id"
      properties:
        type:
          type: "string"
          enum:
            - "tweet"
            - "user"
            - "community"
        id:
          type: "string"
      example:
        type: "tweet"
        id: "9876543210"
    XWriteActionRequest:
      type: "object"
      description: "Stable fingerprint and sanitized payload for replay checks."
      additionalProperties: false
      required:
        - "hash"
        - "payload"
      properties:
        hash:
          type:
            - "string"
            - "null"
          pattern: "^[0-9a-f]{64}$"
          description: "Stable hash of account, action, target, and payload."
        payload:
          type:
            - "object"
            - "null"
          additionalProperties: true
          description: "Exact sanitized payload dispatched for this action."
      example:
        hash: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
        payload:
          tweet_id: "9876543210"
    XWriteActionResult:
      type:
        - "object"
        - "null"
      description: "Confirmed result produced by the write, when available."
      additionalProperties: false
      properties:
        type:
          type: "string"
          enum:
            - "tweet"
            - "direct_message"
            - "media"
            - "community"
            - "state_change"
        id:
          type: "string"
        state:
          type: "string"
      example:
        type: "state_change"
        id: "9876543210"
        state: "liked"
    XWriteActionNextAction:
      type:
        - "object"
        - "null"
      description: "Exact follow-up an API client or agent should perform."
      additionalProperties: false
      required:
        - "type"
      properties:
        type:
          type: "string"
          enum:
            - "poll"
            - "retry"
            - "verify_result"
            - "fix_request"
        url:
          type: "string"
        afterMs:
          type: "integer"
          minimum: 0
        requiresNewIdempotencyKey:
          type: "boolean"
      example:
        type: "poll"
        url: "/api/v1/x/write-actions/12345"
        afterMs: 2000
    XWriteAction:
      type: "object"
      required:
        - "object"
        - "id"
        - "writeActionId"
        - "action"
        - "status"
        - "terminal"
        - "retryable"
        - "safeToRetry"
        - "statusUrl"
        - "pollAfterMs"
        - "charged"
        - "chargedCredits"
        - "billing"
        - "request"
        - "account"
        - "target"
        - "targetId"
        - "result"
        - "nextAction"
        - "sendDispatched"
        - "success"
      properties:
        object:
          type: "string"
          const: "x_write_action"
        id:
          type: "string"
          example: "12345"
        writeActionId:
          type: "string"
          example: "12345"
        action:
          type: "string"
          example: "like"
          enum:
            - "create_tweet"
            - "delete_tweet"
            - "like"
            - "unlike"
            - "retweet"
            - "unretweet"
            - "follow"
            - "unfollow"
            - "remove_follower"
            - "send_dm"
            - "upload_media"
            - "update_profile"
            - "update_avatar"
            - "update_banner"
            - "create_community"
            - "delete_community"
            - "join_community"
            - "leave_community"
        status:
          type: "string"
          example: "success"
          enum:
            - "accepted"
            - "dispatching"
            - "pending_confirmation"
            - "success"
            - "failed"
            - "expired"
        terminal:
          type: "boolean"
          example: true
        retryable:
          type: "boolean"
          description: "True only when a new attempt can reasonably succeed."
          example: false
        safeToRetry:
          type: "boolean"
          description: "True only when no write was dispatched and a new idempotency key
            may be used.\n"
          example: false
        statusUrl:
          type: "string"
          example: "/api/v1/x/write-actions/12345"
        pollAfterMs:
          type:
            - "integer"
            - "null"
          minimum: 0
          example: null
        charged:
          type: "boolean"
          example: true
        chargedCredits:
          type: "string"
          pattern: "^\\d+$"
          example: "10"
        billing:
          $ref: "#/components/schemas/XWriteActionBilling"
        request:
          $ref: "#/components/schemas/XWriteActionRequest"
        account:
          $ref: "#/components/schemas/XWriteActionAccount"
        target:
          $ref: "#/components/schemas/XWriteActionTarget"
        targetId:
          type:
            - "string"
            - "null"
          example: "9876543210"
        result:
          $ref: "#/components/schemas/XWriteActionResult"
        nextAction:
          $ref: "#/components/schemas/XWriteActionNextAction"
        requestHash:
          type: "string"
          pattern: "^[0-9a-f]{64}$"
          example: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
        requestId:
          type: "string"
          example: "01JZ8R7QSC9QKT0V7JX4M2A6B8"
        idempotent:
          type: "boolean"
          example: false
        error:
          type: "string"
          example: "x_write_ambiguous"
        message:
          type: "string"
          example: "Invalid input. Check request fields."
        sendDispatched:
          type: "boolean"
          example: true
        sendDispatchedAt:
          type: "string"
          format: "date-time"
          description: "Dispatch timestamp when the write reached execution."
          example: "2026-07-21T05:00:00Z"
        createdAt:
          type: "string"
          format: "date-time"
          example: "2026-07-21T05:00:00Z"
        updatedAt:
          type: "string"
          format: "date-time"
          example: "2026-07-21T05:00:02Z"
        completedAt:
          type: "string"
          format: "date-time"
          example: "2026-07-21T05:00:02Z"
        expiresAt:
          type: "string"
          format: "date-time"
          description: "Deadline for resolving a non-terminal write. This is not the
            Idempotency-Key retention deadline.\n"
          example: "2026-07-22T05:00:00Z"
        confirmedAt:
          type: "string"
          format: "date-time"
          example: "2026-07-21T05:00:02Z"
        confirmationCheckedAt:
          type: "string"
          format: "date-time"
          example: "2026-07-21T05:00:02Z"
        confirmationAttempts:
          type: "integer"
          minimum: 0
          example: 1
        tweetId:
          type: "string"
          description: "Compatibility field for a confirmed tweet result ID."
          example: "9876543210"
        messageId:
          type: "string"
          description: "Compatibility field for a confirmed direct message ID."
          example: "1234567890"
        mediaId:
          type: "string"
          description: "Compatibility field for a confirmed media upload ID."
          example: "2345678901"
        mediaUrl:
          type: "string"
          format: "uri"
          description: "Public media URL when the upload creates one."
          example: "https://media.xquik.com/example.jpg"
        communityId:
          type: "string"
          description: "Compatibility field for a confirmed community ID."
          example: "3456789012"
        communityName:
          type: "string"
          description: "Confirmed community name when available."
          example: "Builders"
        resultId:
          type: "string"
          description: "Compatibility result ID for other write actions."
          example: "9876543210"
        media:
          type: "object"
          additionalProperties: true
          description: "Media count, kind, size, and billing details when used."
          example:
            count: 1
            kind: "image"
        details:
          type: "object"
          additionalProperties: true
          description: "Structured recovery context for a failed write."
          example:
            suggestion: "Poll the action status URL."
        success:
          type: "boolean"
          example: true
      description: "Durable write lifecycle record. Poll statusUrl until terminal is
        true. Reusing the original Idempotency-Key returns this same record.
        Submit a new write only when safeToRetry is true, using a new key.\n"
    XWriteActionError:
      type: "object"
      description: "Canonical pre-dispatch error with safe recovery guidance."
      additionalProperties: true
      required:
        - "error"
        - "message"
        - "retryable"
        - "safeToRetry"
        - "charged"
        - "chargedCredits"
        - "success"
        - "nextAction"
      properties:
        error:
          type: "string"
          example: "invalid_input"
        message:
          type: "string"
          example: "Invalid input. Check request fields."
        retryable:
          type: "boolean"
          example: false
        safeToRetry:
          type: "boolean"
          example: true
        charged:
          type: "boolean"
          const: false
        chargedCredits:
          type: "string"
          const: "0"
        success:
          type: "boolean"
          const: false
        writeActionId:
          type: "string"
          example: "12345"
        statusUrl:
          type: "string"
          example: "/api/v1/x/write-actions/12345"
        nextAction:
          $ref: "#/components/schemas/XWriteActionNextAction"
        allowedFields:
          type: "array"
          example:
            - "account"
            - "text"
          items:
            type: "string"
        fieldErrors:
          type: "array"
          example:
            - code: "required"
              message: "Account is required."
              path: "account"
          items:
            type: "object"
            required:
              - "code"
              - "message"
              - "path"
            properties:
              code:
                type: "string"
              message:
                type: "string"
              path:
                type: "string"
    XWritePaymentRequired:
      allOf:
        - $ref: "#/components/schemas/XWriteAction"
        - type: "object"
          required:
            - "error"
            - "message"
      description: "Durable failed write action with the applicable payment guidance.\n"
    SupportAttachment:
      description: "Downloadable image or video attached to a support message."
      type: "object"
      required:
        - "publicId"
        - "filename"
        - "contentType"
        - "kind"
        - "sizeBytes"
        - "status"
        - "url"
      properties:
        publicId:
          type: "string"
          example: "att_a1b2c3d4e5f6a1b2c3d4e5f6"
        filename:
          type: "string"
          example: "screen.png"
        contentType:
          type: "string"
          description: "Validated media type."
          enum:
            - "image/jpeg"
            - "image/png"
            - "image/gif"
            - "image/webp"
            - "video/mp4"
            - "video/quicktime"
            - "video/webm"
        kind:
          type: "string"
          description: "Attachment media class."
          enum:
            - "image"
            - "video"
          example: "image"
        sizeBytes:
          type: "integer"
          format: "int64"
          example: 204800
        status:
          type: "string"
          description: "Storage processing state."
          enum:
            - "pending"
            - "ready"
            - "failed"
          example: "ready"
        url:
          type: "string"
          example: "/api/v1/support/attachments/att_a1b2c3d4e5f6a1b2c3d4e5f6"
    SupportAttachmentReceipt:
      description: "Attachment identifier and initial processing state."
      type: "object"
      required:
        - "publicId"
        - "status"
      properties:
        publicId:
          type: "string"
          example: "att_a1b2c3d4e5f6a1b2c3d4e5f6"
        status:
          type: "string"
          enum:
            - "pending"
            - "ready"
            - "failed"
          example: "pending"
    PaginatedTweets:
      description: "Automatic search, user Tweet, and reply coverage preserves shape,
        filters, aliases, and billing. Follow next_cursor while has_next_page is
        true. An empty filtered page can still have has_next_page true.
        Unprefixed cursors are legacy.\n"
      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"
    CoverageStopReason:
      type: "string"
      enum:
        - "cursor_failure"
        - "deadline"
        - "exhausted"
        - "failed"
        - "page_limit"
        - "result_limit"
        - "stalled"
    TweetSearchCoverageWindow:
      description: "Non-overlapping time partition used by one strategy."
      type: "object"
      required:
        - "sinceTime"
        - "untilTime"
      properties:
        sinceTime:
          type: "string"
          format: "date-time"
        untilTime:
          type: "string"
          format: "date-time"
    TweetSearchCoverageStrategy:
      type: "object"
      required:
        - "duplicateCount"
        - "pagesFetched"
        - "queryType"
        - "stopReason"
        - "strategy"
        - "uniqueAdded"
      properties:
        duplicateCount:
          type: "integer"
          minimum: 0
        pagesFetched:
          type: "integer"
          minimum: 0
        queryType:
          type: "string"
          enum:
            - "Latest"
            - "Top"
        stopReason:
          $ref: "#/components/schemas/CoverageStopReason"
        strategy:
          type: "integer"
          minimum: 1
          maximum: 8
        uniqueAdded:
          type: "integer"
          minimum: 0
        window:
          $ref: "#/components/schemas/TweetSearchCoverageWindow"
    TweetSearchCoverageDiagnostic:
      description: "Coverage evidence across parallel search strategies."
      type: "object"
      required:
        - "complete"
        - "cursorFailureCount"
        - "deadlineReached"
        - "duplicateCount"
        - "failedStrategyCount"
        - "malformedCount"
        - "pagesFetched"
        - "partitioned"
        - "responseTruncated"
        - "resultLimitReached"
        - "returnedTweets"
        - "stalledStrategyCount"
        - "strategies"
        - "strategyCount"
        - "uniqueTweets"
      properties:
        complete:
          type: "boolean"
          description: "True when every strategy exhausted its source."
        cursorFailureCount:
          type: "integer"
          minimum: 0
        deadlineReached:
          type: "boolean"
        duplicateCount:
          type: "integer"
          minimum: 0
        failedStrategyCount:
          type: "integer"
          minimum: 0
        malformedCount:
          type: "integer"
          minimum: 0
        pagesFetched:
          type: "integer"
          minimum: 0
        partitioned:
          type: "boolean"
          description: "Whether bounded time windows ran in parallel."
        responseTruncated:
          type: "boolean"
          description: "Whether credits or the requested limit reduced output."
        resultLimitReached:
          type: "boolean"
        returnedTweets:
          type: "integer"
          minimum: 0
          maximum: 10000
        stalledStrategyCount:
          type: "integer"
          minimum: 0
        strategies:
          type: "array"
          items:
            $ref: "#/components/schemas/TweetSearchCoverageStrategy"
        strategyCount:
          type: "integer"
          minimum: 1
          maximum: 8
        uniqueTweets:
          type: "integer"
          minimum: 0
          maximum: 10000
    TweetSearchCoverageResponse:
      allOf:
        - $ref: "#/components/schemas/PaginatedTweets"
        - type: "object"
          required:
            - "diagnostic"
          properties:
            has_next_page:
              type: "boolean"
              const: false
            next_cursor:
              type: "string"
              const: ""
            diagnostic:
              $ref: "#/components/schemas/TweetSearchCoverageDiagnostic"
    TweetReplies:
      description: "Direct reply rows. No-mode requests use resumable automatic
        coverage. Complete mode also returns nested replies and coverage
        diagnostics. Keep nested replies separate from direct coverage.\n"
      allOf:
        - $ref: "#/components/schemas/PaginatedTweets"
        - type: "object"
          properties:
            nested_replies:
              type: "array"
              items:
                $ref: "#/components/schemas/SearchTweet"
              description: "Nested replies. Excluded from direct coverage."
            diagnostic:
              $ref: "#/components/schemas/ReplyCoverageDiagnostic"
    IncompleteTweetReplies:
      allOf:
        - $ref: "#/components/schemas/TweetReplies"
        - type: "object"
          required:
            - "error"
            - "message"
            - "nested_replies"
            - "diagnostic"
          properties:
            error:
              type: "string"
              const: "replies_incomplete"
            message:
              type: "string"
            has_next_page:
              type: "boolean"
              const: false
            next_cursor:
              type: "string"
              const: ""
    ReplyCoverageStrategy:
      type: "object"
      required:
        - "name"
        - "pagesAttempted"
        - "newDirectReplies"
        - "newNestedReplies"
        - "stopReason"
      properties:
        name:
          type: "string"
        pagesAttempted:
          type: "integer"
          minimum: 0
        newDirectReplies:
          type: "integer"
          minimum: 0
        newNestedReplies:
          type: "integer"
          minimum: 0
        stopReason:
          type: "string"
          enum:
            - "deadline"
            - "empty_pages"
            - "error"
            - "missing_cursor"
            - "no_next_page"
            - "page_cap"
            - "repeated_cursor"
    ReplyCoverageRichness:
      description: "Field-presence counts across the collected direct replies."
      type: "object"
      required:
        - "totalReplies"
        - "text"
        - "author"
        - "createdAt"
        - "language"
        - "url"
        - "entities"
        - "media"
        - "article"
        - "card"
        - "communityNote"
        - "quotedOrRepostedTweet"
        - "engagementCounts"
      properties:
        totalReplies:
          type: "integer"
          minimum: 0
          description: "Total unique direct replies evaluated for richness."
        text:
          type: "integer"
          minimum: 0
          description: "Replies with text."
        author:
          type: "integer"
          minimum: 0
          description: "Replies with author details."
        createdAt:
          type: "integer"
          minimum: 0
          description: "Replies with a creation timestamp."
        language:
          type: "integer"
          minimum: 0
          description: "Replies with a language value."
        url:
          type: "integer"
          minimum: 0
          description: "Replies with a canonical URL."
        entities:
          type: "integer"
          minimum: 0
          description: "Replies with entity metadata."
        media:
          type: "integer"
          minimum: 0
          description: "Replies with media metadata."
        article:
          type: "integer"
          minimum: 0
          description: "Replies with article content."
        card:
          type: "integer"
          minimum: 0
          description: "Replies with card metadata."
        communityNote:
          type: "integer"
          minimum: 0
          description: "Replies with community-note data."
        quotedOrRepostedTweet:
          type: "integer"
          minimum: 0
          description: "Replies with quoted or reposted tweet data."
        engagementCounts:
          type: "integer"
          minimum: 0
          description: "Replies with engagement counts."
    ReplyCoverageDiagnostic:
      description: "Evidence for direct-reply coverage and collector behavior."
      type: "object"
      required:
        - "complete"
        - "reportedReplyCount"
        - "targetDirectReplies"
        - "uniqueDirectReplies"
        - "coveragePercentage"
        - "nestedReplyCount"
        - "pagesAttempted"
        - "strategiesAttempted"
        - "duplicateCount"
        - "cursorFailures"
        - "repeatedCursorCount"
        - "emptyFalseProgressPages"
        - "malformedCount"
        - "unrelatedCount"
        - "missingResponseModulesOrFields"
        - "recommendedFallback"
        - "richness"
        - "responseTruncated"
      properties:
        complete:
          type: "boolean"
          description: "Whether coverage met the target without truncation."
        reportedReplyCount:
          type: "integer"
          minimum: 0
          description: "Reply count reported on the source post."
        targetDirectReplies:
          type: "integer"
          minimum: 0
          description: "Minimum direct replies required for the coverage target."
        uniqueDirectReplies:
          type: "integer"
          minimum: 0
          description: "Unique replies whose parent ID equals the source post ID."
        coveragePercentage:
          type: "number"
          minimum: 0
          maximum: 100
          description: "Unique direct replies as a percentage of the reported count."
        nestedReplyCount:
          type: "integer"
          minimum: 0
          description: "Unique nested replies kept outside direct coverage."
        pagesAttempted:
          type: "integer"
          minimum: 0
          description: "Total pages attempted across all strategies."
        strategiesAttempted:
          type: "array"
          description: "Per-strategy pagination and contribution evidence."
          items:
            $ref: "#/components/schemas/ReplyCoverageStrategy"
        duplicateCount:
          type: "integer"
          minimum: 0
          description: "Duplicate tweet IDs removed across pages and strategies."
        cursorFailures:
          type: "integer"
          minimum: 0
          description: "Cursor requests that failed."
        repeatedCursorCount:
          type: "integer"
          minimum: 0
          description: "Repeated cursors rejected to prevent loops."
        emptyFalseProgressPages:
          type: "integer"
          minimum: 0
          description: "Empty pages rejected because they did not make progress."
        malformedCount:
          type: "integer"
          minimum: 0
          description: "Malformed response items rejected."
        unrelatedCount:
          type: "integer"
          minimum: 0
          description: "Tweets rejected because they belonged elsewhere."
        missingResponseModulesOrFields:
          type: "array"
          description: "Expected response modules or fields missing from X."
          items:
            type: "string"
        recommendedFallback:
          type: "string"
          description: "Recommended next action when coverage is incomplete."
        richness:
          $ref: "#/components/schemas/ReplyCoverageRichness"
        responseTruncated:
          type: "boolean"
          description: "Whether the requested row limit truncated safe results."
    PaginatedUsers:
      description: "Profile coverage preserves shape, billing, aliases, and filters.
        Follow next_cursor while has_next_page is true. Unprefixed cursors
        remain legacy.\n"
      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"
    UserListCoverageStrategy:
      type: "object"
      required:
        - "duplicateCount"
        - "pagesFetched"
        - "stopReason"
        - "strategy"
        - "uniqueAdded"
      properties:
        duplicateCount:
          type: "integer"
          minimum: 0
        pagesFetched:
          type: "integer"
          minimum: 0
        stopReason:
          $ref: "#/components/schemas/CoverageStopReason"
        strategy:
          type: "integer"
          minimum: 1
          maximum: 8
        uniqueAdded:
          type: "integer"
          minimum: 0
    UserListCoverageDiagnostic:
      description: "Coverage evidence across parallel relationship strategies."
      type: "object"
      required:
        - "complete"
        - "cursorFailureCount"
        - "deadlineReached"
        - "duplicateCount"
        - "failedStrategyCount"
        - "malformedCount"
        - "pagesFetched"
        - "responseTruncated"
        - "resultLimitReached"
        - "returnedUsers"
        - "stalledStrategyCount"
        - "strategies"
        - "strategyCount"
        - "uniqueUsers"
      properties:
        complete:
          type: "boolean"
          description: "True when every strategy exhausted its source."
        cursorFailureCount:
          type: "integer"
          minimum: 0
        deadlineReached:
          type: "boolean"
        duplicateCount:
          type: "integer"
          minimum: 0
        failedStrategyCount:
          type: "integer"
          minimum: 0
        malformedCount:
          type: "integer"
          minimum: 0
        pagesFetched:
          type: "integer"
          minimum: 0
        responseTruncated:
          type: "boolean"
          description: "Whether credits or the requested limit reduced output."
        resultLimitReached:
          type: "boolean"
        returnedUsers:
          type: "integer"
          minimum: 0
          maximum: 10000
        stalledStrategyCount:
          type: "integer"
          minimum: 0
        strategies:
          type: "array"
          items:
            $ref: "#/components/schemas/UserListCoverageStrategy"
        strategyCount:
          type: "integer"
          minimum: 1
          maximum: 8
        uniqueUsers:
          type: "integer"
          minimum: 0
          maximum: 10000
    UserListCoverageResponse:
      allOf:
        - $ref: "#/components/schemas/PaginatedUsers"
        - type: "object"
          required:
            - "diagnostic"
          properties:
            has_next_page:
              type: "boolean"
              const: false
            next_cursor:
              type: "string"
              const: ""
            diagnostic:
              $ref: "#/components/schemas/UserListCoverageDiagnostic"
    BatchUsers:
      description: "Batch lookup preserves first-seen ID order and ignores duplicate
        IDs. unavailable_ids were processed without profiles. unprocessed_ids
        were credit-limited.\n"
      type: "object"
      required:
        - "users"
        - "has_next_page"
        - "next_cursor"
        - "requested_count"
        - "processed_count"
        - "returned_count"
        - "unavailable_ids"
        - "unprocessed_ids"
      properties:
        users:
          type: "array"
          example:
            - id: "9876543210"
              username: "elonmusk"
              name: "Elon Musk"
          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."
          example: 2
        processed_count:
          type: "integer"
          minimum: 0
          maximum: 100
          description: "Number of requested IDs included in the lookup."
          example: 2
        returned_count:
          type: "integer"
          minimum: 0
          maximum: 100
          description: "Number of user profiles returned and charged."
          example: 1
        unavailable_ids:
          type: "array"
          description: "Processed IDs with no returned profile, in first-seen request
            order."
          items:
            type: "string"
            pattern: "^\\d+$"
          example:
            - "1234567890"
        unprocessed_ids:
          type: "array"
          description: "Requested IDs skipped because available credits limited
            processing. Retry these IDs after adding credits."
          items:
            type: "string"
            pattern: "^\\d+$"
          example: []
    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: "USD cents accepted for this checkout."
          example: 1000
        currency:
          type: "string"
          const: "usd"
    GuestWalletCheckoutResponse:
      description: "Pending hosted 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.\n"
          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"
          description: "Hosted checkout URL for user interaction."
          example: "https://checkout.example/guest/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"
          description: "Hosted checkout and status polling instructions."
        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"
            - 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"
          example: 2
        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.\n"
          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"
          example:
            method: "POST"
            path: "/api/v1/guest-wallets/topups"
        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"
          deprecated: true
          const: "stripe"
        required_headers:
          type: "object"
          additionalProperties: false
          required:
            - "Idempotency-Key"
          properties:
            Idempotency-Key:
              type: "string"
              const: "<cryptographically random UUID v4>"
        requires_authentication:
          type: "boolean"
          const: false
        requires_user_confirmation:
          type: "boolean"
          const: true
        requires_user_interaction:
          type: "boolean"
          const: true
        response_fields:
          type: "array"
          minItems: 3
          maxItems: 3
          prefixItems:
            - type: "string"
              const: "checkout_url"
            - type: "string"
              const: "api_key"
            - type: "string"
              const: "status_url"
          items:
            type: "string"
            enum:
              - "checkout_url"
              - "api_key"
              - "status_url"
        response_url_field:
          type: "string"
          const: "checkout_url"
    GuestWalletTopupCheckoutAction:
      description: "Explicit direct REST action for a guest wallet top-up."
      type: "object"
      additionalProperties: false
      required:
        - "account_required"
        - "amount_bounds"
        - "body"
        - "creates"
        - "method"
        - "path"
        - "provider"
        - "required_headers"
        - "requires_authentication"
        - "requires_user_confirmation"
        - "requires_user_interaction"
        - "response_fields"
        - "response_url_field"
      properties:
        account_required:
          type: "boolean"
          const: false
        amount_bounds:
          $ref: "#/components/schemas/GuestWalletAmountBounds"
        body:
          $ref: "#/components/schemas/GuestWalletPurchaseRequest"
        creates:
          type: "string"
          const: "checkout_url"
        method:
          type: "string"
          const: "POST"
        path:
          type: "string"
          const: "/api/v1/guest-wallets/topups"
        provider:
          type: "string"
          deprecated: true
          const: "stripe"
        required_headers:
          type: "object"
          additionalProperties: false
          required:
            - "Idempotency-Key"
          properties:
            Idempotency-Key:
              type: "string"
              const: "<cryptographically random UUID v4>"
        requires_authentication:
          type: "boolean"
          const: true
        requires_user_confirmation:
          type: "boolean"
          const: true
        requires_user_interaction:
          type: "boolean"
          const: true
        response_fields:
          type: "array"
          minItems: 2
          maxItems: 2
          prefixItems:
            - type: "string"
              const: "checkout_url"
            - type: "string"
              const: "status_url"
          items:
            type: "string"
            enum:
              - "checkout_url"
              - "status_url"
        response_url_field:
          type: "string"
          const: "checkout_url"
    AnonymousGuestAuthenticationRequired:
      description: "Authentication error for a non-MPP anonymous paid read. The
        response also offers an optional accountless checkout after
        confirmation.\n"
      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.\n"
      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
        hosted checkout actions."
      type: "object"
      additionalProperties: false
      required:
        - "balance"
        - "dashboard"
        - "error"
        - "message"
        - "next_step"
        - "payment_options"
        - "required"
        - "top_up_endpoint"
        - "top_up_url"
      properties:
        balance:
          type: "string"
          pattern: "^\\d+$"
          description: "Available credits as a decimal string."
          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"
                      deprecated: true
                      const: "stripe"
                    requires_authentication:
                      type: "boolean"
                      const: true
                    requires_user_confirmation:
                      type: "boolean"
                      const: true
                    response_url_field:
                      type: "string"
                      const: "url"
            subscription:
              type: "object"
              additionalProperties: false
              required:
                - "create_checkout"
              properties:
                create_checkout:
                  type: "object"
                  additionalProperties: false
                  required:
                    - "body"
                    - "creates"
                    - "method"
                    - "path"
                    - "provider"
                    - "requires_authentication"
                    - "requires_user_confirmation"
                    - "response_url_field"
                  properties:
                    body:
                      type: "object"
                      additionalProperties: false
                      required:
                        - "tier"
                      properties:
                        tier:
                          type: "string"
                          const: "starter"
                    creates:
                      type: "string"
                      const: "checkout_url"
                    method:
                      type: "string"
                      const: "POST"
                    path:
                      type: "string"
                      const: "/api/v1/subscribe"
                    provider:
                      type: "string"
                      deprecated: true
                      const: "stripe"
                    requires_authentication:
                      type: "boolean"
                      const: true
                    requires_user_confirmation:
                      type: "boolean"
                      const: true
                    response_url_field:
                      type: "string"
                      const: "url"
        required:
          type: "string"
          pattern: "^\\d+$"
          description: "Credits required for the blocked request."
          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 checkout action."
      type: "object"
      required:
        - "account_required"
        - "detail"
        - "next_step"
        - "payment_options"
        - "status"
        - "title"
        - "type"
      properties:
        account_required:
          type: "boolean"
          const: false
        challengeId:
          type: "string"
          description: "Opaque identifier for the MPP payment challenge."
          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.\n"
      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"
                - "closed"
                - "dm_not_permitted"
                - "invalid_format"
                - "invalid_id"
                - "invalid_input"
                - "invalid_params"
                - "invalid_tool_type"
                - "invalid_tweet_id"
                - "invalid_tweet_url"
                - "invalid_user_id"
                - "invalid_user_ids"
                - "invalid_username"
                - "invalid_json"
                - "insufficient_credits"
                - "login_cooldown"
                - "login_failed"
                - "media_download_failed"
                - "missing_params"
                - "missing_query"
                - "monitor_already_exists"
                - "monitor_profile_unavailable"
                - "no_media"
                - "no_credits"
                - "no_subscription"
                - "not_found"
                - "payment_failed"
                - "rate_limit_exceeded"
                - "service_unavailable"
                - "style_not_found"
                - "subscription_inactive"
                - "tweet_not_found"
                - "unauthenticated"
                - "unsupported_field"
                - "user_not_found"
                - "body_too_large"
                - "checkout_unavailable"
                - "connection_challenge_expired"
                - "connection_challenge_inactive"
                - "coverage_cursor_gone"
                - "coverage_cursor_unavailable"
                - "draft_not_found"
                - "expired"
                - "favoriters_unavailable"
                - "forbidden"
                - "guest_wallet_unavailable"
                - "guest_wallets_disabled"
                - "guest_wallets_unavailable"
                - "idempotency_conflict"
                - "idempotency_key_conflict"
                - "invalid_community_id"
                - "invalid_complete_replies_request"
                - "invalid_coverage_cursor"
                - "invalid_coverage_request"
                - "invalid_idempotency_key"
                - "invalid_list_id"
                - "invalid_output_options"
                - "invalid_payment_amount"
                - "invalid_range"
                - "invalid_reply_options"
                - "login_rate_limited"
                - "login_service_unavailable"
                - "missing_idempotency_key"
                - "missing_ids"
                - "missing_url"
                - "no_cached_style"
                - "passkey_required"
                - "rate_limited"
                - "read_request_timeout"
                - "replies_incomplete"
                - "support_media_rate_limit"
                - "support_request_rate_limit"
                - "too_many_ids"
                - "too_many_tweets"
                - "unknown_field"
                - "unsupported_media_type"
                - "webhook_inactive"
                - "write_tracking_unavailable"
                - "x_write_unconfirmed"
                - "x_account_feature_required"
                - "x_account_protected"
                - "x_account_suspended"
                - "x_api_rate_limited"
                - "x_api_unavailable"
                - "x_api_unauthorized"
                - "x_auth_failure"
                - "x_content_too_long"
                - "x_daily_limit"
                - "x_dm_not_allowed"
                - "x_duplicate_action"
                - "x_login_auth_failed"
                - "x_login_challenge"
                - "x_login_denied"
                - "x_login_failed"
                - "x_login_proxy_error"
                - "x_login_rate_limited"
                - "x_login_service_unavailable"
                - "x_login_suspended"
                - "x_rate_limited"
                - "x_rejected"
                - "x_target_not_found"
                - "x_transient_error"
                - "x_user_lookup_failed"
                - "x_write_ambiguous"
                - "x_write_failed"
              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"
                    - "closed"
                    - "dm_not_permitted"
                    - "invalid_format"
                    - "invalid_id"
                    - "invalid_input"
                    - "invalid_params"
                    - "invalid_tool_type"
                    - "invalid_tweet_id"
                    - "invalid_tweet_url"
                    - "invalid_user_id"
                    - "invalid_user_ids"
                    - "invalid_username"
                    - "invalid_json"
                    - "insufficient_credits"
                    - "login_cooldown"
                    - "login_failed"
                    - "media_download_failed"
                    - "missing_params"
                    - "missing_query"
                    - "monitor_already_exists"
                    - "monitor_profile_unavailable"
                    - "no_media"
                    - "no_credits"
                    - "no_subscription"
                    - "not_found"
                    - "payment_failed"
                    - "rate_limit_exceeded"
                    - "service_unavailable"
                    - "style_not_found"
                    - "subscription_inactive"
                    - "tweet_not_found"
                    - "unauthenticated"
                    - "unsupported_field"
                    - "user_not_found"
                    - "body_too_large"
                    - "checkout_unavailable"
                    - "connection_challenge_expired"
                    - "connection_challenge_inactive"
                    - "coverage_cursor_gone"
                    - "coverage_cursor_unavailable"
                    - "draft_not_found"
                    - "expired"
                    - "favoriters_unavailable"
                    - "forbidden"
                    - "guest_wallet_unavailable"
                    - "guest_wallets_disabled"
                    - "guest_wallets_unavailable"
                    - "idempotency_conflict"
                    - "idempotency_key_conflict"
                    - "invalid_community_id"
                    - "invalid_complete_replies_request"
                    - "invalid_coverage_cursor"
                    - "invalid_coverage_request"
                    - "invalid_idempotency_key"
                    - "invalid_list_id"
                    - "invalid_output_options"
                    - "invalid_payment_amount"
                    - "invalid_range"
                    - "invalid_reply_options"
                    - "login_rate_limited"
                    - "login_service_unavailable"
                    - "missing_idempotency_key"
                    - "missing_ids"
                    - "missing_url"
                    - "no_cached_style"
                    - "passkey_required"
                    - "rate_limited"
                    - "read_request_timeout"
                    - "replies_incomplete"
                    - "support_media_rate_limit"
                    - "support_request_rate_limit"
                    - "too_many_ids"
                    - "too_many_tweets"
                    - "unknown_field"
                    - "unsupported_media_type"
                    - "webhook_inactive"
                    - "write_tracking_unavailable"
                    - "x_write_unconfirmed"
                    - "x_account_feature_required"
                    - "x_account_protected"
                    - "x_account_suspended"
                    - "x_api_rate_limited"
                    - "x_api_unavailable"
                    - "x_api_unauthorized"
                    - "x_auth_failure"
                    - "x_content_too_long"
                    - "x_daily_limit"
                    - "x_dm_not_allowed"
                    - "x_duplicate_action"
                    - "x_login_auth_failed"
                    - "x_login_challenge"
                    - "x_login_denied"
                    - "x_login_failed"
                    - "x_login_proxy_error"
                    - "x_login_rate_limited"
                    - "x_login_service_unavailable"
                    - "x_login_suspended"
                    - "x_rate_limited"
                    - "x_rejected"
                    - "x_target_not_found"
                    - "x_transient_error"
                    - "x_user_lookup_failed"
                    - "x_write_ambiguous"
                    - "x_write_failed"
                  example: "invalid_input"
        message:
          type: "string"
          description: "Human-readable error guidance."
          example: "Invalid input. Check the request body."
        reason:
          type: "string"
          description: "Machine-readable reason for a login cooldown."
          example: "temporary_issue"
        retryAfter:
          type: "integer"
          minimum: 1
          description: "Seconds until the next permitted request."
          example: 60
        retryAfterMs:
          type: "integer"
          minimum: 1
          description: "Required wait in milliseconds."
          example: 60000
    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"
    ExtractionRequest:
      description: "One synchronous estimate or asynchronous extraction request."
      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"
        targetTweetIds:
          type: "array"
          minItems: 1
          maxItems: 10000
          uniqueItems: true
          items:
            type: "string"
          description: "Tweet IDs processed as one collection job."
        targetUsernames:
          type: "array"
          minItems: 1
          maxItems: 100
          uniqueItems: true
          items:
            type: "string"
          description: "Usernames processed as one collection job."
        targetCommunityIds:
          type: "array"
          minItems: 1
          maxItems: 100
          uniqueItems: true
          items:
            type: "string"
          description: "Community IDs processed as one collection job."
        targetListIds:
          type: "array"
          minItems: 1
          maxItems: 100
          uniqueItems: true
          items:
            type: "string"
          description: "List IDs processed as one collection job."
        searchQueries:
          type: "array"
          minItems: 1
          maxItems: 100
          uniqueItems: true
          items:
            type: "string"
          description: "Search queries processed as one collection job."
        targets:
          type: "array"
          maxItems: 10000
          items:
            $ref: "#/components/schemas/ExtractionMixedTarget"
          description: "Mixed targets auto-routed within one job."
        relationTargets:
          type: "array"
          maxItems: 100
          items:
            $ref: "#/components/schemas/ExtractionRelationTarget"
          description: "Profile relations processed within one job."
        queryType:
          type: "string"
          enum:
            - "Latest"
            - "Top"
            - "Both"
          default: "Latest"
          description: "Search ranking applied to every query."
        maxItemsPerTarget:
          type: "integer"
          minimum: 1
          description: "Maximum results collected for each target."
        maxPagesPerTarget:
          type: "integer"
          minimum: 1
          maximum: 1000
          description: "Reply pages collected for each target."
        startCursor:
          type: "string"
          minLength: 1
          description: "Resume one reply target from this cursor."
        dedupeAcrossTargets:
          type: "boolean"
          default: true
          description: "Merge duplicate results across collection targets."
        dedupeMode:
          type: "string"
          enum:
            - "none"
            - "first"
            - "merge"
          description: "Keep target duplicates, first rows, or merged overlap."
        overlapMode:
          type: "boolean"
          default: false
          description: "Shortcut for dedupeMode=merge."
        includeSearchTerms:
          type: "boolean"
          default: false
          description: "Add matching search terms to collection metadata."
        includeTargetMetadata:
          type: "boolean"
          default: true
          description: "Add source target metadata to each result."
        collectionStrategy:
          type: "string"
          enum:
            - "auto"
            - "complete"
            - "direct"
            - "search"
            - "thread"
          default: "auto"
          description: "Reply collection strategy."
        scope:
          type: "string"
          enum:
            - "all"
            - "direct"
            - "nested"
          default: "all"
          description: "Reply depth scope."
        maxDepth:
          type: "integer"
          minimum: 1
          description: "Maximum nested reply depth."
        sort:
          type: "string"
          enum:
            - "relevance"
            - "latest"
            - "oldest"
            - "likes"
          default: "relevance"
          description: "Reply result order."
        excludeOriginalAuthor:
          type: "boolean"
          default: false
          description: "Exclude replies from the source author."
        includeOriginalPost:
          type: "boolean"
          default: false
          description: "Include the source post in reply results."
        hasMediaOnly:
          type: "boolean"
          default: false
          description: "Return only replies with media."
        sinceTime:
          oneOf:
            - type: "string"
              format: "date-time"
            - type: "integer"
          description: "Reply start time as ISO 8601 or Unix seconds."
        untilTime:
          oneOf:
            - type: "string"
              format: "date-time"
            - type: "integer"
          description: "Reply end time as ISO 8601 or Unix seconds."
        minViews:
          type: "integer"
          minimum: 0
          description: "Minimum Tweet view count."
        minBookmarks:
          type: "integer"
          minimum: 0
          description: "Minimum Tweet bookmark count."
        maxLikes:
          type: "integer"
          minimum: 0
          description: "Maximum Tweet like count."
        maxRetweets:
          type: "integer"
          minimum: 0
          description: "Maximum Tweet repost count."
        maxReplies:
          type: "integer"
          minimum: 0
          description: "Maximum Tweet reply count."
        maxQuotes:
          type: "integer"
          minimum: 0
          description: "Maximum Tweet quote count."
        blueVerifiedOnly:
          type: "boolean"
          default: false
          description: "Return only Blue-verified Tweet authors."
        cardName:
          type: "string"
          description: "Match the Tweet card name."
        source:
          type: "string"
          description: "Match the source application."
        excludeSource:
          type: "string"
          description: "Exclude a source application."
        geocode:
          type: "string"
          description: "Match latitude, longitude, and radius."
        sinceId:
          type: "string"
          description: "Return Tweets newer than this Tweet ID."
        maxId:
          type: "string"
          description: "Return Tweets older than this Tweet ID."
        near:
          type: "string"
          description: "Match a place name."
        within:
          type: "string"
          description: "Set the radius for the near filter."
        withinTime:
          type: "string"
          description: "Match Tweets inside a recent time window."
        nativeRetweets:
          type: "boolean"
          default: false
          description: "Only return native reposts."
        safe:
          type: "boolean"
          default: false
          description: "Enable the safe-search filter."
        news:
          type: "boolean"
          default: false
          description: "Only return news results."
        minFollowers:
          type: "integer"
          minimum: 0
          description: "Minimum follower count for profile results."
        maxFollowers:
          type: "integer"
          minimum: 0
          description: "Maximum follower count for profile results."
        minFollowing:
          type: "integer"
          minimum: 0
          description: "Minimum following count for profile results."
        maxFollowing:
          type: "integer"
          minimum: 0
          description: "Maximum following count for profile results."
        minPosts:
          type: "integer"
          minimum: 0
          description: "Minimum post count for profile results."
        maxPosts:
          type: "integer"
          minimum: 0
          description: "Maximum post count for profile results."
        minAccountAgeDays:
          type: "integer"
          minimum: 0
          description: "Minimum profile age in days."
        verifiedType:
          type: "string"
          description: "Exact profile verification type."
        hasWebsite:
          type: "boolean"
          default: false
          description: "Require a profile website."
        hasLocation:
          type: "boolean"
          default: false
          description: "Require a profile location."
        bioContains:
          type: "string"
          description: "Bio terms separated by commas or lines."
        locationContains:
          type: "string"
          description: "Required profile location text."
        usernameContains:
          type: "string"
          description: "Required username text."
        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"
    ExtractionMixedTarget:
      description: "One auto-routed target in a mixed Tweet collection."
      oneOf:
        - type: "string"
          description: "X URL, numeric Tweet ID, @username, kind:value target, or search.\n"
        - type: "object"
          required:
            - "kind"
            - "value"
          properties:
            kind:
              type: "string"
              enum:
                - "favoriters"
                - "list"
                - "profile"
                - "profile_likes"
                - "profile_media"
                - "profile_replies"
                - "quotes"
                - "replies"
                - "retweeters"
                - "search"
                - "thread"
                - "tweet"
            value:
              type: "string"
              minLength: 1
    ExtractionRelationTarget:
      description: "One target and relation in a mixed profile collection."
      type: "object"
      required:
        - "relation"
        - "value"
      properties:
        relation:
          type: "string"
          enum:
            - "community_members"
            - "followers"
            - "following"
            - "list_followers"
            - "list_members"
            - "verified_followers"
        value:
          type: "string"
          minLength: 1
    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"
        pausedReason:
          type: "string"
          enum:
            - "x_user_not_found"
          description: "Why Xquik automatically paused this monitor."
        pausedAt:
          type: "string"
          format: "date-time"
          description: "When Xquik automatically paused this monitor."
    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:
          $ref: "#/components/schemas/PublicMetadata"
          description: "Event payload - shape varies by event type (JSON)"
          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. paused means the user paused delivery.
            needs_attention marks repeated failures. Delivery attempts
            continue."
          example: "active"
        failureHardCap:
          type: "integer"
          description: "Maximum reported failures before needs_attention. It does not
            pause delivery."
          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"
    TweetMedia:
      description: "Tweet media."
      type: "object"
      required:
        - "mediaUrl"
        - "type"
        - "url"
      properties:
        mediaUrl:
          type: "string"
          description: "Preview URL."
        type:
          type: "string"
          enum:
            - "photo"
            - "video"
            - "animated_gif"
        url:
          type: "string"
          description: "Tweet media link."
        adultContent:
          type: "boolean"
          description: "Adult-content warning."
        allowDownload:
          type: "boolean"
          description: "Direct download permission."
        altText:
          type: "string"
          description: "Accessibility text."
        aspectRatio:
          type: "array"
          description: "Video width and height ratio."
          items:
            type: "integer"
        availabilityReason:
          type: "string"
          description: "Availability reason."
        availabilityStatus:
          type: "string"
          description: "Availability state."
        description:
          type: "string"
          description: "Media description."
        displayUrl:
          type: "string"
          description: "Display URL."
        durationMillis:
          type: "integer"
          description: "Video duration in milliseconds."
        expandedUrl:
          type: "string"
          description: "Expanded media URL."
        embeddable:
          type: "boolean"
          description: "Embeddable status."
        faceRects:
          type: "object"
          description: "Face crop rectangles by size."
          additionalProperties:
            type: "array"
            items:
              type: "object"
              required:
                - "x"
                - "y"
                - "w"
                - "h"
              properties:
                x:
                  type: "integer"
                y:
                  type: "integer"
                w:
                  type: "integer"
                h:
                  type: "integer"
        focusRects:
          type: "array"
          description: "Suggested image crops."
          items:
            type: "object"
            required:
              - "x"
              - "y"
              - "w"
              - "h"
            properties:
              x:
                type: "integer"
              y:
                type: "integer"
              w:
                type: "integer"
              h:
                type: "integer"
        grokPostId:
          type: "string"
          description: "Grok post ID associated with the media."
        height:
          type: "integer"
          description: "Original height."
        id:
          type: "string"
          description: "Media entity ID."
        indices:
          type: "array"
          description: "Tweet text offsets."
          items:
            type: "integer"
        mediaKey:
          type: "string"
          description: "Stable X media key."
        monetizable:
          type: "boolean"
          description: "Monetization status."
        sizes:
          type: "object"
          description: "Named media renditions and resize modes."
          additionalProperties:
            type: "object"
            required:
              - "w"
              - "h"
              - "resize"
            properties:
              w:
                type: "integer"
              h:
                type: "integer"
              resize:
                type: "string"
        sourceStatusId:
          type: "string"
          description: "Source tweet ID for copied media."
        sourceUserId:
          type: "string"
          description: "Source profile ID for copied media."
        tags:
          type: "array"
          description: "Public profiles tagged in the media."
          items:
            type: "object"
            properties:
              name:
                type: "string"
              screen_name:
                type: "string"
              type:
                type: "string"
              user_id:
                type: "string"
        title:
          type: "string"
          description: "Media title."
        videoVariants:
          type: "array"
          description: "Video encodings in source order."
          items:
            type: "object"
            required:
              - "contentType"
              - "url"
            properties:
              bitrate:
                type: "integer"
              contentType:
                type: "string"
              url:
                type: "string"
        watchNowUrl:
          type: "string"
          description: "Public media action URL."
        visitSiteUrl:
          type: "string"
          description: "Public destination URL."
        width:
          type: "integer"
          description: "Original width."
    PublicMetadata:
      description: "Public metadata whose fields are defined by X."
      type: "object"
      additionalProperties: true
      x-stainless-any: true
      x-stainless-terraform-type: "string"
    TweetArticleMetadata:
      description: "Article metadata attached to a tweet."
      type: "object"
      properties:
        coverMedia:
          $ref: "#/components/schemas/PublicMetadata"
        id:
          type: "string"
        lifecycleState:
          $ref: "#/components/schemas/PublicMetadata"
        metadata:
          $ref: "#/components/schemas/PublicMetadata"
        title:
          type: "string"
        previewText:
          type: "string"
        coverMediaUrl:
          type: "string"
    TweetCard:
      description: "Public card metadata attached to a tweet."
      type: "object"
      properties:
        id:
          type: "string"
        name:
          type: "string"
        url:
          type: "string"
        bindingValues:
          $ref: "#/components/schemas/PublicMetadata"
        platform:
          $ref: "#/components/schemas/PublicMetadata"
          description: "Public card delivery platform metadata."
        userReferences:
          type: "array"
          items:
            $ref: "#/components/schemas/UserProfile"
    TweetCommunityNote:
      description: "Community Note presentation metadata returned by X."
      type: "object"
      properties:
        id:
          type: "string"
        title:
          type: "string"
        shortTitle:
          type: "string"
        subtitle:
          type: "string"
        footer:
          type: "string"
        destinationUrl:
          type: "string"
        visualStyle:
          type: "string"
    TweetEdit:
      description: "Tweet edits."
      type: "object"
      properties:
        editTweetIds:
          type: "array"
          items:
            type: "string"
        editableUntilMsecs:
          type: "string"
        initialTweetId:
          type: "string"
    TweetEntities:
      description: "Public tweet entities."
      type: "object"
      additionalProperties: true
      properties:
        hashtags:
          type: "array"
          items:
            $ref: "#/components/schemas/TweetHashtag"
        smarttags:
          type: "array"
          items:
            type: "object"
            additionalProperties: true
        symbols:
          type: "array"
          items:
            $ref: "#/components/schemas/TweetSymbol"
        timestamps:
          description: "Video timestamp entities with indices, seconds, and text."
          type: "array"
          items:
            type: "object"
            additionalProperties: true
        urls:
          type: "array"
          items:
            $ref: "#/components/schemas/TweetUrlEntity"
        user_mentions:
          type: "array"
          items:
            $ref: "#/components/schemas/TweetUserMention"
    TweetHashtag:
      type: "object"
      additionalProperties: true
      required:
        - "text"
      properties:
        indices:
          type: "array"
          items:
            type: "integer"
        text:
          type: "string"
    TweetSymbol:
      description: "Public cashtag and market metadata."
      type: "object"
      additionalProperties: true
      properties:
        indices:
          type: "array"
          items:
            type: "integer"
        text:
          type: "string"
        tag:
          type: "object"
          additionalProperties: true
          properties:
            info:
              type: "object"
              additionalProperties: true
              properties:
                info:
                  type: "object"
                  additionalProperties: true
                  properties:
                    name:
                      type: "string"
                    ticker:
                      type: "string"
    TweetUrlEntity:
      type: "object"
      additionalProperties: true
      properties:
        display_url:
          type: "string"
        expanded_url:
          type: "string"
        indices:
          type: "array"
          items:
            type: "integer"
        url:
          type: "string"
    TweetUserMention:
      type: "object"
      additionalProperties: true
      required:
        - "screen_name"
      properties:
        id_str:
          type: "string"
        indices:
          type: "array"
          items:
            type: "integer"
        name:
          type: "string"
        screen_name:
          type: "string"
    TweetNote:
      description: "Complete Note Tweet content and rich-text metadata."
      type: "object"
      required:
        - "text"
      properties:
        id:
          type: "string"
        text:
          type: "string"
        isExpandable:
          type: "boolean"
        entities:
          $ref: "#/components/schemas/TweetEntities"
        richtextTags:
          type: "array"
          items:
            type: "object"
            required:
              - "fromIndex"
              - "toIndex"
              - "types"
            properties:
              fromIndex:
                type: "integer"
              toIndex:
                type: "integer"
              types:
                type: "array"
                items:
                  type: "string"
    TweetPreviousCounts:
      description: "Engagement counts retained from a prior tweet edit."
      type: "object"
      properties:
        bookmarkCount:
          type: "integer"
        likeCount:
          type: "integer"
        quoteCount:
          type: "integer"
        replyCount:
          type: "integer"
        retweetCount:
          type: "integer"
    TweetPlace:
      description: "Public place metadata attached to a tweet."
      type: "object"
      properties:
        boundingBox:
          $ref: "#/components/schemas/PublicMetadata"
        country:
          type: "string"
        countryCode:
          type: "string"
        fullName:
          type: "string"
        id:
          type: "string"
        name:
          type: "string"
        placeType:
          type: "string"
        url:
          type: "string"
    TweetTombstone:
      description: "Public visibility notice attached to an available tweet."
      type: "object"
      properties:
        type:
          type: "string"
          description: "Visibility notice type."
        text:
          type: "object"
          properties:
            text:
              type: "string"
              description: "Human-readable notice text."
            rtl:
              type: "boolean"
              description: "Right-to-left text direction."
            entities:
              type: "array"
              items:
                type: "object"
                properties:
                  fromIndex:
                    type: "integer"
                  toIndex:
                    type: "integer"
                  ref:
                    type: "object"
                    properties:
                      type:
                        type: "string"
                      url:
                        type: "string"
                      urlType:
                        type: "string"
    TweetPublicData:
      description: "Public fields shared by tweet response shapes."
      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"
        url:
          type: "string"
          example: "https://x.com/example_user/status/1234567890"
        lang:
          type: "string"
          example: "en"
        isReply:
          type: "boolean"
          example: false
        isLimitedReply:
          type: "boolean"
          example: false
        isNoteTweet:
          type: "boolean"
          example: false
        isQuoteStatus:
          type: "boolean"
          example: false
        quotedTweetId:
          type: "string"
          description: "Quoted tweet ID."
        inReplyToId:
          type: "string"
          example: "1234567890"
        inReplyToUserId:
          type: "string"
          example: "9876543210"
        inReplyToUsername:
          type: "string"
          example: "example_user"
        conversationId:
          type: "string"
          example: "1234567890"
        conversationControl:
          type: "object"
          description: "Public reply policy and conversation owner."
          properties:
            inviteViaMention:
              type: "boolean"
            ownerUsername:
              type: "string"
            policy:
              type: "string"
              example: "by_invitation"
        limitedActions:
          type: "array"
          description: "Public interaction restrictions and user-facing prompts."
          items:
            type: "object"
            properties:
              action:
                type: "string"
                example: "Reply"
              prompt:
                type: "object"
                properties:
                  ctaType:
                    type: "string"
                    example: "SeeConversation"
                  headline:
                    type: "string"
                  subtext:
                    type: "string"
        source:
          type: "string"
          example: "Twitter Web App"
        displayTextRange:
          type: "array"
          items:
            type: "integer"
          example:
            - 0
            - 31
        contentDisclosure:
          $ref: "#/components/schemas/ContentDisclosure"
        article:
          $ref: "#/components/schemas/TweetArticleMetadata"
        card:
          $ref: "#/components/schemas/TweetCard"
        communityId:
          type: "string"
          description: "Community ID."
        communityNote:
          $ref: "#/components/schemas/TweetCommunityNote"
        edit:
          $ref: "#/components/schemas/TweetEdit"
        isTranslatable:
          type: "boolean"
        noteTweet:
          $ref: "#/components/schemas/TweetNote"
        place:
          $ref: "#/components/schemas/TweetPlace"
        possiblySensitive:
          type: "boolean"
        previousCounts:
          $ref: "#/components/schemas/TweetPreviousCounts"
        tombstone:
          $ref: "#/components/schemas/TweetTombstone"
        unmentionedUserIds:
          type: "array"
          description: "User IDs that left this conversation."
          items:
            type: "string"
        viewState:
          type: "string"
        entities:
          $ref: "#/components/schemas/TweetEntities"
        quoted_tweet:
          $ref: "#/components/schemas/EmbeddedTweet"
        retweeted_tweet:
          $ref: "#/components/schemas/EmbeddedTweet"
        media:
          type: "array"
          items:
            $ref: "#/components/schemas/TweetMedia"
          description: "Attached media items, omitted when unavailable."
        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
    EmbeddedTweet:
      description: "Quoted or retweeted tweet context."
      allOf:
        - $ref: "#/components/schemas/TweetPublicData"
        - type: "object"
          properties:
            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"
            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."
      allOf:
        - $ref: "#/components/schemas/TweetPublicData"
        - type: "object"
          properties:
            author:
              $ref: "#/components/schemas/TweetAuthor"
    TweetAuthor:
      description: "Tweet author profile. The lookup route always includes follower
        count and verification state. Other profile fields appear when
        available."
      example:
        id: "9876543210"
        username: "elonmusk"
        name: "Elon Musk"
        followers: 150000000
        verified: true
      allOf:
        - $ref: "#/components/schemas/UserProfile"
        - title: "TweetAuthorRequirements"
          type: "object"
          required:
            - "followers"
            - "verified"
          properties:
            followers:
              type: "integer"
              minimum: 0
              example: 150000000
            verified:
              type: "boolean"
              example: true
    SearchTweet:
      description: "Tweet returned from search results with inline author info. A zero
        metric can mean X did not report the count."
      allOf:
        - $ref: "#/components/schemas/TweetPublicData"
        - type: "object"
          properties:
            author:
              $ref: "#/components/schemas/UserProfile"
    UserAffiliateLabel:
      description: "Organization affiliation label shown on an X profile."
      type: "object"
      properties:
        badgeUrl:
          type: "string"
        description:
          type: "string"
        url:
          type: "string"
        urlType:
          type: "string"
        userLabelDisplayType:
          type: "string"
        userLabelType:
          type: "string"
    UserHighlightsInfo:
      description: "Profile highlight availability and count metadata."
      type: "object"
      properties:
        canHighlightTweets:
          type: "boolean"
        highlightedTweets:
          type: "string"
    UserIdentityVerification:
      description: "Identity verification metadata displayed by X."
      type: "object"
      properties:
        description:
          type: "string"
        isIdentityVerified:
          type: "boolean"
        verifiedSinceMsec:
          type: "string"
    UserTipJar:
      description: "Public payment and creator-support handles shown on X."
      type: "object"
      properties:
        bandcampHandle:
          type: "string"
        bitcoinHandle:
          type: "string"
        cashAppHandle:
          type: "string"
        ethereumHandle:
          type: "string"
        gofundmeHandle:
          type: "string"
        isEnabled:
          type: "boolean"
        patreonHandle:
          type: "string"
        payPalHandle:
          type: "string"
        venmoHandle:
          type: "string"
    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
        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"
        withheldScope:
          type: "string"
          description: "Whether X withholds a post or user"
          example: "user"
        possiblySensitive:
          type: "boolean"
          example: false
        professional:
          $ref: "#/components/schemas/PublicMetadata"
          description: "Public professional profile metadata returned by X"
        grokTranslatedBio:
          $ref: "#/components/schemas/PublicMetadata"
          description: "Public profile bio translation returned by X"
        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"
        affiliatesHighlightedLabel:
          $ref: "#/components/schemas/UserAffiliateLabel"
        businessAccountAffiliatesCount:
          type: "integer"
        creatorSubscriptionsCount:
          type: "integer"
        hasGraduatedAccess:
          type: "boolean"
        hasHiddenSubscriptionsOnProfile:
          type: "boolean"
        highlightsInfo:
          $ref: "#/components/schemas/UserHighlightsInfo"
        identityVerification:
          $ref: "#/components/schemas/UserIdentityVerification"
        isProfileTranslatable:
          type: "boolean"
        parodyCommentaryFanLabel:
          type: "string"
        profileDescriptionLanguage:
          type: "string"
        profileImageShape:
          type: "string"
        profileInterstitialType:
          type: "string"
        profileSortEnabled:
          type: "boolean"
        profileTranslatorType:
          type: "string"
        superFollowEligible:
          type: "boolean"
        superFollowsUserProfileActive:
          type: "boolean"
          description: "Whether X marks the subscription profile as active."
        tipJar:
          $ref: "#/components/schemas/UserTipJar"
        communityRole:
          type: "string"
          description: "Community role when returned by community member reads"
          example: "Member"
        profile_bio:
          $ref: "#/components/schemas/PublicMetadata"
          description: "Structured profile bio with entity annotations"
          example:
            description: "CEO of Tesla, SpaceX, and X"
            entities:
              urls: []
    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"
          description: "BCP-47 language code. und means the source did not identify a
            language."
        metadata:
          type: "object"
          description: "Source fields vary:

            - reddit: { author, authorId?, subreddit, subredditId?,

            \  subredditSubscribers?, sourceFormat, score?, upvoteRatio?,

            \  estimatedUpvotes?, estimatedDownvotes?, numberComments?,

            \  numberCrossposts?, selftext?, contentUrl?, domain?, postHint?,

            \  linkFlairText?, distinguished?, totalAwardsReceived?, viewCount?,

            \  editedAt?, galleryImageUrls?, redditVideo?, archived?,
            contestMode?,

            \  isCrosspostable?, isMeta?, isNsfw?, isOriginalContent?,

            \  isRobotIndexable?, isSelf?, isSpoiler?, isVideo?, locked?,

            \  stickied? }.

            - github: { starsToday }

            - hacker_news: { points, numberComments }

            - google_trends: { approxTraffic }

            - polymarket: { volume24hr }

            - wikipedia: { views }

            - trustmrr: { mrr, growthPercent, last30Days, total, customers,
            activeSubscriptions, onSale, xHandle?, category?, askingPrice?,
            country?, foundedDate?, googleSearchImpressionsLast30Days?,
            growthMrrPercent?, multiple?, paymentProvider?,
            profitMarginLast30Days?, rank?, revenuePerVisitor?, targetAudience?,
            visitorsLast30Days? }

            Reddit score is public net. Vote estimates use its fuzzed ratio.

            Comments are omitted. Startup xHandle omits @. rank is its growth

            rank.\n"
          properties:
            author:
              type: "string"
            contentUrl:
              type: "string"
              format: "uri"
            estimatedDownvotes:
              type: "integer"
              minimum: 0
            estimatedUpvotes:
              type: "integer"
              minimum: 0
            numberComments:
              type: "integer"
              minimum: 0
            score:
              type: "integer"
            selftext:
              type: "string"
            sourceFormat:
              type: "string"
              enum:
                - "html"
                - "json"
                - "rss"
              description: "Current items use html. json and rss are retained for legacy
                rows."
            subreddit:
              type: "string"
            upvoteRatio:
              type: "number"
              minimum: 0
              maximum: 1
          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"
          description: "Source image. Startup growth items return the logo here."
          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 health. `healthy` is ready. `needsReauth` needs
            credentials. `locked` must be unlocked on X. `suspended` is banned.
            `recovering` can reconnect. Wait before using `temporaryIssue`.\n"
          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"
          const: "x_account_connection_challenge"
          example: "x_account_connection_challenge"
        id:
          type: "string"
          example: "xch_8vGd8Y9JvH6dV0xA"
        status:
          type: "string"
          const: "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"
    XAccountConnectionContinuation:
      description: "The connection is still running or needs an email code."
      oneOf:
        - $ref: "#/components/schemas/XAccountConnectionAttemptPending"
        - $ref: "#/components/schemas/XAccountConnectionChallenge"
      discriminator:
        propertyName: "status"
        mapping:
          pending: "#/components/schemas/XAccountConnectionAttemptPending"
          requires_email_code: "#/components/schemas/XAccountConnectionChallenge"
    XAccountConnectionAttemptPending:
      description: "The connection is still in progress."
      type: "object"
      additionalProperties: false
      required:
        - "object"
        - "id"
        - "status"
        - "pollAfterMs"
      properties:
        object:
          type: "string"
          const: "x_account_connection_attempt"
          example: "x_account_connection_attempt"
        id:
          type: "string"
          example: "xatt_0123456789abcdef0123456789abcdef"
        status:
          type: "string"
          const: "pending"
          example: "pending"
        pollAfterMs:
          type: "integer"
          minimum: 0
          example: 3000
    XAccountConnectionAttemptSuccess:
      description: "The account connected successfully."
      type: "object"
      additionalProperties: false
      required:
        - "object"
        - "id"
        - "status"
      properties:
        object:
          type: "string"
          const: "x_account_connection_attempt"
          example: "x_account_connection_attempt"
        id:
          type: "string"
          example: "xatt_0123456789abcdef0123456789abcdef"
        status:
          type: "string"
          const: "success"
          example: "success"
    XAccountConnectionAttemptFailed:
      description: "The connection reached a final failure."
      type: "object"
      additionalProperties: false
      required:
        - "object"
        - "id"
        - "status"
        - "error"
        - "retryable"
      properties:
        object:
          type: "string"
          const: "x_account_connection_attempt"
          example: "x_account_connection_attempt"
        id:
          type: "string"
          example: "xatt_0123456789abcdef0123456789abcdef"
        status:
          type: "string"
          const: "failed"
          example: "failed"
        error:
          type: "string"
          example: "service_unavailable"
        reason:
          type: "string"
          example: "wrong_password"
        retryable:
          type: "boolean"
          example: true
    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"
          const: "active"
          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"
webhooks:
  monitorEvent:
    post:
      description: "Receive one signed Xquik monitor event."
      operationId: "receiveMonitorEvent"
      requestBody:
        content:
          application/json:
            example:
              data:
                id: "1893456789012345678"
                text: "Example post."
              eventType: "tweet.new"
              username: "example"
            schema:
              properties:
                data:
                  additionalProperties: true
                  type: "object"
                eventType:
                  $ref: "#/components/schemas/EventType"
                username:
                  type: "string"
              required:
                - "eventType"
                - "data"
              type: "object"
        required: true
      responses:
        "200":
          description: "Event accepted."
      security: []
      summary: "Receive monitor event"
      tags:
        - "Webhooks"
