diff --git a/docs/usage/administration/admin_api/background_updates.md b/docs/usage/administration/admin_api/background_updates.md
index b36d7fe398..9f6ac7d567 100644
--- a/docs/usage/administration/admin_api/background_updates.md
+++ b/docs/usage/administration/admin_api/background_updates.md
@@ -42,7 +42,6 @@ For each update:
`average_items_per_ms` how many items are processed per millisecond based on an exponential average.
-
## Enabled
This API allow pausing background updates.
@@ -82,3 +81,29 @@ The API returns the `enabled` param.
```
There is also a `GET` version which returns the `enabled` state.
+
+
+## Run
+
+This API schedules a specific background update to run. The job starts immediately after calling the API.
+
+
+The API is:
+
+```
+POST /_synapse/admin/v1/background_updates/start_job
+```
+
+with the following body:
+
+```json
+{
+ "job_name": "populate_stats_process_rooms"
+}
+```
+
+The following JSON body parameters are available:
+
+- `job_name` - A string which job to run. Valid values are:
+ - `populate_stats_process_rooms` - Recalculate the stats for all rooms.
+ - `regenerate_directory` - Recalculate the [user directory](../../../user_directory.md) if it is stale or out of sync.
diff --git a/docs/usage/administration/admin_api/federation.md b/docs/usage/administration/admin_api/federation.md
new file mode 100644
index 0000000000..8f9535f57b
--- /dev/null
+++ b/docs/usage/administration/admin_api/federation.md
@@ -0,0 +1,114 @@
+# Federation API
+
+This API allows a server administrator to manage Synapse's federation with other homeservers.
+
+Note: This API is new, experimental and "subject to change".
+
+## List of destinations
+
+This API gets the current destination retry timing info for all remote servers.
+
+The list contains all the servers with which the server federates,
+regardless of whether an error occurred or not.
+If an error occurs, it may take up to 20 minutes for the error to be displayed here,
+as a complete retry must have failed.
+
+The API is:
+
+A standard request with no filtering:
+
+```
+GET /_synapse/admin/v1/federation/destinations
+```
+
+A response body like the following is returned:
+
+```json
+{
+ "destinations":[
+ {
+ "destination": "matrix.org",
+ "retry_last_ts": 1557332397936,
+ "retry_interval": 3000000,
+ "failure_ts": 1557329397936,
+ "last_successful_stream_ordering": null
+ }
+ ],
+ "total": 1
+}
+```
+
+To paginate, check for `next_token` and if present, call the endpoint again
+with `from` set to the value of `next_token`. This will return a new page.
+
+If the endpoint does not return a `next_token` then there are no more destinations
+to paginate through.
+
+**Parameters**
+
+The following query parameters are available:
+
+- `from` - Offset in the returned list. Defaults to `0`.
+- `limit` - Maximum amount of destinations to return. Defaults to `100`.
+- `order_by` - The method in which to sort the returned list of destinations.
+ Valid values are:
+ - `destination` - Destinations are ordered alphabetically by remote server name.
+ This is the default.
+ - `retry_last_ts` - Destinations are ordered by time of last retry attempt in ms.
+ - `retry_interval` - Destinations are ordered by how long until next retry in ms.
+ - `failure_ts` - Destinations are ordered by when the server started failing in ms.
+ - `last_successful_stream_ordering` - Destinations are ordered by the stream ordering
+ of the most recent successfully-sent PDU.
+- `dir` - Direction of room order. Either `f` for forwards or `b` for backwards. Setting
+ this value to `b` will reverse the above sort order. Defaults to `f`.
+
+*Caution:* The database only has an index on the column `destination`.
+This means that if a different sort order is used,
+this can cause a large load on the database, especially for large environments.
+
+**Response**
+
+The following fields are returned in the JSON response body:
+
+- `destinations` - An array of objects, each containing information about a destination.
+ Destination objects contain the following fields:
+ - `destination` - string - Name of the remote server to federate.
+ - `retry_last_ts` - integer - The last time Synapse tried and failed to reach the
+ remote server, in ms. This is `0` if the last attempt to communicate with the
+ remote server was successful.
+ - `retry_interval` - integer - How long since the last time Synapse tried to reach
+ the remote server before trying again, in ms. This is `0` if no further retrying occuring.
+ - `failure_ts` - nullable integer - The first time Synapse tried and failed to reach the
+ remote server, in ms. This is `null` if communication with the remote server has never failed.
+ - `last_successful_stream_ordering` - nullable integer - The stream ordering of the most
+ recent successfully-sent [PDU](understanding_synapse_through_grafana_graphs.md#federation)
+ to this destination, or `null` if this information has not been tracked yet.
+- `next_token`: string representing a positive integer - Indication for pagination. See above.
+- `total` - integer - Total number of destinations.
+
+# Destination Details API
+
+This API gets the retry timing info for a specific remote server.
+
+The API is:
+
+```
+GET /_synapse/admin/v1/federation/destinations/<destination>
+```
+
+A response body like the following is returned:
+
+```json
+{
+ "destination": "matrix.org",
+ "retry_last_ts": 1557332397936,
+ "retry_interval": 3000000,
+ "failure_ts": 1557329397936,
+ "last_successful_stream_ordering": null
+}
+```
+
+**Response**
+
+The response fields are the same like in the `destinations` array in
+[List of destinations](#list-of-destinations) response.
|
