Client-Server API

The foundational protocol for Matrix clients to communicate with homeservers.

Overview

Base URL

https://matrix.org/_matrix/client/v3

Authentication

  • OAuth 2.0 Bearer token
  • JWT tokens
  • Session cookies

Supported Methods

  • GET /rooms/{roomId}/messages
  • POST /rooms/{roomId}/send
  • PUT /user/{userId}/presence

Key Concepts

Client Capabilities

  • End-to-end encryption
  • Real-time event streaming
  • Identity verification
  • Rich timeline formatting

Resource Structure


GET /_matrix/client/v3/rooms
 GET /_matrix/client/v3/rooms/{roomId}/join
POST /_matrix/client/v3/rooms/{roomId}/state

Authentication


curl 'https://matrix.org/_matrix/client/v3/rooms/{roomId}/members'
  -H 'Authorization: Bearer eyJraW....'

Token Types

  • User access token
  • Application service token
  • Guest access token

Scopes

  • read:rooms
  • write:messages
  • admin:users

Example: Room Creation


POST /_matrix/client/v3/createRoom
Content-Type: application/json
Authorization: Bearer eyJraW5...

{
  "name": "Dev Team",
  "topic": "Project updates",
  "is_encrypted": true,
  "initial_state": [
    {
      "type": "m.room.encryption",
      "state_key": "",
      "content": {
        "algorithm": "m.megolm.v1.aes-sha2"
      }
    }
  ]
}

Ready to Build?

View Tutorials
```