Skip to main content

Using Python with the Admin + Client-Server APIs

You can use Python to make consume and utilise APIs, including those available with Matrix - such as the Synapse Admin API, and the Matrix Client-Server API. See the below docs to learn more about them before progressing with this guide.

The key requirement before progressing is getting the Matrix Accounts' access_token, if your using the Synapse Admin API, you must use a Matrix Account which is a Synapse Admin.

Using python

You will need Python setup on your system to make use of the script. The best way to use Python is to keep individual projects / scripts in separate virtual environments (venv). The documentation on this can be found here, for example on Windows you'd use:

python -m venv .\myPythonProject\

The script uses the requests library in order to make the API requests, to install in in you venv, after activating run:

python -m pip install requests

You will then be able to run scripts you create by using:

python .\myPythonProject\

Writing a python script

At it's most basic, you will need to setup the below template within your script:

import requests

homeseverURL = ''
accountToken = 'accountTokenStringExample'
requestHeaders = {
    'Authorization': 'Bearer ' + accountToken
requestData = {
    'key': 'value'

getResponse ='API Endpoint URL', headers=requestHeaders).json()
postResponse ='API Endpoint URL', headers=requestHeaders, data=requestData).json()

For example, let's say you wanted to join a list of users to a list of rooms, you would adapt this template to something like the below to make use of the Edit Room Membership API:

import requests

# Homeserver
homeserverURL = ''

# Credentials
accountToken = 'mat_Hwpn2I2gVIZ8WodfsdfsdfsdfSBf7xAV_BAGYU1'

# Rooms to Auto-Join
roomAliasList = ['', '']

# Users to Auto-Join
userList = ['', '']

# API Auth Header
requestHeaders = {
    'Authorization': 'Bearer ' + accountToken,

# Loop through all rooms, adding all users to those rooms
for roomAlias in roomAliasList:
    editRoomMembershipURL = 'https://' + homeserverURL + '/_synapse/admin/v1/join/' + roomAlias
    for user in userList:
        editRoomMembershipData = {
            "user_id": user
        response =, headers=requestHeaders, data=editRoomMembershipData).json()