> ## Documentation Index
> Fetch the complete documentation index at: https://x-preview-smedina-x-calls-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a call

> Starts an X call hosted by the authenticated user (typically a bot). Pass an XChat conversation_id to start the call in that conversation, or omit it for a standalone call anyone can join with the returned join_url (subject to join_policy). The call starts empty: put an agent in it with POST /2/calls/:id/join. When the host joins a conversation call, the other members are rung.



## OpenAPI

````yaml xcalls/openapi.json POST /2/calls
openapi: 3.0.0
info:
  title: X Calls API
  version: '2'
  description: >-
    Start, join and schedule X calls as your app's user, and put a voice agent
    in them. In development: endpoints and payloads may change.
servers:
  - description: X API
    url: https://api.x.com
security: []
tags:
  - name: Calls
paths:
  /2/calls:
    post:
      tags:
        - Calls
      summary: Create a call
      description: >-
        Starts an X call hosted by the authenticated user (typically a bot).
        Pass an XChat conversation_id to start the call in that conversation, or
        omit it for a standalone call anyone can join with the returned join_url
        (subject to join_policy). The call starts empty: put an agent in it with
        POST /2/calls/:id/join. When the host joins a conversation call, the
        other members are rung.
      operationId: createCall
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCallRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCallResponse'
          description: The request has succeeded.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: The request has failed.
      security:
        - OAuth2UserToken:
            - dm.write
            - users.read
            - tweet.read
        - UserToken: []
