Matrix Specification

https://spec.matrix.org/v1.16
Admin
Matrix defines a set of open APIs for decentralised communication, enabling secure publishing,...
Tokens:150,027
Snippets:567
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Account GET Response Example

Source: https://spec.matrix.org/v1.16/identity-service-api

Example of a successful response (200 OK) when retrieving account information using a valid access token. It includes the user ID associated with the token.

```JSON
{
  "user_id": "@alice:example.org"
}
```

--------------------------------

### Publish Homeserver Signing Keys - JSON Response Example

Source: https://spec.matrix.org/v1.16/server-server-api

Example JSON response for the GET /_matrix/key/v2/server endpoint, detailing the homeserver's active and old verification keys, server name, signatures, and validity timestamp. This data is used for signing federation requests and events.

```json
{
  "old_verify_keys": {
    "ed25519:0ldk3y": {
      "expired_ts": 1532645052628,
      "key": "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg"
    }
  },
  "server_name": "example.org",
  "signatures": {
    "example.org": {
      "ed25519:auto2": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU"
    }
  },
  "valid_until_ts": 1652262000000,
  "verify_keys": {
    "ed25519:abc123": {
      "key": "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA"
    }
  }
}
```

--------------------------------

### Matrix Public Rooms Directory Request Example (HTTP)

Source: https://spec.matrix.org/v1.16/server-server-api

An example HTTP GET request to the /_matrix/federation/v1/publicRooms endpoint. This endpoint is used to query a server's published room directory, with optional query parameters for pagination and network inclusion.

```http
GET /_matrix/federation/v1/publicRooms?limit=10&include_all_networks=true HTTP/1.1
Host: your-homeserver.tld
```

--------------------------------

### Server-Server API - Request Signing Clarification

Source: https://spec.matrix.org/v1.16/changelog/v1.10/checklist

Clarifies the request signing example for the Server-Server API by using the POST HTTP method, as GET requests do not support request bodies.

```APIDOC
## POST /server-server/api/request-signing

### Description
This endpoint clarifies the request signing process for server-to-server communication. It emphasizes the use of the POST method to accommodate request bodies, which is not possible with GET requests.

### Method
POST

### Endpoint
/server-server/api/request-signing

### Parameters
#### Query Parameters
- **access_token** (string) - Required - The access token for authentication.

#### Request Body
- **data** (object) - Required - The payload to be signed.
  - **key1** (string) - Description of key1
  - **key2** (number) - Description of key2

### Request Example
```json
{
  "data": {
    "key1": "value1",
    "key2": 123
  }
}
```

### Response
#### Success Response (200)
- **signed_data** (string) - The signed request data.

#### Response Example
```json
{
  "signed_data": "signed_payload_string"
}
```
```

--------------------------------

### Matrix Federation Media Download GET Request Example

Source: https://spec.matrix.org/v1.16/server-server-api

This snippet represents a GET request to the `/_matrix/federation/v1/media/download/{mediaId}` endpoint. It's used by servers to download media from a remote server when the content is referenced via an MXC URI.

```http
GET /_matrix/federation/v1/media/download/someMediaId?timeout_ms=10000 HTTP/1.1
Host: remote.server.com
Authorization: Bearer <federation_token>


```

--------------------------------

### Successful Response Example for /lookup (200 OK)

Source: https://spec.matrix.org/v1.16/identity-service-api

An example of a successful JSON response from the /lookup endpoint, showing the mapping of provided addresses to Matrix User IDs.

```json
{
  "mappings": {
    "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org"
  }
}
```

--------------------------------

### Identity Assertion Example Request (GET /_matrix/client/v3/account/whoami)

Source: https://spec.matrix.org/v1.16/application-service-api

This example demonstrates how an application service can assert its identity to the Client-Server API to act as a specific user. It shows the use of an `Authorization` header with a bearer token and a `user_id` query parameter to specify the virtual user.

```http
GET /_matrix/client/v3/account/whoami?user_id=@_irc_user:example.org
Authorization: Bearer YourApplicationServiceTokenHere

```

--------------------------------

### 404 Response Example

Source: https://spec.matrix.org/v1.16/server-server-api

Example of a 404 error response when a room does not exist.

