openapi: 3.1.0
info:
  title: Matrix Client-Server API
  version: v3
  description: |
    REST API used by Matrix clients to communicate with a homeserver. Covers
    login, account management, sync, room creation and membership, message
    send and history, profile and presence, device management, end-to-end
    encryption keys, and the public rooms directory. Newer endpoints sit
    under /_matrix/client/v3 with selected features under /v1.
  contact:
    name: Matrix.org Foundation
    url: https://matrix.org
servers:
  - url: https://{homeserver}/_matrix/client
    description: Matrix homeserver Client-Server API root
    variables:
      homeserver:
        default: matrix.org
security:
  - BearerAuth: []
paths:
  /v3/login:
    get:
      summary: List supported login flows
      operationId: getLoginFlows
      security: []
      responses:
        '200':
          description: Supported login flows.
    post:
      summary: Authenticate and obtain an access token
      operationId: login
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [type]
              properties:
                type:
                  type: string
                  description: e.g. `m.login.password`
                identifier:
                  type: object
                password:
                  type: string
                device_id:
                  type: string
                initial_device_display_name:
                  type: string
                refresh_token:
                  type: boolean
      responses:
        '200':
          description: Access token issued.
  /v3/logout:
    post:
      summary: Invalidate the current access token
      operationId: logout
      responses:
        '200':
          description: Logged out.
  /v3/refresh:
    post:
      summary: Refresh an access token
      operationId: refresh
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [refresh_token]
              properties:
                refresh_token:
                  type: string
      responses:
        '200':
          description: New access (and refresh) token.
  /v3/register:
    post:
      summary: Register a new user account
      operationId: register
      security: []
      parameters:
        - in: query
          name: kind
          schema:
            type: string
            enum: [user, guest]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Account created.
  /v3/account/whoami:
    get:
      summary: Get the current user ID
      operationId: whoami
      responses:
        '200':
          description: User and device identifiers.
  /v3/capabilities:
    get:
      summary: Query server capabilities
      operationId: getCapabilities
      responses:
        '200':
          description: Capabilities.
  /v3/sync:
    get:
      summary: Synchronize client state with the server
      operationId: sync
      parameters:
        - in: query
          name: since
          schema:
            type: string
        - in: query
          name: timeout
          schema:
            type: integer
        - in: query
          name: full_state
          schema:
            type: boolean
        - in: query
          name: set_presence
          schema:
            type: string
            enum: [offline, online, unavailable]
        - in: query
          name: filter
          schema:
            type: string
      responses:
        '200':
          description: Sync state delta.
  /v3/createRoom:
    post:
      summary: Create a new room
      operationId: createRoom
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Room created.
  /v3/join/{roomIdOrAlias}:
    post:
      summary: Join a room by ID or alias
      operationId: joinRoom
      parameters:
        - in: path
          name: roomIdOrAlias
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Joined.
  /v3/rooms/{roomId}/leave:
    post:
      summary: Leave a room
      operationId: leaveRoom
      parameters:
        - $ref: '#/components/parameters/RoomId'
      responses:
        '200':
          description: Left.
  /v3/rooms/{roomId}/invite:
    post:
      summary: Invite a user to a room
      operationId: inviteToRoom
      parameters:
        - $ref: '#/components/parameters/RoomId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [user_id]
              properties:
                user_id:
                  type: string
      responses:
        '200':
          description: Invitation sent.
  /v3/rooms/{roomId}/send/{eventType}/{txnId}:
    put:
      summary: Send a message event to a room
      operationId: sendRoomEvent
      parameters:
        - $ref: '#/components/parameters/RoomId'
        - in: path
          name: eventType
          required: true
          schema:
            type: string
        - in: path
          name: txnId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Event ID returned.
  /v3/rooms/{roomId}/messages:
    get:
      summary: Get message history for a room
      operationId: getRoomMessages
      parameters:
        - $ref: '#/components/parameters/RoomId'
        - in: query
          name: from
          schema:
            type: string
        - in: query
          name: to
          schema:
            type: string
        - in: query
          name: dir
          schema:
            type: string
            enum: [b, f]
        - in: query
          name: limit
          schema:
            type: integer
        - in: query
          name: filter
          schema:
            type: string
      responses:
        '200':
          description: Paginated room messages.
  /v3/directory/room/{roomAlias}:
    get:
      summary: Look up a room ID by alias
      operationId: getRoomIdByAlias
      parameters:
        - in: path
          name: roomAlias
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Room identifier and servers.
  /v3/publicRooms:
    get:
      summary: List public rooms in the homeserver directory
      operationId: getPublicRooms
      responses:
        '200':
          description: Public room chunks.
  /v3/profile/{userId}:
    get:
      summary: Retrieve a user profile
      operationId: getProfile
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Profile.
  /v3/profile/{userId}/{keyName}:
    put:
      summary: Set a profile field (display name or avatar URL)
      operationId: setProfileField
      parameters:
        - $ref: '#/components/parameters/UserId'
        - in: path
          name: keyName
          required: true
          schema:
            type: string
            enum: [displayname, avatar_url]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Updated.
  /v3/devices:
    get:
      summary: List the current user's devices
      operationId: listDevices
      responses:
        '200':
          description: Devices.
  /v3/keys/upload:
    post:
      summary: Upload end-to-end encryption keys
      operationId: uploadKeys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Counts of one-time keys remaining.
components:
  parameters:
    RoomId:
      in: path
      name: roomId
      required: true
      schema:
        type: string
    UserId:
      in: path
      name: userId
      required: true
      schema:
        type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        Matrix access token issued by the homeserver after login, passed as
        `Authorization: Bearer {access_token}`. Some endpoints (login,
        register, refresh) do not require authentication.