openapi.yaml

openapi: 3.1.0
info:
  title: Xquik API
  version: '1.0'
  description: >-
    Look up any tweet, user, or trend on X. Search tweets, check follower
    relationships, download media, and monitor accounts in real time. 32
    pay-per-use read endpoints work without a subscription — just pay per call.
    Write endpoints (post, like, retweet, follow, DM) and automation endpoints
    (bulk extractions, giveaway draws, monitors, webhooks) require an API key or
    OAuth 2.1 bearer token.
  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 (from:, to:, has:media, min_faves:, lang:). 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 user IDs or @usernames. Cost: $0.00105.


    **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: $0.00015
    per media item.


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


    ## Pagination


    All list endpoints return {items, cursor}. Pass cursor as ?after={cursor} to
    fetch the next page. Dynamic-priced endpoints charge per item returned, not
    per request.


    ## Authentication


    Read-only paid endpoints accept pay-per-use payments (no account needed).
    Write endpoints and automation features require an X-Api-Key header or OAuth
    2.1 bearer token.
  contact:
    name: Xquik
    url: https://xquik.com
    email: support@xquik.com

servers:
  - url: https://xquik.com/api/v1

x-discovery:
  ownershipProofs:
    - 'dns:xquik.com'

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

tags:
  - name: Tweets
    description: Look up, search, and analyze individual tweets
  - name: Users
    description: Look up, search, and explore user profiles and relationships
  - name: Trends
    description: Trending topics and hashtags by region
  - name: Communities
    description: X Community info, members, and tweets
  - name: Lists
    description: X List followers, members, and tweets
  - name: Articles
    description: Long-form X Article extraction
  - name: Media
    description: Media upload and download
  - name: Composition
    description: AI tweet composition, drafts, writing styles, and radar
  - name: Draws
    description: Giveaway draws from tweet replies
  - name: Extractions
    description: Bulk data extraction (20 tool types)
  - name: Monitors
    description: Real-time X account monitoring
  - name: Events
    description: Activity events from monitored accounts
  - name: Webhooks
    description: Webhook endpoint management and delivery
  - name: Integrations
    description: Push notification integrations (Telegram)
  - name: Account
    description: Account info and settings
  - name: API Keys
    description: API key management (session auth only)
  - name: Subscribe
    description: Subscription, billing, and credits
  - name: X Accounts
    description: Connected X account management
  - name: X Write
    description: X write actions (tweets, likes, follows, DMs)
  - name: Bot
    description: Telegram bot service endpoints
  - name: Support
    description: Support ticket management