```APIDOC
## 404 /websites/spec_matrix_v1_16

### Description
This endpoint returns a 404 error if the specified room does not exist.

### Method
GET

### Endpoint
/websites/spec_matrix_v1_16

### Parameters

### Request Body

### Request Example

### Response
#### Error Response (404)
- **errcode** (string) - Required: An error code.
- **error** (string) - A human-readable error message.

#### Response Example
```json
{
  "errcode": "M_NOT_FOUND",
  "error": "Room does not exist."
}
```
```

--------------------------------

### Request Body Example for /lookup

Source: https://spec.matrix.org/v1.16/identity-service-api

An example of the JSON request body for the /lookup endpoint. It includes the addresses to query, the hashing algorithm used, and the pepper.

```json
{
  "addresses": [
    "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc",
    "nlo35_T5fzSGZzJApqu8lgIudJvmOQtDaHtr-I4rU7I"
  ],
  "algorithm": "sha256",
  "pepper": "matrixrocks"
}
```

--------------------------------

### Invite API Request Body Example (JSON)

Source: https://spec.matrix.org/v1.16/server-server-api

This is an example of the JSON request body used for inviting a user to a room. It includes the event details and the room version.

```json
{
  "event": {
    "content": {
      "membership": "invite"
    },
    "origin": "matrix.org",
    "origin_server_ts": 1234567890,
    "sender": "@someone:example.org",
    "state_key": "@joe:elsewhere.com",
    "type": "m.room.member"
  },
  "room_version": "2"
}
```

--------------------------------

### Ping 400 Response Example

Source: https://spec.matrix.org/v1.16/application-service-api

An example of a 400 Bad Request response from the /_matrix/app/v1/ping endpoint, indicating that the application service URL is not configured.

```json
{
  "errcode": "M_URL_NOT_SET",
  "error": "Application service doesn't have a URL configured"
}
```

--------------------------------

### m.device_list_update EDU Example (JSON)

Source: https://spec.matrix.org/v1.16/server-server-api

An example of the m.device_list_update Event Description Unit (EDU) in JSON format. This structure is used by servers to push device list updates to each other, including details about device names, keys, and sequence identifiers.

```json
{
  "content": {
    "device_display_name": "Mobile",
    "device_id": "QBUAZIFURK",
    "keys": {
      "algorithms": [
        "m.olm.v1.curve25519-aes-sha2",
        "m.megolm.v1.aes-sha2"
      ],
      "device_id": "JLAFKJWSCS",
      "keys": {
        "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
        "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
      },
      "signatures": {
        "@alice:example.com": {
          "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
        }
      },
      "user_id": "@alice:example.com"
    },
    "prev_id": [
      5
    ],
    "stream_id": 6,
    "user_id": "@john:example.com"
  },
  "edu_type": "m.device_list_update"
}
```

--------------------------------

### Matrix Room Alias Resolution Example

Source: https://spec.matrix.org/v1.16/index

Illustrates the process of resolving a Matrix room alias to a room ID. It shows a GET request to a domain and the server's response, including mappings from aliases to room IDs and servers in the room.

```http
HTTP GET
#matrix:example.org      !aaabaa:matrix.org
       |
       |
_______
|          example.org           |
| Mappings:                      |
| #matrix >> !aaabaa:matrix.org  |
| #golf   >> !wfeiofh:sport.com  |
| #bike   >> !4rguxf:matrix.org  |
|________________________________|

```

--------------------------------

### GET /_matrix/federation/v1/make_join/{roomId}/{userId}

Source: https://spec.matrix.org/v1.16/server-server-api

Asks the receiving server to return information that the sending server will need to prepare a join event to get into the room.

