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. Look up tweets, users, and X trends. Search tweets, check follow relationships, download media, and monitor\
    \ accounts. 33 paid-read endpoints accept prepaid credits without a subscription. 7 fixed-price lookups also accept direct\
    \ MPP payments. Write and automation endpoints require an API key or OAuth 2.1 bearer token.\n\n## Xquik SDKs\n\nStainless\
    \ generates each SDK from this OpenAPI schema. Pick a language:\n\n- TypeScript / Node.js: `npm i x-twitter-scraper` -\n\
    \  [Xquik-dev/x-twitter-scraper-typescript](https://github.com/Xquik-dev/x-twitter-scraper-typescript)\n\n- Python: `pip\
    \ install x-twitter-scraper` -\n  [Xquik-dev/x-twitter-scraper-python](https://github.com/Xquik-dev/x-twitter-scraper-python)\n\
    \n- Go: `go get github.com/Xquik-dev/x-twitter-scraper-go` -\n  [Xquik-dev/x-twitter-scraper-go](https://github.com/Xquik-dev/x-twitter-scraper-go)\n\
    \n- Ruby: `gem install x-twitter-scraper` -\n  [Xquik-dev/x-twitter-scraper-ruby](https://github.com/Xquik-dev/x-twitter-scraper-ruby)\n\
    \n- Java (source build; Maven Central pending) -\n  [Xquik-dev/x-twitter-scraper-java](https://github.com/Xquik-dev/x-twitter-scraper-java)\n\
    \n- Kotlin (source build; Maven Central pending) -\n  [Xquik-dev/x-twitter-scraper-kotlin](https://github.com/Xquik-dev/x-twitter-scraper-kotlin)\n\
    \n- C# / .NET: `dotnet add package XTwitterScraper` -\n  [Xquik-dev/x-twitter-scraper-csharp](https://github.com/Xquik-dev/x-twitter-scraper-csharp)\n\
    \n- PHP: `composer require xquik/x-twitter-scraper` -\n  [Xquik-dev/x-twitter-scraper-php](https://github.com/Xquik-dev/x-twitter-scraper-php)\n\
    \n- CLI: `go install github.com/Xquik-dev/x-twitter-scraper-cli/cmd/x-twitter-scraper@latest` -\n  [Xquik-dev/x-twitter-scraper-cli](https://github.com/Xquik-dev/x-twitter-scraper-cli)\n\
    \n- Terraform Provider (Terraform Registry) -\n  [Xquik-dev/terraform-provider-x-twitter-scraper](https://github.com/Xquik-dev/terraform-provider-x-twitter-scraper)\n\
    \n\nOpenClaw plugin: [Xquik-dev/tweetclaw](https://github.com/Xquik-dev/tweetclaw) (`openclaw plugins install clawhub:@xquik/tweetclaw`)."
  x-guidance: '## Common tasks


    **Find a tweet** - GET /x/tweets/{id} with a numeric tweet ID. Returns full tweet data: text, author, metrics (likes,
    retweets, replies, views), media URLs, and creation timestamp. Cost: $0.00015 per lookup.


    **Search tweets** - GET /x/tweets/search?q={query}&limit={n}. Supports X search operators, structured filters like fromUser,
    mediaType, minFaves, hashtags, and verifiedOnly, plus exact lookup for a pasted Tweet ID or X status URL. Plain from:user
    date windows are optimized for timeline completeness. Returns up to 200 tweets per page with cursor-based pagination.
    Cost: $0.00015 per tweet returned.


    **Find a user** - GET /x/users/{id} where {id} is a numeric user ID or @username. Returns profile data: name, bio, follower/following
    counts, verification status, join date. Cost: $0.00015 per lookup.


    **Check if A follows B** - GET /x/followers/check?source={a}&target={b} where source and target are usernames, @usernames,
    or X or Twitter profile URLs. Cost: $0.00075.


    **Get trending topics** - GET /trends?woeid={region}&count={n}. WOEID 1 = worldwide, 23424977 = US, 23424975 = UK, 23424969
    = Turkey. Cost: $0.00045.


    **Download media** - POST /x/media/download with {"tweetIds": ["123", "456"]} body. Returns download URLs for images and
    videos. Cost: 1 credit per fresh tweet processed with media; cached repeat downloads are free.


    **Read an article** - GET /x/articles/{tweetId} for long-form X Articles. Returns full article HTML, cover image, and
    metadata. Cost: $0.00075.


    ## Pagination


    Default v1 responses keep their existing pagination fields for compatibility. Platform list endpoints return `hasMore`
    and `nextCursor`; X data endpoints return `has_next_page` and `next_cursor`. Send `xquik-api-contract: 2026-04-29` to
    receive the unified best-practice fields `has_more` and `next_cursor`. Pass the cursor back as `?cursor={cursor}`; legacy
    `?after={cursor}` still works. Dynamic-priced endpoints charge per item returned, not per request.


    ## Authentication


    Eligible paid read endpoints accept accountless prepaid credit wallets. Fixed-price lookups also accept direct MPP payments.
    Media downloads, write endpoints, and automation features require authentication. Send an Xquik API key through `x-api-key`,
    `Xquik-Api-Key`, or `Authorization: Bearer xq_...`. Send an OAuth 2.1 access token through `Authorization: Bearer`.


    ## Best-Practice Response Contract


    v1 keeps its original response contract by default so existing integrations do not break. Send `xquik-api-contract: 2026-04-29`
    to opt in to the best-practice contract: snake_case response fields, Unix timestamps in seconds, structured error objects,
    `has_more` and `next_cursor` pagination fields, `object` resource identifiers, and prefixed IDs where available. Dependency
    failures that returned 502 in default v1 return 424 in the opt-in contract. Future major API versions should make this
    contract the default.'
  contact:
    name: Xquik
    url: https://xquik.com
    email: support@xquik.com
servers:
- url: https://xquik.com
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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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.

        '
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
  /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.

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

                  '
                passed: true
                passedCount: 9
                topSuggestion: All Xquik editorial checks passed.
                totalChecks: 9
                intentUrl: https://x.com/intent/tweet?text=PostgreSQL%2018%20reduced%20query%20latency
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
  /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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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: elonmusk
                tweetCount: 1
                isOwnAccount: true
                fetchedAt: '2025-01-15T12:00:00Z'
                tweets:
                - id: '1234567890'
                  text: Excited to share our latest research findings.
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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':
          description: X user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: user_not_found
                message: X user not found. Check the username.
        '409':
          description: Monitor already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: monitor_already_exists
                message: Monitor already exists.
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
  /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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
  /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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: 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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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: Filter events by monitor ID
        schema:
          type: string
      - name: eventType
        in: query
        description: Filter events by type
        schema:
          $ref: '#/components/schemas/EventType'
      responses:
        '200':
          description: Event list
          content:
            application/json:
              schema:
                type: object
                required:
                - events
                - hasMore
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                    example: []
                  hasMore:
                    type: boolean
                    example: false
                  nextCursor:
                    type: string
                    example: abc123
              example:
                events: []
                hasMore: false
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: List extraction jobs.
    post:
      operationId: createExtraction
      summary: Run extraction
      tags:
      - Extractions
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - name: dry_run
        in: query
        description: Return a cost estimate without creating or running 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:
              type: object
              required:
              - toolType
              properties:
                toolType:
                  $ref: '#/components/schemas/ExtractionToolType'
                  example: follower_explorer
                targetTweetId:
                  type: string
                  example: '1234567890'
                targetUsername:
                  type: string
                  example: elonmusk
                targetCommunityId:
                  type: string
                  description: Required for community_post_extractor & community_search.
                  example: '1500000000000000000'
                targetListId:
                  type: string
                  description: Required for list_follower_explorer, list_member_extractor & list_post_extractor.
                  example: '1234567890'
                targetSpaceId:
                  type: string
                  description: Required for space_explorer.
                  example: 1vOGwMdBqpwGB
                resultsLimit:
                  type: integer
                  description: Maximum number of results to extract. When set, the extraction stops after reaching this limit.
                  example: 1000
                searchQuery:
                  type: string
                  description: Required for tweet_search_extractor & community_search.
                  example: AI trends 2025
                fromUser:
                  type: string
                  description: Filter by author username (tweet_search_extractor)
                  example: nasa
                toUser:
                  type: string
                  description: Filter replies sent to a username (tweet_search_extractor)
                  example: openai
                mentioning:
                  type: string
                  description: Filter tweets mentioning a username (tweet_search_extractor)
                  example: example_user
                language:
                  type: string
                  description: Language code filter (tweet_search_extractor)
                  example: en
                sinceDate:
                  type: string
                  format: date
                  description: Start date YYYY-MM-DD (tweet_search_extractor)
                  example: '2025-01-01'
                untilDate:
                  type: string
                  format: date
                  description: End date YYYY-MM-DD (tweet_search_extractor)
                  example: '2025-12-31'
                mediaType:
                  type: string
                  enum:
                  - images
                  - videos
                  - gifs
                  - media
                  - links
                  - none
                  description: Media type filter (tweet_search_extractor)
                  example: images
                minFaves:
                  type: integer
                  minimum: 0
                  description: Minimum likes threshold (tweet_search_extractor)
                  example: 10
                minRetweets:
                  type: integer
                  minimum: 0
                  description: Minimum retweets threshold (tweet_search_extractor)
                  example: 5
                minReplies:
                  type: integer
                  minimum: 0
                  description: Minimum replies threshold (tweet_search_extractor)
                  example: 3
                minQuotes:
                  type: integer
                  minimum: 0
                  description: Minimum quote count threshold (tweet_search_extractor)
                  example: 2
                verifiedOnly:
                  type: boolean
                  description: Only verified authors (tweet_search_extractor)
                  example: false
                replies:
                  type: string
                  enum:
                  - include
                  - exclude
                  - only
                  description: Reply mode (tweet_search_extractor)
                  example: include
                retweets:
                  type: string
                  enum:
                  - include
                  - exclude
                  - only
                  description: Retweet mode (tweet_search_extractor)
                  example: exclude
                quotes:
                  type: string
                  enum:
                  - include
                  - exclude
                  - only
                  description: Quote mode (tweet_search_extractor)
                  example: include
                exactPhrase:
                  type: string
                  description: Exact phrase to match (tweet_search_extractor)
                  example: artificial intelligence
                excludeWords:
                  type: string
                  description: Words or quoted phrases to exclude. Separate with spaces, commas, or lines. (tweet_search_extractor)
                  example: spam
                anyWords:
                  type: string
                  description: Words or quoted phrases where any one can match. Separate with spaces, commas, or lines. (tweet_search_extractor)
                  example: ChatGPT AI model
                hashtags:
                  type: string
                  description: Hashtags separated by spaces, commas, or lines. (tweet_search_extractor)
                  example: '#AI startups'
                cashtags:
                  type: string
                  description: Cashtags separated by spaces, commas, or lines. (tweet_search_extractor)
                  example: $TSLA $NVDA
                url:
                  type: string
                  description: URL substring or domain filter (tweet_search_extractor)
                  example: example.com
                conversationId:
                  type: string
                  description: Conversation ID filter (tweet_search_extractor)
                  example: '1234567890'
                inReplyToTweetId:
                  type: string
                  description: Only replies to this tweet ID (tweet_search_extractor)
                  example: '1234567890'
                quotesOfTweetId:
                  type: string
                  description: Only quotes of this tweet ID (tweet_search_extractor)
                  example: '1234567890'
                retweetsOfTweetId:
                  type: string
                  description: Only retweets of this tweet ID (tweet_search_extractor)
                  example: '1234567890'
                listId:
                  type: string
                  description: Search within a list ID (tweet_search_extractor)
                  example: '1234567890'
                place:
                  type: string
                  description: Search within a place ID (tweet_search_extractor)
                  example: 96683cc9126741d1
                placeCountry:
                  type: string
                  description: Search within a country code (tweet_search_extractor)
                  example: US
                pointRadius:
                  type: string
                  description: Geo point radius, e.g. -73.99 40.73 25mi (tweet_search_extractor)
                  example: -73.99 40.73 25mi
                boundingBox:
                  type: string
                  description: Geo bounding box, e.g. -74.1 40.6 -73.9 40.8 (tweet_search_extractor)
                  example: -74.1 40.6 -73.9 40.8
                advancedQuery:
                  type: string
                  description: Raw advanced search query appended as-is (tweet_search_extractor)
                  example: min_faves:100
            example:
              toolType: follower_explorer
              targetUsername: elonmusk
      responses:
        '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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
              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: Community ID used to price community_post_extractor or community_search.
                  example: '1500000000000000000'
                targetListId:
                  type: string
                  description: List ID used to price list_follower_explorer, list_member_extractor, or list_post_extractor.
                  example: '1234567890'
                targetSpaceId:
                  type: string
                  description: Space ID used to price space_explorer.
                  example: 1vOGwMdBqpwGB
                resultsLimit:
                  type: integer
                  description: Maximum number of results to estimate. When set, the estimate caps projected results to this
                    value.
                  example: 1000
                searchQuery:
                  type: string
                  description: Query used to price tweet_search_extractor or community_search.
                  example: AI trends 2025
                fromUser:
                  type: string
                  description: Estimate only tweets from this author username (tweet_search_extractor)
                  example: nasa
                toUser:
                  type: string
                  description: Estimate replies sent to this username (tweet_search_extractor)
                  example: openai
                mentioning:
                  type: string
                  description: Estimate tweets mentioning this username (tweet_search_extractor)
                  example: example_user
                language:
                  type: string
                  description: Language code used for estimate filtering (tweet_search_extractor)
                  example: en
                sinceDate:
                  type: string
                  format: date
                  description: Estimate start date in YYYY-MM-DD format (tweet_search_extractor)
                  example: '2025-01-01'
                untilDate:
                  type: string
                  format: date
                  description: Estimate end date in YYYY-MM-DD format (tweet_search_extractor)
                  example: '2025-12-31'
                mediaType:
                  type: string
                  enum:
                  - images
                  - videos
                  - gifs
                  - media
                  - links
                  - none
                  description: Media type used for estimate filtering (tweet_search_extractor)
                  example: images
                minFaves:
                  type: integer
                  minimum: 0
                  description: Minimum likes threshold for estimated results (tweet_search_extractor)
                  example: 10
                minRetweets:
                  type: integer
                  minimum: 0
                  description: Minimum retweets threshold for estimated results (tweet_search_extractor)
                  example: 5
                minReplies:
                  type: integer
                  minimum: 0
                  description: Minimum replies threshold for estimated results (tweet_search_extractor)
                  example: 3
                minQuotes:
                  type: integer
                  minimum: 0
                  description: Minimum quote count threshold for estimated results (tweet_search_extractor)
                  example: 2
                verifiedOnly:
                  type: boolean
                  description: Estimate only verified authors (tweet_search_extractor)
                  example: false
                replies:
                  type: string
                  enum:
                  - include
                  - exclude
                  - only
                  description: Reply mode used for estimation (tweet_search_extractor)
                  example: include
                retweets:
                  type: string
                  enum:
                  - include
                  - exclude
                  - only
                  description: Retweet mode used for estimation (tweet_search_extractor)
                  example: exclude
                quotes:
                  type: string
                  enum:
                  - include
                  - exclude
                  - only
                  description: Quote mode used for estimation (tweet_search_extractor)
                  example: include
                exactPhrase:
                  type: string
                  description: Exact phrase filter for search estimation
                  example: artificial intelligence
                excludeWords:
                  type: string
                  description: Words or quoted phrases excluded from estimated results. Separate with spaces, commas, or lines.
                  example: spam
                anyWords:
                  type: string
                  description: Alternative words or quoted phrases for estimated results. Separate with spaces, commas, or
                    lines.
                  example: ChatGPT AI model
                hashtags:
                  type: string
                  description: Hashtags applied to the estimate, separated by spaces, commas, or lines.
                  example: '#AI startups'
                cashtags:
                  type: string
                  description: Cashtags applied to the estimate, separated by spaces, commas, or lines.
                  example: $TSLA $NVDA
                url:
                  type: string
                  description: URL substring or domain filter used for estimation (tweet_search_extractor)
                  example: example.com
                conversationId:
                  type: string
                  description: Conversation ID filter used for estimation (tweet_search_extractor)
                  example: '1234567890'
                inReplyToTweetId:
                  type: string
                  description: Estimate only replies to this tweet ID (tweet_search_extractor)
                  example: '1234567890'
                quotesOfTweetId:
                  type: string
                  description: Estimate only quotes of this tweet ID (tweet_search_extractor)
                  example: '1234567890'
                retweetsOfTweetId:
                  type: string
                  description: Estimate only retweets of this tweet ID (tweet_search_extractor)
                  example: '1234567890'
                listId:
                  type: string
                  description: Estimate search results within this list ID (tweet_search_extractor)
                  example: '1234567890'
                place:
                  type: string
                  description: Estimate search results within this place ID (tweet_search_extractor)
                  example: 96683cc9126741d1
                placeCountry:
                  type: string
                  description: Estimate search results within this country code (tweet_search_extractor)
                  example: US
                pointRadius:
                  type: string
                  description: Geo point radius used for estimation, e.g. -73.99 40.73 25mi (tweet_search_extractor)
                  example: -73.99 40.73 25mi
                boundingBox:
                  type: string
                  description: Geo bounding box used for estimation, e.g. -74.1 40.6 -73.9 40.8 (tweet_search_extractor)
                  example: -74.1 40.6 -73.9 40.8
                advancedQuery:
                  type: string
                  description: Raw advanced query string appended to the estimate (tweet_search_extractor)
                  example: min_faves:100
            example:
              toolType: follower_explorer
              targetUsername: elonmusk
      responses:
        '200':
          description: Extraction estimate
          content:
            application/json:
              schema:
                type: object
                required:
                - estimatedResults
                - creditsRequired
                - creditsAvailable
                - allowed
                - source
                properties:
                  estimatedResults:
                    type: integer
                    example: 500
                  creditsRequired:
                    type: string
                    example: '500'
                  creditsAvailable:
                    type: string
                    example: '50000'
                  allowed:
                    type: boolean
                    example: true
                  source:
                    type: string
                    enum:
                    - followers
                    - following
                    - paginationCap
                    - posts
                    - quoteCount
                    - replyCount
                    - resultsLimit
                    - retweetCount
                    - unknown
                    example: replyCount
                  resolvedXUserId:
                    type: string
                    example: '123456'
              example:
                estimatedResults: 500
                creditsRequired: '500'
                creditsAvailable: '50000'
                allowed: true
                source: replyCount
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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'
      responses:
        '200':
          description: Extraction job with results
          content:
            application/json:
              schema:
                type: object
                required:
                - job
                - results
                - hasMore
                properties:
                  job:
                    type: object
                    additionalProperties: true
                    x-stainless-any: true
                    description: Extraction job metadata - shape varies by tool type (JSON)
                    x-stainless-terraform-type: string
                    example:
                      id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      toolType: follower_explorer
                      status: completed
                  results:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                    example: []
                  hasMore:
                    type: boolean
                    example: false
                  nextCursor:
                    type: string
                    example: abc123
              example:
                job:
                  id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  toolType: follower_explorer
                  status: completed
                results: []
                hasMore: false
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
  /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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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
        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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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: List of tweets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
              example:
                tweets:
                - id: '1234567890'
                  text: Just launched our new feature!
                  createdAt: '2025-01-15T12:00:00Z'
                  likeCount: 42
                  retweetCount: 5
                  replyCount: 3
                  quoteCount: 1
                  viewCount: 1500
                  bookmarkCount: 2
                  author:
                    id: '9876543210'
                    username: elonmusk
                    name: Elon Musk
                    verified: true
                has_next_page: true
                next_cursor: DAACCgACGRElMJcAAA
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Get multiple tweets by IDs.
    post:
      operationId: createTweet
      summary: Create tweet
      tags:
      - X Write
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - $ref: '#/components/parameters/WriteIdempotencyKey'
      requestBody:
        required: true
        description: Account and tweet content. Requires text, media, or both.
        content:
          application/json:
            schema:
              type: object
              required:
              - account
              properties:
                account:
                  type: string
                  description: X account (@username or account ID)
                  example: '@elonmusk'
                text:
                  type: string
                  description: Tweet text (optional when media is provided)
                  example: Just launched our new feature!
                reply_to_tweet_id:
                  type: string
                  example: '1234567890'
                community_id:
                  type: string
                  example: '1500000000000000000'
                is_note_tweet:
                  type: boolean
                  example: false
                media:
                  type: array
                  items:
                    type: string
                  maxItems: 4
                  description: Array of public media URLs to attach. Supports up to 4 images or exactly 1 MP4 video up to
                    100 MB. Each URL must be publicly reachable. Attached media adds 2 credits per started MB across all files.
                  example:
                  - https://example.com/video.mp4
            example:
              account: '@elonmusk'
              text: Just launched our new feature!
      responses:
        '200':
          $ref: '#/components/responses/WriteActionCompleted'
        '202':
          $ref: '#/components/responses/WriteActionAccepted'
        '400':
          $ref: '#/components/responses/WriteInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '409':
          $ref: '#/components/responses/WriteIdempotencyConflict'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '500':
          $ref: '#/components/responses/WriteError'
        '503':
          $ref: '#/components/responses/WriteTrackingUnavailable'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Create tweet.
  /api/v1/x/write-actions/{id}:
    get:
      operationId: getWriteActionStatus
      summary: Get write action status
      tags:
      - X Write
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Write action ID returned by a pending write response.
      responses:
        '200':
          $ref: '#/components/responses/WriteActionCompleted'
        '202':
          $ref: '#/components/responses/WriteActionAccepted'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Get write action status.
  /api/v1/x/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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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
      tags:
      - Tweets
      security:
      - apiKey: []
      - oauthBearer: []
      - {}
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
        description: Search query (keywords,
      - name: queryType
        in: query
        required: false
        schema:
          type: string
          enum:
          - Latest
          - Top
          default: Latest
        description: Sort order - Latest (chronological) or Top (engagement-ranked)
      - name: cursor
        in: query
        schema:
          type: string
        description: Pagination cursor from previous response
      - name: sinceTime
        in: query
        schema:
          type: string
        description: ISO 8601 timestamp - only return tweets after this time
      - name: untilTime
        in: query
        schema:
          type: string
        description: ISO 8601 timestamp - only return tweets before this time
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          maximum: 200
        description: 'Max tweets to return (server paginates internally). Omit for single page (~20). This is an upper bound
          for paid authenticated calls: remaining credits can reduce the returned page size, and zero affordable results returns
          402 insufficient_credits.

          '
      - $ref: '#/components/parameters/TweetFilterFromUser'
      - $ref: '#/components/parameters/TweetFilterToUser'
      - $ref: '#/components/parameters/TweetFilterMentioning'
      - $ref: '#/components/parameters/TweetFilterLanguage'
      - $ref: '#/components/parameters/TweetFilterSinceDate'
      - $ref: '#/components/parameters/TweetFilterUntilDate'
      - $ref: '#/components/parameters/TweetFilterMediaType'
      - $ref: '#/components/parameters/TweetFilterMinFaves'
      - $ref: '#/components/parameters/TweetFilterMinRetweets'
      - $ref: '#/components/parameters/TweetFilterMinReplies'
      - $ref: '#/components/parameters/TweetFilterMinQuotes'
      - $ref: '#/components/parameters/TweetFilterVerifiedOnly'
      - $ref: '#/components/parameters/TweetFilterReplies'
      - $ref: '#/components/parameters/TweetFilterRetweets'
      - $ref: '#/components/parameters/TweetFilterQuotes'
      - $ref: '#/components/parameters/TweetFilterExactPhrase'
      - $ref: '#/components/parameters/TweetFilterExcludeWords'
      - $ref: '#/components/parameters/TweetFilterAnyWords'
      - $ref: '#/components/parameters/TweetFilterHashtags'
      - $ref: '#/components/parameters/TweetFilterCashtags'
      - $ref: '#/components/parameters/TweetFilterUrl'
      - $ref: '#/components/parameters/TweetFilterConversationId'
      - $ref: '#/components/parameters/TweetFilterInReplyToTweetId'
      - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId'
      - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId'
      - $ref: '#/components/parameters/TweetSearchListId'
      - $ref: '#/components/parameters/TweetSearchPlace'
      - $ref: '#/components/parameters/TweetSearchPlaceCountry'
      - $ref: '#/components/parameters/TweetSearchPointRadius'
      - $ref: '#/components/parameters/TweetSearchBoundingBox'
      - $ref: '#/components/parameters/TweetSearchAdvancedQuery'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
              example:
                tweets:
                - id: '1234567890'
                  text: Just launched our new feature!
                  createdAt: '2025-01-15T12:00:00Z'
                  likeCount: 42
                  retweetCount: 5
                  replyCount: 3
                  quoteCount: 1
                  viewCount: 1500
                  bookmarkCount: 2
                  author:
                    id: '9876543210'
                    username: elonmusk
                    name: Elon Musk
                    verified: true
                has_next_page: true
                next_cursor: DAACCgACGRElMJcAAA
        '400':
          description: Missing query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: missing_query
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Search tweets by query, Tweet ID, X status URL, or account date window.
  /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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
  /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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Get tweet with full text, author, metrics and media.
    delete:
      operationId: deleteTweet
      summary: Delete tweet
      tags:
      - X Write
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - $ref: '#/components/parameters/WriteIdempotencyKey'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Tweet ID to delete
      requestBody:
        required: true
        description: Account that owns the tweet.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XAccountBody'
            example:
              account: '@elonmusk'
      responses:
        '200':
          $ref: '#/components/responses/WriteActionCompleted'
        '202':
          $ref: '#/components/responses/WriteActionAccepted'
        '400':
          $ref: '#/components/responses/WriteInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '409':
          $ref: '#/components/responses/WriteIdempotencyConflict'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '500':
          $ref: '#/components/responses/WriteError'
        '503':
          $ref: '#/components/responses/WriteTrackingUnavailable'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Delete tweet.
  /api/v1/x/tweets/{id}/like:
    post:
      operationId: likeTweet
      summary: Like tweet
      tags:
      - X Write
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - $ref: '#/components/parameters/WriteIdempotencyKey'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Tweet ID to like
      requestBody:
        required: true
        description: Account to perform the like.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XAccountBody'
            example:
              account: '@elonmusk'
      responses:
        '200':
          $ref: '#/components/responses/WriteActionCompleted'
        '202':
          $ref: '#/components/responses/WriteActionAccepted'
        '400':
          $ref: '#/components/responses/WriteInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '409':
          $ref: '#/components/responses/WriteIdempotencyConflict'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '500':
          $ref: '#/components/responses/WriteError'
        '503':
          $ref: '#/components/responses/WriteTrackingUnavailable'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Like tweet.
    delete:
      operationId: unlikeTweet
      summary: Unlike tweet
      tags:
      - X Write
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - $ref: '#/components/parameters/WriteIdempotencyKey'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Tweet ID to unlike
      requestBody:
        required: true
        description: Account that liked the tweet.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XAccountBody'
      responses:
        '200':
          $ref: '#/components/responses/WriteActionCompleted'
        '202':
          $ref: '#/components/responses/WriteActionAccepted'
        '400':
          $ref: '#/components/responses/WriteInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '409':
          $ref: '#/components/responses/WriteIdempotencyConflict'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '500':
          $ref: '#/components/responses/WriteError'
        '503':
          $ref: '#/components/responses/WriteTrackingUnavailable'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Unlike tweet.
  /api/v1/x/tweets/{id}/retweet:
    post:
      operationId: retweet
      summary: Retweet
      tags:
      - X Write
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - $ref: '#/components/parameters/WriteIdempotencyKey'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Tweet ID to retweet
      requestBody:
        required: true
        description: Account to perform the retweet.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XAccountBody'
      responses:
        '200':
          $ref: '#/components/responses/WriteActionCompleted'
        '202':
          $ref: '#/components/responses/WriteActionAccepted'
        '400':
          $ref: '#/components/responses/WriteInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '409':
          $ref: '#/components/responses/WriteIdempotencyConflict'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '500':
          $ref: '#/components/responses/WriteError'
        '503':
          $ref: '#/components/responses/WriteTrackingUnavailable'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Retweet.
    delete:
      operationId: unretweet
      summary: Unretweet
      tags:
      - X Write
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - $ref: '#/components/parameters/WriteIdempotencyKey'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Tweet ID to unretweet
      requestBody:
        required: true
        description: Account that retweeted the tweet.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XAccountBody'
      responses:
        '200':
          $ref: '#/components/responses/WriteActionCompleted'
        '202':
          $ref: '#/components/responses/WriteActionAccepted'
        '400':
          $ref: '#/components/responses/WriteInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '409':
          $ref: '#/components/responses/WriteIdempotencyConflict'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '500':
          $ref: '#/components/responses/WriteError'
        '503':
          $ref: '#/components/responses/WriteTrackingUnavailable'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Unretweet.
  /api/v1/x/users/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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: user_not_found
                message: X user not found. Check the username.
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Get user profile with follower counts and verification.
  /api/v1/x/users/{id}/follow:
    post:
      operationId: followUser
      summary: Follow user
      tags:
      - X Write
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - $ref: '#/components/parameters/WriteIdempotencyKey'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: User ID to follow
      requestBody:
        required: true
        description: Account to perform the follow.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XAccountBody'
      responses:
        '200':
          $ref: '#/components/responses/WriteActionCompleted'
        '202':
          $ref: '#/components/responses/WriteActionAccepted'
        '400':
          $ref: '#/components/responses/WriteInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '409':
          $ref: '#/components/responses/WriteIdempotencyConflict'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '500':
          $ref: '#/components/responses/WriteError'
        '503':
          $ref: '#/components/responses/WriteTrackingUnavailable'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Follow user.
    delete:
      operationId: unfollowUser
      summary: Unfollow user
      tags:
      - X Write
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - $ref: '#/components/parameters/WriteIdempotencyKey'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: User ID to unfollow
      requestBody:
        required: true
        description: Account that follows the target user.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XAccountBody'
      responses:
        '200':
          $ref: '#/components/responses/WriteActionCompleted'
        '202':
          $ref: '#/components/responses/WriteActionAccepted'
        '400':
          $ref: '#/components/responses/WriteInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '409':
          $ref: '#/components/responses/WriteIdempotencyConflict'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '500':
          $ref: '#/components/responses/WriteError'
        '503':
          $ref: '#/components/responses/WriteTrackingUnavailable'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Unfollow user.
  /api/v1/x/users/{id}/remove-follower:
    post:
      operationId: removeFollower
      summary: Remove follower
      tags:
      - X Write
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - $ref: '#/components/parameters/WriteIdempotencyKey'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: User ID to remove from your followers
      requestBody:
        required: true
        description: Account whose follower list should be updated.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XAccountBody'
      responses:
        '200':
          $ref: '#/components/responses/WriteActionCompleted'
        '202':
          $ref: '#/components/responses/WriteActionAccepted'
        '400':
          $ref: '#/components/responses/WriteInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '409':
          $ref: '#/components/responses/WriteIdempotencyConflict'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '500':
          $ref: '#/components/responses/WriteError'
        '503':
          $ref: '#/components/responses/WriteTrackingUnavailable'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Remove follower.
  /api/v1/x/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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Check if one user follows another.
  /api/v1/x/dm/{userId}:
    post:
      operationId: sendDm
      summary: Send direct message
      tags:
      - X Write
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - $ref: '#/components/parameters/WriteIdempotencyKey'
      - name: userId
        in: path
        required: true
        schema:
          type: string
        description: Recipient user ID
      requestBody:
        required: true
        description: Account, message text, and an optional media attachment.
        content:
          application/json:
            schema:
              type: object
              required:
              - account
              - text
              properties:
                account:
                  type: string
                  description: X account (@username or ID) sending the DM
                  example: '@elonmusk'
                text:
                  type: string
                  example: Example text
                media_ids:
                  type: array
                  minItems: 1
                  maxItems: 1
                  items:
                    type: string
                  description: Optional array containing exactly 1 uploaded media ID.
                  example:
                  - '1234567890123456789'
            example:
              account: '@elonmusk'
              text: Example text content
              media_ids:
              - '1234567890123456789'
      responses:
        '200':
          $ref: '#/components/responses/WriteActionCompleted'
        '202':
          $ref: '#/components/responses/WriteActionAccepted'
        '400':
          $ref: '#/components/responses/WriteInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '409':
          $ref: '#/components/responses/WriteIdempotencyConflict'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '500':
          $ref: '#/components/responses/WriteError'
        '503':
          $ref: '#/components/responses/WriteTrackingUnavailable'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Send direct message.
  /api/v1/x/media:
    post:
      operationId: uploadMedia
      summary: Upload media
      tags:
      - X Write
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - $ref: '#/components/parameters/WriteIdempotencyKey'
      requestBody:
        required: true
        description: Upload media with multipart form data, or provide a JSON URL for server-side download.
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - account
              - file
              properties:
                account:
                  type: string
                  description: X account (@username or ID) uploading media
                  example: '@elonmusk'
                file:
                  type: string
                  format: binary
                  description: Media file to upload
                  example: binary-content
                is_long_video:
                  type: boolean
                  description: Set true only for video/mp4 multipart uploads longer than 140 seconds.
                  example: false
            example:
              account: '@elonmusk'
              file: file_value
              is_long_video: true
          application/json:
            schema:
              type: object
              required:
              - account
              - url
              properties:
                account:
                  type: string
                  description: X account (@username or ID) uploading media from URL
                  example: '@elonmusk'
                url:
                  type: string
                  format: uri
                  description: HTTPS URL to download and upload as media
                  example: https://example.com/image.png
            example:
              account: '@elonmusk'
              url: https://example.com/image.png
      responses:
        '200':
          $ref: '#/components/responses/WriteActionCompleted'
        '202':
          $ref: '#/components/responses/WriteActionAccepted'
        '400':
          $ref: '#/components/responses/WriteInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '404':
          $ref: '#/components/responses/XAccountNotFound'
        '409':
          $ref: '#/components/responses/WriteIdempotencyConflict'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '500':
          $ref: '#/components/responses/WriteError'
        '503':
          $ref: '#/components/responses/WriteTrackingUnavailable'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Upload media.
  /api/v1/x/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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Download images and videos from tweets.
  /api/v1/x/profile:
    patch:
      operationId: updateProfile
      summary: Update X profile
      tags:
      - X Write
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - $ref: '#/components/parameters/WriteIdempotencyKey'
      requestBody:
        required: true
        description: Account and profile fields to update (name, bio, location, website).
        content:
          application/json:
            schema:
              type: object
              required:
              - account
              properties:
                account:
                  type: string
                  description: X account (@username or ID) to update profile
                  example: '@elonmusk'
                name:
                  type: string
                  description: Display name
                  example: Example Name
                description:
                  type: string
                  description: Bio description
                  example: CEO of Tesla, SpaceX, and X
                location:
                  type: string
                  example: Austin, TX
                url:
                  type: string
                  description: Website URL
                  example: https://x.com
            example:
              account: '@elonmusk'
              name: Example Name
              description: description_value
              location: location_value
              url: https://xquik.com/example
      responses:
        '200':
          $ref: '#/components/responses/WriteActionCompleted'
        '202':
          $ref: '#/components/responses/WriteActionAccepted'
        '400':
          $ref: '#/components/responses/WriteInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '404':
          $ref: '#/components/responses/XAccountNotFound'
        '409':
          $ref: '#/components/responses/WriteIdempotencyConflict'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '500':
          $ref: '#/components/responses/WriteError'
        '503':
          $ref: '#/components/responses/WriteTrackingUnavailable'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Update X profile.
  /api/v1/x/profile/avatar:
    patch:
      operationId: updateAvatar
      summary: Update profile avatar
      tags:
      - X Write
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - $ref: '#/components/parameters/WriteIdempotencyKey'
      requestBody:
        required: true
        description: Account and avatar image file or HTTPS image URL (max 700 KB).
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - account
              - file
              properties:
                account:
                  type: string
                  description: X account (@username or ID) for avatar update
                  example: '@elonmusk'
                file:
                  type: string
                  format: binary
                  description: Avatar image (max 700 KB)
                  example: binary-content
            example:
              account: '@elonmusk'
              file: file_value
          application/json:
            schema:
              type: object
              required:
              - account
              - url
              properties:
                account:
                  type: string
                  description: X account (@username or ID) receiving avatar from URL
                  example: '@elonmusk'
                url:
                  type: string
                  format: uri
                  description: HTTPS URL to the avatar image to download
                  example: https://example.com/avatar.png
            example:
              account: '@elonmusk'
              url: https://example.com/avatar.png
      responses:
        '200':
          $ref: '#/components/responses/WriteActionCompleted'
        '202':
          $ref: '#/components/responses/WriteActionAccepted'
        '400':
          $ref: '#/components/responses/WriteInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '404':
          $ref: '#/components/responses/XAccountNotFound'
        '409':
          $ref: '#/components/responses/WriteIdempotencyConflict'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '500':
          $ref: '#/components/responses/WriteError'
        '503':
          $ref: '#/components/responses/WriteTrackingUnavailable'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Update profile avatar.
  /api/v1/x/profile/banner:
    patch:
      operationId: updateBanner
      summary: Update profile banner
      tags:
      - X Write
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - $ref: '#/components/parameters/WriteIdempotencyKey'
      requestBody:
        required: true
        description: Account and banner image file or HTTPS image URL (max 2 MB).
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - account
              - file
              properties:
                account:
                  type: string
                  description: X account (@username or ID) for banner update
                  example: '@elonmusk'
                file:
                  type: string
                  format: binary
                  description: Banner image (max 2MB)
                  example: binary-content
            example:
              account: '@elonmusk'
              file: file_value
          application/json:
            schema:
              type: object
              required:
              - account
              - url
              properties:
                account:
                  type: string
                  description: X account (@username or ID) receiving banner from URL
                  example: '@elonmusk'
                url:
                  type: string
                  format: uri
                  description: HTTPS URL to the banner image to download
                  example: https://example.com/banner.png
            example:
              account: '@elonmusk'
              url: https://example.com/banner.png
      responses:
        '200':
          $ref: '#/components/responses/WriteActionCompleted'
        '202':
          $ref: '#/components/responses/WriteActionAccepted'
        '400':
          $ref: '#/components/responses/WriteInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '404':
          $ref: '#/components/responses/XAccountNotFound'
        '409':
          $ref: '#/components/responses/WriteIdempotencyConflict'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '500':
          $ref: '#/components/responses/WriteError'
        '503':
          $ref: '#/components/responses/WriteTrackingUnavailable'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Update profile banner.
  /api/v1/x/communities:
    post:
      operationId: createCommunity
      summary: Create community
      tags:
      - X Write
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - $ref: '#/components/parameters/WriteIdempotencyKey'
      requestBody:
        required: true
        description: Account, community name, and optional description.
        content:
          application/json:
            schema:
              type: object
              required:
              - account
              - name
              properties:
                account:
                  type: string
                  description: X account (@username or ID) creating the community
                  example: '@elonmusk'
                name:
                  type: string
                  description: Community name
                  example: Example Name
                description:
                  type: string
                  description: Community description
                  example: A community for Tesla enthusiasts
            example:
              account: '@elonmusk'
              name: Example Name
              description: A community for Tesla enthusiasts
      responses:
        '200':
          $ref: '#/components/responses/WriteActionCompleted'
        '202':
          $ref: '#/components/responses/WriteActionAccepted'
        '400':
          $ref: '#/components/responses/WriteInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '404':
          $ref: '#/components/responses/XAccountNotFound'
        '409':
          $ref: '#/components/responses/WriteIdempotencyConflict'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '500':
          $ref: '#/components/responses/WriteError'
        '503':
          $ref: '#/components/responses/WriteTrackingUnavailable'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Create community.
  /api/v1/x/communities/{id}:
    delete:
      operationId: deleteCommunity
      summary: Delete community
      tags:
      - X Write
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - $ref: '#/components/parameters/WriteIdempotencyKey'
      - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        description: Account and community name for deletion confirmation.
        content:
          application/json:
            schema:
              type: object
              required:
              - account
              - community_name
              properties:
                account:
                  type: string
                  description: X account (@username or ID) deleting the community
                  example: '@elonmusk'
                community_name:
                  type: string
                  description: Community name for confirmation
                  example: Tesla Fans
            example:
              account: '@elonmusk'
              community_name: Tesla Fans
      responses:
        '200':
          $ref: '#/components/responses/WriteActionCompleted'
        '202':
          $ref: '#/components/responses/WriteActionAccepted'
        '400':
          $ref: '#/components/responses/WriteInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '404':
          $ref: '#/components/responses/XAccountNotFound'
        '409':
          $ref: '#/components/responses/WriteIdempotencyConflict'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '500':
          $ref: '#/components/responses/WriteError'
        '503':
          $ref: '#/components/responses/WriteTrackingUnavailable'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Delete community.
  /api/v1/x/communities/{id}/join:
    post:
      operationId: joinCommunity
      summary: Join community
      tags:
      - X Write
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - $ref: '#/components/parameters/WriteIdempotencyKey'
      - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        description: Account to join the community.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XAccountBody'
      responses:
        '200':
          $ref: '#/components/responses/WriteActionCompleted'
        '202':
          $ref: '#/components/responses/WriteActionAccepted'
        '400':
          $ref: '#/components/responses/WriteInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '404':
          $ref: '#/components/responses/XAccountNotFound'
        '409':
          $ref: '#/components/responses/WriteIdempotencyConflict'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '500':
          $ref: '#/components/responses/WriteError'
        '503':
          $ref: '#/components/responses/WriteTrackingUnavailable'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Join community.
    delete:
      operationId: leaveCommunity
      summary: Leave community
      tags:
      - X Write
      security:
      - apiKey: []
      - oauthBearer: []
      parameters:
      - $ref: '#/components/parameters/WriteIdempotencyKey'
      - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        description: Account to leave the community.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XAccountBody'
      responses:
        '200':
          $ref: '#/components/responses/WriteActionCompleted'
        '202':
          $ref: '#/components/responses/WriteActionAccepted'
        '400':
          $ref: '#/components/responses/WriteInvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AccountAuthError'
        '404':
          $ref: '#/components/responses/XAccountNotFound'
        '409':
          $ref: '#/components/responses/WriteIdempotencyConflict'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/WriteRateLimited'
        '500':
          $ref: '#/components/responses/WriteError'
        '503':
          $ref: '#/components/responses/WriteTrackingUnavailable'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Leave community.
  /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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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_0123456789abcdef0123456789abcdef
            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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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.

        '
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
  /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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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.

        '
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
  /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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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 Stripe-hosted checkout after the user explicitly confirms a $10-$250 USD amount. This
        request creates no charge by itself. The user opens checkout_url on Stripe. This endpoint returns the paid-read API
        key without requiring an Xquik account, email, dashboard, or Xquik web page. An idempotent replay returns the same
        key.

        '
      tags:
      - Guest Wallets
      security: []
      parameters:
      - $ref: '#/components/parameters/GuestIdempotencyKey'
      requestBody:
        required: true
        description: Confirmed USD amount in cents.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GuestWalletPurchaseRequest'
            example:
              amount_minor: 1000
              currency: usd
      responses:
        '201':
          description: 'Stripe-hosted checkout, guest API key, and API status URL.

            '
          headers:
            Cache-Control:
              description: Prevents storage of the secret-bearing response.
              schema:
                type: string
                const: no-store, private
            Idempotent-Replayed:
              description: 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://buy.stripe.com/example
                credential_notice: Store api_key and the Idempotency-Key securely before sharing checkout_url. No email recovery
                  is available.
                credits: '66666'
                expires_at: '2026-07-13T13:00:00.000Z'
                instructions: Give checkout_url to the user. They must complete payment on Stripe. Never submit payment for
                  them. After payment, poll status_url every poll_after_seconds until latest_purchase.status is no longer
                  pending.
                poll_after_seconds: 2
                purchase_id: gp_example
                requires_user_interaction: true
                status: pending
                status_url: https://xquik.com/api/v1/guest-wallets/status
                wallet_id: gw_example
        '400':
          $ref: '#/components/responses/InvalidInput'
        '409':
          description: Idempotency-Key was reused with a different request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
  /api/v1/guest-wallets/topups:
    post:
      operationId: topUpGuestWallet
      summary: Create another guest wallet checkout
      description: 'Create a one-use Stripe-hosted checkout for an existing paid-read guest key after the user explicitly
        confirms a $10-$250 USD amount. The key remains the same. This request creates no charge by itself and never redirects
        through an Xquik web page.

        '
      tags:
      - Guest Wallets
      security:
      - apiKey: []
      parameters:
      - $ref: '#/components/parameters/GuestIdempotencyKey'
      requestBody:
        required: true
        description: Confirmed top-up amount in USD cents.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GuestWalletPurchaseRequest'
            example:
              amount_minor: 1000
              currency: usd
      responses:
        '201':
          description: Stripe-hosted checkout and API status URL.
          headers:
            Cache-Control:
              description: Prevents 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://buy.stripe.com/example
                credits: '66666'
                expires_at: '2026-07-13T13:00:00.000Z'
                instructions: Give checkout_url to the user. They must complete payment on Stripe. Never submit payment for
                  them. After payment, poll status_url every poll_after_seconds until latest_purchase.status is no longer
                  pending.
                poll_after_seconds: 2
                purchase_id: gp_example
                requires_user_interaction: true
                status: pending
                status_url: https://xquik.com/api/v1/guest-wallets/status
                wallet_id: gw_example
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '409':
          description: 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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
  /api/v1/guest-wallets/status:
    get:
      operationId: getGuestWalletStatus
      summary: Get guest wallet and payment status
      description: 'Poll after Stripe payment. Use usable to decide whether paid reads can run. An active wallet can remain
        usable while a top-up is pending. A new wallet becomes usable only after verified webhook fulfillment. Send the guest
        key as Authorization: Bearer.

        '
      tags:
      - Guest Wallets
      security:
      - apiKey: []
      responses:
        '200':
          description: Guest wallet status without exposing the API key.
          headers:
            Cache-Control:
              description: Prevents storage of wallet status.
              schema:
                type: string
                const: no-store, private
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuestWalletStatusResponse'
              example:
                balance: '66666'
                latest_purchase:
                  amount:
                    amount_minor: 1000
                    currency: usd
                  checkout_url: null
                  credits: '66666'
                  expires_at: '2026-07-13T13:00:00.000Z'
                  purchase_id: gp_example
                  status: paid
                poll_after_seconds: null
                scope: paid_reads
                status: active
                top_up:
                  method: POST
                  path: /api/v1/guest-wallets/topups
                usable: true
                wallet_id: gw_example
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/GuestWalletRateLimited'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
  /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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: Get credits balance.
  /api/v1/credits/topup:
    post:
      operationId: topUpCredits
      summary: Create credit top-up checkout
      description: 'Create a Stripe Checkout session only after the user confirms. The request never completes payment or
        adds credits by itself.

        '
      tags:
      - Subscribe
      security:
      - apiKey: []
      - oauthBearer: []
      requestBody:
        required: true
        description: Confirmed dollar amount for the credit top-up checkout.
        content:
          application/json:
            schema:
              type: object
              required:
              - dollars
              properties:
                dollars:
                  type: integer
                  description: Amount to top up in US dollars. Minimum 10.
                  minimum: 10
                  example: 10
                locale:
                  type: string
                  description: Optional checkout locale. Defaults to en.
                  example: en
            example:
              dollars: 10
      responses:
        '200':
          description: Top-up payment links
          content:
            application/json:
              schema:
                type: object
                required:
                - url
                - redirect_url
                properties:
                  redirect_url:
                    type: string
                    format: uri
                    description: Stable first-party Xquik redirect URL for the active Stripe Checkout session.
                    example: https://xquik.com/api/v1/credits/topup/redirect?session_id=cs_test_123
                  url:
                    type: string
                    format: uri
                    description: Same stable first-party Xquik redirect URL as redirect_url. The response never exposes a
                      raw Stripe Checkout URL.
                    example: https://xquik.com/api/v1/credits/topup/redirect?session_id=cs_test_123
              example:
                redirect_url: https://xquik.com/api/v1/credits/topup/redirect?session_id=cs_test_123
                url: https://xquik.com/api/v1/credits/topup/redirect?session_id=cs_test_123
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
  /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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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.

        '
      tags:
      - Tweets
      security:
      - apiKey: []
      - oauthBearer: []
      - {}
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Tweet ID to get favoriters
      - name: cursor
        in: query
        schema:
          type: string
        description: Pagination cursor for favoriters
      - $ref: '#/components/parameters/FollowerPageSize'
      responses:
        '200':
          description: Visible users who liked the tweet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '424':
          $ref: '#/components/responses/FavoritersUnavailable'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
  /api/v1/x/users/{id}/tweets:
    get:
      operationId: getUserTweets
      summary: List recent tweets posted by a user
      tags:
      - Users
      security:
      - apiKey: []
      - oauthBearer: []
      - {}
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: X user ID or username
      - name: cursor
        in: query
        schema:
          type: string
        description: Pagination cursor for user tweets
      - $ref: '#/components/parameters/ResultPageSize'
      - name: includeReplies
        in: query
        schema:
          type: boolean
          default: false
        description: Include reply tweets
      - name: includeParentTweet
        in: query
        schema:
          type: boolean
          default: false
        description: Include parent tweet for replies
      - $ref: '#/components/parameters/TweetFilterFromUser'
      - $ref: '#/components/parameters/TweetFilterToUser'
      - $ref: '#/components/parameters/TweetFilterMentioning'
      - $ref: '#/components/parameters/TweetFilterLanguage'
      - $ref: '#/components/parameters/TweetFilterSinceDate'
      - $ref: '#/components/parameters/TweetFilterUntilDate'
      - $ref: '#/components/parameters/TweetFilterMediaType'
      - $ref: '#/components/parameters/TweetFilterMinFaves'
      - $ref: '#/components/parameters/TweetFilterMinRetweets'
      - $ref: '#/components/parameters/TweetFilterMinReplies'
      - $ref: '#/components/parameters/TweetFilterMinQuotes'
      - $ref: '#/components/parameters/TweetFilterVerifiedOnly'
      - $ref: '#/components/parameters/TweetFilterReplies'
      - $ref: '#/components/parameters/TweetFilterRetweets'
      - $ref: '#/components/parameters/TweetFilterQuotes'
      - $ref: '#/components/parameters/TweetFilterExactPhrase'
      - $ref: '#/components/parameters/TweetFilterExcludeWords'
      - $ref: '#/components/parameters/TweetFilterAnyWords'
      - $ref: '#/components/parameters/TweetFilterHashtags'
      - $ref: '#/components/parameters/TweetFilterCashtags'
      - $ref: '#/components/parameters/TweetFilterUrl'
      - $ref: '#/components/parameters/TweetFilterConversationId'
      - $ref: '#/components/parameters/TweetFilterInReplyToTweetId'
      - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId'
      - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId'
      responses:
        '200':
          description: User tweets list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      description: List recent tweets posted by a user.
  /api/v1/x/users/{id}/replies:
    get:
      operationId: getUserReplies
      summary: List a user's With Replies timeline
      description: Returns the user's timeline with replies included by default.
      tags:
      - Users
      security:
      - apiKey: []
      - oauthBearer: []
      - {}
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Target user ID or username for the replies timeline.
      - name: cursor
        in: query
        schema:
          type: string
        description: Pagination cursor for user replies
      - $ref: '#/components/parameters/ResultPageSize'
      - name: includeParentTweet
        in: query
        schema:
          type: boolean
          default: false
        description: Include 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/TweetFilterVerifiedOnly'
      - $ref: '#/components/parameters/TweetFilterReplies'
      - $ref: '#/components/parameters/TweetFilterRetweets'
      - $ref: '#/components/parameters/TweetFilterQuotes'
      - $ref: '#/components/parameters/TweetFilterExactPhrase'
      - $ref: '#/components/parameters/TweetFilterExcludeWords'
      - $ref: '#/components/parameters/TweetFilterAnyWords'
      - $ref: '#/components/parameters/TweetFilterHashtags'
      - $ref: '#/components/parameters/TweetFilterCashtags'
      - $ref: '#/components/parameters/TweetFilterUrl'
      - $ref: '#/components/parameters/TweetFilterConversationId'
      - $ref: '#/components/parameters/TweetFilterInReplyToTweetId'
      - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId'
      - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId'
      responses:
        '200':
          description: User timeline with replies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
  /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/TweetFilterVerifiedOnly'
      - $ref: '#/components/parameters/TweetFilterReplies'
      - $ref: '#/components/parameters/TweetFilterRetweets'
      - $ref: '#/components/parameters/TweetFilterQuotes'
      - $ref: '#/components/parameters/TweetFilterExactPhrase'
      - $ref: '#/components/parameters/TweetFilterExcludeWords'
      - $ref: '#/components/parameters/TweetFilterAnyWords'
      - $ref: '#/components/parameters/TweetFilterHashtags'
      - $ref: '#/components/parameters/TweetFilterCashtags'
      - $ref: '#/components/parameters/TweetFilterUrl'
      - $ref: '#/components/parameters/TweetFilterConversationId'
      - $ref: '#/components/parameters/TweetFilterInReplyToTweetId'
      - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId'
      - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId'
      responses:
        '200':
          description: List of liked tweets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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/TweetFilterVerifiedOnly'
      - $ref: '#/components/parameters/TweetFilterReplies'
      - $ref: '#/components/parameters/TweetFilterRetweets'
      - $ref: '#/components/parameters/TweetFilterQuotes'
      - $ref: '#/components/parameters/TweetFilterExactPhrase'
      - $ref: '#/components/parameters/TweetFilterExcludeWords'
      - $ref: '#/components/parameters/TweetFilterAnyWords'
      - $ref: '#/components/parameters/TweetFilterHashtags'
      - $ref: '#/components/parameters/TweetFilterCashtags'
      - $ref: '#/components/parameters/TweetFilterUrl'
      - $ref: '#/components/parameters/TweetFilterConversationId'
      - $ref: '#/components/parameters/TweetFilterInReplyToTweetId'
      - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId'
      - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId'
      responses:
        '200':
          description: List of media tweets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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'
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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.

          '
      - name: cursor
        in: query
        schema:
          type: string
        description: Pagination cursor for DM history
      - name: maxId
        in: query
        schema:
          type: string
        description: Legacy pagination cursor (backward compat)
      responses:
        '200':
          description: List of DM messages
          content:
            application/json:
              schema:
                type: object
                required:
                - messages
                - has_next_page
                - next_cursor
                properties:
                  messages:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - senderId
                      - receiverId
                      properties:
                        id:
                          type: string
                          example: '1234567890123456789'
                        text:
                          type: string
                          example: Hey, how are you?
                        senderId:
                          type: string
                          example: '9876543210'
                        receiverId:
                          type: string
                          example: '1234567890'
                        createdAt:
                          type: string
                          example: '2025-01-15T12:00:00Z'
                        mediaUrl:
                          type: string
                          example: https://pbs.twimg.com/dm_media/abc.jpg
                          description: 'URL of attached media (image, GIF, or video). Omitted when the message has no media
                            attachment.

                            '
                    example:
                    - id: '1234567890123456789'
                      text: Hey, how are you?
                      senderId: '9876543210'
                      receiverId: '1234567890'
                  has_next_page:
                    type: boolean
                    example: true
                  next_cursor:
                    type: string
                    example: DAACCgACGRElMJcAAA
              example:
                messages:
                - id: '1234567890123456789'
                  text: Hey, how are you?
                  senderId: '9876543210'
                  receiverId: '1234567890'
                has_next_page: true
                next_cursor: DAACCgACGRElMJcAAA
        '400':
          description: 'Invalid input. Either `invalid_user_id` (path user ID is empty or invalid) or `account_required` (the
            `account` query parameter was missing or empty).

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalidUserId:
                  summary: Invalid user ID
                  value:
                    error: invalid_user_id
                accountRequired:
                  summary: Account query parameter missing
                  value:
                    error: account_required
                    message: Provide ?account=<x_handle> for a connected X account. DM history requires a connected participant
                      account.
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          description: 'DM read forbidden. Either the connected account is not a participant in this conversation (`dm_not_permitted`),
            the account is suspended, locked, or otherwise restricted (`account_restricted`), or the account session needs
            to be re-authenticated (`account_needs_reauth`).

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                dmNotPermitted:
                  summary: Account is not a conversation participant
                  value:
                    error: dm_not_permitted
                    message: X rejected the DM read. The connected account is not a participant in this conversation, or it
                      needs reauthentication. Reconnect the account on the dashboard and try again.
                accountRestricted:
                  summary: Connected account is restricted
                  value:
                    error: account_restricted
                accountNeedsReauth:
                  summary: Connected account needs reauthentication
                  value:
                    error: account_needs_reauth
        '404':
          description: Connected X account not found for the authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: account_not_found
                message: X account not found. Connect it first at /dashboard/account?tab=x-accounts.
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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.

          '
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
  /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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
  /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'
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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)
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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
      - name: cursor
        in: query
        schema:
          type: string
        description: Pagination cursor for quote tweets
      - $ref: '#/components/parameters/ResultPageSize'
      - name: sinceTime
        in: query
        schema:
          type: string
        description: Unix timestamp - return quotes posted after this time
      - name: untilTime
        in: query
        schema:
          type: string
        description: Unix timestamp - return quotes posted before this time
      - name: includeReplies
        in: query
        schema:
          type: boolean
        description: Include reply quotes (default false)
      - $ref: '#/components/parameters/TweetFilterFromUser'
      - $ref: '#/components/parameters/TweetFilterToUser'
      - $ref: '#/components/parameters/TweetFilterMentioning'
      - $ref: '#/components/parameters/TweetFilterLanguage'
      - $ref: '#/components/parameters/TweetFilterSinceDate'
      - $ref: '#/components/parameters/TweetFilterUntilDate'
      - $ref: '#/components/parameters/TweetFilterMediaType'
      - $ref: '#/components/parameters/TweetFilterMinFaves'
      - $ref: '#/components/parameters/TweetFilterMinRetweets'
      - $ref: '#/components/parameters/TweetFilterMinReplies'
      - $ref: '#/components/parameters/TweetFilterMinQuotes'
      - $ref: '#/components/parameters/TweetFilterVerifiedOnly'
      - $ref: '#/components/parameters/TweetFilterReplies'
      - $ref: '#/components/parameters/TweetFilterRetweets'
      - $ref: '#/components/parameters/TweetFilterQuotes'
      - $ref: '#/components/parameters/TweetFilterExactPhrase'
      - $ref: '#/components/parameters/TweetFilterExcludeWords'
      - $ref: '#/components/parameters/TweetFilterAnyWords'
      - $ref: '#/components/parameters/TweetFilterHashtags'
      - $ref: '#/components/parameters/TweetFilterCashtags'
      - $ref: '#/components/parameters/TweetFilterUrl'
      - $ref: '#/components/parameters/TweetFilterConversationId'
      - $ref: '#/components/parameters/TweetFilterInReplyToTweetId'
      - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId'
      - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId'
      responses:
        '200':
          description: List of quote tweets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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. Complete mode merges available timeline views, supported rankings, every forward
        cursor module, labeled hidden-content branches, exact-parent time partitions scaled to the reported reply count, and
        search. It separates nested replies and returns 424 below 80% coverage.

        '
      tags:
      - Tweets
      security:
      - apiKey: []
      - oauthBearer: []
      - {}
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Tweet ID to get replies
      - name: cursor
        in: query
        schema:
          type: string
        description: Pagination cursor for tweet replies
      - name: mode
        in: query
        schema:
          type: string
          enum:
          - standard
          - complete
          default: standard
        description: 'Use standard for pagination and filters. Use complete for maximum coverage. Complete mode accepts only
          limit. Remove other pagination and filter parameters.

          '
      - 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). Without
          complete mode, this is the deprecated pageSize alias and accepts only 1-100.

          '
      - $ref: '#/components/parameters/ResultPageSize'
      - name: sinceTime
        in: query
        schema:
          type: string
        description: Unix timestamp - return replies posted after this time
      - name: untilTime
        in: query
        schema:
          type: string
        description: Unix timestamp - return replies posted before this time
      - $ref: '#/components/parameters/TweetFilterFromUser'
      - $ref: '#/components/parameters/TweetFilterToUser'
      - $ref: '#/components/parameters/TweetFilterMentioning'
      - $ref: '#/components/parameters/TweetFilterLanguage'
      - $ref: '#/components/parameters/TweetFilterSinceDate'
      - $ref: '#/components/parameters/TweetFilterUntilDate'
      - $ref: '#/components/parameters/TweetFilterMediaType'
      - $ref: '#/components/parameters/TweetFilterMinFaves'
      - $ref: '#/components/parameters/TweetFilterMinRetweets'
      - $ref: '#/components/parameters/TweetFilterMinReplies'
      - $ref: '#/components/parameters/TweetFilterMinQuotes'
      - $ref: '#/components/parameters/TweetFilterVerifiedOnly'
      - $ref: '#/components/parameters/TweetFilterReplies'
      - $ref: '#/components/parameters/TweetFilterRetweets'
      - $ref: '#/components/parameters/TweetFilterQuotes'
      - $ref: '#/components/parameters/TweetFilterExactPhrase'
      - $ref: '#/components/parameters/TweetFilterExcludeWords'
      - $ref: '#/components/parameters/TweetFilterAnyWords'
      - $ref: '#/components/parameters/TweetFilterHashtags'
      - $ref: '#/components/parameters/TweetFilterCashtags'
      - $ref: '#/components/parameters/TweetFilterUrl'
      - $ref: '#/components/parameters/TweetFilterConversationId'
      - $ref: '#/components/parameters/TweetFilterInReplyToTweetId'
      - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId'
      - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId'
      responses:
        '200':
          description: List of replies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TweetReplies'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '424':
          $ref: '#/components/responses/RepliesIncomplete'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        '503':
          description: Complete reply extraction 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: Complete reply extraction is busy. Retry shortly.
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
  /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'
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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'
      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:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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.
      - name: cursor
        in: query
        schema:
          type: string
        description: Pagination cursor for followers list
      - name: after
        in: query
        deprecated: true
        schema:
          type: string
        description: Legacy cursor alias. Prefer cursor.
      - $ref: '#/components/parameters/FollowerPageSize'
      - name: limit
        in: query
        deprecated: true
        schema:
          type: integer
        description: Legacy integer page size alias for following lists. Prefer pageSize.
      responses:
        '200':
          description: List of user followers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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
      - name: cursor
        in: query
        schema:
          type: string
        description: Pagination cursor for following list
      - name: after
        in: query
        deprecated: true
        schema:
          type: string
        description: Deprecated following cursor alias. Prefer cursor.
      - $ref: '#/components/parameters/FollowerPageSize'
      - name: limit
        in: query
        deprecated: true
        schema:
          type: integer
        description: Legacy page size alias. Prefer pageSize.
      responses:
        '200':
          description: List of following
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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/TweetFilterVerifiedOnly'
      - $ref: '#/components/parameters/TweetFilterReplies'
      - $ref: '#/components/parameters/TweetFilterRetweets'
      - $ref: '#/components/parameters/TweetFilterQuotes'
      - $ref: '#/components/parameters/TweetFilterExactPhrase'
      - $ref: '#/components/parameters/TweetFilterExcludeWords'
      - $ref: '#/components/parameters/TweetFilterAnyWords'
      - $ref: '#/components/parameters/TweetFilterHashtags'
      - $ref: '#/components/parameters/TweetFilterCashtags'
      - $ref: '#/components/parameters/TweetFilterUrl'
      - $ref: '#/components/parameters/TweetFilterConversationId'
      - $ref: '#/components/parameters/TweetFilterInReplyToTweetId'
      - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId'
      - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId'
      responses:
        '200':
          description: List of mentions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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
      - name: cursor
        in: query
        schema:
          type: string
        description: Pagination cursor for verified followers
      - $ref: '#/components/parameters/FollowerPageSize'
      responses:
        '200':
          description: List of verified followers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/AnonymousGuestAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '424':
          $ref: '#/components/responses/XApiError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          $ref: '#/components/responses/XApiError'
        default:
          content:
            application/json:
              example:
                error: internal_error
                message: Unexpected error. Try again.
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error.
      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.

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

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

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

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

        '
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    FollowerPageSize:
      name: pageSize
      in: query
      description: 'Maximum user profiles requested from this page (20-200, default 200). The response can contain fewer profiles
        because the source returned fewer or remaining credits cover fewer results. Keep requesting next_cursor while has_next_page
        is true. The deprecated limit and count aliases remain accepted.

        '
      schema:
        type: integer
        minimum: 20
        maximum: 200
        default: 200
    After:
      name: cursor
      in: query
      schema:
        type: string
      description: Cursor for keyset pagination from prior response next_cursor
    StyleId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Style profile ID or X username
    TweetFilterFromUser:
      name: fromUser
      in: query
      schema:
        type: string
      description: Filter by author username.
    TweetFilterToUser:
      name: toUser
      in: query
      schema:
        type: string
      description: Filter replies sent to a username.
    TweetFilterMentioning:
      name: mentioning
      in: query
      schema:
        type: string
      description: Filter tweets mentioning a username.
    TweetFilterLanguage:
      name: language
      in: query
      schema:
        type: string
      description: Language code filter, e.g. en or tr.
    TweetFilterSinceDate:
      name: sinceDate
      in: query
      schema:
        type: string
        format: date
      description: Start date in YYYY-MM-DD format.
    TweetFilterUntilDate:
      name: untilDate
      in: query
      schema:
        type: string
        format: date
      description: End date in YYYY-MM-DD format.
    TweetFilterMediaType:
      name: mediaType
      in: query
      schema:
        type: string
        enum:
        - images
        - videos
        - gifs
        - media
        - links
        - none
      description: Filter by media type.
    TweetFilterMinFaves:
      name: minFaves
      in: query
      schema:
        type: integer
        minimum: 0
      description: Minimum likes threshold.
    TweetFilterMinRetweets:
      name: minRetweets
      in: query
      schema:
        type: integer
        minimum: 0
      description: Minimum retweets threshold.
    TweetFilterMinReplies:
      name: minReplies
      in: query
      schema:
        type: integer
        minimum: 0
      description: Minimum replies threshold.
    TweetFilterMinQuotes:
      name: minQuotes
      in: query
      schema:
        type: integer
        minimum: 0
      description: Minimum quote count threshold.
    TweetFilterVerifiedOnly:
      name: verifiedOnly
      in: query
      schema:
        type: boolean
      description: Only return tweets from verified authors.
    TweetFilterReplies:
      name: replies
      in: query
      schema:
        type: string
        enum:
        - include
        - exclude
        - only
      description: Reply mode.
    TweetFilterRetweets:
      name: retweets
      in: query
      schema:
        type: string
        enum:
        - include
        - exclude
        - only
      description: Retweet mode.
    TweetFilterQuotes:
      name: quotes
      in: query
      schema:
        type: string
        enum:
        - include
        - exclude
        - only
      description: Quote mode.
    TweetFilterExactPhrase:
      name: exactPhrase
      in: query
      schema:
        type: string
      description: Exact phrase to match.
    TweetFilterExcludeWords:
      name: excludeWords
      in: query
      schema:
        type: string
      description: Words or quoted phrases to exclude. Separate with spaces, commas, or lines.
    TweetFilterAnyWords:
      name: anyWords
      in: query
      schema:
        type: string
      description: Words or quoted phrases where any one can match. Separate with spaces, commas, or lines.
    TweetFilterHashtags:
      name: hashtags
      in: query
      schema:
        type: string
      description: Hashtags separated by spaces, commas, or lines.
    TweetFilterCashtags:
      name: cashtags
      in: query
      schema:
        type: string
      description: Cashtags separated by spaces, commas, or lines.
    TweetFilterUrl:
      name: url
      in: query
      schema:
        type: string
      description: URL substring or domain filter.
    TweetFilterConversationId:
      name: conversationId
      in: query
      schema:
        type: string
      description: Conversation ID filter.
    TweetFilterInReplyToTweetId:
      name: inReplyToTweetId
      in: query
      schema:
        type: string
      description: Only replies to this tweet ID.
    TweetFilterQuotesOfTweetId:
      name: quotesOfTweetId
      in: query
      schema:
        type: string
      description: Only quotes of this tweet ID.
    TweetFilterRetweetsOfTweetId:
      name: retweetsOfTweetId
      in: query
      schema:
        type: string
      description: Only retweets of this tweet ID.
    TweetSearchListId:
      name: listId
      in: query
      schema:
        type: string
      description: Search within a list ID.
    TweetSearchPlace:
      name: place
      in: query
      schema:
        type: string
      description: Search within a place ID.
    TweetSearchPlaceCountry:
      name: placeCountry
      in: query
      schema:
        type: string
      description: Search within a country code.
    TweetSearchPointRadius:
      name: pointRadius
      in: query
      schema:
        type: string
      description: Geo point radius, e.g. -73.99 40.73 25mi.
    TweetSearchBoundingBox:
      name: boundingBox
      in: query
      schema:
        type: string
      description: Geo bounding box, e.g. -74.1 40.6 -73.9 40.8.
    TweetSearchAdvancedQuery:
      name: advancedQuery
      in: query
      schema:
        type: string
      description: Raw advanced search query appended as-is.
  responses:
    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.

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

        '
      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: 'Authentication required for a non-MPP paid read. The Bearer challenge requests authentication and is not
        a Payment challenge. Requests without credentials advertise accountless Stripe checkout, but create no checkout. Explicit
        invalid credentials return the plain error shape. Call an advertised action only after explicit user confirmation.

        '
      headers:
        Cache-Control:
          description: Prevents storage of the guest checkout action.
          schema:
            type: string
            const: no-store
        WWW-Authenticate:
          description: Bearer authentication challenge, not a Payment challenge.
          schema:
            type: string
            const: Bearer realm="xquik"
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/AnonymousGuestAuthenticationRequired'
            - allOf:
              - $ref: '#/components/schemas/Error'
              - not:
                  required:
                  - payment_options
          example:
            account_required: false
            error: unauthenticated
            message: Authentication required.
            next_step: Ask the user to confirm a USD amount before creating checkout.
            payment_options:
              guest_wallet:
                create_checkout:
                  account_required: false
                  amount_bounds:
                    currency: usd
                    maximum_minor: 25000
                    minimum_minor: 1000
                  body:
                    amount_minor: 1000
                    currency: usd
                  creates: checkout_url
                  method: POST
                  path: /api/v1/guest-wallets
                  provider: stripe
                  required_headers:
                    Idempotency-Key: <cryptographically random UUID v4>
                  requires_authentication: false
                  requires_user_confirmation: true
                  requires_user_interaction: true
                  response_fields:
                  - checkout_url
                  - api_key
                  - status_url
                  response_url_field: checkout_url
    InvalidInput:
      description: Invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: invalid_input
            message: Invalid input. Check the request body.
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: not_found
            message: Resource not found.
    PaymentRequired:
      description: 'Payment required. Fixed-price direct MPP requests return a Machine Payments Protocol problem document
        and a WWW-Authenticate challenge. Authenticated X data requests return balances and explicit Stripe checkout-creation
        actions. Guest paid-read keys receive only the accountless guest top-up action. Direct MPP challenges also advertise
        the Stripe wallet action. Other authenticated endpoints return a legacy error shape. A failed request never creates
        checkout. Create checkout only after the user confirms a payment option.

        '
      headers:
        WWW-Authenticate:
          description: MPP payment challenge for eligible anonymous pay-per-use requests. Authenticated credit or subscription
            errors omit this header.
          schema:
            type: string
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/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`.

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

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: x_write_failed
            message: Write action failed unexpectedly. Contact support if this persists.
    WriteRejected:
      description: 'X rejected the write or the media URL could not be downloaded. Possible codes: `x_content_too_long`, `x_duplicate_action`,
        `x_account_suspended`, `x_account_protected`, `x_dm_not_allowed`, `x_target_not_found`, `x_account_feature_required`,
        `x_rejected`, `media_download_failed` (URL fetch path only - body.url not HTTPS, resolves to private IP, file too
        large, origin error, or timeout).

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: x_rejected
            message: X rejected this request. Wait a few minutes and try again.
    RateLimitedByX:
      description: 'X throttled the write. Possible codes: `x_rate_limited` (short-term throttle) or `x_daily_limit` (daily
        cap hit). Back off and retry later. Distinct from Xquik tier-based 429.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: x_rate_limited
            message: Rate limited by X. Wait before retrying.
      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.

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

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: x_api_unavailable
            message: X data source temporarily unavailable. Try again later.
    FavoritersUnavailable:
      description: 'X reports likes for the post but does not expose the corresponding user identities. Returns error code
        `favoriters_unavailable`.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: favoriters_unavailable
            message: Users who liked this post are unavailable. Use retweeters or replies instead.
    RepliesIncomplete:
      description: Incomplete replies
      content:
        application/json:
          schema:
            anyOf:
            - $ref: '#/components/schemas/Error'
            - $ref: '#/components/schemas/IncompleteTweetReplies'
    ConnectAlreadyConnected:
      description: 'The specified X account is already connected to this Xquik account. Returns error code `account_already_connected`.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: account_already_connected
            message: This X account is already connected.
    ConnectLoginFailed:
      description: 'Login could not continue because credentials or account verification require user action. When a cooldown
        applies, the response includes `retryAfterMs` and a `Retry-After` header in seconds. Returns error code `login_failed`
        or `passkey_required`.

        '
      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`.

        '
      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. Either the generous connection safety limit was exceeded (`rate_limit_exceeded`, `retryAfter`
        seconds, `Retry-After: 900` header) or a prior login attempt triggered a cooldown (`login_cooldown`, `reason`, `retryAfterMs`,
        `Retry-After` header in seconds).

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

        '
      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`.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: x_user_lookup_failed
            message: X username lookup failed. Try again later.
    ConnectServiceUnavailable:
      description: 'The X connection service is temporarily unavailable. Retry after a short delay. Returns error code `service_unavailable`.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: service_unavailable
            message: Service temporarily unavailable. Try again later.
    ReauthAccountNotFound:
      description: 'No X account with this ID belongs to the authenticated user. Returns error code `account_not_found`.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: account_not_found
            message: X account not found.
  schemas:
    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.

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

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

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

            '
          example: false
        statusUrl:
          type: string
          example: /api/v1/x/write-actions/12345
        pollAfterMs:
          type:
          - integer
          - 'null'
          minimum: 0
          example: null
        charged:
          type: boolean
          example: true
        chargedCredits:
          type: string
          pattern: ^\d+$
          example: '10'
        billing:
          $ref: '#/components/schemas/XWriteActionBilling'
        request:
          $ref: '#/components/schemas/XWriteActionRequest'
        account:
          $ref: '#/components/schemas/XWriteActionAccount'
        target:
          $ref: '#/components/schemas/XWriteActionTarget'
        targetId:
          type:
          - string
          - 'null'
          example: '9876543210'
        result:
          $ref: '#/components/schemas/XWriteActionResult'
        nextAction:
          $ref: '#/components/schemas/XWriteActionNextAction'
        requestHash:
          type: string
          pattern: ^[0-9a-f]{64}$
          example: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
        requestId:
          type: string
          example: 01JZ8R7QSC9QKT0V7JX4M2A6B8
        idempotent:
          type: boolean
          example: false
        error:
          type: string
          example: x_write_ambiguous
        message:
          type: string
          example: Invalid input. Check request fields.
        sendDispatched:
          type: boolean
          example: true
        sendDispatchedAt:
          type: string
          format: date-time
          description: Dispatch timestamp when the write reached execution.
          example: '2026-07-21T05:00:00Z'
        createdAt:
          type: string
          format: date-time
          example: '2026-07-21T05:00:00Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-07-21T05:00:02Z'
        completedAt:
          type: string
          format: date-time
          example: '2026-07-21T05:00:02Z'
        expiresAt:
          type: string
          format: date-time
          description: 'Deadline for resolving a non-terminal write. This is not the Idempotency-Key retention deadline.

            '
          example: '2026-07-22T05:00:00Z'
        confirmedAt:
          type: string
          format: date-time
          example: '2026-07-21T05:00:02Z'
        confirmationCheckedAt:
          type: string
          format: date-time
          example: '2026-07-21T05:00:02Z'
        confirmationAttempts:
          type: integer
          minimum: 0
          example: 1
        tweetId:
          type: string
          description: Compatibility field for a confirmed tweet result ID.
          example: '9876543210'
        messageId:
          type: string
          description: Compatibility field for a confirmed direct message ID.
          example: '1234567890'
        mediaId:
          type: string
          description: Compatibility field for a confirmed media upload ID.
          example: '2345678901'
        mediaUrl:
          type: string
          format: uri
          description: Public media URL when the upload creates one.
          example: https://media.xquik.com/example.jpg
        communityId:
          type: string
          description: Compatibility field for a confirmed community ID.
          example: '3456789012'
        communityName:
          type: string
          description: Confirmed community name when available.
          example: Builders
        resultId:
          type: string
          description: Compatibility result ID for other write actions.
          example: '9876543210'
        media:
          type: object
          additionalProperties: true
          description: Media count, kind, size, and billing details when used.
          example:
            count: 1
            kind: image
        details:
          type: object
          additionalProperties: true
          description: Structured recovery context for a failed write.
          example:
            suggestion: Poll the action status URL.
        success:
          type: boolean
          example: true
      description: 'Durable write lifecycle record. Poll statusUrl until terminal is true. Reusing the original Idempotency-Key
        returns this same record. Submit a new write only when safeToRetry is true, using a new key.

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

        '
    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: 'Paginated tweets. Source visibility, filters, or remaining credits can reduce results. An empty filtered
        page can still have has_next_page true. Follow next_cursor while has_next_page is true. Zero affordable results returns
        402 insufficient_credits.

        '
      type: object
      required:
      - tweets
      - has_next_page
      - next_cursor
      properties:
        tweets:
          type: array
          items:
            $ref: '#/components/schemas/SearchTweet'
          example:
          - id: '1234567890'
            text: Just launched our new feature!
            retweetCount: 5
            replyCount: 3
            likeCount: 42
            quoteCount: 1
            viewCount: 1500
            bookmarkCount: 2
        has_next_page:
          type: boolean
          example: true
        next_cursor:
          type: string
          example: DAACCgACGRElMJcAAA
    TweetReplies:
      description: 'Reply rows. Complete mode also returns nested replies and coverage diagnostics. Keep nested replies separate
        from direct coverage.

        '
      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: 'Paginated user profiles. The item count can be lower than pageSize when the source returns fewer profiles
        or remaining credits cover fewer results. Follow next_cursor while has_next_page is true. A relationship can naturally
        contain fewer profiles than requested. Zero affordable results returns 402 insufficient_credits.

        '
      type: object
      required:
      - users
      - has_next_page
      - next_cursor
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserProfile'
          example:
          - id: '9876543210'
            username: elonmusk
            name: Elon Musk
        has_next_page:
          type: boolean
          example: true
        next_cursor:
          type: string
          example: DAACCgACGRElMJcAAA
    BatchUsers:
      description: 'Batch user lookup results. Duplicate requested IDs are ignored while preserving first-seen order. unavailable_ids
        identifies processed IDs with no returned profile. unprocessed_ids identifies IDs skipped when available credits limit
        processing.

        '
      type: object
      required:
      - users
      - has_next_page
      - next_cursor
      - requested_count
      - processed_count
      - returned_count
      - unavailable_ids
      - unprocessed_ids
      properties:
        users:
          type: array
          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 Stripe checkout and guest wallet purchase details.
      type: object
      additionalProperties: false
      required:
      - account_required
      - amount
      - checkout_url
      - credits
      - expires_at
      - instructions
      - poll_after_seconds
      - purchase_id
      - requires_user_interaction
      - status
      - status_url
      - wallet_id
      properties:
        account_required:
          type: boolean
          const: false
        amount:
          $ref: '#/components/schemas/GuestWalletAmount'
        api_key:
          type: string
          format: password
          description: 'Paid-read bearer credential returned only by initial creation. Store it as a secret. Never place it
            in a URL or log.

            '
          example: xq_example_returned_once
        authorization:
          type: object
          additionalProperties: false
          required:
          - header
          - scheme
          properties:
            header:
              type: string
              enum:
              - Authorization
              example: Authorization
            scheme:
              type: string
              enum:
              - Bearer
              example: Bearer
        checkout_url:
          type: string
          format: uri
          pattern: ^https://buy\.stripe\.com/
          description: Raw Stripe-hosted checkout URL for user interaction.
          example: https://buy.stripe.com/example
        credits:
          type: string
          pattern: ^\d+$
          description: Credits granted after verified payment.
          example: '66666'
        credential_notice:
          type: string
          const: Store api_key and the Idempotency-Key securely before sharing checkout_url. No email recovery is available.
        expires_at:
          type: string
          format: date-time
          description: Time when the pending checkout expires.
          example: '2026-07-13T13:00:00.000Z'
        instructions:
          type: string
          const: Give checkout_url to the user. They must complete payment on Stripe. Never submit payment for them. After
            payment, poll status_url every poll_after_seconds until latest_purchase.status is no longer pending.
        poll_after_seconds:
          type: integer
          const: 2
          description: Wait at least this long before polling status_url.
        purchase_id:
          type: string
          pattern: ^gp_[A-Za-z0-9_-]+$
          example: gp_example
        requires_user_interaction:
          type: boolean
          const: true
        status:
          type: string
          enum:
          - creating
          - pending
          - paid
          - expired
          - failed
          - refunded
          - disputed
          example: pending
        status_url:
          type: string
          format: uri
          const: https://xquik.com/api/v1/guest-wallets/status
        wallet_id:
          type: string
          pattern: ^gw_[A-Za-z0-9_-]+$
          example: gw_example
    GuestWalletCreateResponse:
      description: Initial guest wallet response containing the one-time key.
      allOf:
      - $ref: '#/components/schemas/GuestWalletCheckoutResponse'
      - type: object
        required:
        - api_key
        - authorization
        - credential_notice
    GuestWalletTopupResponse:
      description: Existing guest wallet top-up response without a new key.
      allOf:
      - $ref: '#/components/schemas/GuestWalletCheckoutResponse'
      - not:
          anyOf:
          - type: object
            properties:
              api_key:
                type: string
            required:
            - api_key
          - type: object
            properties:
              authorization:
                type: object
            required:
            - authorization
    GuestWalletPurchaseStatus:
      description: Latest guest wallet purchase fulfillment state.
      type: object
      additionalProperties: false
      required:
      - amount
      - checkout_url
      - credits
      - expires_at
      - purchase_id
      - status
      properties:
        amount:
          $ref: '#/components/schemas/GuestWalletAmount'
        checkout_url:
          anyOf:
          - type: string
            format: uri
            pattern: ^https://buy\.stripe\.com/
          - type: 'null'
          description: Present only while the purchase is pending.
          example: null
        credits:
          type: string
          pattern: ^\d+$
          example: '66666'
        expires_at:
          type: string
          format: date-time
          example: '2026-07-13T13:00:00.000Z'
        purchase_id:
          type: string
          pattern: ^gp_[A-Za-z0-9_-]+$
          example: gp_example
        status:
          type: string
          enum:
          - creating
          - pending
          - paid
          - expired
          - failed
          - refunded
          - disputed
          example: paid
    GuestWalletStatusResponse:
      description: Current balance, usability, and latest guest purchase state.
      type: object
      additionalProperties: false
      required:
      - balance
      - latest_purchase
      - poll_after_seconds
      - scope
      - status
      - top_up
      - usable
      - wallet_id
      properties:
        balance:
          type: string
          pattern: ^\d+$
          example: '66666'
        latest_purchase:
          description: Latest purchase state. This does not determine usability.
          anyOf:
          - $ref: '#/components/schemas/GuestWalletPurchaseStatus'
          - type: 'null'
          example:
            amount:
              amount_minor: 1000
              currency: usd
            checkout_url: null
            credits: '66666'
            expires_at: '2026-07-13T13:00:00.000Z'
            purchase_id: gp_example
            status: paid
        poll_after_seconds:
          description: Polling delay while payment is pending. Null means stop.
          anyOf:
          - type: integer
            const: 2
          - type: 'null'
          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.

            '
          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
          const: stripe
        required_headers:
          type: object
          additionalProperties: false
          required:
          - Idempotency-Key
          properties:
            Idempotency-Key:
              type: string
              const: <cryptographically random UUID v4>
        requires_authentication:
          type: boolean
          const: false
        requires_user_confirmation:
          type: boolean
          const: true
        requires_user_interaction:
          type: boolean
          const: true
        response_fields:
          type: array
          minItems: 3
          maxItems: 3
          prefixItems:
          - type: string
            const: checkout_url
          - type: string
            const: api_key
          - type: string
            const: status_url
          items:
            type: string
            enum:
            - checkout_url
            - api_key
            - status_url
        response_url_field:
          type: string
          const: checkout_url
    GuestWalletTopupCheckoutAction:
      description: Explicit direct REST action for a guest wallet top-up.
      type: object
      additionalProperties: false
      required:
      - account_required
      - amount_bounds
      - body
      - creates
      - method
      - path
      - provider
      - required_headers
      - requires_authentication
      - requires_user_confirmation
      - requires_user_interaction
      - response_fields
      - response_url_field
      properties:
        account_required:
          type: boolean
          const: false
        amount_bounds:
          $ref: '#/components/schemas/GuestWalletAmountBounds'
        body:
          $ref: '#/components/schemas/GuestWalletPurchaseRequest'
        creates:
          type: string
          const: checkout_url
        method:
          type: string
          const: POST
        path:
          type: string
          const: /api/v1/guest-wallets/topups
        provider:
          type: string
          const: stripe
        required_headers:
          type: object
          additionalProperties: false
          required:
          - Idempotency-Key
          properties:
            Idempotency-Key:
              type: string
              const: <cryptographically random UUID v4>
        requires_authentication:
          type: boolean
          const: true
        requires_user_confirmation:
          type: boolean
          const: true
        requires_user_interaction:
          type: boolean
          const: true
        response_fields:
          type: array
          minItems: 2
          maxItems: 2
          prefixItems:
          - type: string
            const: checkout_url
          - type: string
            const: status_url
          items:
            type: string
            enum:
            - checkout_url
            - status_url
        response_url_field:
          type: string
          const: checkout_url
    AnonymousGuestAuthenticationRequired:
      description: 'Authentication error for a non-MPP anonymous paid read. The response also advertises optional accountless
        Stripe checkout after confirmation.

        '
      type: object
      additionalProperties: false
      required:
      - account_required
      - error
      - message
      - next_step
      - payment_options
      properties:
        account_required:
          type: boolean
          const: false
        error:
          type: string
          const: unauthenticated
        message:
          type: string
          example: Authentication required.
        next_step:
          type: string
          const: Ask the user to confirm a USD amount before creating checkout.
        payment_options:
          type: object
          additionalProperties: false
          required:
          - guest_wallet
          properties:
            guest_wallet:
              type: object
              additionalProperties: false
              required:
              - create_checkout
              properties:
                create_checkout:
                  $ref: '#/components/schemas/GuestWalletCreateCheckoutAction'
    GuestPaymentRequired:
      description: 'Credit error for a paid-read guest key with only its accountless guest top-up action.

        '
      type: object
      additionalProperties: false
      required:
      - balance
      - error
      - message
      - next_step
      - payment_options
      - required
      - top_up_endpoint
      - top_up_url
      properties:
        balance:
          type: string
          pattern: ^\d+$
          example: '0'
        error:
          type: string
          enum:
          - insufficient_credits
          - no_credits
          - no_subscription
          - subscription_inactive
          example: insufficient_credits
        message:
          type: string
          example: Insufficient credits. Top up or subscribe to continue.
        next_step:
          type: string
          const: Ask the user to confirm a USD amount before creating checkout.
        payment_options:
          type: object
          additionalProperties: false
          required:
          - credits
          properties:
            credits:
              type: object
              additionalProperties: false
              required:
              - create_checkout
              properties:
                create_checkout:
                  $ref: '#/components/schemas/GuestWalletTopupCheckoutAction'
        required:
          type: string
          pattern: ^\d+$
          example: '1'
        top_up_endpoint:
          type: string
          const: /api/v1/guest-wallets/topups
        top_up_url:
          type: string
          const: POST /api/v1/guest-wallets/topups
    AuthenticatedPaymentRequired:
      description: Authenticated credit or subscription error with confirmation-gated Stripe checkout actions.
      type: object
      additionalProperties: false
      required:
      - balance
      - dashboard
      - error
      - message
      - next_step
      - payment_options
      - required
      - top_up_endpoint
      - top_up_url
      properties:
        balance:
          type: string
          pattern: ^\d+$
          description: Available credits as a decimal string.
          example: '0'
        dashboard:
          type: string
          const: /dashboard/account
          description: Account page for manual billing management.
        error:
          type: string
          enum:
          - insufficient_credits
          - no_credits
          - no_subscription
          - subscription_inactive
          example: insufficient_credits
        message:
          type: string
          example: Insufficient credits. Top up or subscribe to continue.
        next_step:
          type: string
          const: Ask the user to confirm a payment option before creating checkout.
        payment_options:
          type: object
          additionalProperties: false
          required:
          - credits
          - subscription
          properties:
            credits:
              type: object
              additionalProperties: false
              required:
              - create_checkout
              properties:
                create_checkout:
                  type: object
                  additionalProperties: false
                  required:
                  - body
                  - creates
                  - method
                  - path
                  - provider
                  - requires_authentication
                  - requires_user_confirmation
                  - response_url_field
                  properties:
                    body:
                      type: object
                      additionalProperties: false
                      required:
                      - dollars
                      - locale
                      properties:
                        dollars:
                          type: integer
                          const: 10
                        locale:
                          type: string
                          const: en
                    creates:
                      type: string
                      const: checkout_url
                    method:
                      type: string
                      const: POST
                    path:
                      type: string
                      const: /api/v1/credits/topup
                    provider:
                      type: string
                      const: stripe
                    requires_authentication:
                      type: boolean
                      const: true
                    requires_user_confirmation:
                      type: boolean
                      const: true
                    response_url_field:
                      type: string
                      const: url
            subscription:
              type: object
              additionalProperties: false
              required:
              - create_checkout
              properties:
                create_checkout:
                  type: object
                  additionalProperties: false
                  required:
                  - body
                  - creates
                  - method
                  - path
                  - provider
                  - requires_authentication
                  - requires_user_confirmation
                  - response_url_field
                  properties:
                    body:
                      type: object
                      additionalProperties: false
                      required:
                      - tier
                      properties:
                        tier:
                          type: string
                          const: starter
                    creates:
                      type: string
                      const: checkout_url
                    method:
                      type: string
                      const: POST
                    path:
                      type: string
                      const: /api/v1/subscribe
                    provider:
                      type: string
                      const: stripe
                    requires_authentication:
                      type: boolean
                      const: true
                    requires_user_confirmation:
                      type: boolean
                      const: true
                    response_url_field:
                      type: string
                      const: url
        required:
          type: string
          pattern: ^\d+$
          description: Credits required for the blocked request.
          example: '1'
        top_up_endpoint:
          type: string
          const: /api/v1/credits/topup
        top_up_url:
          type: string
          const: POST /api/v1/credits/topup
    MppPaymentRequired:
      description: Anonymous payment requirement for a direct MPP operation. The response includes an MPP challenge and an
        accountless Stripe action.
      type: object
      required:
      - account_required
      - detail
      - next_step
      - payment_options
      - status
      - title
      - type
      properties:
        account_required:
          type: boolean
          const: false
        challengeId:
          type: string
          description: Opaque identifier for the MPP payment challenge.
          example: mpp_challenge_example
        detail:
          type: string
          example: Payment is required.
        hint:
          type: string
          description: Instructions for selecting and paying an MPP offer.
          example: Use a supported wallet with an offer from the WWW-Authenticate header.
        next_step:
          type: string
          const: Ask the user to confirm a USD amount before creating checkout.
        payment_options:
          type: object
          additionalProperties: false
          required:
          - guest_wallet
          properties:
            guest_wallet:
              type: object
              additionalProperties: false
              required:
              - create_checkout
              properties:
                create_checkout:
                  $ref: '#/components/schemas/GuestWalletCreateCheckoutAction'
        status:
          type: integer
          const: 402
        title:
          type: string
          const: Payment Required
        type:
          type: string
          format: uri
          const: https://paymentauth.org/problems/payment-required
    Error:
      description: 'Error response. Default v1 returns a legacy string error code. Send `xquik-api-contract: 2026-04-29` to
        receive the structured best-practice error object.

        '
      type: object
      required:
      - error
      properties:
        error:
          x-stainless-naming:
            python:
              type_name: ErrorValue
            java:
              type_name: ErrorValue
          example: invalid_input
          oneOf:
          - type: string
            title: LegacyErrorCode
            enum:
            - internal_error
            - account_already_connected
            - account_needs_reauth
            - account_not_found
            - account_required
            - account_restricted
            - api_key_limit_reached
            - article_not_found
            - dm_not_permitted
            - invalid_format
            - invalid_id
            - invalid_input
            - invalid_params
            - invalid_tool_type
            - invalid_tweet_id
            - invalid_tweet_url
            - invalid_user_id
            - invalid_user_ids
            - invalid_username
            - invalid_json
            - insufficient_credits
            - login_cooldown
            - login_failed
            - media_download_failed
            - missing_params
            - missing_query
            - monitor_already_exists
            - no_media
            - no_credits
            - no_subscription
            - not_found
            - payment_failed
            - rate_limit_exceeded
            - service_unavailable
            - style_not_found
            - subscription_inactive
            - tweet_not_found
            - unauthenticated
            - unsupported_field
            - user_not_found
            - body_too_large
            - checkout_unavailable
            - connection_challenge_expired
            - connection_challenge_inactive
            - draft_not_found
            - favoriters_unavailable
            - forbidden
            - guest_wallet_unavailable
            - guest_wallets_disabled
            - guest_wallets_unavailable
            - idempotency_conflict
            - idempotency_key_conflict
            - invalid_community_id
            - invalid_idempotency_key
            - invalid_list_id
            - invalid_payment_amount
            - invalid_range
            - login_rate_limited
            - missing_idempotency_key
            - missing_ids
            - no_cached_style
            - passkey_required
            - rate_limited
            - read_request_timeout
            - replies_incomplete
            - support_media_rate_limit
            - support_request_rate_limit
            - too_many_ids
            - unknown_field
            - unsupported_media_type
            - webhook_inactive
            - write_tracking_unavailable
            - x_write_unconfirmed
            - x_account_feature_required
            - x_account_protected
            - x_account_suspended
            - x_api_rate_limited
            - x_api_unavailable
            - x_api_unauthorized
            - x_auth_failure
            - x_content_too_long
            - x_daily_limit
            - x_dm_not_allowed
            - x_duplicate_action
            - x_login_auth_failed
            - x_login_challenge
            - x_login_denied
            - x_login_failed
            - x_login_proxy_error
            - x_login_rate_limited
            - x_login_service_unavailable
            - x_login_suspended
            - x_rate_limited
            - x_rejected
            - x_target_not_found
            - x_transient_error
            - x_user_lookup_failed
            - x_write_ambiguous
            - x_write_failed
            example: invalid_input
          - type: object
            title: StructuredError
            required:
            - message
            - type
            - code
            properties:
              message:
                type: string
                example: Invalid input. Check the request body.
              type:
                type: string
                enum:
                - api_error
                - authentication_error
                - billing_error
                - dependency_error
                - invalid_request_error
                - permission_error
                - rate_limit_error
                example: invalid_request_error
              code:
                type: string
                title: ErrorCode
                enum:
                - internal_error
                - account_already_connected
                - account_needs_reauth
                - account_not_found
                - account_required
                - account_restricted
                - api_key_limit_reached
                - article_not_found
                - dm_not_permitted
                - invalid_format
                - invalid_id
                - invalid_input
                - invalid_params
                - invalid_tool_type
                - invalid_tweet_id
                - invalid_tweet_url
                - invalid_user_id
                - invalid_user_ids
                - invalid_username
                - invalid_json
                - insufficient_credits
                - login_cooldown
                - login_failed
                - media_download_failed
                - missing_params
                - missing_query
                - monitor_already_exists
                - no_media
                - no_credits
                - no_subscription
                - not_found
                - payment_failed
                - rate_limit_exceeded
                - service_unavailable
                - style_not_found
                - subscription_inactive
                - tweet_not_found
                - unauthenticated
                - unsupported_field
                - user_not_found
                - body_too_large
                - checkout_unavailable
                - connection_challenge_expired
                - connection_challenge_inactive
                - draft_not_found
                - favoriters_unavailable
                - forbidden
                - guest_wallet_unavailable
                - guest_wallets_disabled
                - guest_wallets_unavailable
                - idempotency_conflict
                - idempotency_key_conflict
                - invalid_community_id
                - invalid_idempotency_key
                - invalid_list_id
                - invalid_payment_amount
                - invalid_range
                - login_rate_limited
                - missing_idempotency_key
                - missing_ids
                - no_cached_style
                - passkey_required
                - rate_limited
                - read_request_timeout
                - replies_incomplete
                - support_media_rate_limit
                - support_request_rate_limit
                - too_many_ids
                - unknown_field
                - unsupported_media_type
                - webhook_inactive
                - write_tracking_unavailable
                - x_write_unconfirmed
                - x_account_feature_required
                - x_account_protected
                - x_account_suspended
                - x_api_rate_limited
                - x_api_unavailable
                - x_api_unauthorized
                - x_auth_failure
                - x_content_too_long
                - x_daily_limit
                - x_dm_not_allowed
                - x_duplicate_action
                - x_login_auth_failed
                - x_login_challenge
                - x_login_denied
                - x_login_failed
                - x_login_proxy_error
                - x_login_rate_limited
                - x_login_service_unavailable
                - x_login_suspended
                - x_rate_limited
                - x_rejected
                - x_target_not_found
                - x_transient_error
                - x_user_lookup_failed
                - x_write_ambiguous
                - x_write_failed
                example: invalid_input
        message:
          type: string
          description: Human-readable error guidance.
          example: Invalid input. Check the request body.
        reason:
          type: string
          description: Machine-readable reason for a login cooldown.
          example: temporary_issue
        retryAfter:
          type: integer
          minimum: 1
          description: Seconds until the next permitted request.
          example: 60
        retryAfterMs:
          type: integer
          minimum: 1
          description: Required wait in milliseconds.
          example: 60000
    EventType:
      description: Type of monitor event fired when account activity occurs.
      type: string
      enum:
      - tweet.new
      - tweet.reply
      - tweet.retweet
      - tweet.quote
      - tweet.media
      - tweet.link
      - tweet.poll
      - tweet.mention
      - tweet.hashtag
      - tweet.longform
      - profile.avatar.changed
      - profile.banner.changed
      - profile.name.changed
      - profile.username.changed
      - profile.bio.changed
      - profile.location.changed
      - profile.url.changed
      - profile.verified.changed
      - profile.protected.changed
      - profile.pinned_tweet.changed
      - profile.unavailable.changed
      example: tweet.new
    EventTypeArray:
      description: Array of event types to subscribe to.
      type: array
      items:
        $ref: '#/components/schemas/EventType'
      minItems: 1
      example:
      - tweet.new
      - tweet.reply
    ExtractionToolType:
      description: Identifier for the extraction tool used to run a job.
      type: string
      example: follower_explorer
      enum:
      - article_extractor
      - community_extractor
      - community_moderator_explorer
      - community_post_extractor
      - community_search
      - favoriters
      - follower_explorer
      - following_explorer
      - list_follower_explorer
      - list_member_extractor
      - list_post_extractor
      - mention_extractor
      - people_search
      - post_extractor
      - quote_extractor
      - reply_extractor
      - repost_extractor
      - space_explorer
      - thread_extractor
      - tweet_search_extractor
      - user_likes
      - user_media
      - verified_follower_explorer
    ApiKey:
      description: API key metadata returned when listing keys.
      type: object
      required:
      - id
      - name
      - prefix
      - isActive
      - createdAt
      properties:
        id:
          type: string
        name:
          type: string
        prefix:
          type: string
        isActive:
          type: boolean
        createdAt:
          type: string
          format: date-time
        lastUsedAt:
          type: string
          format: date-time
    Monitor:
      description: Account monitor that tracks activity for a given X user.
      type: object
      required:
      - id
      - username
      - xUserId
      - eventTypes
      - isActive
      - createdAt
      - nextBillingAt
      properties:
        id:
          type: string
          example: '42'
        username:
          type: string
          example: elonmusk
        xUserId:
          type: string
          example: '9876543210'
        eventTypes:
          $ref: '#/components/schemas/EventTypeArray'
          example:
          - tweet.new
          - tweet.reply
        isActive:
          type: boolean
          example: true
        createdAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'
        nextBillingAt:
          type: string
          format: date-time
          description: Next hourly credit charge time for this account monitor.
          example: '2025-01-15T12:00:00Z'
    KeywordMonitor:
      description: Keyword monitor that tracks matching public X activity.
      type: object
      required:
      - id
      - query
      - eventTypes
      - isActive
      - createdAt
      - nextBillingAt
      properties:
        id:
          type: string
          example: '21'
        query:
          type: string
          example: xquik OR "x api"
        eventTypes:
          $ref: '#/components/schemas/EventTypeArray'
          example:
          - tweet.new
        isActive:
          type: boolean
          example: true
        createdAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'
        nextBillingAt:
          type: string
          format: date-time
          description: Next hourly credit charge time for this keyword query monitor.
          example: '2025-01-15T12:00:00Z'
    Event:
      description: Monitor event summary with source metadata and occurrence time.
      type: object
      required:
      - id
      - type
      - monitorId
      - monitorType
      - occurredAt
      - data
      properties:
        id:
          type: string
        type:
          $ref: '#/components/schemas/EventType'
        username:
          type: string
          description: Account username, present for account monitor events.
        query:
          type: string
          description: Keyword query, present for keyword monitor events.
        monitorId:
          type: string
          description: Account monitor ID for account events, or keyword monitor ID for keyword events.
        monitorType:
          type: string
          enum:
          - account
          - keyword
          description: Source monitor type.
        keywordMonitorId:
          type: string
          description: Keyword monitor ID, present for keyword monitor events.
        occurredAt:
          type: string
          format: date-time
        data:
          type: object
          additionalProperties: true
    EventDetail:
      description: Full monitor event including payload data and optional X event ID.
      type: object
      required:
      - id
      - type
      - monitorId
      - monitorType
      - occurredAt
      - data
      properties:
        id:
          type: string
          example: '42'
        type:
          $ref: '#/components/schemas/EventType'
          example: tweet.new
        username:
          type: string
          description: Account username for this detailed monitor event.
          example: elonmusk
        query:
          type: string
          description: Keyword query for this detailed monitor event.
          example: xquik OR "x api"
        monitorId:
          type: string
          description: Monitor ID associated with this detailed event payload.
          example: '10'
        monitorType:
          type: string
          enum:
          - account
          - keyword
          description: Source monitor type for this detailed event.
          example: account
        keywordMonitorId:
          type: string
          description: Keyword monitor ID included on detailed keyword events.
          example: '21'
        occurredAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'
        data:
          type: object
          additionalProperties: true
          x-stainless-any: true
          description: Event payload - shape varies by event type (JSON)
          x-stainless-terraform-type: string
          example:
            tweetId: '1234567890'
        xEventId:
          type: string
          example: '1234567890'
    ExtractionJob:
      description: Extraction job tracking status, tool type, and result count.
      type: object
      required:
      - id
      - toolType
      - status
      - totalResults
      - createdAt
      properties:
        id:
          type: string
        toolType:
          $ref: '#/components/schemas/ExtractionToolType'
        status:
          type: string
          enum:
          - running
          - completed
          - failed
        totalResults:
          type: integer
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
    DrawListItem:
      description: Giveaway draw summary with entry counts and status.
      type: object
      required:
      - id
      - tweetUrl
      - status
      - totalEntries
      - validEntries
      - createdAt
      properties:
        id:
          type: string
          description: Draw public ID for detail responses.
          example: f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345
        tweetUrl:
          type: string
          format: uri
        status:
          type: string
        totalEntries:
          type: integer
        validEntries:
          type: integer
        createdAt:
          type: string
          format: date-time
        drawnAt:
          type: string
          format: date-time
    DrawDetail:
      description: Full giveaway draw with tweet metrics, entries, and timing.
      type: object
      required:
      - id
      - tweetUrl
      - tweetId
      - tweetText
      - tweetAuthorUsername
      - status
      - totalEntries
      - validEntries
      - tweetLikeCount
      - tweetRetweetCount
      - tweetReplyCount
      - tweetQuoteCount
      - createdAt
      properties:
        id:
          type: string
          description: Draw public ID.
          example: f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345
        tweetUrl:
          type: string
          format: uri
        tweetId:
          type: string
        tweetText:
          type: string
        tweetAuthorUsername:
          type: string
        status:
          type: string
        totalEntries:
          type: integer
        validEntries:
          type: integer
        tweetLikeCount:
          type: integer
        tweetRetweetCount:
          type: integer
        tweetReplyCount:
          type: integer
        tweetQuoteCount:
          type: integer
        createdAt:
          type: string
          format: date-time
        drawnAt:
          type: string
          format: date-time
    Winner:
      description: Giveaway draw winner with position and backup flag.
      type: object
      required:
      - authorUsername
      - tweetId
      - position
      - isBackup
      properties:
        authorUsername:
          type: string
        tweetId:
          type: string
        position:
          type: integer
        isBackup:
          type: boolean
    Webhook:
      description: Webhook endpoint registered to receive event deliveries.
      type: object
      required:
      - id
      - url
      - eventTypes
      - isActive
      - consecutiveFailures
      - deliveryStatus
      - failureHardCap
      - createdAt
      properties:
        id:
          type: string
          example: '42'
        url:
          type: string
          format: uri
          example: https://example.com/webhooks/xquik
        eventTypes:
          $ref: '#/components/schemas/EventTypeArray'
          example:
          - tweet.new
          - tweet.reply
        isActive:
          type: boolean
          example: true
        consecutiveFailures:
          type: integer
          description: Consecutive failed delivery attempts since the last success.
          example: 0
        deliveryStatus:
          type: string
          enum:
          - active
          - paused
          - needs_attention
          description: Endpoint delivery state. needs_attention means delivery stopped after repeated failures.
          example: active
        failureHardCap:
          type: integer
          description: Consecutive delivery failures that pause the endpoint.
          example: 200
        createdAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'
    Delivery:
      description: Webhook delivery attempt record with status and retry count.
      type: object
      required:
      - id
      - streamEventId
      - status
      - attempts
      - createdAt
      properties:
        id:
          type: string
        streamEventId:
          type: string
        status:
          type: string
        attempts:
          type: integer
        createdAt:
          type: string
          format: date-time
        deliveredAt:
          type: string
          format: date-time
        lastStatusCode:
          type: integer
        lastError:
          type: string
    ArticleAuthor:
      description: X Article author profile fields returned when available.
      type: object
      required:
      - id
      - name
      - username
      properties:
        id:
          type: string
          example: '9876543210'
        name:
          type: string
          example: Elon Musk
        username:
          type: string
          example: elonmusk
        description:
          type: string
        location:
          type: string
        url:
          type: string
        createdAt:
          type: string
        followersCount:
          type: integer
        followingCount:
          type: integer
        statusesCount:
          type: integer
        mediaCount:
          type: integer
        favouritesCount:
          type: integer
        profilePicture:
          type: string
        profileBannerUrl:
          type: string
        isBlueVerified:
          type: boolean
        isVerified:
          type: boolean
        isTranslator:
          type: boolean
        protected:
          type: boolean
    TweetMedia:
      description: Normalized media attached to a tweet.
      type: object
      required:
      - mediaUrl
      - type
      - url
      properties:
        mediaUrl:
          type: string
          description: Media preview URL
        type:
          type: string
          enum:
          - photo
          - video
          - animated_gif
        url:
          type: string
          description: X media link from the tweet
        allowDownload:
          type: boolean
          description: Whether X permits direct media download.
        altText:
          type: string
          description: Accessibility text supplied for the media.
        aspectRatio:
          type: array
          description: Video aspect ratio as width and height.
          items:
            type: integer
        availabilityStatus:
          type: string
          description: Media availability state reported by X.
        displayUrl:
          type: string
          description: Display-friendly media URL reported by X.
        durationMillis:
          type: integer
          description: Video duration in milliseconds.
        expandedUrl:
          type: string
          description: Expanded X media URL.
        faceRects:
          type: object
          description: Face-aware crop rectangles grouped by media size.
          additionalProperties:
            type: array
            items:
              type: object
              required:
              - x
              - y
              - w
              - h
              properties:
                x:
                  type: integer
                y:
                  type: integer
                w:
                  type: integer
                h:
                  type: integer
        focusRects:
          type: array
          description: Suggested image crops reported by X.
          items:
            type: object
            required:
            - x
            - y
            - w
            - h
            properties:
              x:
                type: integer
              y:
                type: integer
              w:
                type: integer
              h:
                type: integer
        height:
          type: integer
          description: Original media height.
        id:
          type: string
          description: X media entity ID.
        indices:
          type: array
          description: Media entity offsets in the tweet text.
          items:
            type: integer
        mediaKey:
          type: string
          description: Stable X media key.
        monetizable:
          type: boolean
          description: Whether X reports the media as monetizable.
        sizes:
          type: object
          description: Named media renditions and resize modes.
          additionalProperties:
            type: object
            required:
            - w
            - h
            - resize
            properties:
              w:
                type: integer
              h:
                type: integer
              resize:
                type: string
        videoVariants:
          type: array
          description: Available video encodings, ordered as returned
          items:
            type: object
            required:
            - contentType
            - url
            properties:
              bitrate:
                type: integer
              contentType:
                type: string
              url:
                type: string
        width:
          type: integer
          description: Original media width.
    TweetArticleMetadata:
      description: Article metadata attached to a tweet.
      type: object
      properties:
        id:
          type: string
        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:
          type: object
          additionalProperties: true
          x-stainless-any: true
          x-stainless-terraform-type: string
    TweetCommunityNote:
      description: Community Note presentation metadata returned by X.
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        shortTitle:
          type: string
        subtitle:
          type: string
        footer:
          type: string
        destinationUrl:
          type: string
        visualStyle:
          type: string
    TweetEdit:
      description: Edit history metadata returned by X.
      type: object
      properties:
        editTweetIds:
          type: array
          items:
            type: string
        editableUntilMsecs:
          type: string
    TweetNote:
      description: Complete Note Tweet content and rich-text metadata.
      type: object
      required:
      - text
      properties:
        id:
          type: string
        text:
          type: string
        isExpandable:
          type: boolean
        entities:
          type: object
          additionalProperties: true
          x-stainless-any: true
          x-stainless-terraform-type: string
        richtextTags:
          type: array
          items:
            type: object
            required:
            - fromIndex
            - toIndex
            - types
            properties:
              fromIndex:
                type: integer
              toIndex:
                type: integer
              types:
                type: array
                items:
                  type: string
    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:
          type: object
          additionalProperties: true
          x-stainless-any: true
          x-stainless-terraform-type: string
        country:
          type: string
        countryCode:
          type: string
        fullName:
          type: string
        id:
          type: string
        name:
          type: string
        placeType:
          type: string
        url:
          type: string
    EmbeddedTweet:
      description: 'Quoted or retweeted tweet context. Every object includes id, text, and engagement metrics. A zero metric
        can mean X did not report the count. Author, media, and conversation fields appear when available.

        '
      type: object
      required:
      - id
      - text
      - retweetCount
      - replyCount
      - likeCount
      - quoteCount
      - viewCount
      - bookmarkCount
      properties:
        id:
          type: string
        text:
          type: string
        type:
          type: string
        createdAt:
          type: string
        url:
          type: string
        lang:
          type: string
        retweetCount:
          type: integer
        replyCount:
          type: integer
        likeCount:
          type: integer
        quoteCount:
          type: integer
        viewCount:
          type: integer
        bookmarkCount:
          type: integer
        isReply:
          type: boolean
        isLimitedReply:
          type: boolean
        isNoteTweet:
          type: boolean
        isQuoteStatus:
          type: boolean
        inReplyToId:
          type: string
        inReplyToUserId:
          type: string
        inReplyToUsername:
          type: string
        conversationId:
          type: string
        source:
          type: string
        displayTextRange:
          type: array
          items:
            type: integer
        contentDisclosure:
          $ref: '#/components/schemas/ContentDisclosure'
        article:
          $ref: '#/components/schemas/TweetArticleMetadata'
        card:
          $ref: '#/components/schemas/TweetCard'
        communityNote:
          $ref: '#/components/schemas/TweetCommunityNote'
        edit:
          $ref: '#/components/schemas/TweetEdit'
        isTranslatable:
          type: boolean
        noteTweet:
          $ref: '#/components/schemas/TweetNote'
        place:
          $ref: '#/components/schemas/TweetPlace'
        possiblySensitive:
          type: boolean
        previousCounts:
          $ref: '#/components/schemas/TweetPreviousCounts'
        viewState:
          type: string
        entities:
          type: object
          additionalProperties: true
          x-stainless-any: true
          x-stainless-terraform-type: string
        quoted_tweet:
          $ref: '#/components/schemas/EmbeddedTweet'
        retweeted_tweet:
          $ref: '#/components/schemas/EmbeddedTweet'
        media:
          type: array
          items:
            $ref: '#/components/schemas/TweetMedia'
        author:
          $ref: '#/components/schemas/UserProfile'
    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.
      type: object
      required:
      - id
      - text
      - retweetCount
      - replyCount
      - likeCount
      - quoteCount
      - viewCount
      - bookmarkCount
      properties:
        id:
          type: string
          example: '1234567890'
        text:
          type: string
          example: Just launched our new feature!
        createdAt:
          type: string
          example: '2025-01-15T12:00:00Z'
        isNoteTweet:
          type: boolean
          description: Whether this is a Note Tweet (long-form post, up to 25,000 characters)
          example: false
        isReply:
          type: boolean
          description: Whether this tweet is a reply to another tweet
          example: false
        isLimitedReply:
          type: boolean
          description: Whether replies are limited for this tweet
          example: false
        isQuoteStatus:
          type: boolean
          description: Whether this tweet quotes another tweet
          example: false
        conversationId:
          type: string
          description: ID of the root tweet in the conversation thread
          example: '1234567890'
        source:
          type: string
          description: Client application used to post this tweet
          example: Twitter Web App
        type:
          type: string
          description: Tweet result type
          example: tweet
        url:
          type: string
          description: Tweet permalink URL
          example: https://x.com/example_user/status/1234567890
        lang:
          type: string
          description: Tweet language code
          example: en
        inReplyToId:
          type: string
          description: Tweet ID being replied to
          example: '1234567890'
        inReplyToUserId:
          type: string
          description: User ID being replied to
          example: '9876543210'
        inReplyToUsername:
          type: string
          description: Username being replied to
          example: example_user
        displayTextRange:
          type: array
          items:
            type: integer
          description: Start and end offsets for rendered tweet text
          example:
          - 0
          - 31
        contentDisclosure:
          $ref: '#/components/schemas/ContentDisclosure'
        article:
          $ref: '#/components/schemas/TweetArticleMetadata'
        card:
          $ref: '#/components/schemas/TweetCard'
        communityNote:
          $ref: '#/components/schemas/TweetCommunityNote'
        edit:
          $ref: '#/components/schemas/TweetEdit'
        isTranslatable:
          type: boolean
        noteTweet:
          $ref: '#/components/schemas/TweetNote'
        place:
          $ref: '#/components/schemas/TweetPlace'
        possiblySensitive:
          type: boolean
        previousCounts:
          $ref: '#/components/schemas/TweetPreviousCounts'
        viewState:
          type: string
        entities:
          type: object
          additionalProperties: true
          x-stainless-any: true
          x-stainless-terraform-type: string
          description: Parsed entities from the tweet text (URLs, mentions, hashtags, media)
        quoted_tweet:
          $ref: '#/components/schemas/EmbeddedTweet'
        retweeted_tweet:
          $ref: '#/components/schemas/EmbeddedTweet'
        author:
          $ref: '#/components/schemas/TweetAuthor'
        media:
          type: array
          items:
            $ref: '#/components/schemas/TweetMedia'
          description: Attached media items, omitted when the tweet has no media
        retweetCount:
          type: integer
          example: 5
        replyCount:
          type: integer
          example: 3
        likeCount:
          type: integer
          example: 42
        quoteCount:
          type: integer
          example: 1
        viewCount:
          type: integer
          example: 1500
        bookmarkCount:
          type: integer
          example: 2
    TweetAuthor:
      description: Tweet author profile. The lookup route always includes follower count and verification state. Other profile
        fields appear when available.
      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.
      type: object
      required:
      - id
      - text
      - retweetCount
      - replyCount
      - likeCount
      - quoteCount
      - viewCount
      - bookmarkCount
      properties:
        id:
          type: string
          example: '1234567890'
        text:
          type: string
          example: Just launched our new feature!
        type:
          type: string
          example: tweet
        createdAt:
          type: string
          example: '2025-01-15T12:00:00Z'
        isNoteTweet:
          type: boolean
          description: True for Note Tweets (long-form content, up to 25,000 characters)
          example: false
        isReply:
          type: boolean
          description: True when this search result is a reply
          example: false
        isQuoteStatus:
          type: boolean
          description: True when this search result quotes another tweet
          example: false
        isLimitedReply:
          type: boolean
          description: Whether the tweet has limited reply permissions
          example: false
        inReplyToId:
          type: string
          description: ID of the tweet this result replies to.
          example: '1234567890'
        inReplyToUserId:
          type: string
          description: ID of the user this result replies to.
          example: '9876543210'
        inReplyToUsername:
          type: string
          description: Username this result replies to.
          example: example_user
        conversationId:
          type: string
          description: Root tweet ID for the search result conversation
          example: '1234567890'
        source:
          type: string
          description: Client application used to post the tweet
          example: Twitter Web App
        displayTextRange:
          type: array
          items:
            type: integer
          description: Rendered text's start and end offsets.
          example:
          - 0
          - 31
        contentDisclosure:
          $ref: '#/components/schemas/ContentDisclosure'
        article:
          $ref: '#/components/schemas/TweetArticleMetadata'
        card:
          $ref: '#/components/schemas/TweetCard'
        communityNote:
          $ref: '#/components/schemas/TweetCommunityNote'
        edit:
          $ref: '#/components/schemas/TweetEdit'
        isTranslatable:
          type: boolean
        noteTweet:
          $ref: '#/components/schemas/TweetNote'
        place:
          $ref: '#/components/schemas/TweetPlace'
        possiblySensitive:
          type: boolean
        previousCounts:
          $ref: '#/components/schemas/TweetPreviousCounts'
        viewState:
          type: string
        entities:
          type: object
          additionalProperties: true
          description: Parsed search-result entities including URLs, mentions, hashtags, and media markers
        quoted_tweet:
          $ref: '#/components/schemas/EmbeddedTweet'
        retweeted_tweet:
          $ref: '#/components/schemas/EmbeddedTweet'
        media:
          type: array
          items:
            $ref: '#/components/schemas/TweetMedia'
          description: Search-result media attachments, omitted when no media is present
        url:
          type: string
          description: Search result permalink.
          example: https://x.com/example_user/status/1234567890
        lang:
          type: string
          description: Search result language code.
          example: en
        likeCount:
          type: integer
          example: 42
        retweetCount:
          type: integer
          example: 5
        replyCount:
          type: integer
          example: 3
        quoteCount:
          type: integer
          example: 1
        viewCount:
          type: integer
          example: 1500
        bookmarkCount:
          type: integer
          example: 2
        author:
          $ref: '#/components/schemas/UserProfile'
    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
    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
        possiblySensitive:
          type: boolean
          example: false
        pinnedTweetIds:
          type: array
          items:
            type: string
          example:
          - '1234567890'
        isAutomated:
          type: boolean
          example: false
        automatedBy:
          type: string
          example: example_user
        unavailable:
          type: boolean
          example: false
        unavailableReason:
          type: string
          example: suspended
        verifiedType:
          type: string
          example: Business
        affiliatesHighlightedLabel:
          $ref: '#/components/schemas/UserAffiliateLabel'
        businessAccountAffiliatesCount:
          type: integer
        creatorSubscriptionsCount:
          type: integer
        hasGraduatedAccess:
          type: boolean
        hasHiddenSubscriptionsOnProfile:
          type: boolean
        highlightsInfo:
          $ref: '#/components/schemas/UserHighlightsInfo'
        identityVerification:
          $ref: '#/components/schemas/UserIdentityVerification'
        isProfileTranslatable:
          type: boolean
        parodyCommentaryFanLabel:
          type: string
        profileDescriptionLanguage:
          type: string
        profileImageShape:
          type: string
        profileInterstitialType:
          type: string
        profileSortEnabled:
          type: boolean
        profileTranslatorType:
          type: string
        superFollowEligible:
          type: boolean
        communityRole:
          type: string
          description: Community role when returned by community member reads
          example: Member
        profile_bio:
          type: object
          additionalProperties: true
          x-stainless-any: true
          x-stainless-terraform-type: string
          description: Structured profile bio with entity annotations
          example:
            description: CEO of Tesla, SpaceX, and X
            entities:
              urls: []
    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-specific fields. Shape varies per source:\n- reddit: { author, authorId?, subreddit, subredditId?,\n\
            \  subredditSubscribers?, sourceFormat, score?, upvoteRatio?,\n  estimatedUpvotes?, estimatedDownvotes?, numberComments?,\n\
            \  numberCrossposts?, selftext?, contentUrl?, domain?, postHint?,\n  linkFlairText?, distinguished?, totalAwardsReceived?,\
            \ viewCount?,\n  editedAt?, galleryImageUrls?, redditVideo?, archived?, contestMode?,\n  isCrosspostable?, isMeta?,\
            \ isNsfw?, isOriginalContent?,\n  isRobotIndexable?, isSelf?, isSpoiler?, isVideo?, locked?,\n  stickied? }. `score`\
            \ is Reddit's public net score. Exact public\n  upvote and downvote counts are not available. Estimated counts\n\
            \  derive from the public score and upvote ratio, which Reddit may\n  fuzz. Comment bodies are not included. Current\
            \ items combine\n  public listing discovery with server-rendered post data and use\n  `sourceFormat: html`; `json`\
            \ and `rss` remain for legacy rows.\n- github: { starsToday: number }\n- hacker_news: { points: number, numberComments:\
            \ number }\n- google_trends: { approxTraffic: number }\n- polymarket: { volume24hr: number }\n- wikipedia: { views:\
            \ number }\n- trustmrr: { mrr, growthPercent, last30Days, total, customers, activeSubscriptions, onSale, xHandle?,\
            \ category?, askingPrice?, country?, foundedDate?, googleSearchImpressionsLast30Days?, growthMrrPercent?, multiple?,\
            \ paymentProvider?, profitMarginLast30Days?, rank?, revenuePerVisitor?, targetAudience?, visitorsLast30Days? }\n\
            For the startup growth source, xHandle is the founder's X username\nwithout @. The rank field is the source's\
            \ revenue rank. Result order\nrepresents reported 30-day revenue-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 connection health. `healthy` = ready to use. `needsReauth` = user must submit fresh credentials.
            `locked` = X locked the account; unlock on x.com first. `suspended` = X banned the account. `recovering` = cooldown
            ended; the account can reconnect on its next use. `temporaryIssue` = temporary connection problem; wait before
            the next use.

            '
          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