---
title: "Join a Matrix room by its address"
method: POST
path: "/ocs/v2.php/apps/spreed/api/{apiVersion}/matrix/room/join"
tags: ["matrix_room"]
---

# Join a Matrix room by its address

`POST /ocs/v2.php/apps/spreed/api/{apiVersion}/matrix/room/join`

## Request

- The document declares no server URL.
- Auth: one of:
  - HTTP bearer
  - HTTP basic

## Path parameters

- `apiVersion` 'v1', required

## Headers

- `OCS-APIRequest` boolean, required

## Request body

- object
  - `reference` string, required: Room alias like `#room:example.org`, room id or a matrix.to link

## Response `200`

Room joined, the token is null when the conversation is still created by another sync

- object
  - `ocs` object, required
    - `meta` OCSMeta, required
      - `status` string, required
      - `statuscode` integer, required
      - `message` string
      - `totalitems` string
      - `itemsperpage` string
    - `data` object, required
      - `token` string, nullable, required

## Other responses

- `400`: The reference is not a Matrix room
- `401`: Current user is not logged in
- `404`: Matrix account not found, or the room does not exist or can not be joined
- `502`: The Matrix homeserver could not be reached

## Changes

- **2026-10-11** `550ac31a5f64`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nextcloud/apis/spreed-full/changes/ocs/v2.php/apps/spreed/api/:apiVersion/matrix/room/join/post.md)

---

[API](https://skmtc.dev/nextcloud/apis/spreed-full.md) - [All operations](https://skmtc.dev/nextcloud/apis/spreed-full/llms.txt) - [OpenAPI document](https://skmtc.dev/nextcloud/apis/spreed-full/revisions/1d24d3b8fec0?raw)