```APIDOC
## GET /_matrix/federation/v1/make_join/{roomId}/{userId}

### Description
Asks the receiving server to return information that the sending server will need to prepare a join event to get into the room.

### Method
GET

### Endpoint
`/_matrix/federation/v1/make_join/{roomId}/{userId}`

### Parameters
#### Path Parameters
- **roomId** (string) - Required - The room ID that is about to be joined.
- **userId** (string) - Required - The user ID the join event will be for.

#### Query Parameters
- **ver** (string) - Optional - The room versions the sending server has support for. Defaults to `[1]`.

### Responses
#### Success Response (200)
- **A template to be used for the rest of the Joining Rooms handshake.** Note that events have a different format depending on the room version - check the room version specification for precise event formats. The response body here describes the common event fields in more detail and may be missing other required fields for a PDU.

#### Error Response (400)
- **The request is invalid, the room the server is attempting to join has a version that is not listed in the `ver` parameters, or the server was unable to validate restricted room conditions.** The error should be passed through to clients so that they may give better feedback to users. New in `v1.2`, the following error conditions might happen: If the room is restricted and none of the conditions can be validated by the server then the `errcode` `M_UNABLE_TO_AUTHORISE_JOIN` must be used. This can happen if the server does not know about any of the rooms listed as conditions, for example. `M_UNABLE_TO_GRANT_JOIN` is returned to denote that a different server should be attempted for the join. This is typically because the resident server can see that the joining user satisfies one or more conditions, such as in the case of restricted rooms, but the resident server would be unable to meet the auth rules governing `join_authorised_via_users_server` on the resulting `m.room.member` event.

#### Error Response (403)
- **The room that the joining server is attempting to join does not permit the user to join.**

#### Error Response (404)
- **The room that the joining server is attempting to join is unknown to the receiving server.**

### Request Example
```json
{
  "ver": ["1"]
}
```

### Response Example (200)
```json
{
  "room_id": "!aBcDeFgHiJkLmNoPqRsT:example.org",
  "canonical_alias": "#some:example.org",
  "aliases": [
    "#some:example.org",
    "#another:example.org"
  ],
  "name": "Example Room Name",
  "topic": "Room topic",
  "join_state": {
    "events": [
      {
        "type": "m.room.create",
        "content": {
          "creator": "@user:example.org",
          "type": "m.room.create"
        },
        "room_id": "!aBcDeFgHiJkLmNoPqRsT:example.org",
        "sender": "@user:example.org",
        "state_key": "",
        "origin": "example.org",
        "origin_server_ts": 1678886400000,
        "event_id": "$abcdef1234567890",
        "signatures": {
          "example.org": {
            "ed25519:1": "..."
          }
        }
      },
      {
        "type": "m.room.member",
        "content": {
          "membership": "join",
          "displayname": "Example User",
          "avatar_url": "mxc://example.org/aBcDeFgHiJkLmNoPqRsT",
          "type": "m.room.member"
        },
        "room_id": "!aBcDeFgHiJkLmNoPqRsT:example.org",
        "sender": "@user:example.org",
        "state_key": "@user:example.org",
        "origin": "example.org",
        "origin_server_ts": 1678886400000,
        "event_id": "$abcdef1234567891",
        "signatures": {
          "example.org": {
            "ed25519:1": "..."
          }
        }
      }
    ]
  }
}
```
```

--------------------------------

### Example Persistent Data Unit (JSON)

Source: https://spec.matrix.org/v1.16/rooms/v11

An example JSON object representing a persistent data unit (event) for room version 1.16. This includes all required fields and an example of the unsigned data.

```json
{
  "auth_events": [
    "$urlsafe_base64_encoded_eventid",
    "$a-different-event-id"
  ],
  "content": {
    "key": "value"
  },
  "depth": 12,
  "hashes": {
    "sha256": "thishashcoversallfieldsincasethisisredacted"
  },
  "origin_server_ts": 1404838188000,
  "prev_events": [
    "$urlsafe_base64_encoded_eventid",
    "$a-different-event-id"
  ],
  "room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
  "sender": "@alice:example.com",
  "signatures": {
    "example.com": {
      "ed25519:key_version": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
    }
  },
  "type": "m.room.message",
  "unsigned": {
    "age": 4612
  }
}
```

--------------------------------

### Account Registration Success Response Example (200)

Source: https://spec.matrix.org/v1.16/identity-service-api

Example of a successful response (200 OK) when registering an account and exchanging an OpenID token for an identity server access token. The response contains the new access token.

```JSON
{
  "token": "abc123_OpaqueString"
}
```

--------------------------------

### Matrix URI Example: Linking to a Room Alias

Source: https://spec.matrix.org/v1.16/appendices

An example demonstrating how to create a Matrix URI to link to a room alias. This shows the practical application of the 'r' type for room aliases.

```text
matrix:r/somewhere:example.org
```

--------------------------------

### Example 200 Response for Room State (Federation API)

Source: https://spec.matrix.org/v1.16/server-server-api

An example JSON structure for a successful response to a request for room state. This includes the authorization chain and the PDU events. Note that the event format can differ based on the room version.

