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 towhich Admin

You can promoteis a user via the Server Admin tab of the EMS Control Panel.

On the Users tab, find the user you wish to be admin in the list or via search, then click their username. Alternatively, enter their username in the User Info tab. Click the checkbox next to Synapse Admin, then confirm the admin permissions.

You should then recieve a confirmation banner that Admin capabilities enabled.

Getting your access_token

In order to use the Synapse Admin API you will need to authenticate your calls to the API using an access_token from that Admin user account.

You can find your access_token from the Help & About section of your settings, you can access settings by clicking your profile icon in the top left of the Element client. By default, this will be a coloured circle with the first letter of your Matrix ID. From the presented drop-down menu, select 'All Settings', then navigate to the Help & About section.

Under the Advanced section, click Access Token to reveal the token, then make note of the string.


Using the python script

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

DownloadYou thewill script, saving it into the venv root, i.e. Using the example above, it'dthen be .\myPythonProject\


Finally,to run thescripts script:you create by using:

python .\myPythonProject\


Writing file, calleda results.csvpython script

At it's most basic, you will beneed availableto insetup the directorybelow fromtemplate where you run the final command. You can open this to see a list of allinto your rooms, and whether they should be deleted. You will then be asked if you'd like to delete those rooms, I'd strongly suggest you manually delete the rooms, using the information from the results.csv - the script doesn't offer any options to customise which rooms you want deleted (nor will editing the CSV prior to running have any effect).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()