X Broadcasts API

openapi: 3.2.0
info:
  description: X API v2 core endpoints
  version: '2.168'
  title: X API v2 Broadcasts 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: Broadcasts
  description: Endpoints related to live broadcasts and their chat
  externalDocs:
    description: Find out more
    url: https://developer.x.com/
paths:
  /2/broadcasts:
    get:
      security:
      - OAuth2UserToken:
        - broadcast.read
      - UserToken: []
      tags:
      - Broadcasts
      summary: List broadcasts
      description: 'Returns the authenticated user''s live-video broadcasts, or selected owned broadcasts when ids are provided.


        At most one of `ids`, `max_results` may be provided. At most one of `ids`, `pagination_token` may be provided.'
      operationId: listBroadcasts
      parameters:
      - name: ids
        in: query
        description: Comma-separated broadcast IDs to retrieve instead of listing broadcasts.
        required: false
        schema:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: string
            pattern: ^[a-zA-Z0-9]{1,13}$
        explode: false
        style: form
      - name: max_results
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          format: int32
        style: form
      - name: pagination_token
        in: query
        required: false
        schema:
          type: string
          minLength: 1
        style: form
      - $ref: '#/components/parameters/BroadcastFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBroadcastsResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/broadcasts/scheduled:
    get:
      security:
      - OAuth2UserToken:
        - broadcast.read
      - UserToken: []
      tags:
      - Broadcasts
      summary: List scheduled broadcasts
      description: Returns scheduled broadcasts owned by the authenticated user.
      operationId: listScheduledBroadcasts
      parameters:
      - name: max_results
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          format: int32
        style: form
      - name: oldest_start_time
        in: query
        required: false
        schema:
          type: string
        style: form
      - name: newest_start_time
        in: query
        required: false
        schema:
          type: string
        style: form
      - name: pagination_token
        in: query
        required: false
        schema:
          type: string
        style: form
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListScheduledBroadcastsResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    post:
      security:
      - OAuth2UserToken:
        - broadcast.read
        - broadcast.write
      - UserToken: []
      tags:
      - Broadcasts
      summary: Create a scheduled broadcast
      description: Schedules a one-off or recurring broadcast for the authenticated user. A `source_id` (ingest) is required at create time.
      operationId: createScheduledBroadcast
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScheduledBroadcastRequest'
        required: true
      responses:
        '201':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateScheduledBroadcastResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/broadcasts/scheduled/{id}:
    delete:
      security:
      - OAuth2UserToken:
        - broadcast.write
        - broadcast.read
      - UserToken: []
      tags:
      - Broadcasts
      summary: Delete a scheduled broadcast
      description: Deletes a scheduled broadcast by its alphanumeric UBS broadcast id.
      operationId: deleteScheduledBroadcast
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z0-9]{1,13}$
        style: simple
      - name: roll_forward
        in: query
        required: false
        schema:
          type: boolean
        style: form
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteScheduledBroadcastResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    get:
      security:
      - OAuth2UserToken:
        - broadcast.read
      - UserToken: []
      tags:
      - Broadcasts
      summary: Get a scheduled broadcast
      description: Returns a single scheduled broadcast by its alphanumeric UBS broadcast id.
      operationId: getScheduledBroadcast
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z0-9]{1,13}$
        style: simple
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetScheduledBroadcastResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    put:
      security:
      - OAuth2UserToken:
        - broadcast.write
        - broadcast.read
      - UserToken: []
      tags:
      - Broadcasts
      summary: Update a scheduled broadcast
      description: Fully replaces schedule fields for a broadcast. Path `:id` is the UBS broadcast id; the body must include `scheduled_broadcast_id` and re-send any fields that should be kept.
      operationId: updateScheduledBroadcast
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z0-9]{1,13}$
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScheduledBroadcastRequest'
        required: true
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateScheduledBroadcastResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/broadcasts/scheduled/{id}/live:
    post:
      security:
      - OAuth2UserToken:
        - broadcast.write
        - broadcast.read
      - UserToken: []
      tags:
      - Broadcasts
      summary: Go live on a scheduled broadcast
      description: 'Publishes a schedule that was created or updated with `manual_publish: true`. Without that flag the coordinator auto-publishes at start and this call is rejected.'
      operationId: goLiveScheduledBroadcast
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z0-9]{1,13}$
        style: simple
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoLiveScheduledBroadcastResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/broadcasts/{id}:
    get:
      security:
      - OAuth2UserToken:
        - broadcast.read
      - UserToken: []
      tags:
      - Broadcasts
      summary: Get a broadcast
      description: Returns a broadcast owned by the authenticated user.
      operationId: getBroadcast
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z0-9]{1,13}$
        style: simple
      - $ref: '#/components/parameters/BroadcastFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBroadcastResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/broadcasts/{id}/chat:
    get:
      security:
      - OAuth2UserToken:
        - broadcast.read
      - UserToken: []
      tags:
      - Broadcasts
      summary: Get broadcast chat history
      description: Returns newest-first chat messages for a broadcast owned by the authenticated user.
      operationId: getBroadcastChat
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z0-9]{1,13}$
        style: simple
      - name: max_results
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
          format: int32
          default: 100
        style: form
      - name: pagination_token
        in: query
        description: A 64-bit signed integer.
        required: false
        schema:
          type: string
        style: form
      - $ref: '#/components/parameters/BroadcastChatMessageFieldsParameter'
      - $ref: '#/components/parameters/BroadcastChatMessageExpansionsParameter'
      - $ref: '#/components/parameters/UserFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBroadcastChatResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    post:
      security:
      - OAuth2UserToken:
        - broadcast.write
        - broadcast.read
      - UserToken: []
      tags:
      - Broadcasts
      summary: Send a chat message to a live broadcast
      description: Posts a chat message to a running broadcast, attributed to the authenticated user.
      operationId: sendBroadcastChat
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z0-9]{1,13}$
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendBroadcastChatRequest'
        required: true
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendBroadcastChatResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/broadcasts/{id}/chat/mutes:
    post:
      security:
      - OAuth2UserToken:
        - broadcast.read
        - broadcast.write
      - UserToken: []
      tags:
      - Broadcasts
      summary: Mute or time out a user in a broadcast chat
      description: Prevents a user from posting further messages in a running broadcast chat. When `end_at_ms` is provided, the mute expires at that time. The authenticated user must own the broadcast.
      operationId: muteBroadcastChatUser
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z0-9]{1,13}$
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MuteBroadcastChatUserRequest'
        required: true
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MuteBroadcastChatUserResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/broadcasts/{id}/chat/mutes/{user_id}:
    delete:
      security:
      - OAuth2UserToken:
        - broadcast.write
        - broadcast.read
      - UserToken: []
      tags:
      - Broadcasts
      summary: Unmute a user in a broadcast chat
      description: Allows a muted user to post messages in a running broadcast chat again. The authenticated user must own the broadcast.
      operationId: unmuteBroadcastChatUser
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z0-9]{1,13}$
        style: simple
      - name: user_id
        in: path
        description: A 64-bit signed integer.
        required: true
        schema:
          type: string
          pattern: ^[1-9][0-9]{0,18}$
        style: simple
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnmuteBroadcastChatUserResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/broadcasts/{id}/chat/{message_id}:
    delete:
      security:
      - OAuth2UserToken:
        - broadcast.read
        - broadcast.write
      - UserToken: []
      tags:
      - Broadcasts
      summary: Remove a chat message from a live broadcast
      description: Removes a specific chat message from a running broadcast owned by the authenticated user.
      operationId: deleteBroadcastChatMessage
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z0-9]{1,13}$
        style: simple
      - name: message_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/DeleteBroadcastChatMessageResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    MuteBroadcastChatUserRequest:
      type: object
      required:
      - user_id
      properties:
        end_at_ms:
          type: string
          description: The Unix timestamp in milliseconds when the mute expires. Omit this field to mute indefinitely.
          pattern: ^[1-9][0-9]{0,18}$
        message_id:
          type: string
          description: A chat message to remove while muting the user.
          pattern: ^[1-9][0-9]{0,18}$
        user_id:
          type: string
          description: The user to mute.
          pattern: ^[1-9][0-9]{0,18}$
      additionalProperties: false
    UnmuteBroadcastChatUserResponseData:
      type: object
      required:
      - muted
      properties:
        muted:
          type: boolean
          description: Whether the user is muted in this broadcast chat.
    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
    ListBroadcastsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Broadcast'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Problem'
        meta:
          type: object
          properties:
            next_token:
              type: string
              description: Pagination token for the next page of results.
            result_count:
              type: integer
              description: Number of items in the data array.
              format: int32
    CreateScheduledBroadcastRequest:
      type: object
      required:
      - source_id
      - scheduled_start_ms
      - scheduled_end_ms
      properties:
        available_for_replay:
          type: boolean
          description: Enable replay.
        chat_option:
          type: string
          description: Chat permission option (numeric string).
          pattern: ^[0-9]{1,19}$
        description:
          type: string
          description: Description.
        is_locked:
          type: boolean
          description: Lock the broadcast.
        locale:
          type: string
          description: Locale.
        manual_publish:
          type: boolean
          description: If true, do not auto-publish at start; call POST .../live when ready.
        recurrence:
          description: If set, creates a recurring series.
          $ref: '#/components/schemas/CreateScheduledBroadcastRecurrence'
        scheduled_end_ms:
          type: string
          description: End time, ms since Unix epoch (decimal string).
          pattern: ^[0-9]{1,19}$
        scheduled_start_ms:
          type: string
          description: Start time, ms since Unix epoch (decimal string).
          pattern: ^[0-9]{1,19}$
        source_id:
          type: string
          description: Ingest / source id to bind (same as sources `rtmp_stream_key`).
          minLength: 1
        telecast_id:
          type: string
          description: Optional telecast id (numeric string).
          pattern: ^[0-9]{1,19}$
        thumbnail_media_id:
          type: string
          description: Pre-live slate media id (numeric string).
          pattern: ^[0-9]{1,19}$
        title:
          type: string
          description: Title / status text.
      additionalProperties: false
    Poll:
      type: object
      properties:
        duration_minutes:
          type: integer
        end_datetime:
          type: string
        id:
          type: string
        options:
          $ref: '#/components/schemas/PollOptions'
        voting_status:
          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
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    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
    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:
                    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
                - username
                properties:
                  end:
                    type: integer
                    format: int64
                  id:
                    type:
                    - string
                    - 'null'
                  start:
                    type: integer
                    format: int64
                  username:
                    type: string
            urls:
              type:
              - array
              - 'null'
              items:
                type: object
                description: A URL entity found in profile text.
                required:
                - start
                - end
                - url
                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
                    description: The t.co shortened URL.
        url:
          type:
          - object
          - 'null'
          description: Entities for the User's profile website URL.
          properties:
            urls:
              type:
              - array
              - 'null'
              items:
                type: object
                description: A URL entity found in profile text.
                required:
                - start
                - end
                - url
                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
                    description: The t.co shortened URL.
    PostMediaMetadata:
      type: array
      description: Metadata for media attached to this Post.
      items:
        type: object
        description: Metadata for one media item attached to this Post.
        properties:
          alt_text:
            type:
            - string
            - 'null'
            description: Alternative text describing the media for accessibility.
          description:
            type:
            - string
            - 'null'
            description: Description of the media.
          media_key:
            type:
            - string
            - 'null'
            description: The unique identifier of the media.
          title:
            type:
            - string
            - 'null'
            description: Title of the media.
    GoLiveScheduledBroadcastResponseData:
      type: object
      properties:
        available_for_replay:
          type: boolean
          description: Whether replay is enabled.
        broadcast_id:
          type: string
          description: Alphanumeric UBS broadcast id (path `:id` for get/update/delete/live).
        chat_option:
          type: string
          description: Optional chat permission option.
        description:
          type: string
          description: Optional description.
        locale:
          type: string
          description: Optional locale.
        manual_publish:
          type: boolean
          description: When true, coordinator will not auto-publish; call POST .../live when ready.
        recurring_schedule_id:
          type: string
          description: Set when this occurrence belongs to a recurrence.
        scheduled_broadcast_id:
          type: string
          description: Numeric scheduler id. Required in the update request body.
        scheduled_end_ms:
          type: string
          description: Scheduled end, milliseconds since Unix epoch (decimal string).
        scheduled_start_ms:
          type: string
          description: Scheduled start, milliseconds since Unix epoch (decimal string).
        source_id:
          type: string
          description: Bound ingest / source id (`rtmp

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