```json
{
  "auth_chain": [
    {
      "content": {
        "see_room_version_spec": "The event format changes depending on the room version."
      },
      "room_id": "!somewhere:example.org",
      "type": "m.room.minimal_pdu"
    }
  ],
  "pdus": [
    {
      "content": {
        "see_room_version_spec": "The event format changes depending on the room version."
      },
      "room_id": "!somewhere:example.org",
      "type": "m.room.minimal_pdu"
    }
  ]
}
```

--------------------------------

### Request Body Example for User Acceptance

Source: https://spec.matrix.org/v1.16/identity-service-api

An example of the JSON request body used to indicate user acceptance of specific URLs. It contains a list of strings, where each string is a URL the user has accepted.

```json
{
  "user_accepts": [
    "https://example.org/somewhere/terms-2.0-en.html"
  ]
}
```

--------------------------------

### Ping 502 Response Example

Source: https://spec.matrix.org/v1.16/application-service-api

An example of a 502 Bad Gateway response from the /_matrix/app/v1/ping endpoint, detailing the error and the original status code from the application service.

```json
{
  "body": "{\"errcode\": \"M_UNKNOWN_TOKEN\"}",
  "errcode": "M_BAD_STATUS",
  "error": "Ping returned status 401",
  "status": 401
}
```

--------------------------------

### Update Room Directory Visibility Request Body Example

Source: https://spec.matrix.org/v1.16/application-service-api

An example of the request body for the PUT /_matrix/client/v3/directory/list/appservice/{networkId}/{roomId} endpoint, specifying the visibility of a room in the published directory.

```json
{
  "visibility": "public"
}
```

--------------------------------

### Federation Transaction Request Body Example (JSON)

Source: https://spec.matrix.org/v1.16/server-server-api

Example of the JSON request body for sending a transaction between homeservers. It includes origin, timestamp, and a list of PDUs. The PDU structure contains content, room ID, and type, with specific content details varying by room version.

```json
{
  "origin": "matrix.org",
  "origin_server_ts": 1234567890,
  "pdus": [
    {
      "content": {
        "see_room_version_spec": "The event format changes depending on the room version."
      },
      "room_id": "!somewhere:example.org",
      "type": "m.room.minimal_pdu"
    }
  ]
}
```

--------------------------------

### Send Join 200 Response Example (JSON)

Source: https://spec.matrix.org/v1.16/server-server-api

This example demonstrates a successful (200 OK) response from the send_join endpoint. It contains the 'auth_chain' and 'state' which represent the room's state prior to the join event, and the 'event' itself, including its content, sender, and other metadata. The response format is standardized for v2.

```json
[
  200,
  {
    "auth_chain": [
      {
        "content": {
          "see_room_version_spec": "The event format changes depending on the room version."
        },
        "room_id": "!somewhere:example.org",
        "type": "m.room.minimal_pdu"
      }
    ],
    "event": {
      "auth_events": [
        "$urlsafe_base64_encoded_eventid",
        "$a-different-event-id"
      ],
      "content": {
        "join_authorised_via_users_server": "@arbitrary:resident.example.com",
        "membership": "join"
      },
      "depth": 12,
      "hashes": {
        "sha256": "thishashcoversallfieldsincasethisisredacted"
      },
      "origin_server_ts": 1404838188000,
      "prev_events": [
        "$urlsafe_base64_encoded_eventid",
        "$a-different-event-id"
      ],
      "room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
      "sender": "@alice:example.com",
      "signatures": {
        "example.com": {
          "ed25519:key_version": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
        },
        "resident.example.com": {
          "ed25519:other_key_version": "a different signature"
        }
      },
      "state_key": "@alice:example.com",
      "type": "m.room.member",
      "unsigned": {
        "age": 4612
      }
    },
    "state": [
      {
        "content": {
          "see_room_version_spec": "The event format changes depending on the room version."
        },
        "room_id": "!somewhere:example.org",
        "type": "m.room.minimal_pdu"
      }
    ]
  }
]
```

--------------------------------

### Send Join Request Body Example (JSON)

Source: https://spec.matrix.org/v1.16/server-server-api

This is an example of the JSON request body for the send_join endpoint. It includes the necessary fields for initiating a room join, such as content, origin, origin server timestamp, sender, state key, and event type. The 'content' field specifies the membership as 'join'.

```json
{
  "content": {
    "membership": "join"
  },
  "origin": "matrix.org",
  "origin_server_ts": 1234567890,
  "sender": "@someone:example.org",
  "state_key": "@someone:example.org",
  "type": "m.room.member"
}
```

