X Bots API

openapi: 3.2.0
info:
  description: X API v2 core endpoints
  version: '2.168'
  title: X API v2 Bots API
  termsOfService: https://developer.x.com/en/developer-terms/agreement-and-policy.html
  contact:
    name: X Developers
    url: https://developer.x.com/
  license:
    name: X Developer Agreement and Policy
    url: https://developer.x.com/en/developer-terms/agreement-and-policy.html
servers:
- description: X API
  url: https://api.x.com
tags:
- name: Bots
paths:
  /2/bots:
    get:
      security:
      - BearerToken: []
      tags:
      - Bots
      summary: Get Bots
      operationId: getBots
      parameters:
      - $ref: '#/components/parameters/UserFieldsParameter'
      - $ref: '#/components/parameters/UserExpansionsParameter'
      - $ref: '#/components/parameters/PostFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBotsResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    post:
      security:
      - BearerToken: []
      tags:
      - Bots
      summary: Create a bot
      description: 'Creates a bot account in the calling app''s project and returns its bearer token. Idempotent on handle: repeating the request for a handle that already names one of the project''s bots returns that bot with a freshly minted token, revoking the previous one — safe to retry when a response was lost, since the replaced token was never seen.'
      operationId: createBot
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBotRequest'
        required: true
      responses:
        '201':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateBotResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/bots/{id}:
    delete:
      security:
      - BearerToken: []
      tags:
      - Bots
      summary: Delete Bot
      operationId: deleteBot
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[0-9]{1,19}$
        style: simple
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteBotResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    put:
      security:
      - BearerToken: []
      tags:
      - Bots
      summary: Update Bot
      operationId: updateBot
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[0-9]{1,19}$
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBotRequest'
        required: true
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateBotResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/bots/{id}/token:
    delete:
      security:
      - BearerToken: []
      tags:
      - Bots
      summary: Revoke Bot Token
      operationId: revokeBotToken
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[0-9]{1,19}$
        style: simple
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokeBotTokenResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    post:
      security:
      - BearerToken: []
      tags:
      - Bots
      summary: Rotate Bot Token
      operationId: rotateBotToken
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[0-9]{1,19}$
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RotateBotTokenRequest'
        required: true
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RotateBotTokenResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    PostPublicMetrics:
      type: object
      description: Engagement metrics for the Post at the time of the request.
      required:
      - repost_count
      - reply_count
      - like_count
      - quote_count
      - bookmark_count
      - impression_count
      properties:
        bookmark_count:
          type: integer
          description: Number of times this Post has been bookmarked.
          format: int64
        impression_count:
          type: integer
          description: Number of times this Post has been viewed.
          format: int64
        like_count:
          type: integer
          description: Number of likes on this Post.
          format: int64
        quote_count:
          type: integer
          description: Number of quote Posts of this Post.
          format: int64
        reply_count:
          type: integer
          description: Number of replies to this Post.
          format: int64
        repost_count:
          type: integer
          description: Number of times this Post has been reposted.
          format: int64
    PostDisplayTextRange:
      type: array
      description: The inclusive start and exclusive end indices of the displayable content of the Post.
      minItems: 2
      maxItems: 2
      items:
        type: integer
        format: int64
    Expansions:
      type: object
      properties:
        media:
          type: array
          items:
            $ref: '#/components/schemas/Media'
        places:
          type: array
          items:
            $ref: '#/components/schemas/Place'
        polls:
          type: array
          items:
            $ref: '#/components/schemas/Poll'
        posts:
          type: array
          items:
            $ref: '#/components/schemas/Post'
        topics:
          type: array
          items:
            $ref: '#/components/schemas/Topic'
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'
    Media:
      type: object
      properties:
        alt_text:
          type: string
        duration_ms:
          type: integer
        height:
          type: integer
        media_key:
          type: string
        non_public_metrics:
          $ref: '#/components/schemas/MediaNonPublicMetrics'
        organic_metrics:
          $ref: '#/components/schemas/MediaOrganicMetrics'
        preview_image_url:
          type: string
        promoted_metrics:
          $ref: '#/components/schemas/MediaPromotedMetrics'
        public_metrics:
          $ref: '#/components/schemas/MediaPublicMetrics'
        type:
          type: string
        url:
          type: string
        variants:
          $ref: '#/components/schemas/MediaVariants'
        width:
          type: integer
    CreateBotResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CreateBotResponseData'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Problem'
    PostGeo:
      type: object
      description: The location tagged on the Post, if the user provided one.
      properties:
        coordinates:
          type:
          - object
          - 'null'
          description: A GeoJSON Point geometry.
          required:
          - type
          - coordinates
          properties:
            coordinates:
              type: array
              description: '[longitude, latitude].'
              minItems: 2
              maxItems: 2
              items:
                type: number
                format: double
            type:
              type: string
              description: The GeoJSON geometry type.
              enum:
              - Point
        place_id:
          type:
          - string
          - 'null'
          description: The unique identifier of the tagged place.
    FieldHydrationFailureProblem:
      type: object
      required:
      - type
      - title
      - detail
      - field
      properties:
        detail:
          type: string
        field:
          type: string
        resource_type:
          type: string
        section:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          type: string
          enum:
          - https://api.x.com/2/problems/field-hydration-failure
    PostSuggestedSourceLinks:
      type: array
      description: URLs suggested as sources for this Post.
      items:
        type: string
    NotAuthorizedForResourceProblem:
      type: object
      required:
      - type
      - title
      - detail
      - resource_type
      properties:
        detail:
          type: string
        parameter:
          type: string
        resource_id:
          type: string
        resource_type:
          type: string
        section:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          type: string
          enum:
          - https://api.x.com/2/problems/not-authorized-for-resource
        value:
          type: string
    RevokeBotTokenResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/RevokeBotTokenResponseData'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Problem'
    PostEntities:
      type: object
      description: A list of metadata entities (hashtags, mentions, URLs) found in the Post text.
      properties:
        cashtags:
          type:
          - array
          - 'null'
          items:
            type: object
            description: A hashtag or cashtag entity.
            required:
            - start
            - end
            - tag
            properties:
              end:
                type: integer
                description: End index in the text (exclusive).
                format: int64
              start:
                type: integer
                description: Start index in the text (inclusive).
                format: int64
              tag:
                type: string
        hashtags:
          type:
          - array
          - 'null'
          items:
            type: object
            description: A hashtag or cashtag entity.
            required:
            - start
            - end
            - tag
            properties:
              end:
                type: integer
                description: End index in the text (exclusive).
                format: int64
              start:
                type: integer
                description: Start index in the text (inclusive).
                format: int64
              tag:
                type: string
        mentions:
          type:
          - array
          - 'null'
          items:
            type: object
            description: A user mention entity.
            required:
            - start
            - end
            properties:
              end:
                type: integer
                format: int64
              id:
                type:
                - string
                - 'null'
              start:
                type: integer
                format: int64
              username:
                type:
                - string
                - 'null'
        urls:
          type:
          - array
          - 'null'
          items:
            type: object
            description: A URL entity found in the Post text, enriched with link metadata.
            required:
            - start
            - end
            properties:
              description:
                type:
                - string
                - 'null'
                description: Description of the linked page, when available.
              display_url:
                type:
                - string
                - 'null'
                description: The URL as displayed in the Post text.
              end:
                type: integer
                format: int64
              expanded_url:
                type:
                - string
                - 'null'
                description: The fully resolved URL.
              images:
                type:
                - array
                - 'null'
                items:
                  type: object
                  description: A preview image for a linked page.
                  properties:
                    height:
                      type:
                      - integer
                      - 'null'
                      format: int64
                    url:
                      type:
                      - string
                      - 'null'
                    width:
                      type:
                      - integer
                      - 'null'
                      format: int64
              media_key:
                type:
                - string
                - 'null'
              start:
                type: integer
                format: int64
              status:
                type:
                - integer
                - 'null'
                description: HTTP status from resolving the URL.
                format: int64
              title:
                type:
                - string
                - 'null'
                description: Title of the linked page, when available.
              unwound_url:
                type:
                - string
                - 'null'
                description: The final destination after following redirects.
              url:
                type:
                - string
                - 'null'
                description: The t.co shortened URL.
    MediaVariants:
      type: array
      description: Each media object may have multiple display or playback variants, with different resolutions or formats.
      items:
        type: object
        description: A single playback or display variant of a media object.
        properties:
          bit_rate:
            type:
            - integer
            - 'null'
            description: The bit rate of this variant, in bits per second. Absent for playlist variants.
            format: int64
          content_type:
            type:
            - string
            - 'null'
            description: The MIME type of this variant, for example "video/mp4" or "application/x-mpegURL".
          url:
            type:
            - string
            - 'null'
            description: The URL to this media variant.
    RotateBotTokenResponseData:
      type: object
      required:
      - id
      - token
      properties:
        id:
          type: string
          description: Unique identifier of the bot's User account.
          pattern: ^[0-9]{1,19}$
        name:
          type: string
          description: The bot's display name.
        scopes:
          type: array
          description: Scopes granted to the new bearer token.
          items:
            type: string
        token:
          type: string
          description: The bot's new bearer token. Returned exactly once; store it securely. Every previously issued token for this bot is invalidated.
        token_expires_at_ms:
          type: integer
          description: Expiry of the new bearer token, in epoch milliseconds.
        username:
          type: string
          description: The bot's X handle (screen name).
    PostReferencedPosts:
      type: array
      description: A list of Posts this Post refers to. If the Post is a Retweet, Quote or Reply, it includes the referenced Post's type and ID.
      items:
        type: object
        description: A reference from this Post to another Post (repost, quote, or reply).
        required:
        - type
        - id
        properties:
          id:
            type: string
            description: Unique identifier of the referenced Post.
          type:
            description: How this Post references the other Post.
            oneOf:
            - type: string
              description: The kind of Post-to-Post reference.
              enum:
              - retweeted
              - quoted
              - replied_to
    DeleteBotResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/DeleteBotResponseData'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Problem'
    MediaNonPublicMetrics:
      type: object
      description: Nonpublic engagement metrics for the media at the time of the request.
      properties:
        playback_0_count:
          type:
          - integer
          - 'null'
          description: Number of users who started playback (0% quartile) of this video.
          format: int64
        playback_100_count:
          type:
          - integer
          - 'null'
          description: Number of users who completed playback (100% quartile) of this video.
          format: int64
        playback_25_count:
          type:
          - integer
          - 'null'
          description: Number of users who watched at least 25% of this video.
          format: int64
        playback_50_count:
          type:
          - integer
          - 'null'
          description: Number of users who watched at least 50% of this video.
          format: int64
        playback_75_count:
          type:
          - integer
          - 'null'
          description: Number of users who watched at least 75% of this video.
          format: int64
    RevokeBotTokenResponseData:
      type: object
      required:
      - revoked
      properties:
        revoked:
          type: boolean
          description: Whether the bot's token was revoked.
    UserConnectionStatus:
      type: array
      description: Returns detailed information about the relationship between two users.
      items:
        type: string
        description: A connection between the authenticated User and this User.
        enum:
        - blocking
        - follow_request_received
        - follow_request_sent
        - followed_by
        - following
        - muting
    NotAuthorizedForFieldProblem:
      type: object
      required:
      - type
      - title
      - detail
      - field
      properties:
        detail:
          type: string
        field:
          type: string
        parameter:
          type: string
        resource_id:
          type: string
        resource_type:
          type: string
        section:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          type: string
          enum:
          - https://api.x.com/2/problems/not-authorized-for-field
        value:
          type: string
    PostNotePost:
      type: object
      description: The full content of the Post, including text beyond 280 characters.
      required:
      - text
      properties:
        entities:
          type:
          - object
          - 'null'
          description: Metadata entities (hashtags, cashtags, mentions, URLs) found in the note Post text.
          properties:
            cashtags:
              type:
              - array
              - 'null'
              items:
                type: object
                description: A hashtag or cashtag entity.
                required:
                - start
                - end
                - tag
                properties:
                  end:
                    type: integer
                    description: End index in the text (exclusive).
                    format: int64
                  start:
                    type: integer
                    description: Start index in the text (inclusive).
                    format: int64
                  tag:
                    type: string
            hashtags:
              type:
              - array
              - 'null'
              items:
                type: object
                description: A hashtag or cashtag entity.
                required:
                - start
                - end
                - tag
                properties:
                  end:
                    type: integer
                    description: End index in the text (exclusive).
                    format: int64
                  start:
                    type: integer
                    description: Start index in the text (inclusive).
                    format: int64
                  tag:
                    type: string
            mentions:
              type:
              - array
              - 'null'
              items:
                type: object
                description: A user mention entity.
                required:
                - start
                - end
                properties:
                  end:
                    type: integer
                    format: int64
                  id:
                    type:
                    - string
                    - 'null'
                  start:
                    type: integer
                    format: int64
                  username:
                    type:
                    - string
                    - 'null'
            urls:
              type:
              - array
              - 'null'
              items:
                type: object
                description: A URL entity found in note Post text.
                required:
                - start
                - end
                properties:
                  display_url:
                    type:
                    - string
                    - 'null'
                  end:
                    type: integer
                    format: int64
                  expanded_url:
                    type:
                    - string
                    - 'null'
                  start:
                    type: integer
                    format: int64
                  url:
                    type:
                    - string
                    - 'null'
        text:
          type: string
          description: The full note text of the Post.
    Post:
      type: object
      properties:
        article:
          type: object
        article_title:
          type: object
          description: Metadata about the long-form Article attached to this Post, if any.
        attachments:
          $ref: '#/components/schemas/PostAttachments'
        author_id:
          type: string
          description: Unique identifier of the author of this Post.
        card_uri:
          type: string
        community_id:
          type: string
          description: The unique identifier of the Community this Post belongs to, if any.
        context_annotations:
          $ref: '#/components/schemas/PostContextAnnotations'
        conversation_id:
          type: string
          description: The ID of the conversation this Post belongs to (matches the root Post's ID).
        created_at:
          type: string
          description: Creation time of the Post.
          format: date-time
        display_text_range:
          $ref: '#/components/schemas/PostDisplayTextRange'
        edit_controls:
          $ref: '#/components/schemas/PostEditControls'
        edit_history_post_ids:
          type: array
          description: A list of Post IDs in this Post's edit history chain.
          items:
            type: string
        entities:
          $ref: '#/components/schemas/PostEntities'
        geo:
          $ref: '#/components/schemas/PostGeo'
        id:
          type: string
          description: Unique identifier of this Post.
        in_reply_to_user_id:
          type: string
          description: Unique identifier of the User this Post is replying to.
        lang:
          type: string
          description: Language of the Post, if detected by X. Returned as a BCP47 language tag.
        matched_media_notes:
          $ref: '#/components/schemas/PostMatchedMediaNotes'
        media_metadata:
          $ref: '#/components/schemas/PostMediaMetadata'
        non_public_metrics:
          type: object
          description: Nonpublic engagement metrics for the Post at the time of the request.
        note_post:
          $ref: '#/components/schemas/PostNotePost'
        note_request_suggestions:
          $ref: '#/components/schemas/PostNoteRequestSuggestions'
        organic_metrics:
          type: object
          description: Organic nonpublic engagement metrics for the Post at the time of the request.
        paid_partnership:
          type: boolean
          description: Indicates if this Post is a paid partnership, i.e. it has been disclosed by the author as containing paid promotion.
        possibly_sensitive:
          type: boolean
          description: Indicates if this Post contains URLs marked as sensitive, for example content suitable for mature audiences.
        promoted_metrics:
          type: object
          description: Promoted nonpublic engagement metrics for the Post at the time of the request.
        public_metrics:
          $ref: '#/components/schemas/PostPublicMetrics'
        referenced_posts:
          $ref: '#/components/schemas/PostReferencedPosts'
        reply_settings:
          type: string
          description: Shows who can reply to this Post.
        scopes:
          $ref: '#/components/schemas/PostScopes'
        source:
          type: string
          description: The name of the app the user posted from. This is deprecated.
        suggested_source_links:
          $ref: '#/components/schemas/PostSuggestedSourceLinks'
        suggested_source_links_with_counts:
          $ref: '#/components/schemas/PostSuggestedSourceLinksWithCounts'
        text:
          type: string
          description: The content of the Post.
        username:
          type: string
        withheld:
          $ref: '#/components/schemas/PostWithheld'
    PostNoteRequestSuggestions:
      type: array
      description: Community-Notes request suggestions for this Post.
      items:
        type: object
        description: A Community-Notes request suggestion for this Post.
        properties:
          source_link:
            type:
            - string
            - 'null'
            description: A suggested source link supporting the note request.
          suggestion:
            type:
            - string
            - 'null'
            description: The text of the note request suggestion.
          suggestion_id:
            type:
            - string
            - 'null'
            description: The unique identifier of the note request suggestion.
    Poll:
      type: object
      properties:
        duration_minutes:
          type: integer
        end_datetime:
          type: string
        id:
          type: string
        options:
          $ref: '#/components/schemas/PollOptions'
        voting_status:
          type: string
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    UserWithheld:
      type: object
      description: Withholding details for withheld content.
      properties:
        country_codes:
          type:
          - array
          - 'null'
          description: A list of countries (as ISO 3166-1 alpha-2 codes) where this content is withheld.
          items:
            type: string
        scope:
          type:
          - string
          - 'null'
          description: The scope of the withholding. Only present, with the value "user", when the entire User is withheld.
          enum:
          - user
    MediaPromotedMetrics:
      type: object
      description: Promoted nonpublic engagement metrics for the media at the time of the request.
      properties:
        playback_0_count:
          type:
          - integer
          - 'null'
          description: Number of users who started playback (0% quartile) of this video.
          format: int64
        playback_100_count:
          type:
          - integer
          - 'null'
          description: Number of users who completed playback (100% quartile) of this video.
          format: int64
        playback_25_count:
          type:
          - integer
          - 'null'
          description: Number of users who watched at least 25% of this video.
          format: int64
        playback_50_count:
          type:
          - integer
          - 'null'
          description: Number of users who watched at least 50% of this video.
          format: int64
        playback_75_count:
          type:
          - integer
          - 'null'
          description: Number of users who watched at least 75% of this video.
          format: int64
        view_count:
          type:
          - integer
          - 'null'
          description: The number of promoted views of this video. Null when the backend returns quartile data without a view count.
          format: int64
    ResourceUnavailableProblem:
      type: object
      required:
      - type
      - title
      - detail
      - resource_type
      properties:
        detail:
          type: string
        resource_id:
          type: string
        resource_type:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          type: string
          enum:
          - https://api.x.com/2/problems/resource-unavailable
    InvalidRequestProblem:
      type: object
      required:
      - type
      - title
      - detail
      properties:
        detail:
          type: string
        parameter:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          type: string
          enum:
          - https://api.x.com/2/problems/invalid-request
        value:
          type: string
    UserEntities:
      type: object
      description: A list of metadata found in the User's profile description.
      properties:
        description:
          type:
          - object
          - 'null'
          description: Entities found in the User's bio.
          properties:
            cashtags:
              type:
              - array
              - 'null'
              items:
                type: object
                description: A hashtag or cashtag entity.
                required:
                - start
                - end
                - tag
                properties:
                  end:
        

# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/x/refs/heads/main/openapi/x-bots-api-openapi.yml