components:
  schemas:
    CreateCallRequest:
      additionalProperties: false
      properties:
        audio_only:
          description: Start the call without video.
          type: boolean
        conversation_id:
          description: XChat conversation to start the call in.
          maxLength: 128
          pattern: ^[A-Za-z0-9:_-]+$
          type: string
        join_policy:
          description: >-
            open (default): anyone with the link joins; closed: the host admits
            each person; trusted: members of the host's Verified Organization
            join, others ask.
          enum:
            - open
            - closed
            - trusted
          type: string
        title:
          description: Title shown to participants.
          maxLength: 100
          type: string
      type: object
    CreateCallResponse:
      properties:
        data:
          $ref: '#/components/schemas/CreateCallResponseData'
        errors:
          items:
            $ref: '#/components/schemas/Problem'
          type: array
      type: object
    Error:
      properties:
        code:
          format: int32
          type: integer
        message:
          type: string
      required:
        - code
        - message
      type: object
    Problem:
      discriminator:
        mapping:
          https://api.twitter.com/2/problems/duplicate-rules: '#/components/schemas/DuplicateRuleProblem'
          https://api.twitter.com/2/problems/invalid-rules: '#/components/schemas/InvalidRuleProblem'
          https://api.x.com/2/problems/disallowed-resource: '#/components/schemas/DisallowedResourceProblem'
          https://api.x.com/2/problems/field-hydration-failure: '#/components/schemas/FieldHydrationFailureProblem'
          https://api.x.com/2/problems/field-unauthorized: '#/components/schemas/FieldUnauthorizedProblem'
          https://api.x.com/2/problems/internal-error: '#/components/schemas/InternalErrorProblem'
          https://api.x.com/2/problems/invalid-request: '#/components/schemas/InvalidRequestProblem'
          https://api.x.com/2/problems/not-authorized-for-field: '#/components/schemas/NotAuthorizedForFieldProblem'
          https://api.x.com/2/problems/not-authorized-for-resource: '#/components/schemas/NotAuthorizedForResourceProblem'
          https://api.x.com/2/problems/recipient-not-messageable: '#/components/schemas/RecipientNotMessageableProblem'
          https://api.x.com/2/problems/resource-not-found: '#/components/schemas/ResourceNotFoundProblem'
          https://api.x.com/2/problems/resource-unavailable: '#/components/schemas/ResourceUnavailableProblem'
        propertyName: type
      oneOf:
        - $ref: '#/components/schemas/ResourceNotFoundProblem'
        - $ref: '#/components/schemas/InvalidRequestProblem'
        - $ref: '#/components/schemas/NotAuthorizedForResourceProblem'
        - $ref: '#/components/schemas/NotAuthorizedForFieldProblem'
        - $ref: '#/components/schemas/FieldUnauthorizedProblem'
        - $ref: '#/components/schemas/FieldHydrationFailureProblem'
        - $ref: '#/components/schemas/ResourceUnavailableProblem'
        - $ref: '#/components/schemas/DisallowedResourceProblem'
        - $ref: '#/components/schemas/RecipientNotMessageableProblem'
        - $ref: '#/components/schemas/InternalErrorProblem'
        - $ref: '#/components/schemas/DuplicateRuleProblem'
        - $ref: '#/components/schemas/InvalidRuleProblem'
    CreateCallResponseData:
      additionalProperties: false
      properties:
        conversation_id:
          description: XChat conversation the call belongs to, if any.
          type: string
        created_at:
          description: Creation time (RFC 3339).
          type: string
        host_id:
          description: X user id of the call's host.
          type: string
        id:
          description: Unique identifier of the call; also its join secret.
          type: string
        join_policy:
          description: >-
            Who may join: open (anyone with the link), closed (the host admits
            people), or trusted (the host's Verified Organization).
          type: string
        join_url:
          description: Link people open to join the call on X.
          type: string
        participant_count:
          description: People in the call right now.
          type: integer
        title:
          description: Title of the call.
          type: string
        viewer_may_join:
          description: Whether the authenticated user may join without asking the host.
          type: boolean
      required:
        - id
      type: object
    DuplicateRuleProblem:
      properties:
        detail:
          type: string
        id:
          type: string
        title:
          type: string
        type:
          enum:
            - https://api.twitter.com/2/problems/duplicate-rules
          type: string
        value:
          type: string
      required:
        - type
        - title
        - value
      type: object
    InvalidRuleProblem:
      properties:
        detail:
          type: string
        details:
          items:
            type: string
          type: array
        title:
          type: string
        type:
          enum:
            - https://api.twitter.com/2/problems/invalid-rules
          type: string
        value:
          type: string
      required:
        - type
        - title
        - details
      type: object
    DisallowedResourceProblem:
      properties:
        detail:
          type: string
        resource_id:
          type: string
        resource_type:
          type: string
        section:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          enum:
            - https://api.x.com/2/problems/disallowed-resource
          type: string
      required:
        - type
        - title
        - detail
      type: object
    FieldHydrationFailureProblem:
      properties:
        detail:
          type: string
        field:
          type: string
        resource_type:
          type: string
        section:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          enum:
            - https://api.x.com/2/problems/field-hydration-failure
          type: string
      required:
        - type
        - title
        - detail
        - field
      type: object
    FieldUnauthorizedProblem:
      properties:
        detail:
          type: string
        field:
          type: string
        resource_type:
          type: string
        section:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          enum:
            - https://api.x.com/2/problems/field-unauthorized
          type: string
      required:
        - type
        - title
        - detail
        - field
      type: object
    InternalErrorProblem:
      properties:
        detail:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          enum:
            - https://api.x.com/2/problems/internal-error
          type: string
      required:
        - type
        - title
        - detail
      type: object
    InvalidRequestProblem:
      properties:
        detail:
          type: string
        parameter:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          enum:
            - https://api.x.com/2/problems/invalid-request
          type: string
        value:
          type: string
      required:
        - type
        - title
        - detail
      type: object
    NotAuthorizedForFieldProblem:
      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:
          enum:
            - https://api.x.com/2/problems/not-authorized-for-field
          type: string
        value:
          type: string
      required:
        - type
        - title
        - detail
        - field
      type: object
    NotAuthorizedForResourceProblem:
      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:
          enum:
            - https://api.x.com/2/problems/not-authorized-for-resource
          type: string
        value:
          type: string
      required:
        - type
        - title
        - detail
        - resource_type
      type: object
    RecipientNotMessageableProblem:
      properties:
        detail:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          enum:
            - https://api.x.com/2/problems/recipient-not-messageable
          type: string
      required:
        - type
        - title
        - detail
      type: object
    ResourceNotFoundProblem:
      properties:
        detail:
          type: string
        parameter:
          type: string
        resource_id:
          type: string
        resource_type:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          enum:
            - https://api.x.com/2/problems/resource-not-found
          type: string
        value:
          type: string
      required:
        - type
        - title
        - detail
        - resource_type
      type: object
    ResourceUnavailableProblem:
      properties:
        detail:
          type: string
        resource_id:
          type: string
        resource_type:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          enum:
            - https://api.x.com/2/problems/resource-unavailable
          type: string
      required:
        - type
        - title
        - detail
        - resource_type
      type: object
  securitySchemes:
    OAuth2UserToken:
      flows:
        authorizationCode:
          authorizationUrl: https://api.x.com/2/oauth2/authorize
          scopes:
            block.read: View accounts you have blocked.
            block.write: Block and unblock accounts on your behalf.
            bookmark.read: Read your bookmarked Posts.
            bookmark.write: Create and delete your bookmarks.
            broadcast.read: View your live broadcasts and their chat.
            broadcast.write: Manage your live broadcasts and send chat messages on your behalf.
            developer.read: View your developer accounts, apps, and settings.
            developer.write: Create and manage your X Developer Platform account.
            dm.read: Read all your Direct Messages.
            dm.write: Send and manage your Direct Messages.
            follows.read: View accounts you follow and accounts following you.
            follows.write: Follow and unfollow accounts on your behalf.
            like.read: View Posts you have liked and likes you can see.
            like.write: Like and unlike Posts on your behalf.
            list.read: >-
              View Lists, members, and followers of Lists you created or are a
              member of, including private Lists.
            list.write: Create and manage Lists on your behalf.
            media.write: Upload media, such as photos and videos, on your behalf.
            mute.read: View accounts you have muted.
            mute.write: Mute and unmute accounts on your behalf.
            offline.access: Request a refresh token for the app.
            space.read: View all Spaces you have access to.
            timeline.read: View all Custom Timelines you can see.
            tweet.moderate.write: Hide and unhide replies to your posts.
            tweet.read: >-
              View all posts you can see, including those from protected
              accounts.
            tweet.write: Create and repost on your behalf.
            users.read: View any account you can see, including protected accounts.
          tokenUrl: https://api.x.com/2/oauth2/token
      type: oauth2
    UserToken:
      scheme: OAuth
      type: http

````