--------------------------------

### Example Application Service Registration Configuration

Source: https://spec.matrix.org/v1.16/application-service-api

A YAML configuration file demonstrating how to register an application service. It includes essential fields like ID, URL, authentication tokens, sender localpart, and namespace definitions for users, aliases, and rooms.

```yaml
id: "IRC Bridge"
url: "http://127.0.0.1:1234"
as_token: "30c05ae90a248a4188e620216fa72e349803310ec83e2a77b34fe90be6081f46"
hs_token: "312df522183efd404ec1cd22d2ffa4bbc76a8c1ccf541dd692eef281356bb74e"
sender_localpart: "_irc_bot" # Will result in @_irc_bot:example.org
namespaces:
  users:
    - exclusive: true
      regex: "@_irc_bridge_.*"
  aliases:
    - exclusive: false
      regex: "#_irc_bridge_.*"
  rooms: []

```

--------------------------------

### POST /_matrix/client/v3/createRoom

Source: https://context7.com/context7/spec_matrix_v1_16/llms.txt

Create a new room on the homeserver. This endpoint allows for specifying room name, topic, preset, and inviting users.

```APIDOC
## POST /_matrix/client/v3/createRoom

### Description
Create a new room on the homeserver. This endpoint allows for specifying room name, topic, preset, and inviting users.

### Method
POST

### Endpoint
`https://matrix.example.org/_matrix/client/v3/createRoom`

### Parameters
#### Request Body
- **name** (string) - Optional - The name of the room.
- **topic** (string) - Optional - The topic of the room.
- **preset** (string) - Optional - The preset for the room (e.g., `private_chat`, `public_chat`).
- **invite** (array) - Optional - A list of user IDs to invite to the room.
- **room_alias_name** (string) - Optional - An alias for the room.
- **creation_content** (object) - Optional - Content for room creation.
  - **m.federate** (boolean) - Optional - Whether to allow federation for this room.

### Request Example
```json
{
  "name": "My Private Room",
  "topic": "Discussion about Matrix",
  "preset": "private_chat",
  "invite": ["@bob:example.org"],
  "room_alias_name": "my-room",
  "creation_content": {
    "m.federate": true
  }
}
```

### Response
#### Success Response (200)
- **room_id** (string) - The ID of the newly created room.

#### Response Example
```json
{
  "room_id": "!qporfwt:matrix.org"
}
```
```

--------------------------------

### GET /_matrix/identity/v2/terms API Response

Source: https://spec.matrix.org/v1.16/identity-service-api

This is an example JSON response from the `GET /_matrix/identity/v2/terms` endpoint. It lists the terms of service policies offered by the server, including different languages and versions. Clients parse this to determine which terms require user acceptance.

```json
{
  "policies": {
    "privacy_policy": {
      "en": {
        "name": "Privacy Policy",
        "url": "https://example.org/somewhere/privacy-1.2-en.html"
      },
      "fr": {
        "name": "Politique de confidentialité",
        "url": "https://example.org/somewhere/privacy-1.2-fr.html"
      },
      "version": "1.2"
    },
    "terms_of_service": {
      "en": {
        "name": "Terms of Service",
        "url": "https://example.org/somewhere/terms-2.0-en.html"
      },
      "fr": {
        "name": "Conditions d'utilisation",
        "url": "https://example.org/somewhere/terms-2.0-fr.html"
      },
      "version": "2.0"
    }
  }
}
```

--------------------------------

### POST /keys/query

Source: https://spec.matrix.org/v1.16/changelog/v1.1/checklist

Endpoint to query for device keys and cross-signing information.

```APIDOC
## POST /keys/query

### Description
Queries for device keys and cross-signing information for specified users and devices.

### Method
POST

### Endpoint
/keys/query

### Parameters
#### Request Body
- **users** (array) - Required - A list of user IDs to query keys for.
- **device_ids** (object) - Optional - A map of user IDs to a list of device IDs to query.
- **token** (string) - Optional - A token to paginate results.

### Response
#### Success Response (200)
- **device_keys** (object) - A map of user IDs to their device keys.
- **cross_signing_keys** (object) - A map of user IDs to their cross-signing keys.
- **next_batch** (string) - A token for fetching the next batch of results.

