mirror of
https://github.com/element-hq/synapse.git
synced 2025-03-28 10:28:32 +00:00
deploy: 2d044667cf
This commit is contained in:
richvdh
parent
44b8bf9404
commit
762f838ace
4 changed files with 48 additions and 94 deletions
|
|
@ -184,19 +184,12 @@
|
|||
|
||||
<h1 id="contents"><a class="header" href="#contents">Contents</a></h1>
|
||||
<ul>
|
||||
<li><a href="#list-room-api">List Room API</a>
|
||||
<ul>
|
||||
<li><a href="#parameters">Parameters</a></li>
|
||||
<li><a href="#usage">Usage</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#list-room-api">List Room API</a></li>
|
||||
<li><a href="#room-details-api">Room Details API</a></li>
|
||||
<li><a href="#room-members-api">Room Members API</a></li>
|
||||
<li><a href="#room-state-api">Room State API</a></li>
|
||||
<li><a href="#delete-room-api">Delete Room API</a>
|
||||
<ul>
|
||||
<li><a href="#parameters-1">Parameters</a></li>
|
||||
<li><a href="#response">Response</a></li>
|
||||
<li><a href="#undoing-room-shutdowns">Undoing room shutdowns</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
|
|
@ -208,7 +201,7 @@
|
|||
<p>The List Room admin API allows server admins to get a list of rooms on their
|
||||
server. There are various parameters available that allow for filtering and
|
||||
sorting the returned list. This API supports pagination.</p>
|
||||
<h2 id="parameters"><a class="header" href="#parameters">Parameters</a></h2>
|
||||
<p><strong>Parameters</strong></p>
|
||||
<p>The following query parameters are available:</p>
|
||||
<ul>
|
||||
<li><code>from</code> - Offset in the returned list. Defaults to <code>0</code>.</li>
|
||||
|
|
@ -237,6 +230,7 @@ this value to <code>b</code> will reverse the above sort order. Defaults to <cod
|
|||
<li><code>search_term</code> - Filter rooms by their room name. Search term can be contained in any
|
||||
part of the room name. Defaults to no filtering.</li>
|
||||
</ul>
|
||||
<p><strong>Response</strong></p>
|
||||
<p>The following fields are possible in the JSON response body:</p>
|
||||
<ul>
|
||||
<li><code>rooms</code> - An array of objects, each containing information about a room.
|
||||
|
|
@ -276,13 +270,11 @@ the value of <code>next_batch</code>.</li>
|
|||
Use <code>prev_batch</code> for the <code>from</code> value in the next request to
|
||||
get the "previous page" of results.</li>
|
||||
</ul>
|
||||
<h2 id="usage"><a class="header" href="#usage">Usage</a></h2>
|
||||
<p>The API is:</p>
|
||||
<p>A standard request with no filtering:</p>
|
||||
<pre><code>GET /_synapse/admin/v1/rooms
|
||||
|
||||
{}
|
||||
</code></pre>
|
||||
<p>Response:</p>
|
||||
<p>A response body like the following is returned:</p>
|
||||
<pre><code class="language-jsonc">{
|
||||
"rooms": [
|
||||
{
|
||||
|
|
@ -325,10 +317,8 @@ get the "previous page" of results.</li>
|
|||
</code></pre>
|
||||
<p>Filtering by room name:</p>
|
||||
<pre><code>GET /_synapse/admin/v1/rooms?search_term=TWIM
|
||||
|
||||
{}
|
||||
</code></pre>
|
||||
<p>Response:</p>
|
||||
<p>A response body like the following is returned:</p>
|
||||
<pre><code class="language-json">{
|
||||
"rooms": [
|
||||
{
|
||||
|
|
@ -354,10 +344,8 @@ get the "previous page" of results.</li>
|
|||
</code></pre>
|
||||
<p>Paginating through a list of rooms:</p>
|
||||
<pre><code>GET /_synapse/admin/v1/rooms?order_by=size
|
||||
|
||||
{}
|
||||
</code></pre>
|
||||
<p>Response:</p>
|
||||
<p>A response body like the following is returned:</p>
|
||||
<pre><code class="language-jsonc">{
|
||||
"rooms": [
|
||||
{
|
||||
|
|
@ -404,10 +392,8 @@ than returned in this request, and we need to make another request to get them.
|
|||
To get the next batch of room results, we repeat our request, setting the <code>from</code>
|
||||
parameter to the value of <code>next_token</code>.</p>
|
||||
<pre><code>GET /_synapse/admin/v1/rooms?order_by=size&from=100
|
||||
|
||||
{}
|
||||
</code></pre>
|
||||
<p>Response:</p>
|
||||
<p>A response body like the following is returned:</p>
|
||||
<pre><code class="language-jsonc">{
|
||||
"rooms": [
|
||||
{
|
||||
|
|
@ -473,13 +459,10 @@ end of the list.</p>
|
|||
<li><code>history_visibility</code> - Who can see the room history. One of: ["invited", "joined", "shared", "world_readable"].</li>
|
||||
<li><code>state_events</code> - Total number of state_events of a room. Complexity of the room.</li>
|
||||
</ul>
|
||||
<h2 id="usage-1"><a class="header" href="#usage-1">Usage</a></h2>
|
||||
<p>A standard request:</p>
|
||||
<p>The API is:</p>
|
||||
<pre><code>GET /_synapse/admin/v1/rooms/<room_id>
|
||||
|
||||
{}
|
||||
</code></pre>
|
||||
<p>Response:</p>
|
||||
<p>A response body like the following is returned:</p>
|
||||
<pre><code class="language-json">{
|
||||
"room_id": "!mscvqgqpHYjBGDxNym:matrix.org",
|
||||
"name": "Music Theory",
|
||||
|
|
@ -507,13 +490,10 @@ end of the list.</p>
|
|||
<li><code>members</code> - A list of all the members that are present in the room, represented by their ids.</li>
|
||||
<li><code>total</code> - Total number of members in the room.</li>
|
||||
</ul>
|
||||
<h2 id="usage-2"><a class="header" href="#usage-2">Usage</a></h2>
|
||||
<p>A standard request:</p>
|
||||
<p>The API is:</p>
|
||||
<pre><code>GET /_synapse/admin/v1/rooms/<room_id>/members
|
||||
|
||||
{}
|
||||
</code></pre>
|
||||
<p>Response:</p>
|
||||
<p>A response body like the following is returned:</p>
|
||||
<pre><code class="language-json">{
|
||||
"members": [
|
||||
"@foo:matrix.org",
|
||||
|
|
@ -529,13 +509,10 @@ end of the list.</p>
|
|||
<ul>
|
||||
<li><code>state</code> - The current state of the room at the time of request.</li>
|
||||
</ul>
|
||||
<h2 id="usage-3"><a class="header" href="#usage-3">Usage</a></h2>
|
||||
<p>A standard request:</p>
|
||||
<p>The API is:</p>
|
||||
<pre><code>GET /_synapse/admin/v1/rooms/<room_id>/state
|
||||
|
||||
{}
|
||||
</code></pre>
|
||||
<p>Response:</p>
|
||||
<p>A response body like the following is returned:</p>
|
||||
<pre><code class="language-json">{
|
||||
"state": [
|
||||
{"type": "m.room.create", "state_key": "", "etc": true},
|
||||
|
|
@ -589,7 +566,7 @@ server admin: see <a href="../usage/administration/admin_api">Admin API</a>.</p>
|
|||
"new_room_id": "!newroomid:example.com"
|
||||
}
|
||||
</code></pre>
|
||||
<h2 id="parameters-1"><a class="header" href="#parameters-1">Parameters</a></h2>
|
||||
<p><strong>Parameters</strong></p>
|
||||
<p>The following parameters should be set in the URL:</p>
|
||||
<ul>
|
||||
<li><code>room_id</code> - The ID of the room.</li>
|
||||
|
|
@ -616,7 +593,7 @@ use this unless a regular <code>purge</code> operation fails, as it could leave
|
|||
clients in a confused state.</li>
|
||||
</ul>
|
||||
<p>The JSON body must not be empty. The body must be at least <code>{}</code>.</p>
|
||||
<h2 id="response"><a class="header" href="#response">Response</a></h2>
|
||||
<p><strong>Response</strong></p>
|
||||
<p>The following fields are returned in the JSON response body:</p>
|
||||
<ul>
|
||||
<li><code>kicked_users</code> - An array of users (<code>user_id</code>) that were kicked.</li>
|
||||
|
|
@ -663,10 +640,10 @@ to recover at all:</p>
|
|||
If the user is not in the room, and it is not publicly joinable, then invite the user.</p>
|
||||
<p>By default the server admin (the caller) is granted power, but another user can
|
||||
optionally be specified, e.g.:</p>
|
||||
<pre><code> POST /_synapse/admin/v1/rooms/<room_id_or_alias>/make_room_admin
|
||||
{
|
||||
"user_id": "@foo:example.com"
|
||||
}
|
||||
<pre><code>POST /_synapse/admin/v1/rooms/<room_id_or_alias>/make_room_admin
|
||||
{
|
||||
"user_id": "@foo:example.com"
|
||||
}
|
||||
</code></pre>
|
||||
<h1 id="forward-extremities-admin-api"><a class="header" href="#forward-extremities-admin-api">Forward Extremities Admin API</a></h1>
|
||||
<p>Enables querying and deleting forward extremities from rooms. When a lot of forward
|
||||
|
|
@ -674,7 +651,7 @@ extremities accumulate in a room, performance can become degraded. For details,
|
|||
<a href="https://github.com/matrix-org/synapse/issues/1760">#1760</a>.</p>
|
||||
<h2 id="check-for-forward-extremities"><a class="header" href="#check-for-forward-extremities">Check for forward extremities</a></h2>
|
||||
<p>To check the status of forward extremities for a room:</p>
|
||||
<pre><code> GET /_synapse/admin/v1/rooms/<room_id_or_alias>/forward_extremities
|
||||
<pre><code>GET /_synapse/admin/v1/rooms/<room_id_or_alias>/forward_extremities
|
||||
</code></pre>
|
||||
<p>A response as follows will be returned:</p>
|
||||
<pre><code class="language-json">{
|
||||
|
|
@ -687,7 +664,7 @@ extremities accumulate in a room, performance can become degraded. For details,
|
|||
"received_ts": 1611263016761
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
</code></pre>
|
||||
<h2 id="deleting-forward-extremities"><a class="header" href="#deleting-forward-extremities">Deleting forward extremities</a></h2>
|
||||
<p><strong>WARNING</strong>: Please ensure you know what you're doing and have read
|
||||
|
|
@ -695,7 +672,7 @@ the related issue <a href="https://github.com/matrix-org/synapse/issues/1760">#1
|
|||
Under no situations should this API be executed as an automated maintenance task!</p>
|
||||
<p>If a room has lots of forward extremities, the extra can be
|
||||
deleted as follows:</p>
|
||||
<pre><code> DELETE /_synapse/admin/v1/rooms/<room_id_or_alias>/forward_extremities
|
||||
<pre><code>DELETE /_synapse/admin/v1/rooms/<room_id_or_alias>/forward_extremities
|
||||
</code></pre>
|
||||
<p>A response as follows will be returned, indicating the amount of forward extremities
|
||||
that were deleted.</p>
|
||||
|
|
|
|||
|
|
@ -8961,19 +8961,12 @@ server admin: see <a href="admin_api/../usage/administration/admin_api">Admin AP
|
|||
</code></pre>
|
||||
<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="contents-2"><a class="header" href="#contents-2">Contents</a></h1>
|
||||
<ul>
|
||||
<li><a href="admin_api/rooms.html#list-room-api">List Room API</a>
|
||||
<ul>
|
||||
<li><a href="admin_api/rooms.html#parameters">Parameters</a></li>
|
||||
<li><a href="admin_api/rooms.html#usage">Usage</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="admin_api/rooms.html#list-room-api">List Room API</a></li>
|
||||
<li><a href="admin_api/rooms.html#room-details-api">Room Details API</a></li>
|
||||
<li><a href="admin_api/rooms.html#room-members-api">Room Members API</a></li>
|
||||
<li><a href="admin_api/rooms.html#room-state-api">Room State API</a></li>
|
||||
<li><a href="admin_api/rooms.html#delete-room-api">Delete Room API</a>
|
||||
<ul>
|
||||
<li><a href="admin_api/rooms.html#parameters-1">Parameters</a></li>
|
||||
<li><a href="admin_api/rooms.html#response">Response</a></li>
|
||||
<li><a href="admin_api/rooms.html#undoing-room-shutdowns">Undoing room shutdowns</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
|
|
@ -8985,7 +8978,7 @@ server admin: see <a href="admin_api/../usage/administration/admin_api">Admin AP
|
|||
<p>The List Room admin API allows server admins to get a list of rooms on their
|
||||
server. There are various parameters available that allow for filtering and
|
||||
sorting the returned list. This API supports pagination.</p>
|
||||
<h2 id="parameters-1"><a class="header" href="#parameters-1">Parameters</a></h2>
|
||||
<p><strong>Parameters</strong></p>
|
||||
<p>The following query parameters are available:</p>
|
||||
<ul>
|
||||
<li><code>from</code> - Offset in the returned list. Defaults to <code>0</code>.</li>
|
||||
|
|
@ -9014,6 +9007,7 @@ this value to <code>b</code> will reverse the above sort order. Defaults to <cod
|
|||
<li><code>search_term</code> - Filter rooms by their room name. Search term can be contained in any
|
||||
part of the room name. Defaults to no filtering.</li>
|
||||
</ul>
|
||||
<p><strong>Response</strong></p>
|
||||
<p>The following fields are possible in the JSON response body:</p>
|
||||
<ul>
|
||||
<li><code>rooms</code> - An array of objects, each containing information about a room.
|
||||
|
|
@ -9053,13 +9047,11 @@ the value of <code>next_batch</code>.</li>
|
|||
Use <code>prev_batch</code> for the <code>from</code> value in the next request to
|
||||
get the "previous page" of results.</li>
|
||||
</ul>
|
||||
<h2 id="usage-2"><a class="header" href="#usage-2">Usage</a></h2>
|
||||
<p>The API is:</p>
|
||||
<p>A standard request with no filtering:</p>
|
||||
<pre><code>GET /_synapse/admin/v1/rooms
|
||||
|
||||
{}
|
||||
</code></pre>
|
||||
<p>Response:</p>
|
||||
<p>A response body like the following is returned:</p>
|
||||
<pre><code class="language-jsonc">{
|
||||
"rooms": [
|
||||
{
|
||||
|
|
@ -9102,10 +9094,8 @@ get the "previous page" of results.</li>
|
|||
</code></pre>
|
||||
<p>Filtering by room name:</p>
|
||||
<pre><code>GET /_synapse/admin/v1/rooms?search_term=TWIM
|
||||
|
||||
{}
|
||||
</code></pre>
|
||||
<p>Response:</p>
|
||||
<p>A response body like the following is returned:</p>
|
||||
<pre><code class="language-json">{
|
||||
"rooms": [
|
||||
{
|
||||
|
|
@ -9131,10 +9121,8 @@ get the "previous page" of results.</li>
|
|||
</code></pre>
|
||||
<p>Paginating through a list of rooms:</p>
|
||||
<pre><code>GET /_synapse/admin/v1/rooms?order_by=size
|
||||
|
||||
{}
|
||||
</code></pre>
|
||||
<p>Response:</p>
|
||||
<p>A response body like the following is returned:</p>
|
||||
<pre><code class="language-jsonc">{
|
||||
"rooms": [
|
||||
{
|
||||
|
|
@ -9181,10 +9169,8 @@ than returned in this request, and we need to make another request to get them.
|
|||
To get the next batch of room results, we repeat our request, setting the <code>from</code>
|
||||
parameter to the value of <code>next_token</code>.</p>
|
||||
<pre><code>GET /_synapse/admin/v1/rooms?order_by=size&from=100
|
||||
|
||||
{}
|
||||
</code></pre>
|
||||
<p>Response:</p>
|
||||
<p>A response body like the following is returned:</p>
|
||||
<pre><code class="language-jsonc">{
|
||||
"rooms": [
|
||||
{
|
||||
|
|
@ -9250,13 +9236,10 @@ end of the list.</p>
|
|||
<li><code>history_visibility</code> - Who can see the room history. One of: ["invited", "joined", "shared", "world_readable"].</li>
|
||||
<li><code>state_events</code> - Total number of state_events of a room. Complexity of the room.</li>
|
||||
</ul>
|
||||
<h2 id="usage-3"><a class="header" href="#usage-3">Usage</a></h2>
|
||||
<p>A standard request:</p>
|
||||
<p>The API is:</p>
|
||||
<pre><code>GET /_synapse/admin/v1/rooms/<room_id>
|
||||
|
||||
{}
|
||||
</code></pre>
|
||||
<p>Response:</p>
|
||||
<p>A response body like the following is returned:</p>
|
||||
<pre><code class="language-json">{
|
||||
"room_id": "!mscvqgqpHYjBGDxNym:matrix.org",
|
||||
"name": "Music Theory",
|
||||
|
|
@ -9284,13 +9267,10 @@ end of the list.</p>
|
|||
<li><code>members</code> - A list of all the members that are present in the room, represented by their ids.</li>
|
||||
<li><code>total</code> - Total number of members in the room.</li>
|
||||
</ul>
|
||||
<h2 id="usage-4"><a class="header" href="#usage-4">Usage</a></h2>
|
||||
<p>A standard request:</p>
|
||||
<p>The API is:</p>
|
||||
<pre><code>GET /_synapse/admin/v1/rooms/<room_id>/members
|
||||
|
||||
{}
|
||||
</code></pre>
|
||||
<p>Response:</p>
|
||||
<p>A response body like the following is returned:</p>
|
||||
<pre><code class="language-json">{
|
||||
"members": [
|
||||
"@foo:matrix.org",
|
||||
|
|
@ -9306,13 +9286,10 @@ end of the list.</p>
|
|||
<ul>
|
||||
<li><code>state</code> - The current state of the room at the time of request.</li>
|
||||
</ul>
|
||||
<h2 id="usage-5"><a class="header" href="#usage-5">Usage</a></h2>
|
||||
<p>A standard request:</p>
|
||||
<p>The API is:</p>
|
||||
<pre><code>GET /_synapse/admin/v1/rooms/<room_id>/state
|
||||
|
||||
{}
|
||||
</code></pre>
|
||||
<p>Response:</p>
|
||||
<p>A response body like the following is returned:</p>
|
||||
<pre><code class="language-json">{
|
||||
"state": [
|
||||
{"type": "m.room.create", "state_key": "", "etc": true},
|
||||
|
|
@ -9366,7 +9343,7 @@ server admin: see <a href="admin_api/../usage/administration/admin_api">Admin AP
|
|||
"new_room_id": "!newroomid:example.com"
|
||||
}
|
||||
</code></pre>
|
||||
<h2 id="parameters-2"><a class="header" href="#parameters-2">Parameters</a></h2>
|
||||
<p><strong>Parameters</strong></p>
|
||||
<p>The following parameters should be set in the URL:</p>
|
||||
<ul>
|
||||
<li><code>room_id</code> - The ID of the room.</li>
|
||||
|
|
@ -9393,7 +9370,7 @@ use this unless a regular <code>purge</code> operation fails, as it could leave
|
|||
clients in a confused state.</li>
|
||||
</ul>
|
||||
<p>The JSON body must not be empty. The body must be at least <code>{}</code>.</p>
|
||||
<h2 id="response"><a class="header" href="#response">Response</a></h2>
|
||||
<p><strong>Response</strong></p>
|
||||
<p>The following fields are returned in the JSON response body:</p>
|
||||
<ul>
|
||||
<li><code>kicked_users</code> - An array of users (<code>user_id</code>) that were kicked.</li>
|
||||
|
|
@ -9440,10 +9417,10 @@ to recover at all:</p>
|
|||
If the user is not in the room, and it is not publicly joinable, then invite the user.</p>
|
||||
<p>By default the server admin (the caller) is granted power, but another user can
|
||||
optionally be specified, e.g.:</p>
|
||||
<pre><code> POST /_synapse/admin/v1/rooms/<room_id_or_alias>/make_room_admin
|
||||
{
|
||||
"user_id": "@foo:example.com"
|
||||
}
|
||||
<pre><code>POST /_synapse/admin/v1/rooms/<room_id_or_alias>/make_room_admin
|
||||
{
|
||||
"user_id": "@foo:example.com"
|
||||
}
|
||||
</code></pre>
|
||||
<h1 id="forward-extremities-admin-api"><a class="header" href="#forward-extremities-admin-api">Forward Extremities Admin API</a></h1>
|
||||
<p>Enables querying and deleting forward extremities from rooms. When a lot of forward
|
||||
|
|
@ -9451,7 +9428,7 @@ extremities accumulate in a room, performance can become degraded. For details,
|
|||
<a href="https://github.com/matrix-org/synapse/issues/1760">#1760</a>.</p>
|
||||
<h2 id="check-for-forward-extremities"><a class="header" href="#check-for-forward-extremities">Check for forward extremities</a></h2>
|
||||
<p>To check the status of forward extremities for a room:</p>
|
||||
<pre><code> GET /_synapse/admin/v1/rooms/<room_id_or_alias>/forward_extremities
|
||||
<pre><code>GET /_synapse/admin/v1/rooms/<room_id_or_alias>/forward_extremities
|
||||
</code></pre>
|
||||
<p>A response as follows will be returned:</p>
|
||||
<pre><code class="language-json">{
|
||||
|
|
@ -9464,7 +9441,7 @@ extremities accumulate in a room, performance can become degraded. For details,
|
|||
"received_ts": 1611263016761
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
</code></pre>
|
||||
<h2 id="deleting-forward-extremities"><a class="header" href="#deleting-forward-extremities">Deleting forward extremities</a></h2>
|
||||
<p><strong>WARNING</strong>: Please ensure you know what you're doing and have read
|
||||
|
|
@ -9472,7 +9449,7 @@ the related issue <a href="https://github.com/matrix-org/synapse/issues/1760">#1
|
|||
Under no situations should this API be executed as an automated maintenance task!</p>
|
||||
<p>If a room has lots of forward extremities, the extra can be
|
||||
deleted as follows:</p>
|
||||
<pre><code> DELETE /_synapse/admin/v1/rooms/<room_id_or_alias>/forward_extremities
|
||||
<pre><code>DELETE /_synapse/admin/v1/rooms/<room_id_or_alias>/forward_extremities
|
||||
</code></pre>
|
||||
<p>A response as follows will be returned, indicating the amount of forward extremities
|
||||
that were deleted.</p>
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
Loading…
Add table
Reference in a new issue