---
title: "Add a homeserver (resolves .well-known and validates /versions)"
method: POST
path: "/ocs/v2.php/apps/spreed/api/{apiVersion}/matrix/admin/homeserver"
tags: ["matrix_admin"]
---

# Add a homeserver (resolves .well-known and validates /versions)

`POST /ocs/v2.php/apps/spreed/api/{apiVersion}/matrix/admin/homeserver`

## Request

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

This endpoint requires admin access

## Path parameters

- `apiVersion` 'v1', required

## Headers

- `OCS-APIRequest` boolean, required

## Request body

- object
  - `serverName` string, required: Matrix server name, e.g. example.org
  - `name` string: Label shown to users
  - `baseUrl` string: Optional client API base URL override

## Response `201`

Homeserver added

- object
  - `ocs` object, required
    - `meta` OCSMeta, required
      - `status` string, required
      - `statuscode` integer, required
      - `message` string
      - `totalitems` string
      - `itemsperpage` string
    - `data` MatrixHomeserver, required
      - `id` string, required: SnowflakeID
      - `name` string, required
      - `serverName` string, required
      - `baseUrl` string, required
      - `enabled` boolean, required
      - `specVersions` string[], required

## Other responses

- `400`: Invalid or duplicate server name
- `401`: Current user is not logged in
- `403`: Logged in account must be an admin
- `502`: Server unreachable or not a Matrix homeserver

## Changes

- **2026-10-08** `793a2d8213eb`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nextcloud/apis/spreed-full/changes/ocs/v2.php/apps/spreed/api/:apiVersion/matrix/admin/homeserver/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)