#### Response Example
```json
{
  "device_keys": {
    "@alice:example.com": [
      {
        "device_id": "DEV1",
        "keys": {
          "ed25519:key1": "public_key_data"
        },
        "signatures": {
          "ed25519:key1": "signature_data"
        },
        "user_id": "@alice:example.com",
        "verified": []
      }
    ]
  },
  "cross_signing_keys": {
    "@alice:example.com": [
      {
        "master_key": "master_public_key",
        "user_signing_key": "user_signing_public_key",
        "device_signing_key": "device_signing_public_key",
        "signatures": {
          "ed25519:master_key": "master_signature"
        }
      }
    ]
  },
  "next_batch": "next_token_abc"
}
```
```

--------------------------------

### Media Endpoints

Source: https://spec.matrix.org/v1.16/changelog/v1.11/checklist

Provides access to media configuration, downloads, and thumbnails.

```APIDOC
## GET /_matrix/client/v1/media/config

### Description
Retrieves the media configuration for the server.

### Method
GET

### Endpoint
/_matrix/client/v1/media/config

### Parameters

### Request Example
(No request body)

### Response
#### Success Response (200)
- **config** (object) - The media configuration details.

#### Response Example
```json
{
  "config": {
    "m.upload_filtering": {
      "enabled": true
    }
  }
}
```
```

```APIDOC
## GET /_matrix/client/v1/media/download/{serverName}/{mediaId}

### Description
Downloads a media file from the server.

### Method
GET

### Endpoint
/_matrix/client/v1/media/download/{serverName}/{mediaId}

### Parameters
#### Path Parameters
- **serverName** (string) - Required - The name of the server hosting the media.
- **mediaId** (string) - Required - The ID of the media to download.

### Request Example
(No request body)

### Response
#### Success Response (200)
- The response body will contain the media file content.

#### Response Example
(Binary content of the media file)
```

```APIDOC
## GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}

### Description
Downloads a media file from the server with a specified filename.

### Method
GET

### Endpoint
/_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}

### Parameters
#### Path Parameters
- **serverName** (string) - Required - The name of the server hosting the media.
- **mediaId** (string) - Required - The ID of the media to download.
- **fileName** (string) - Required - The desired filename for the downloaded media.

### Request Example
(No request body)

### Response
#### Success Response (200)
- The response body will contain the media file content.

#### Response Example
(Binary content of the media file)
```

```APIDOC
## GET /_matrix/client/v1/media/preview_url

### Description
Generates a preview for a given URL.

### Method
GET

### Endpoint
/_matrix/client/v1/media/preview_url

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL to preview.

### Request Example
(No request body)

### Response
#### Success Response (200)
- **og:title** (string) - The title of the previewed content.
- **og:description** (string) - The description of the previewed content.
- **og:image** (string) - The URL of the image for the preview.

#### Response Example
```json
{
  "og:title": "Example Title",
  "og:description": "This is an example description.",
  "og:image": "https://example.com/image.jpg"
}
```
```

```APIDOC
## GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}

### Description
Retrieves a thumbnail for a media file.

### Method
GET

### Endpoint
/_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}

### Parameters
#### Path Parameters
- **serverName** (string) - Required - The name of the server hosting the media.
- **mediaId** (string) - Required - The ID of the media for which to get a thumbnail.
#### Query Parameters
- **width** (integer) - Optional - The desired width of the thumbnail.
- **height** (integer) - Optional - The desired height of the thumbnail.
- **animated** (boolean) - Optional - Whether to allow animated thumbnails (e.g., GIFs).

### Request Example
(No request body)

### Response
#### Success Response (200)
- The response body will contain the thumbnail image data.

#### Response Example
(Binary content of the thumbnail image)
```

--------------------------------

### GET /_matrix/federation/v1/backfill/{roomId}

Source: https://spec.matrix.org/v1.16/server-server-api

Retrieves a sliding-window history of previous PDUs that occurred in the given room. It starts from the specified PDU ID(s) and retrieves preceding PDUs up to a specified limit.

```APIDOC
## GET /_matrix/federation/v1/backfill/{roomId}

### Description
Retrieves a sliding-window history of previous PDUs that occurred in the given room. Starting from the PDU ID(s) given in the `v` argument, the PDUs given in `v` and the PDUs that preceded them are retrieved, up to the total number given by the `limit`.

Rate-limited: No
Requires authentication: Yes

### Method
GET

### Endpoint
`/_matrix/federation/v1/backfill/{roomId}`

### Parameters
#### Path Parameters
- **roomId** (string) - Required - The room ID to backfill.