paths:
  # ── Account ──────────────────────────────────────────────
  /account:
    get:
      operationId: getAccount
      summary: Get account info
      tags: [Account]
      security:
        - apiKey: []
        - oauthBearer: []
      responses:
        '200':
          description: Account info
          content:
            application/json:
              schema:
                type: object
                required: [plan, monitorsUsed, monitorsAllowed]
                properties:
                  plan:
                    type: string
                    enum: [active, inactive]
                    example: active
                  monitorsUsed:
                    type: integer
                    example: 3
                  monitorsAllowed:
                    type: integer
                    example: 10
                  creditInfo:
                    type: object
                    required:
                      [
                        balance,
                        lifetimePurchased,
                        lifetimeUsed,
                        autoTopupEnabled,
                      ]
                    properties:
                      balance:
                        type: integer
                        example: 50000
                      lifetimePurchased:
                        type: integer
                        example: 140000
                      lifetimeUsed:
                        type: integer
                        example: 90000
                      autoTopupEnabled:
                        type: boolean
                        example: false
                    example:
                      balance: 50000
                      lifetimePurchased: 140000
                      lifetimeUsed: 90000
                      autoTopupEnabled: false
              example:
                plan: active
                monitorsUsed: 3
                monitorsAllowed: 10
                creditInfo:
                  balance: 50000
                  lifetimePurchased: 140000
                  lifetimeUsed: 90000
                  autoTopupEnabled: false
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
    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'

        '402':
          $ref: '#/components/responses/PaymentRequired'
  /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'

        # ── API Keys ─────────────────────────────────────────────
        '402':
          $ref: '#/components/responses/PaymentRequired'
  /api-keys:
    get:
      operationId: listApiKeys
      summary: List API keys
      tags: [API Keys]
      security:
        - apiKey: []
        - oauthBearer: []
      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'
        '402':
          $ref: '#/components/responses/PaymentRequired'
    post:
      operationId: createApiKey
      summary: Create API key
      tags: [API Keys]
      security:
        - apiKey: []
        - oauthBearer: []
      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'

        '402':
          $ref: '#/components/responses/PaymentRequired'
  /api-keys/{id}:
    delete:
      operationId: revokeApiKey
      summary: Revoke API key
      tags: [API Keys]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  # ── Subscribe ────────────────────────────────────────────
  /subscribe:
    post:
      operationId: subscribe
      summary: Get checkout or billing URL
      tags: [Subscribe]
      security:
        - apiKey: []
        - oauthBearer: []
      responses:
        '200':
          description: Stripe checkout or billing portal URL
          content:
            application/json:
              schema:
                type: object
                required: [url]
                properties:
                  url:
                    type: string
                    format: uri
                    example: 'https://checkout.stripe.com/c/pay/cs_test_123'
                  status:
                    type: string
                    enum: [checkout_created, already_subscribed, payment_issue]
                    example: checkout_created
                  message:
                    type: string
                    example: Checkout session created
              example:
                url: 'https://checkout.stripe.com/c/pay/cs_test_123'
                status: checkout_created
                message: Checkout session created
        '401':
          $ref: '#/components/responses/Unauthenticated'

        # ── Composition ──────────────────────────────────────────
        '402':
          $ref: '#/components/responses/PaymentRequired'
  /compose:
    post:
      operationId: compose
      summary: Compose, refine, or score a tweet
      tags: [Composition]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: Workflow step, topic, goal, and optional style parameters.
        content:
          application/json:
            schema:
              type: object
              required: [step]
              properties:
                step:
                  type: string
                  enum: [compose, refine, score]
                  description: Workflow step
                  example: compose
                topic:
                  type: string
                  description: Tweet topic (compose, refine)
                  example: AI trends in 2025
                goal:
                  type: string
                  enum: [engagement, followers, authority, conversation]
                  description: Optimization goal
                  example: engagement
                draft:
                  type: string
                  description: Tweet draft text to evaluate (score)
                  example: "AI is changing everything. Here's why."
                tone:
                  type: string
                  description: Desired tone (refine)
                  example: professional
                styleUsername:
                  type: string
                  description:
                    Cached style username for voice matching (compose)
                  example: elonmusk
                additionalContext:
                  type: string
                  description: Extra context or URLs (refine)
                  example: 'https://x.com/elonmusk/status/1234567890'
                callToAction:
                  type: string
                  description: Desired call to action (refine)
                  example: Follow for more
                mediaType:
                  type: string
                  enum: [photo, video, none]
                  description: Media type (refine)
                  example: none
                hasLink:
                  type: boolean
                  description: Whether a link is attached (score)
                  example: false
                hasMedia:
                  type: boolean
                  description: Whether media is attached (score)
                  example: false
            example:
              step: compose
              topic: AI trends in 2025
              goal: engagement
      responses:
        '200':
          description: Composition result
          content:
            application/json:
              schema:
                type: object
                properties:
                  text:
                    type: string
                    description: Generated or refined tweet text
                    example:
                      'AI is reshaping every industry. Here are 5 trends to
                      watch in 2025.'
                  score:
                    type: number
                    description: Engagement score (0-100)
                    example: 78
                  feedback:
                    type: string
                    description: AI feedback on the draft
                    example: 'Strong hook. Consider adding a call to action.'
                  suggestions:
                    type: array
                    items:
                      type: string
                    description: Improvement suggestions
                    example: ['Add a thread hook', 'Include a relevant hashtag']
                additionalProperties: true
              example:
                text:
                  'AI is reshaping every industry. Here are 5 trends to watch in
                  2025.'
                score: 78
                feedback: 'Strong hook. Consider adding a call to action.'
                suggestions: ['Add a thread hook', 'Include a relevant hashtag']
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'

        '402':
          $ref: '#/components/responses/PaymentRequired'
  /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'
        '402':
          $ref: '#/components/responses/PaymentRequired'
    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'

        '402':
          $ref: '#/components/responses/PaymentRequired'
  /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'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteDraft
      summary: Delete a draft
      tags: [Composition]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  /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'
        '402':
          $ref: '#/components/responses/PaymentRequired'
    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: Style profile created
          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'
  /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'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  /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'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
    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'
        '402':
          $ref: '#/components/responses/PaymentRequired'
    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'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

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

  /radar:
    get:
      operationId: getRadar
      summary: Get trending topics from curated sources
      tags: [Composition]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: category
          in: query
          schema:
            type: string
          description: 'Filter by category (general, tech, dev, etc.)'
        - name: count
          in: query
          schema:
            type: integer
          description: Number of items to return
        - name: hours
          in: query
          schema:
            type: integer
          description: Lookback window in hours
        - name: region
          in: query
          schema:
            type: string
          description: 'Region filter (us, global, etc.)'
        - 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: [items, total]
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/RadarItem'
                    example: []
                  total:
                    type: integer
                    example: 0
              example:
                items: []
                total: 0
        '401':
          $ref: '#/components/responses/Unauthenticated'

        # ── Monitors ─────────────────────────────────────────────
        '402':
          $ref: '#/components/responses/PaymentRequired'
  /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'
        '402':
          $ref: '#/components/responses/PaymentRequired'
    post:
      operationId: createMonitor
      summary: Create monitor
      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, follower.gained]
            example:
              username: elonmusk
              eventTypes: [tweet.new, follower.gained]
      responses:
        '201':
          description: Monitor created
          content:
            application/json:
              schema:
                type: object
                required: [id, username, xUserId, eventTypes, createdAt]
                properties:
                  id:
                    type: string
                    example: '42'
                  username:
                    type: string
                    example: elonmusk
                  xUserId:
                    type: string
                    example: '1234567890'
                  eventTypes:
                    $ref: '#/components/schemas/EventTypeArray'
                    example: [tweet.new, follower.gained]
                  createdAt:
                    type: string
                    format: date-time
                    example: '2025-01-15T12:00:00Z'
              example:
                id: '42'
                username: elonmusk
                xUserId: '1234567890'
                eventTypes: [tweet.new, follower.gained]
                createdAt: '2025-01-15T12:00:00Z'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          description: Monitor limit reached
          content:
            application/json:
              schema:
                type: object
                required: [error, limit]
                properties:
                  error:
                    type: string
                    example: 'Monitor limit reached'
                  limit:
                    type: integer
                    description: Current monitor quota
                    example: 10
              example:
                error: 'Monitor limit reached'
                limit: 10
        '404':
          description: X user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'user_not_found'
        '409':
          description: Monitor already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'monitor_already_exists'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'internal_error'
        '502':
          description: Stream registration failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'stream_registration_failed'

  /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, follower.gained]
                isActive: true
                createdAt: '2025-01-15T12:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateMonitor
      summary: Update 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: 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'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteMonitor
      summary: Deactivate monitor
      tags: [Monitors]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  # ── Events ───────────────────────────────────────────────
  /events:
    get:
      operationId: listEvents
      summary: List events
      tags: [Events]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/After'
        - name: monitorId
          in: query
          description: Filter events by monitor ID
          schema:
            type: string
        - name: eventType
          in: query
          description: Filter events by type
          schema:
            $ref: '#/components/schemas/EventType'
      responses:
        '200':
          description: Event list
          content:
            application/json:
              schema:
                type: object
                required: [events, hasMore]
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                    example: []
                  hasMore:
                    type: boolean
                    example: false
                  nextCursor:
                    type: string
                    example: 'abc123'
              example:
                events: []
                hasMore: false
        '401':
          $ref: '#/components/responses/Unauthenticated'

        '402':
          $ref: '#/components/responses/PaymentRequired'
  /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'
                occurredAt: '2025-01-15T12:00:00Z'
                data:
                  tweetId: '1234567890'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  # ── Extractions ──────────────────────────────────────────
  /extractions:
    get:
      operationId: listExtractions
      summary: List extraction jobs
      tags: [Extractions]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/After'
        - name: toolType
          in: query
          description: Filter by extraction tool type
          schema:
            $ref: '#/components/schemas/ExtractionToolType'
        - name: status
          in: query
          description: Filter by job status
          schema:
            type: string
            enum: [running, completed, failed]
      responses:
        '200':
          description: Extraction job list
          content:
            application/json:
              schema:
                type: object
                required: [extractions, hasMore]
                properties:
                  extractions:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExtractionJob'
                    example: []
                  hasMore:
                    type: boolean
                    example: false
                  nextCursor:
                    type: string
                    example: 'abc123'
              example:
                extractions: []
                hasMore: false
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
    post:
      operationId: createExtraction
      summary: Run extraction
      tags: [Extractions]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description:
          Tool type and target identifier (tweet, user, community, list, or
          search query).
        content:
          application/json:
            schema:
              type: object
              required: [toolType]
              properties:
                toolType:
                  $ref: '#/components/schemas/ExtractionToolType'
                  example: follower_explorer
                targetTweetId:
                  type: string
                  example: '1234567890'
                targetUsername:
                  type: string
                  example: elonmusk
                targetCommunityId:
                  type: string
                  example: '1500000000000000000'
                targetListId:
                  type: string
                  example: '1234567890'
                targetSpaceId:
                  type: string
                  example: '1vOGwMdBqpwGB'
                searchQuery:
                  type: string
                  example: 'AI trends 2025'
                exactPhrase:
                  type: string
                  description: Exact phrase to match (tweet_search_extractor)
                  example: 'artificial intelligence'
                excludeWords:
                  type: string
                  description:
                    Words to exclude from results (tweet_search_extractor)
                  example: 'spam'
                advancedQuery:
                  type: string
                  description:
                    Raw advanced search query appended as-is
                    (tweet_search_extractor)
                  example: 'min_faves:100'
            example:
              toolType: follower_explorer
              targetUsername: elonmusk
      responses:
        '202':
          description: Extraction started
          content:
            application/json:
              schema:
                type: object
                required: [id, toolType, status]
                properties:
                  id:
                    type: string
                    example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
                  toolType:
                    $ref: '#/components/schemas/ExtractionToolType'
                    example: follower_explorer
                  status:
                    type: string
                    const: running
                    example: running
              example:
                id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
                toolType: follower_explorer
                status: running
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'

  /extractions/estimate:
    post:
      operationId: estimateExtraction
      summary: Estimate extraction cost
      tags: [Extractions]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description:
          Same parameters as a real extraction; returns estimated credit cost
          without running the job.
        content:
          application/json:
            schema:
              type: object
              required: [toolType]
              properties:
                toolType:
                  $ref: '#/components/schemas/ExtractionToolType'
                  example: follower_explorer
                targetTweetId:
                  type: string
                  example: '1234567890'
                targetUsername:
                  type: string
                  example: elonmusk
                targetCommunityId:
                  type: string
                  example: '1500000000000000000'
                targetListId:
                  type: string
                  example: '1234567890'
                targetSpaceId:
                  type: string
                  example: '1vOGwMdBqpwGB'
                searchQuery:
                  type: string
                  example: 'AI trends 2025'
                exactPhrase:
                  type: string
                  description: Exact phrase filter for search estimation
                  example: 'artificial intelligence'
                excludeWords:
                  type: string
                  description: Words excluded from estimated search results
                  example: 'spam'
                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
                    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'

  /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'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  /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
          description: Export file format
          schema:
            type: string
            enum: [csv, json, md, md-document, pdf, txt, xlsx]
            default: csv
      responses:
        '200':
          description: Exported file
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  # ── Draws ────────────────────────────────────────────────
  /draws:
    get:
      operationId: listDraws
      summary: List draws
      tags: [Draws]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/After'
      responses:
        '200':
          description: Draw list
          content:
            application/json:
              schema:
                type: object
                required: [draws, hasMore]
                properties:
                  draws:
                    type: array
                    items:
                      $ref: '#/components/schemas/DrawListItem'
                    example: []
                  hasMore:
                    type: boolean
                    example: false
                  nextCursor:
                    type: string
                    example: 'abc123'
              example:
                draws: []
                hasMore: false
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
    post:
      operationId: createDraw
      summary: Run giveaway draw
      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: '42'
                  tweetId:
                    type: string
                    example: '1234567890'
                  totalEntries:
                    type: integer
                    example: 250
                  validEntries:
                    type: integer
                    example: 200
                  winners:
                    type: array
                    items:
                      $ref: '#/components/schemas/Winner'
                    example: []
              example:
                id: '42'
                tweetId: '1234567890'
                totalEntries: 250
                validEntries: 200
                winners: []
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'

  /draws/{id}:
    get:
      operationId: getDraw
      summary: Get draw details
      tags: [Draws]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Draw with winners
          content:
            application/json:
              schema:
                type: object
                required: [draw, winners]
                properties:
                  draw:
                    $ref: '#/components/schemas/DrawDetail'
                    example:
                      id: '42'
                      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: '42'
                  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'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  /draws/{id}/export:
    get:
      operationId: exportDraw
      summary: Export draw data
      tags: [Draws]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
        - name: format
          in: query
          description: Export output format
          schema:
            type: string
            enum: [csv, json, md, md-document, pdf, txt, xlsx]
            default: csv
        - 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
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  # ── Webhooks ─────────────────────────────────────────────
  /webhooks:
    get:
      operationId: listWebhooks
      summary: List webhooks
      tags: [Webhooks]
      security:
        - apiKey: []
        - oauthBearer: []
      responses:
        '200':
          description: Webhook list
          content:
            application/json:
              schema:
                type: object
                required: [webhooks]
                properties:
                  webhooks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
                    example: []
              example:
                webhooks: []
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
    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, follower.gained]
            example:
              url: 'https://example.com/webhook'
              eventTypes: [tweet.new, follower.gained]
      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
                    example: 'whsec_abc123def456'
                  eventTypes:
                    $ref: '#/components/schemas/EventTypeArray'
                    example: [tweet.new, follower.gained]
                  createdAt:
                    type: string
                    format: date-time
                    example: '2025-01-15T12:00:00Z'
              example:
                id: '42'
                url: 'https://example.com/webhook'
                secret: 'whsec_abc123def456'
                eventTypes: [tweet.new, follower.gained]
                createdAt: '2025-01-15T12:00:00Z'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'

        '402':
          $ref: '#/components/responses/PaymentRequired'
  /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
                createdAt: '2025-01-15T12:00:00Z'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteWebhook
      summary: Deactivate webhook
      tags: [Webhooks]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  /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: []
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

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

  # ── Integrations ─────────────────────────────────────────
  /integrations:
    get:
      operationId: listIntegrations
      summary: List integrations
      tags: [Integrations]
      security:
        - apiKey: []
        - oauthBearer: []
      responses:
        '200':
          description: Integration list
          content:
            application/json:
              schema:
                type: object
                required: [integrations]
                properties:
                  integrations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Integration'
                    example: []
              example:
                integrations: []
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
    post:
      operationId: createIntegration
      summary: Create integration
      tags: [Integrations]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description:
          Integration type, display name, platform config, and subscribed event
          types.
        content:
          application/json:
            schema:
              type: object
              required: [type, name, config, eventTypes]
              properties:
                type:
                  type: string
                  enum: [telegram]
                  x-stainless-const: true
                  example: telegram
                name:
                  type: string
                  example: 'My Telegram Bot'
                config:
                  type: object
                  required: [chatId]
                  properties:
                    chatId:
                      type: string
                      example: '-1001234567890'
                  description: Integration config (e.g. Telegram chatId)
                  example:
                    chatId: '-1001234567890'
                eventTypes:
                  $ref: '#/components/schemas/EventTypeArray'
                  example: [tweet.new, follower.gained]
            example:
              type: telegram
              name: 'My Telegram Bot'
              config:
                chatId: '-1001234567890'
              eventTypes: [tweet.new, follower.gained]
      responses:
        '201':
          description: Integration created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Integration'
              example:
                id: '42'
                type: telegram
                name: 'My Telegram Bot'
                config:
                  chatId: '-1001234567890'
                eventTypes: ['tweet.new', 'follower.gained']
                isActive: true
                createdAt: '2025-01-15T12:00:00Z'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'

        '402':
          $ref: '#/components/responses/PaymentRequired'
  /integrations/{id}:
    get:
      operationId: getIntegration
      summary: Get integration details
      tags: [Integrations]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Integration details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Integration'
              example:
                id: '42'
                type: telegram
                name: 'My Telegram Bot'
                config:
                  chatId: '-1001234567890'
                eventTypes: ['tweet.new', 'follower.gained']
                isActive: true
                createdAt: '2025-01-15T12:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateIntegration
      summary: Update integration
      tags: [Integrations]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        description:
          Updated name, event types, active status, or notification settings.
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: 'My Telegram Bot'
                eventTypes:
                  $ref: '#/components/schemas/EventTypeArray'
                  example: [tweet.new]
                isActive:
                  type: boolean
                  example: true
                silentPush:
                  type: boolean
                  example: false
                scopeAllMonitors:
                  type: boolean
                  example: true
                messageTemplate:
                  type: object
                  additionalProperties: true
                  x-stainless-any: true
                  description: Custom message template (JSON)
                  x-stainless-terraform-type: string
                  example: {}
                filters:
                  type: object
                  additionalProperties: true
                  x-stainless-any: true
                  description: Event filter rules (JSON)
                  x-stainless-terraform-type: string
                  example: {}
            example:
              name: 'My Telegram Bot'
              isActive: true
      responses:
        '200':
          description: Integration updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Integration'
              example:
                id: '42'
                type: telegram
                name: 'My Telegram Bot'
                config:
                  chatId: '-1001234567890'
                eventTypes: ['tweet.new', 'follower.gained']
                isActive: true
                createdAt: '2025-01-15T12:00:00Z'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteIntegration
      summary: Delete integration
      tags: [Integrations]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  /integrations/{id}/deliveries:
    get:
      operationId: listIntegrationDeliveries
      summary: List integration delivery history
      tags: [Integrations]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Integration delivery list
          content:
            application/json:
              schema:
                type: object
                required: [deliveries]
                properties:
                  deliveries:
                    type: array
                    items:
                      $ref: '#/components/schemas/IntegrationDelivery'
                    example: []
              example:
                deliveries: []
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  /integrations/{id}/test:
    post:
      operationId: testIntegration
      summary: Send test delivery
      tags: [Integrations]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  # ── X API (reads) ────────────────────────────────────────
  /x/tweets:
    get:
      operationId: getBatchTweets
      summary: Get multiple tweets by IDs
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: ids
          in: query
          required: true
          schema:
            type: string
          description: Comma-separated tweet IDs (max 100)
      responses:
        '200':
          description: List of tweets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
              example:
                tweets:
                  - id: '1234567890'
                    text: 'Just launched our new feature!'
                    createdAt: '2025-01-15T12:00:00Z'
                    likeCount: 42
                    retweetCount: 5
                    replyCount: 3
                    quoteCount: 1
                    viewCount: 1500
                    bookmarkCount: 2
                    author:
                      id: '9876543210'
                      username: 'elonmusk'
                      name: 'Elon Musk'
                      verified: true
                has_next_page: true
                next_cursor: 'DAACCgACGRElMJcAAA'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
    post:
      operationId: createTweet
      summary: Create tweet
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description:
          Account and tweet content. Requires text, media, or both. media and
          media_ids are mutually exclusive.
        content:
          application/json:
            schema:
              type: object
              required: [account]
              properties:
                account:
                  type: string
                  description: X account (@username or account ID)
                  example: '@elonmusk'
                text:
                  type: string
                  description: Tweet text (optional when media is provided)
                  example: 'Just launched our new feature!'
                reply_to_tweet_id:
                  type: string
                  example: '1234567890'
                attachment_url:
                  type: string
                  example: 'https://x.com/elonmusk/status/1234567890'
                community_id:
                  type: string
                  example: '1500000000000000000'
                is_note_tweet:
                  type: boolean
                  example: false
                media:
                  type: array
                  items:
                    type: string
                  maxItems: 4
                  description:
                    Array of media URLs to attach (mutually exclusive with
                    media_ids)
                  example: ['https://example.com/image.jpg']
                media_ids:
                  type: array
                  items:
                    type: string
                  description:
                    Array of media IDs to attach (mutually exclusive with media)
                  example: ['1234567890123456789']
            example:
              account: '@elonmusk'
              text: 'Just launched our new feature!'
      responses:
        '200':
          description: Tweet created
          content:
            application/json:
              schema:
                type: object
                required: [tweetId, success]
                properties:
                  tweetId:
                    type: string
                    example: '1234567890'
                  success:
                    type: boolean
                    const: true
                    example: true
              example:
                tweetId: '1234567890'
                success: true
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          description: Account needs reauth or is restricted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

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

  /x/tweets/search:
    get:
      operationId: searchTweets
      summary: Search tweets with X query operators & pagination
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.03000'
          currency: USD
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Search query (keywords, #hashtags, from:user, "exact phrases", since:YYYY-MM-DD, until:YYYY-MM-DD, min_faves:N)
        - 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).
      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/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'

  /x/articles/{tweetId}:
    get:
      operationId: getArticle
      summary: Get full X Article content with cover image & metadata
      description:
        Retrieve the full content of an X Article (long-form post) by tweet ID.
      tags:
        - Articles
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: charge
              currency: ''
        price:
          mode: fixed
          amount: '0.00105'
          currency: USD
      parameters:
        - name: tweetId
          in: path
          required: true
          schema:
            type: string
          description: Tweet ID of the article
      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'
                      contents:
                        type: array
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              description:
                                'Block type: unstyled, header-one, header-two,
                                header-three, unordered-list-item,
                                ordered-list-item, image, gif, divider'
                              example: 'unstyled'
                            text:
                              type: string
                              example:
                                'This is the first paragraph of the article.'
                            url:
                              type: string
                              description: Media URL for image/gif blocks
                              example: 'https://pbs.twimg.com/media/example.jpg'
                            width:
                              type: integer
                              example: 1200
                            height:
                              type: integer
                              example: 675
                      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/TweetAuthor'
              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: 'unstyled'
                      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'
                  username: 'elonmusk'
                  followers: 150000000
                  verified: true
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'

  /x/tweets/{id}:
    get:
      operationId: lookupTweet
      summary: Get tweet with full text, author, metrics & media
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: charge
              currency: ''
        price:
          mode: fixed
          amount: '0.00015'
          currency: USD
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Tweet ID
      responses:
        '200':
          description: Tweet with author
          content:
            application/json:
              schema:
                type: object
                required: [tweet]
                properties:
                  tweet:
                    $ref: '#/components/schemas/TweetDetail'
                  author:
                    $ref: '#/components/schemas/TweetAuthor'
              example:
                tweet:
                  id: '1234567890'
                  text: 'Just launched our new feature!'
                  createdAt: '2025-01-15T12:00:00Z'
                  retweetCount: 5
                  replyCount: 3
                  likeCount: 42
                  quoteCount: 1
                  viewCount: 1500
                  bookmarkCount: 2
                author:
                  id: '9876543210'
                  username: 'elonmusk'
                  followers: 150000000
                  verified: true
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'
    delete:
      operationId: deleteTweet
      summary: Delete tweet
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Tweet ID to delete
      requestBody:
        required: true
        description: Account that owns the tweet.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XAccountBody'
            example:
              account: '@elonmusk'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/tweets/{id}/like:
    post:
      operationId: likeTweet
      summary: Like tweet
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Tweet ID to like
      requestBody:
        required: true
        description: Account to perform the like.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XAccountBody'
            example:
              account: '@elonmusk'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          description: Account needs reauth or is restricted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'
    delete:
      operationId: unlikeTweet
      summary: Unlike tweet
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Tweet ID to unlike
      requestBody:
        required: true
        description: Account that liked the tweet.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XAccountBody'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          description: Account needs reauth or is restricted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/tweets/{id}/retweet:
    post:
      operationId: retweet
      summary: Retweet
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Tweet ID to retweet
      requestBody:
        required: true
        description: Account to perform the retweet.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XAccountBody'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          description: Account needs reauth or is restricted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'
    delete:
      operationId: unretweet
      summary: Unretweet
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Tweet ID to unretweet
      requestBody:
        required: true
        description: Account that retweeted the tweet.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XAccountBody'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          description: Account needs reauth or is restricted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/users/{id}:
    get:
      operationId: getUser
      summary: Get user profile with follower counts & verification
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: charge
              currency: ''
        price:
          mode: fixed
          amount: '0.00015'
          currency: USD
      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'
        '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'
        '502':
          $ref: '#/components/responses/XApiError'

  /x/users/{id}/follow:
    post:
      operationId: followUser
      summary: Follow user
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: User ID to follow
      requestBody:
        required: true
        description: Account to perform the follow.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XAccountBody'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          description: Account needs reauth or is restricted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'
    delete:
      operationId: unfollowUser
      summary: Unfollow user
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: User ID to unfollow
      requestBody:
        required: true
        description: Account that follows the target user.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XAccountBody'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          description: Account needs reauth or is restricted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/followers/check:
    get:
      operationId: checkFollow
      summary: Check if one user follows another
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: charge
              currency: ''
        price:
          mode: fixed
          amount: '0.00105'
          currency: USD
      parameters:
        - name: source
          in: query
          required: true
          schema:
            type: string
          description: Username to check (without @)
        - name: target
          in: query
          required: true
          schema:
            type: string
          description: Target username (without @)
      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 params
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'missing_params'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'

  /x/dm/{userId}:
    post:
      operationId: sendDm
      summary: Send direct message
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: Recipient user ID
      requestBody:
        required: true
        description:
          Account, message text, and optional media or reply-to parameters.
        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
                  items:
                    type: string
                  example: ['1234567890123456789']
                reply_to_message_id:
                  type: string
                  example: '1234567890123456789'
            example:
              account: '@elonmusk'
              text: 'Example text content'
              media_ids: ['1234567890123456789']
              reply_to_message_id: '1234567890123456789'
      responses:
        '200':
          description: DM sent
          content:
            application/json:
              schema:
                type: object
                required: [messageId, success]
                properties:
                  messageId:
                    type: string
                    example: '1234567890123456789'
                  success:
                    type: boolean
                    const: true
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          description: Account needs reauth or is restricted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/media:
    post:
      operationId: uploadMedia
      summary: Upload media
      tags: [Media]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: Account, media file, and optional long-video flag.
        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
                  example: false
            example:
              account: '@elonmusk'
              file: 'file_value'
              is_long_video: true
      responses:
        '200':
          description: Media uploaded
          content:
            application/json:
              schema:
                type: object
                required: [mediaId, success]
                properties:
                  mediaId:
                    type: string
                    example: '1234567890123456789'
                  success:
                    type: boolean
                    const: true
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          description: Account needs reauth or is restricted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/media/download:
    post:
      operationId: downloadMedia
      summary: Download images & videos from tweets
      tags:
        - Media
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      requestBody:
        required: true
        description:
          Single tweet URL/ID or array of up to 50 tweet URLs/IDs for bulk
          download.
        content:
          application/json:
            schema:
              type: object
              properties:
                tweetInput:
                  type: string
                  description: Tweet URL or ID (single tweet)
                  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)
                  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'

  /x/profile:
    patch:
      operationId: updateProfile
      summary: Update X profile
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description:
          Account and profile fields to update (name, bio, location, website).
        content:
          application/json:
            schema:
              type: object
              required: [account]
              properties:
                account:
                  type: string
                  description: X account (@username or ID) to update profile
                  example: '@elonmusk'
                name:
                  type: string
                  description: Display name
                  example: 'Example Name'
                description:
                  type: string
                  description: Bio description
                  example: 'CEO of Tesla, SpaceX, and X'
                location:
                  type: string
                  example: 'Austin, TX'
                url:
                  type: string
                  description: Website URL
                  example: 'https://x.com'
            example:
              account: '@elonmusk'
              name: 'Example Name'
              description: 'description_value'
              location: 'location_value'
              url: 'https://xquik.com/example'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          description: Account needs reauth or is restricted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/profile/avatar:
    patch:
      operationId: updateAvatar
      summary: Update profile avatar
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: Account and avatar image file (max 716 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 716KB)
                  example: 'binary-content'
            example:
              account: '@elonmusk'
              file: 'file_value'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          description: Account needs reauth or is restricted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/profile/banner:
    patch:
      operationId: updateBanner
      summary: Update profile banner
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: Account and banner image file (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'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          description: Account needs reauth or is restricted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/communities:
    post:
      operationId: createCommunity
      summary: Create community
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: Account, community name, and optional description.
        content:
          application/json:
            schema:
              type: object
              required: [account, name]
              properties:
                account:
                  type: string
                  description:
                    X account (@username or ID) creating the community
                  example: '@elonmusk'
                name:
                  type: string
                  description: Community name
                  example: 'Example Name'
                description:
                  type: string
                  description: Community description
                  example: 'A community for Tesla enthusiasts'
            example:
              account: '@elonmusk'
              name: 'Example Name'
              description: 'A community for Tesla enthusiasts'
      responses:
        '200':
          description: Community created
          content:
            application/json:
              schema:
                type: object
                required: [communityId, success]
                properties:
                  communityId:
                    type: string
                    example: '1500000000000000000'
                  communityName:
                    type: string
                    example: 'Tesla Fans'
                  success:
                    type: boolean
                    const: true
                    example: true
              example:
                communityId: '1500000000000000000'
                communityName: 'Tesla Fans'
                success: true
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          description: Account needs reauth or is restricted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/communities/{id}:
    delete:
      operationId: deleteCommunity
      summary: Delete community
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        description: Account and community name for deletion confirmation.
        content:
          application/json:
            schema:
              type: object
              required: [account, community_name]
              properties:
                account:
                  type: string
                  description:
                    X account (@username or ID) deleting the community
                  example: '@elonmusk'
                community_name:
                  type: string
                  description: Community name for confirmation
                  example: 'Tesla Fans'
            example:
              account: '@elonmusk'
              community_name: 'Tesla Fans'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/WriteError'

  /x/communities/{id}/join:
    post:
      operationId: joinCommunity
      summary: Join community
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        description: Account to join the community.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XAccountBody'
      responses:
        '200':
          description: Joined community
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunityActionResult'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          description: Account needs reauth or is restricted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'
    delete:
      operationId: leaveCommunity
      summary: Leave community
      tags: [X Write]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        description: Account to leave the community.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XAccountBody'
      responses:
        '200':
          description: Left community
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunityActionResult'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          description: Account needs reauth or is restricted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/WriteRejected'
        '429':
          $ref: '#/components/responses/RateLimitedByX'
        '503':
          $ref: '#/components/responses/TransientError'
        '500':
          $ref: '#/components/responses/WriteError'

  # ── X Accounts ───────────────────────────────────────────
  /x/accounts:
    get:
      operationId: listXAccounts
      summary: List connected X accounts
      tags: [X Accounts]
      security:
        - apiKey: []
        - oauthBearer: []
      responses:
        '200':
          description: X account list
          content:
            application/json:
              schema:
                type: object
                required: [accounts]
                properties:
                  accounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/XAccount'
                    example:
                      - id: '42'
                        xUserId: '9876543210'
                        xUsername: 'elonmusk'
                        status: 'active'
                        createdAt: '2025-01-15T12:00:00Z'
              example:
                accounts:
                  - id: '42'
                    xUserId: '9876543210'
                    xUsername: 'elonmusk'
                    status: 'active'
                    createdAt: '2025-01-15T12:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
    post:
      operationId: connectXAccount
      summary: Connect X account
      tags: [X Accounts]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description:
          X credentials (username, email, password) and optional 2FA secret and
          proxy country.
        content:
          application/json:
            schema:
              type: object
              required: [username, email, password]
              properties:
                username:
                  type: string
                  description: X username
                  example: 'elonmusk'
                email:
                  type: string
                  description: Account email
                  example: 'user@example.com'
                password:
                  type: string
                  description: Account password
                  example: 's3cur3Pa$$w0rd'
                totp_secret:
                  type: string
                  description: TOTP secret for 2FA
                  example: 'JBSWY3DPEHPK3PXP'
                proxy_country:
                  type: string
                  description: Proxy country code
                  example: 'US'
            example:
              username: 'elonmusk'
              email: 'user@example.com'
              password: 's3cur3Pa$$w0rd'
      responses:
        '201':
          description: X account connected
          content:
            application/json:
              schema:
                type: object
                required: [id, xUserId, xUsername, status]
                properties:
                  id:
                    type: string
                    example: '42'
                  xUserId:
                    type: string
                    example: '9876543210'
                  xUsername:
                    type: string
                    example: 'elonmusk'
                  status:
                    type: string
                    example: 'active'
              example:
                id: '42'
                xUserId: '9876543210'
                xUsername: 'elonmusk'
                status: 'active'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'

  /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'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: disconnectXAccount
      summary: Disconnect X account
      tags: [X Accounts]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  /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: 's3cur3Pa$$w0rd'
                totp_secret:
                  type: string
                  description: TOTP secret for 2FA re-authentication
                  example: 'JBSWY3DPEHPK3PXP'
                email:
                  type: string
                  description: Email for the X account (updates stored email)
                  example: 'user@example.com'
                proxy_country:
                  type: string
                  description: Two-letter country code for login proxy region
                  example: 'US'
            example:
              password: 'password_value'
              totp_secret: 'totp_secret_value'
      responses:
        '200':
          description: Re-authenticated
          content:
            application/json:
              schema:
                type: object
                required: [id, xUsername, status]
                properties:
                  id:
                    type: string
                    example: '42'
                  xUsername:
                    type: string
                    example: 'elonmusk'
                  status:
                    type: string
                    example: 'active'
              example:
                id: '42'
                xUsername: 'elonmusk'
                status: 'active'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/XApiError'

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

        # ── Trends ───────────────────────────────────────────────
        '402':
          $ref: '#/components/responses/PaymentRequired'
  /trends:
    get:
      operationId: getTrends
      summary: Get trending hashtags & topics by region (alias)
      tags:
        - Trends
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: charge
              currency: ''
        price:
          mode: fixed
          amount: '0.00045'
          currency: USD
      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: Trending topics
          content:
            application/json:
              schema:
                type: object
                required: [trends, total, woeid]
                properties:
                  trends:
                    type: array
                    items:
                      type: object
                      required: [name]
                      properties:
                        name:
                          type: string
                          example: '#AI'
                        description:
                          type: string
                          example: 'Artificial intelligence discussions'
                        query:
                          type: string
                          example: '%23AI'
                        rank:
                          type: integer
                          example: 1
                    example:
                      - name: '#AI'
                        rank: 1
                  total:
                    type: integer
                    example: 30
                  woeid:
                    type: integer
                    example: 1
              example:
                trends:
                  - name: '#AI'
                    description: 'Artificial intelligence discussions'
                    query: '%23AI'
                    rank: 1
                total: 30
                woeid: 1
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'

  # ── Bot ──────────────────────────────────────────────────
  /bot/platform-links:
    post:
      operationId: createPlatformLink
      summary: Link a platform user to an Xquik account
      tags: [Bot]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: Platform type and platform-specific user identifier.
        content:
          application/json:
            schema:
              type: object
              required: [platform, platformUserId]
              properties:
                platform:
                  type: string
                  enum: [telegram]
                  example: 'telegram'
                platformUserId:
                  type: string
                  example: '123456789'
            example:
              platform: 'telegram'
              platformUserId: '123456789'
      responses:
        '201':
          description: Platform link created
          content:
            application/json:
              schema:
                type: object
                required: [id, platform, platformUserId, createdAt]
                properties:
                  id:
                    type: string
                    example: '42'
                  platform:
                    type: string
                    example: 'telegram'
                  platformUserId:
                    type: string
                    example: '123456789'
                  createdAt:
                    type: string
                    format: date-time
                    example: '2025-01-15T12:00:00Z'
              example:
                id: '42'
                platform: 'telegram'
                platformUserId: '123456789'
                createdAt: '2025-01-15T12:00:00Z'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '409':
          description: Platform link already exists
    delete:
      operationId: deletePlatformLink
      summary: Unlink a platform user from an Xquik account
      tags: [Bot]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description:
          Platform type and platform-specific user identifier to unlink.
        content:
          application/json:
            schema:
              type: object
              required: [platform, platformUserId]
              properties:
                platform:
                  type: string
                  enum: [telegram]
                  example: 'telegram'
                platformUserId:
                  type: string
                  example: '123456789'
            example:
              platform: 'telegram'
              platformUserId: '123456789'
      responses:
        '200':
          description: Platform link deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
              example:
                success: true
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  /bot/platform-links/lookup:
    get:
      operationId: lookupPlatformLink
      summary: Look up an Xquik user by platform identity
      tags: [Bot]
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: platform
          in: query
          required: true
          description: Platform identifier (e.g. telegram)
          schema:
            type: string
        - name: platformUserId
          in: query
          required: true
          description: User ID on the specified platform
          schema:
            type: string
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                type: object
                required: [userId]
                properties:
                  userId:
                    type: string
                    example: '42'
              example:
                userId: '42'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  /bot/usage:
    post:
      operationId: trackBotUsage
      summary: Track bot token usage
      tags: [Bot]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description:
          Platform user ID and token counts for the conversation turn.
        content:
          application/json:
            schema:
              type: object
              required: [platformUserId, inputTokens, outputTokens]
              properties:
                platformUserId:
                  type: string
                  example: '123456789'
                inputTokens:
                  type: integer
                  example: 1500
                outputTokens:
                  type: integer
                  example: 800
            example:
              platformUserId: '123456789'
              inputTokens: 1500
              outputTokens: 800
      responses:
        '200':
          description: Usage tracked
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
              example:
                success: true
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'

        # ── Support Tickets ─────────────────────────────────────
        '402':
          $ref: '#/components/responses/PaymentRequired'
  /support/tickets:
    post:
      operationId: createTicket
      summary: Create a support ticket
      tags: [Support]
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: Ticket subject and message body.
        content:
          application/json:
            schema:
              type: object
              required: [subject, body]
              properties:
                subject:
                  type: string
                  maxLength: 500
                  example: 'Cannot connect X account'
                body:
                  type: string
                  maxLength: 10000
                  title: TicketContent
                  example: 'I am unable to connect my X account. Please help.'
            example:
              subject: 'Cannot connect X account'
              body: 'I am unable to connect my X account. Please help.'
      responses:
        '201':
          description: Ticket created
          content:
            application/json:
              schema:
                type: object
                properties:
                  publicId:
                    type: string
                    example: 'tk_abc123'
              example:
                publicId: 'tk_abc123'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
    get:
      operationId: listTickets
      summary: List user's support tickets
      tags: [Support]
      security:
        - apiKey: []
        - oauthBearer: []
      responses:
        '200':
          description: List of tickets
          content:
            application/json:
              schema:
                type: object
                properties:
                  tickets:
                    type: array
                    items:
                      type: object
                      properties:
                        publicId:
                          type: string
                          example: 'tk_abc123'
                        subject:
                          type: string
                          example: 'Cannot connect X account'
                        status:
                          type: string
                          example: 'open'
                        messageCount:
                          type: integer
                          example: 2
                        createdAt:
                          type: string
                          format: date-time
                          example: '2025-01-15T12:00:00Z'
                        updatedAt:
                          type: string
                          format: date-time
                          example: '2025-01-16T09:30:00Z'
                    example:
                      - publicId: 'tk_abc123'
                        subject: 'Cannot connect X account'
                        status: 'open'
              example:
                tickets:
                  - publicId: 'tk_abc123'
                    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'

        '402':
          $ref: '#/components/responses/PaymentRequired'
  /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 ID
          example: 'messages_value'
      responses:
        '200':
          description: Ticket detail
          content:
            application/json:
              schema:
                type: object
                properties:
                  publicId:
                    type: string
                    example: 'tk_abc123'
                  subject:
                    type: string
                    example: 'Cannot connect X account'
                  status:
                    type: string
                    example: 'open'
                  createdAt:
                    type: string
                    format: date-time
                    example: '2025-01-15T12:00:00Z'
                  updatedAt:
                    type: string
                    format: date-time
                    example: '2025-01-16T09:30:00Z'
                  messages:
                    type: array
                    items:
                      type: object
                      properties:
                        body:
                          type: string
                          example: 'I am unable to connect my X account.'
                        sender:
                          type: string
                          example: 'user'
                        createdAt:
                          type: string
                          format: date-time
                          example: '2025-01-15T12:00:00Z'
                    example:
                      - body: 'I am unable to connect my X account.'
                        sender: 'user'
                        createdAt: '2025-01-15T12:00:00Z'
              example:
                publicId: 'tk_abc123'
                subject: 'Cannot connect X account'
                status: 'open'
                messages:
                  - body: 'I am unable to connect my X account.'
                    sender: 'user'
                    createdAt: '2025-01-15T12:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
    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 ID to update
      requestBody:
        required: true
        description: New ticket status (open, resolved, or closed).
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status:
                  type: string
                  enum: [open, resolved, closed]
                  example: 'resolved'
            example:
              status: 'resolved'
      responses:
        '200':
          description: Status updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  publicId:
                    type: string
                    example: 'tk_abc123'
                  status:
                    type: string
                    example: 'resolved'
              example:
                publicId: 'tk_abc123'
                status: 'resolved'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'

        '402':
          $ref: '#/components/responses/PaymentRequired'
  /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 ID for the reply
      requestBody:
        required: true
        description: Reply message body (max 10,000 characters).
        content:
          application/json:
            schema:
              type: object
              required: [body]
              properties:
                body:
                  type: string
                  maxLength: 10000
                  title: MessageContent
                  example: 'Thank you for the update.'
            example:
              body: 'Thank you for the update.'
      responses:
        '201':
          description: Message added
          content:
            application/json:
              schema:
                type: object
                properties:
                  publicId:
                    type: string
                    example: 'tk_abc123'
              example:
                publicId: 'tk_abc123'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  /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_enabled,
                    balance,
                    lifetime_purchased,
                    lifetime_used,
                  ]
                properties:
                  auto_topup_enabled:
                    type: boolean
                    example: false
                  balance:
                    type: integer
                    example: 50000
                  lifetime_purchased:
                    type: integer
                    example: 200000
                  lifetime_used:
                    type: integer
                    example: 150000
              example:
                auto_topup_enabled: false
                balance: 50000
                lifetime_purchased: 200000
                lifetime_used: 150000
        '401':
          $ref: '#/components/responses/Unauthenticated'

        '402':
          $ref: '#/components/responses/PaymentRequired'
  /credits/topup:
    post:
      operationId: topUpCredits
      summary: Top up credits balance
      tags:
        - Subscribe
      security:
        - apiKey: []
        - oauthBearer: []
      requestBody:
        required: true
        description: Credit amount to add to the account balance.
        content:
          application/json:
            schema:
              type: object
              required: [amount]
              properties:
                amount:
                  type: integer
                  description: Amount to top up in credits
                  example: 10000
            example:
              amount: 10000
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'

        '402':
          $ref: '#/components/responses/PaymentRequired'
  /credits/quick-topup:
    post:
      operationId: quickTopUpCredits
      summary: Instantly charge saved card for credits
      tags:
        - Subscribe
      security:
        - apiKey: []
        - oauthBearer: []
      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 ($10 minimum, $500 maximum)
                  minimum: 10
                  maximum: 500
                  example: 25
            example:
              dollars: 25
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
  /x/tweets/{id}/favoriters:
    get:
      operationId: getTweetFavoriters
      summary: List users who liked a tweet
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      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
      responses:
        '200':
          description: List of users who liked the tweet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'

  /x/users/{id}/tweets:
    get:
      operationId: getUserTweets
      summary: List recent tweets posted by a user
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      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
        - 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
      responses:
        '200':
          description: User tweets list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  /x/users/{id}/likes:
    get:
      operationId: getUserLikes
      summary: List tweets liked by a user
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: User ID
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for liked tweets
      responses:
        '200':
          description: List of liked tweets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/XApiError'

  /x/users/{id}/media:
    get:
      operationId: getUserMedia
      summary: List media tweets posted by a user
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: User ID for media lookup
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for media tweets
      responses:
        '200':
          description: List of media tweets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/XApiError'

  /x/users/{id}/followers-you-know:
    get:
      operationId: getFollowersYouKnow
      summary: List mutual followers between you and a user
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      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
      responses:
        '200':
          description: List of mutual followers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'

  /x/bookmarks:
    get:
      operationId: getBookmarks
      summary: Get bookmarked tweets
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: folderId
          in: query
          schema:
            type: string
          description: Optional bookmark folder ID
        - name: cursor
          in: query
          schema:
            type: string
            example: 'folders_value'
          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'
        '502':
          $ref: '#/components/responses/XApiError'

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

  /x/notifications:
    get:
      operationId: getNotifications
      summary: Get notifications
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum: [All, Verified, Mentions]
            default: All
          description: Notification type filter
        - 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'
                  has_next_page:
                    type: boolean
                    example: true
                  next_cursor:
                    type: string
                    example: 'DAACCgACGRElMJcAAA'
              example:
                notifications:
                  - id: '1234567890'
                    type: 'like'
                    message: 'elonmusk liked your tweet'
                has_next_page: true
                next_cursor: 'DAACCgACGRElMJcAAA'
                message: 'message_value'
                timestamp: 'timestamp_value'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'

  /x/timeline:
    get:
      operationId: getTimeline
      summary: Get home timeline
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: seenTweetIds
          in: query
          schema:
            type: string
          description: Comma-separated tweet IDs to exclude from results
        - 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'
        '502':
          $ref: '#/components/responses/XApiError'

  /x/dm/{userId}/history:
    get:
      operationId: getDmHistory
      summary: Get DM conversation history
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: Target user ID
        - name: 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]
                      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'
                    example:
                      - id: '1234567890123456789'
                        text: 'Hey, how are you?'
                        senderId: '9876543210'
                  has_next_page:
                    type: boolean
                    example: true
                  next_cursor:
                    type: string
                    example: 'DAACCgACGRElMJcAAA'
              example:
                messages:
                  - id: '1234567890123456789'
                    text: 'Hey, how are you?'
                    senderId: '9876543210'
                has_next_page: true
                next_cursor: 'DAACCgACGRElMJcAAA'
                senderId: '42'
                receiverId: '42'
                createdAt: 'createdAt_value'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/XApiError'

  /x/communities/{id}/info:
    get:
      operationId: getCommunityInfo
      summary: Get community name, description & member count
      tags:
        - Communities
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: charge
              currency: ''
        price:
          mode: fixed
          amount: '0.00015'
          currency: USD
      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)
                      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
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /x/communities/{id}/members:
    get:
      operationId: getCommunityMembers
      summary: List members of a community
      tags:
        - Communities
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      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
      responses:
        '200':
          description: List of community members
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /x/communities/{id}/moderators:
    get:
      operationId: getCommunityModerators
      summary: List moderators of a community
      tags:
        - Communities
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      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'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /x/communities/{id}/tweets:
    get:
      operationId: getCommunityTweets
      summary: List tweets posted in a community
      tags:
        - Communities
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      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
      responses:
        '200':
          description: List of community tweets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /x/communities/search:
    get:
      operationId: searchCommunities
      summary: Search for communities by keyword
      tags:
        - Communities
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Search query
        - name: queryType
          in: query
          schema:
            type: string
          description: Sort order (Latest or Top)
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for community search
      responses:
        '200':
          description: Community search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /x/communities/tweets:
    get:
      operationId: getAllCommunityTweets
      summary: List tweets across all communities
      tags:
        - Communities
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Search query for cross-community tweets
        - name: queryType
          in: query
          schema:
            type: string
          description: Sort order for cross-community results (Latest or Top)
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for cross-community results
      responses:
        '200':
          description: Paginated list of tweets from all communities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '400':
          description: Missing query parameter
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /x/lists/{id}/followers:
    get:
      operationId: getListFollowers
      summary: List followers of an X List
      tags:
        - Lists
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      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
      responses:
        '200':
          description: List of followers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /x/lists/{id}/members:
    get:
      operationId: getListMembers
      summary: List members of an X List
      tags:
        - Lists
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      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
      responses:
        '200':
          description: List of members
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /x/lists/{id}/tweets:
    get:
      operationId: getListTweets
      summary: List tweets from an X List
      tags:
        - Lists
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      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
        - 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'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /x/tweets/{id}/quotes:
    get:
      operationId: getTweetQuotes
      summary: List quote tweets of a tweet
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Tweet ID to get quotes
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for quote tweets
        - 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)
      responses:
        '200':
          description: List of quote tweets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /x/tweets/{id}/replies:
    get:
      operationId: getTweetReplies
      summary: List replies to a tweet
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      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: 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
      responses:
        '200':
          description: List of replies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /x/tweets/{id}/retweeters:
    get:
      operationId: getTweetRetweeters
      summary: List users who retweeted a tweet
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      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
      responses:
        '200':
          description: List of retweeters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /x/tweets/{id}/thread:
    get:
      operationId: getTweetThread
      summary: Get full conversation thread for a tweet
      tags:
        - Tweets
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      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
      responses:
        '200':
          description: Thread tweets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /x/users/batch:
    get:
      operationId: getBatchUsers
      summary: Look up multiple users by IDs in one call
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      parameters:
        - name: ids
          in: query
          required: true
          schema:
            type: string
          description: Comma-separated user IDs (max 100)
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /x/users/search:
    get:
      operationId: searchUsers
      summary: Search users by name or username
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      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'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /x/users/{id}/followers:
    get:
      operationId: getUserFollowers
      summary: List followers of a user
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: User ID or username
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor for followers list
        - name: pageSize
          in: query
          schema:
            type: integer
          description: Items per page (20-200, default 200)
      responses:
        '200':
          description: List of user followers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  /x/users/{id}/following:
    get:
      operationId: getUserFollowing
      summary: List accounts a user follows
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      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: pageSize
          in: query
          schema:
            type: integer
          description: Results per page (20-200, default 200)
      responses:
        '200':
          description: List of following
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  /x/users/{id}/mentions:
    get:
      operationId: getUserMentions
      summary: List tweets mentioning a user
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      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
        - 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
      responses:
        '200':
          description: List of mentions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTweets'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

  /x/users/{id}/verified-followers:
    get:
      operationId: getUserVerifiedFollowers
      summary: List verified followers of a user
      tags:
        - Users
      security:
        - apiKey: []
        - oauthBearer: []
        - {}
      x-payment-info:
        protocols:
          - x402: {}
          - mpp:
              method: ''
              intent: session
              currency: ''
        price:
          mode: dynamic
          min: '0.00015'
          max: '0.01500'
          currency: USD
      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
      responses:
        '200':
          description: List of verified followers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key passed via the X-Api-Key header
    oauthBearer:
      type: http
      scheme: bearer
      description: OAuth 2.1 access token

  parameters:
    ResourceId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Resource ID (stringified bigint)
    Limit:
      name: limit
      in: query
      description: Maximum number of items to return (1-100, default 50)
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    After:
      name: after
      in: query
      schema:
        type: string
      description: Cursor for keyset pagination
    StyleId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Style profile ID or X username

  responses:
    Success:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required: [success]
            properties:
              success:
                type: boolean
                const: true
                example: true
          example:
            success: true
    NoContent:
      description: Deleted
    Unauthenticated:
      description: Unauthenticated
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidInput:
      description: Invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description:
        Payment required. Returns a WWW-Authenticate header with an MPP
        challenge for pay-per-use endpoints, or indicates a subscription/credit
        issue for identity-authenticated endpoints.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    WriteError:
      description: >
        Write operation failed. Possible error codes include x_write_failed,
        x_write_ambiguous, x_duplicate_action, x_daily_limit (429 - account
        reached daily posting limit, wait 24 hours), and x_write_unconfirmed
        (202 - action may have completed but could not be confirmed, verify
        before retrying).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    AccountNeedsReauth:
      description: >
        The connected X account failed a recent login attempt and needs to be
        reconnected. Returns `{ "error": "account_needs_reauth" }`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    AccountRestricted:
      description: >
        The connected X account is locked, suspended, recovering, or
        temporarily restricted. Returns `{ "error": "account_restricted" }`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    WriteRejected:
      description: >
        X rejected the write. Possible codes: `x_content_too_long`,
        `x_duplicate_action`, `x_account_suspended`, `x_account_protected`,
        `x_target_not_found`, `x_account_feature_required`, `x_rejected`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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'
    TransientError:
      description: >
        A transient upstream issue occurred. Safe to retry with exponential
        backoff. Returns `{ "error": "x_transient_error" }`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    XApiError:
      description: X API unavailable, unauthorized, or rate limited
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    PaginatedTweets:
      description: Paginated list of tweets with cursor-based navigation.
      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!'
        has_next_page:
          type: boolean
          example: true
        next_cursor:
          type: string
          example: 'DAACCgACGRElMJcAAA'
    PaginatedUsers:
      description: Paginated list of user profiles with cursor-based navigation.
      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'
    Error:
      description: Error response containing a machine-readable error code.
      type: object
      required: [error]
      properties:
        error:
          type: string
          title: ErrorCode
          enum:
            - internal_error
            - invalid_format
            - invalid_id
            - invalid_input
            - invalid_params
            - invalid_tool_type
            - invalid_tweet_id
            - invalid_tweet_url
            - invalid_username
            - insufficient_credits
            - missing_params
            - missing_query
            - monitor_already_exists
            - monitor_limit_reached
            - no_credits
            - no_subscription
            - not_found
            - stream_registration_failed
            - subscription_inactive
            - tweet_not_found
            - unauthenticated
            - user_not_found
            - webhook_inactive
            - x_api_rate_limited
            - x_api_unavailable
            - x_api_unauthorized

          example: 'invalid_input'
    EventType:
      description: Type of monitor event fired when account activity occurs.
      type: string
      enum:
        - tweet.new
        - tweet.reply
        - tweet.retweet
        - tweet.quote
        - follower.gained
        - follower.lost
      example: 'tweet.new'

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

    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
        - 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
        - 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]
      properties:
        id:
          type: string
          example: '42'
        username:
          type: string
          example: 'elonmusk'
        xUserId:
          type: string
          example: '9876543210'
        eventTypes:
          $ref: '#/components/schemas/EventTypeArray'
          example: ['tweet.new', 'follower.gained']
        isActive:
          type: boolean
          example: true
        createdAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'

    Event:
      description:
        Monitor event summary with type, username, and occurrence time.
      type: object
      required: [id, type, username, monitorId, occurredAt, data]
      properties:
        id:
          type: string
        type:
          $ref: '#/components/schemas/EventType'
        username:
          type: string
        monitorId:
          type: string
        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, username, monitorId, occurredAt, data]
      properties:
        id:
          type: string
          example: '42'
        type:
          $ref: '#/components/schemas/EventType'
          example: 'tweet.new'
        username:
          type: string
          example: 'elonmusk'
        monitorId:
          type: string
          example: '10'
        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
        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
          example: 'https://example.com/webhook'
        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, 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', 'follower.gained']
        isActive:
          type: boolean
          example: true
        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

    TweetDetail:
      description:
        Full tweet with text, engagement metrics, media, and metadata.
      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
        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'
        entities:
          type: object
          additionalProperties: true
          description:
            Parsed entities from the tweet text (URLs, mentions, hashtags,
            media)
        quoted_tweet:
          type: object
          additionalProperties: true
          description:
            The quoted tweet object, present when isQuoteStatus is true
        media:
          type: array
          items:
            type: object
            properties:
              mediaUrl:
                type: string
                example: 'https://pbs.twimg.com/media/example.jpg'
              type:
                type: string
                enum: [photo, video, animated_gif]
                example: 'photo'
              url:
                type: string
                example: 'https://t.co/abc123'
          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:
        Author of a tweet with follower count and verification status.
      type: object
      required: [id, username, followers, verified]
      properties:
        id:
          type: string
          example: '9876543210'
        username:
          type: string
          example: 'elonmusk'
        followers:
          type: integer
          example: 150000000
        verified:
          type: boolean
          example: true
        profilePicture:
          type: string
          example: 'https://pbs.twimg.com/profile_images/example.jpg'

    SearchTweet:
      description: Tweet returned from search results with inline author info.
      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'
        isNoteTweet:
          type: boolean
          description:
            True for Note Tweets (long-form content, up to 25,000 characters)
          example: false
        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:
          type: object
          required: [id, username, name]
          properties:
            id:
              type: string
              example: '9876543210'
            username:
              type: string
              example: 'elonmusk'
            name:
              type: string
              example: 'Elon Musk'
            verified:
              type: boolean
              example: true

    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
        profilePicture:
          type: string
          example: 'https://pbs.twimg.com/profile_images/example.jpg'
        location:
          type: string
          example: 'Austin, TX'
        createdAt:
          type: string
          example: '2009-06-02T20:12:29Z'
        statusesCount:
          type: integer
          example: 35000

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

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

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

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

    RadarItem:
      description: Trending topic with score, category, source, and region.
      type: object
      required: [title, score, category, source, region, publishedAt]
      properties:
        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
          example: 'Technology'
        source:
          type: string
          example: 'X'
        region:
          type: string
          example: 'US'
        publishedAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'
        description:
          type: string
          example: 'AI is transforming every industry'
        imageUrl:
          type: string
          example: 'https://example.com/images/ai.jpg'

    Integration:
      description:
        Third-party integration (e.g. Telegram) subscribed to monitor events.
      type: object
      required: [id, type, name, config, eventTypes, isActive, createdAt]
      properties:
        id:
          type: string
          example: '42'
        type:
          type: string
          enum: [telegram]
          x-stainless-const: true
          example: 'telegram'
        name:
          type: string
          example: 'My Telegram Bot'
        config:
          type: object
          additionalProperties: true
          x-stainless-any: true
          description: Integration config — shape varies by type (JSON)
          x-stainless-terraform-type: string
          example:
            chatId: '-1001234567890'
        eventTypes:
          $ref: '#/components/schemas/EventTypeArray'
          example: ['tweet.new', 'follower.gained']
        isActive:
          type: boolean
          example: true
        silentPush:
          type: boolean
          example: false
        scopeAllMonitors:
          type: boolean
          example: true
        messageTemplate:
          type: string
          example: 'New event: {{event.type}}'
        filters:
          type: object
          additionalProperties: true
          x-stainless-any: true
          description: Event filter rules (JSON)
          x-stainless-terraform-type: string
          example:
            minFollowers: 100
        createdAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'

    IntegrationDelivery:
      description:
        Integration delivery attempt record with status and retry count.
      type: object
      required: [id, eventType, status, attempts, createdAt]
      properties:
        id:
          type: string
          example: '42'
        eventType:
          type: string
          example: 'tweet.new'
        status:
          type: string
          example: 'delivered'
        attempts:
          type: integer
          example: 1
        createdAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'
        deliveredAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:01Z'
        lastError:
          type: string
          example: ''
        lastStatusCode:
          type: integer
          example: 200
        sourceId:
          type: string
          example: '100'
        sourceType:
          type: string
          example: 'monitor'

    XAccount:
      description: Linked X account summary with username and connection status.
      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
          description: >
            Derived login/cookie health. `healthy` = cookies valid.
            `needsReauth` = user must submit fresh credentials. `locked` = X
            locked the account; unlock on x.com first. `suspended` = X banned
            the account. `recovering` = past cooldown, will auto-retry on next
            use. `temporaryIssue` = transient backend problem; retry shortly.
          enum:
            [
              healthy,
              locked,
              needsReauth,
              recovering,
              suspended,
              temporaryIssue,
            ]
          example: 'healthy'
        createdAt:
          type: string
          format: date-time
          example: '2025-01-15T12:00:00Z'

    XAccountDetail:
      description:
        Full X account details including proxy, cookies, and update timestamp.
      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'
        proxyCountry:
          type: string
          example: 'US'
        cookiesObtainedAt:
          type: string
          format: date-time
          example: '2025-03-10T08:30: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'

    CommunityActionResult:
      description: Result of a community join or leave action.
      type: object
      required: [communityId, communityName, success]
      properties:
        communityId:
          type: string
          example: '1500000000000000000'
        communityName:
          type: string
          example: 'Tesla Fans'
        success:
          type: boolean
          const: true
          example: true