Matrix

https://spec.matrix.org/
Admin
Matrix is an open standard and communication protocol for real-time, decentralized, federated...
Tokens:155,015
Snippets:1,037
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### GET /_matrix/identity/v2/terms 200 response example

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

Example 200 response for GET /_matrix/identity/v2/terms. Shows the policies object with language-specific names and URLs, plus a version for each policy.

```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"
    }
  }
}
```

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

### 200 response example for GET /_matrix/app/v1/thirdparty/user

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

Example of a 200 response body for the GET /_matrix/app/v1/thirdparty/user endpoint. It returns an array of User objects, each with required fields, protocol, and userid properties.

```json
[
  {
    "fields": {
      "user": "jim"
    },
    "protocol": "gitter",
    "userid": "@_gitter_jim:matrix.org"
  }
]
```

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

### 200 response example for GET /_matrix/app/v1/thirdparty/user/{protocol}

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

Example 200 response body for the third-party user lookup endpoint. Returns an array of User objects, each containing fields, protocol, and userid.

```json
[
  {
    "fields": {
      "user": "jim"
    },
    "protocol": "gitter",
    "userid": "@_gitter_jim:matrix.org"
  }
]

```

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

### 404 response example for GET /_matrix/app/v1/thirdparty/user/{protocol}

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

Example 404 error response body. Contains an errcode field with a custom error code.

```json
{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}

```

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

### POST /_matrix/identity/v2/store-invite request body example

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

Example request body for the POST /_matrix/identity/v2/store-invite endpoint. Includes all required fields (address, medium, room_id, sender) and optional fields for room and sender details. The medium must be the literal string "email".

```json
{
  "address": "foo@example.com",
  "medium": "email",
  "room_alias": "#somewhere:example.org",
  "room_avatar_url": "mxc://example.org/s0meM3dia",
  "room_id": "!something:example.org",
  "room_join_rules": "public",
  "room_name": "Bob's Emporium of Messages",
  "room_type": "m.space",
  "sender": "@bob:example.com",
  "sender_avatar_url": "mxc://example.org/an0th3rM3dia",
  "sender_display_name": "Bob Smith"
}
```

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

### POST /_matrix/identity/v2/lookup request body example

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

Request body example for POST /_matrix/identity/v2/lookup. Contains the required fields: addresses, algorithm, and pepper. The addresses are hashed using the specified algorithm and pepper.

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

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

### 200 response example for GET /_matrix/app/v1/thirdparty/location

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

Example of a successful 200 response body for the GET /_matrix/app/v1/thirdparty/location endpoint. It returns an array of Location objects, each with an alias, fields, and protocol. The example shows a single IRC location with the alias '#freenode_#matrix:matrix.org'.

```json
[
  {
    "alias": "#freenode_#matrix:matrix.org",
    "fields": {
      "channel": "#matrix",
      "network": "freenode"
    },
    "protocol": "irc"
  }
]
```

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

### matrix.to URI examples (fully encoded)

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

Examples of matrix.to URIs with full percent-encoding as per RFC 3986. These are valid alternatives to the minimally encoded versions. The examples cover a room alias, a room ID with via, an event in a room, and a user ID.

```text
https://matrix.to/#/%23somewhere%3Aexample.org
```

```text
https://matrix.to/#/%21somewhere%3Aexample.org?via=elsewhere.ca
```

```text
https://matrix.to/#/%21somewhere%3Aexample.org/%24event%3Aexample.org?via=elsewhere.ca
```

```text
https://matrix.to/#/%40alice%3Aexample.org
```

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

### 403 response example for GET /_matrix/app/v1/thirdparty/user/{protocol}

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

Example 403 error response body. Contains an errcode field with a custom error code.

```json
{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}

```

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

### matrix.to URI examples (minimal encoding)

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

Examples of matrix.to URIs with minimal encoding. The first links to a room alias, the second to a room ID with a via parameter, the third to an event in a room, and the fourth to a user ID. Note that encoding is required only when characters could be misinterpreted.

```text
https://matrix.to/#/%23somewhere:example.org
```

```text
https://matrix.to/#/!somewhere:example.org?via=elsewhere.ca
```

```text
https://matrix.to/#/!somewhere:example.org/$event:example.org?via=elsewhere.ca
```

```text
https://matrix.to/#/@alice:example.org
```

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

### 401 response example for GET /_matrix/app/v1/thirdparty/user/{protocol}

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

Example 401 error response body. Contains an errcode field with a custom error code.

```json
{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}

```

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

### Request body example

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

Request body example for the POST /_matrix/identity/v2/validate/email/submitToken endpoint. Contains the required client_secret, sid, and token parameters.

```json
{
  "client_secret": "monkeys_are_GREAT",
  "sid": "1234",
  "token": "atoken"
}
```

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

### GET /_matrix/identity/v2/pubkey/ephemeral/isvalid - 200 response

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

Example response for the GET /_matrix/identity/v2/pubkey/ephemeral/isvalid endpoint. Shows the expected JSON body when the short-term public key is valid.

```json
{
  "valid": true
}
```

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

### POST /_matrix/identity/v2/lookup 400 response example

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

Example 400 response for POST /_matrix/identity/v2/lookup. Shows the M_INVALID_PEPPER error code and a human-readable error message. Clients should call /hash_details to get a new pepper and avoid retry loops.

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

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

### Example event JSON

Source: https://spec.matrix.org/v1.19/rooms/v3

Shows the structure of a typical event in room version 3, including auth_events, content, hashes, prev_events, redacts, signatures, and unsigned fields.

```json
{
  "auth_events": [
    "$base64encodedeventid",
    "$adifferenteventid"
  ],
  "content": {
    "key": "value"
  },
  "depth": 12,
  "hashes": {
    "sha256": "thishashcoversallfieldsincasethisisredacted"
  },
  "origin_server_ts": 1404838188000,
  "prev_events": [
    "$base64encodedeventid",
    "$adifferenteventid"
  ],
  "redacts": "$some/old+event",
  "room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
  "sender": "@alice:example.com",
  "signatures": {
    "example.com": {
      "ed25519:key_version": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
    }
  },
  "type": "m.room.message",
  "unsigned": {
    "age": 4612
  }
}
```

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

### GET /_matrix/identity/versions 200 response

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

Example response body for the version check endpoint, listing supported specification versions.

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

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

### 200 response JSON example

Source: https://spec.matrix.org/v1.19/push-gateway-api

Example JSON response body for a 200 status, showing the 'rejected' array with a sample pushkey. The array may be empty.

```json
{
  "rejected": [
    "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/"
  ]
}
```

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

### GET /_matrix/identity/v2/account - 403 error response

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

Example error response when the user must take action, such as agreeing to terms (M_TERMS_NOT_SIGNED).

```json
{
  "errcode": "M_TERMS_NOT_SIGNED",
  "error": "Please accept our updated terms of service before continuing"
}
```
Tokens:
Raw