#### Query Parameters
- **limit** (integer) - Required - The maximum number of PDUs to retrieve, including the given events.
- **v** (array of strings) - Required - The event IDs to backfill from.

### Responses
#### Success Response (200)
- **transaction** (object) - A transaction containing the PDUs that preceded the given event(s), including the given event(s), up to the given limit. Note: Though the PDU definitions require that `prev_events` and `auth_events` be limited in number, the response of backfill MUST NOT be validated on these specific restrictions. Due to historical reasons, it is possible that events which were previously accepted would now be rejected by these limitations. The events should be rejected per usual by the `/send`, `/get_missing_events`, and remaining endpoints.

#### Response Example
```json
{
  "transaction_id": "some_transaction_id",
  "origin": "example.org",
  "origin_server_ts": 1500000000000,
  "pdus": [
    {
      "event_id": "$event1:example.org",
      "sender": "@user:example.org",
      "origin": "example.org",
      "origin_server_ts": 1500000000000,
      "room_id": "!some_room:example.org",
      "type": "m.room.message",
      "content": {
        "body": "Hello world!",
        "msgtype": "m.text"
      },
      "prev_events": [],
      "auth_events": []
    }
  ]
}
```
```

--------------------------------

### Media Download/Thumbnail Endpoints (Authenticated)

Source: https://spec.matrix.org/v1.16/changelog/v1.12/checklist

Guest accounts can now download and thumbnail media using authenticated endpoints, as per MSC4189.

```APIDOC
## Media Download/Thumbnail Endpoints (Authenticated)

### Description
Allows guest accounts to access media content through authenticated endpoints, enhancing security and access control as defined in MSC4189.

### Method
GET

### Endpoint
(Specific endpoints for media download and thumbnail generation can be found in the Matrix client-server API specification)

### Parameters
(Authentication parameters will be required for accessing these endpoints)

### Request Example
(Refer to the Matrix client-server API specification for detailed examples)

### Response
(Responses will contain media data or thumbnail representations)
```

--------------------------------

### API Version Check Response

Source: https://spec.matrix.org/v1.16/identity-service-api

Example JSON response for the GET /_matrix/identity/versions endpoint, which returns a list of supported specification versions by the server. Versions are typically in 'vX.Y' or 'rX.Y.Z' format.

```json
{
  "versions": [
    "r0.2.0",
    "r0.2.1",
    "v1.1"
  ]
}
```

--------------------------------

### GET /_matrix/client/v3/thirdparty/protocols and GET /_matrix/client/v3/thirdparty/protocol/{protocol}

Source: https://spec.matrix.org/v1.16/changelog/v1.14/checklist

Documents the `instance_id` field in the responses to `GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`.

```APIDOC
## GET /_matrix/client/v3/thirdparty/protocols and GET /_matrix/client/v3/thirdparty/protocol/{protocol}

### Description
Documents the `instance_id` field in the responses of these endpoints, clarifying the identification of protocol instances.

### Method
GET

### Endpoint
- `/_matrix/client/v3/thirdparty/protocols`
- `/_matrix/client/v3/thirdparty/protocol/{protocol}`

### Parameters
#### Path Parameters
- **protocol** (string) - Required - The protocol to get information about.

#### Query Parameters

#### Request Body

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **protocols** (array) - A list of third-party protocols.
  - **instances** (array) - A list of instances for each protocol.
    - **instance_id** (string) - The unique identifier for a protocol instance.

#### Response Example
```json
{
  "protocols": [
    {
      "brand": "Example Protocol",
      "icon": "mxc:example.com/some/hash",
      "name": "example",
      "instances": [
        {
          "instance_id": "instance1",
          "desc": "An example instance."
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Matrix 200 Response Device List JSON

Source: https://spec.matrix.org/v1.16/server-server-api

Example JSON response for a successful (200 OK) device list query in Matrix. It includes user ID, stream ID, master and self-signing keys, and a list of user devices with their respective keys and signatures. This structure is crucial for understanding device identity and encryption setup.

```json
{
  "devices": [
    {
      "device_display_name": "Alice's Mobile Phone",
      "device_id": "JLAFKJWSCS",
      "keys": {
        "algorithms": [
          "m.olm.v1.curve25519-aes-sha2",
          "m.megolm.v1.aes-sha2"
        ],
        "device_id": "JLAFKJWSCS",
        "keys": {
          "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
          "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
        },
        "signatures": {
          "@alice:example.com": {
            "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
          }
        },
        "user_id": "@alice:example.com"
      }
    }
  ],
  "master_key": {
    "keys": {
      "ed25519:base64+master+public+key": "base64+master+public+key"
    },
    "usage": [
      "master"
    ],
    "user_id": "@alice:example.com"
  },
  "self_signing_key": {
    "keys": {
      "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key"
    },
    "signatures": {
      "@alice:example.com": {
        "ed25519:base64+master+public+key": "signature+of+self+signing+key"
      }
    },
    "usage": [
      "self_signing"
    ],
    "user_id": "@alice:example.com"
  },
  "stream_id": 5,
  "user_id": "@alice:example.org"
}
```

--------------------------------

### Spec Clarifications - `POST /_matrix/client/v3/login` Response

Source: https://spec.matrix.org/v1.16/changelog/v1.12/checklist

Clarification that `window.matrixLogin.onLogin` is called with the response body of `POST /_matrix/client/v3/login`.

```APIDOC
## Spec Clarifications - `POST /_matrix/client/v3/login` Response

### Description
This clarification states that the `window.matrixLogin.onLogin` callback is invoked with the entire response body from the `POST /_matrix/client/v3/login` endpoint.

### Details
- `window.matrixLogin.onLogin` receives the full response body of the login request.
```

--------------------------------

### POST /_matrix/media/v1/create

Source: https://spec.matrix.org/v1.16/changelog/v1.7/checklist

Creates a new media upload endpoint. This is part of the asynchronous media upload support.

```APIDOC
## POST /_matrix/media/v1/create

### Description
Creates a new media upload endpoint, allowing for asynchronous uploads.

### Method
POST

### Endpoint
/_matrix/media/v1/create

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **content_uri** (string) - The URI for the uploaded media.
- **max_upload_size** (integer) - The maximum upload size in bytes.

#### Response Example
```json
{
  "content_uri": "mxc://example.com/some_media_id",
  "max_upload_size": 10485760
}
```
```

--------------------------------

### Request Body Example for Public Rooms API (JSON)

Source: https://spec.matrix.org/v1.16/server-server-api

This is an example of a request body sent to the POST /_matrix/federation/v1/publicRooms endpoint. It demonstrates how to filter the results by a generic search term ('foo') and specific room types (null for rooms without a type, and 'm.space'). It also includes parameters for limiting the number of results and specifying a third-party instance.

```json
{
  "filter": {
    "generic_search_term": "foo",
    "room_types": [
      null,
      "m.space"
    ]
  },
  "include_all_networks": false,
  "limit": 10,
  "third_party_instance_id": "irc-freenode"
}
```

--------------------------------

### Spec Clarifications - `GET /.well-known/matrix/client` Additional Properties

Source: https://spec.matrix.org/v1.16/changelog/v1.12/checklist

Clarification that additional properties in `GET /.well-known/matrix/client` do not necessarily have to be objects.

```APIDOC
## Spec Clarifications - `GET /.well-known/matrix/client` Additional Properties

### Description
This clarification states that additional properties returned by the `GET /.well-known/matrix/client` endpoint are not strictly required to be objects, allowing for more flexible data structures.

### Details
- Additional properties in the response can be of various types, not just objects.
```

--------------------------------

### Error Response Example for /lookup (400 Bad Request)

Source: https://spec.matrix.org/v1.16/identity-service-api

An example of an error response from the /lookup endpoint, indicating an invalid pepper.

```json
{
  "errcode": "M_INVALID_PEPPER",
  "error": "Unknown or invalid pepper - has it been rotated?"
}
```

--------------------------------

### Ping 403 Response Example

Source: https://spec.matrix.org/v1.16/application-service-api

An example of a 403 Forbidden response from the /_matrix/app/v1/ping endpoint, indicating an invalid or incorrect access token.

```json
{
  "errcode": "M_FORBIDDEN",
  "error": "Provided access token is not the appservice's as_token"
}
```

--------------------------------

### Ping 504 Response Example

Source: https://spec.matrix.org/v1.16/application-service-api

An example of a 504 Gateway Timeout response from the /_matrix/app/v1/ping endpoint, indicating that the connection to the application service timed out.

```json
{
  "errcode": "M_CONNECTION_TIMEOUT",
  "error": "Connection to application service timed out"
}
```
Tokens:
Raw