The documentation currently uses Hugo to generate a static site from Markdown.
diff --git a/archetypes/methods.md b/archetypes/methods.md
index 261db256..ba3ea7f7 100644
--- a/archetypes/methods.md
+++ b/archetypes/methods.md
@@ -38,14 +38,14 @@ Authorization
**Internal parameter.** Use HTTP `Link` header for pagination.
-max_id
-: String. Return results older than ID.
+max_id
+: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
since_id
-: String. Return results newer than ID.
+: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
min_id
-: String. Return results immediately newer than ID.
+: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
limit
: Integer. Maximum number of results to return. Defaults to 20 statuses or 40 accounts. Max twice the default limit.
diff --git a/content/en/admin/config.md b/content/en/admin/config.md
index cf13795d..c9025248 100644
--- a/content/en/admin/config.md
+++ b/content/en/admin/config.md
@@ -367,12 +367,23 @@ Defaults to value of `REDIS_NAMESPACE`.
### Elasticsearch {#elasticsearch}
-{{< page-ref page="admin/optional/elasticsearch" >}}
+{{< page-ref page="admin/elasticsearch" >}}
#### `ES_ENABLED`
If set to `true`, Mastodon will use Elasticsearch for its search functions.
+#### `ES_PRESET`
+
+It controls the ElasticSearch indices configuration (number of shards and replica).
+
+Possible values are:
+- `single_node_cluster` (default)
+- `small_cluster`
+- `large_cluster`
+
+See the [ElasticSearch setup page for details on each setting](../elasticsearch#choosing-the-correct-preset).
+
#### `ES_HOST`
Host of the Elasticsearch server. Defaults to `localhost`
@@ -383,11 +394,11 @@ Port of the Elasticsearch server. Defaults to `9200`
#### `ES_USER`
-Used for optionally authenticating with ElasticSearch
+Used for optionally authenticating with Elasticsearch
#### `ES_PASS`
-Used for optionally authenticating with ElasticSearch
+Used for optionally authenticating with Elasticsearch
#### `ES_PREFIX`
diff --git a/content/en/admin/optional/elasticsearch.md b/content/en/admin/elasticsearch.md
similarity index 58%
rename from content/en/admin/optional/elasticsearch.md
rename to content/en/admin/elasticsearch.md
index 769736ee..234097b7 100644
--- a/content/en/admin/optional/elasticsearch.md
+++ b/content/en/admin/elasticsearch.md
@@ -1,16 +1,30 @@
---
-title: Full-text search
-description: Setting up Elasticsearch to search for statuses authored, favourited, or mentioned in.
+title: Configuring full-text search
+description: Setting up Elasticsearch to search for statuses (authored, favourited, or mentioned), public indexable status, and accounts
menu:
docs:
- weight: 10
- parent: admin-optional
+ weight: 40
+ parent: admin
---
-Mastodon supports full-text search when Elasticsearch is available. Mastodon’s full-text search allows logged in users to find results from their own statuses, their mentions, their favourites, and their bookmarks. It deliberately does not allow searching for arbitrary strings in the entire database.
+Mastodon supports full-text search when Elasticsearch is available. It is strongly recommended to configure this feature.
+
+Mastodon’s full-text search allows logged in users to find results from:
+- public statuses from account that opted into appearing in search results
+- their own statuses
+- their mentions
+- their favourites
+- their bookmarks
+- accounts (display name, usernames and bios)
+
+It deliberately does not allow searching for arbitrary strings in the entire database.
## Installing Elasticsearch {#install}
+{{< hint style="info" >}}
+Mastodon is tested with ElasticSearch version 7. It should support OpenSearch, as well as ElectisSearch versions 6 and 8, but those setups are not officially supported.
+{{< /hint >}}
+
Elasticsearch requires a Java runtime. If you don’t have Java already installed, do it now. Assuming you are logged in as `root`:
```bash
@@ -35,10 +49,6 @@ apt install elasticsearch
**Security warning:** By default, Elasticsearch is supposed to bind to localhost only, i.e. be inaccessible from the outside network. You can check which address Elasticsearch binds to by looking at `network.host` within `/etc/elasticsearch/elasticsearch.yml`. Consider that anyone who can access Elasticsearch can access and modify any data within it, as there is no authentication layer. So it’s really important that the access is secured. Having a firewall that only exposes the 22, 80 and 443 ports is advisable, as outlined in the [main installation instructions](../../prerequisites/#install-a-firewall-and-only-whitelist-ssh-http-and-https-ports). If you have a multi-host setup, you must know how to secure internal traffic.
{{< /hint >}}
-{{< hint style="danger" >}}
-**Security warning:** Elasticsearch versions between `2.0` and `2.14.1` are affected by an [exploit](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-44228) in the `log4j` library. If affected, please refer to the [temporary mitigation](https://github.com/elastic/elasticsearch/issues/81618#issuecomment-991000240) from the Elasticsearch issue tracker.
-{{< /hint >}}
-
To start Elasticsearch:
```bash
@@ -54,10 +64,74 @@ Edit `.env.production` to add the following variables:
ES_ENABLED=true
ES_HOST=localhost
ES_PORT=9200
+ES_PRESET= # single_node_cluster, small_cluster or large_cluster
+ES_USER=
+ES_PASS=
```
+### Choosing the correct preset
+
+The value for `ES_PRESET` depends on the size of your Elasticsearch and will be used to set the number of shards and replica for your indices to the best value for your setup:
+- `single_node_cluster` if you only have one node in your Elasticsearch cluster. Indices will be configured without any replica
+- `small_cluster` if you have less than 6 nodes in your cluster. Indices will be configured with 1 replica
+- `large_cluster` if you have 6 or more nodes in your cluster. Indices will be configured with more shards than with the `small_cluster` setting, to allow them to be distributed over more nodes
+
If you have multiple Mastodon servers on the same machine, and you are planning to use the same Elasticsearch installation for all of them, make sure that all of them have unique `REDIS_NAMESPACE` in their configurations, to differentiate the indices. If you need to override the prefix of the Elasticsearch indices, you can set `ES_PREFIX` directly.
+### Security
+
+By default, Elasticsearch does not handle any authentication and every request is made with full admin permission. We strongly advise you to configure Elasticsearch security features on your cluster.
+
+To configure it, please refer [to the official documentation](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/security-minimal-setup.html). It will guide you through:
+- Enabling the security features (`xpack.security.enabled: true`)
+- Creating password for built-in users
+
+Once done, you can create a custom role for Mastodon to connect.
+
+For example (please adapt this snippet to use your Elastic admin password):
+
+```sh
+curl -X POST -u elastic:admin_password "localhost:9200/_security/role/mastodon_full_access?pretty" -H 'Content-Type: application/json' -d'
+{
+ "cluster": ["monitor"],
+ "indices": [{
+ "names": ["*"],
+ "privileges": ["read", "monitor", "write", "manage"]
+ }]
+}
+'
+```
+
+[Elasticsearch documentation for role creation](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/security-api-put-role.html)
+
+Once the role is created, you can create a user for the Mastodon server to use, and assign it the role.
+
+For example (please adapt this snippet to use your Elastic admin password, and customize your new user `mastodon` user password):
+
+```sh
+curl -X POST -u elastic:admin_password "localhost:9200/_security/user/mastodon?pretty" -H 'Content-Type: application/json' -d'
+{
+ "password" : "l0ng-r4nd0m-p@ssw0rd",
+ "roles" : ["mastodon_full_access"]
+}
+'
+```
+
+[Elasticsearch documentation for user creation](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/security-api-put-user.html)
+
+Once this is done, you need to configure Mastodon to use the credentials for your newly created user.
+
+In `.env.production`, adjust your configuration:
+
+```bash
+ES_USER=mastodon
+ES_PASS=l0ng-r4nd0m-p@ssw0rd
+```
+
+You are all set, and your Elasticsearch server should be much more secure!
+
+### Populate the indices
+
After saving the new configuration, restart Mastodon processes for it to take effect:
```bash
@@ -151,4 +225,3 @@ diff --git a/app/chewy/tags_index.rb b/app/chewy/tags_index.rb
edge_ngram: {
```
-
diff --git a/content/en/admin/optional.md b/content/en/admin/optional.md
index 00813b17..2b15bae7 100644
--- a/content/en/admin/optional.md
+++ b/content/en/admin/optional.md
@@ -9,7 +9,6 @@ menu:
Mastodon offers a few optional features that can be used if needed.
-- [Full-text search](./elasticsearch/)
- [Object storage](./object-storage/)
- [Hidden services](./tor/)
- [Single Sign On](./sso/)
diff --git a/content/en/admin/optional/tor.md b/content/en/admin/optional/tor.md
index 67c1d795..f49847fd 100644
--- a/content/en/admin/optional/tor.md
+++ b/content/en/admin/optional/tor.md
@@ -1,6 +1,6 @@
---
-title: Hidden services
-description: Serving Mastodon through TOR hidden services.
+title: Onion services
+description: Serving Mastodon through Tor onion services.
menu:
docs:
weight: 20
@@ -36,7 +36,7 @@ apt install tor deb.torproject.org-keyring
Edit the file at `/etc/tor/torrc` and add the following configuration.
```text
-HiddenServiceDir /var/lib/tor/hidden_service/
+HiddenServiceDir /var/lib/tor/onion_service/
HiddenServiceVersion 3
HiddenServicePort 80 127.0.0.1:80
```
@@ -47,7 +47,7 @@ Restart tor.
sudo service tor restart
```
-Your tor hostname can now be found at `/var/lib/tor/hidden_service/hostname`.
+Your tor hostname can now be found at `/var/lib/tor/onion_service/hostname`.
## Move your Mastodon configuration {#nginx}
@@ -134,7 +134,7 @@ server {
}
```
-Replace the long hash provided here with your Tor domain located in the file at `/var/lib/tor/hidden_service/hostname`.
+Replace the long hash provided here with your Tor domain located in the file at `/var/lib/tor/onion_service/hostname`.
Note that the onion hostname has been prefixed with “mastodon.”. Your Tor address acts a wildcard domain. All subdomains will be routed through, and you can configure Nginx to respond to any subdomain you wish. If you do not wish to host any other services on your tor address you can omit the subdomain, or choose a different subdomain.
diff --git a/content/en/admin/tootctl.md b/content/en/admin/tootctl.md
index 078c75c0..cddc70a8 100644
--- a/content/en/admin/tootctl.md
+++ b/content/en/admin/tootctl.md
@@ -703,7 +703,7 @@ Scans for files that do not belong to existing media attachments, and remove the
### `tootctl media refresh` {#media-refresh}
-Refetch remote media attachments from other servers. You must specify the source of media attachments with either `--status`, `--account`, or `--domain`. If an attachment already exists in the database, it will not be overwritten unless you use `--force`.
+Refetch remote media attachments from other servers. You must specify the source of media attachments with either `--status`, `--account`, `--domain`, or `--days`. If an attachment already exists in the database, it will not be overwritten unless you use `--force`.
`--account ACCT`
: String `username@domain` handle of the account
@@ -714,6 +714,9 @@ Refetch remote media attachments from other servers. You must specify the source
`--status ID`
: Local numeric ID of the status in the database.
+`--days N`
+: The number of days to limit this task to.
+
`--concurrency N`
: The number of workers to use for this task. Defaults to 5.
@@ -728,7 +731,8 @@ Refetch remote media attachments from other servers. You must specify the source
**Version history:**\
3.0.0 - added\
-3.0.1 - add `--force` and skip already downloaded attachments by default
+3.0.1 - add `--force` and skip already downloaded attachments by default\
+4.0.0 - add `--days`
---
@@ -803,7 +807,7 @@ Remove local thumbnails for preview cards.
Create or update an Elasticsearch index and populate it. If Elasticsearch is empty, this command will create the necessary indices and then import data from the database into those indices. This command will also upgrade indices if the underlying schema has been changed since the last run.
`--batch-size`
-: Defaults to 1000. A lower batch size can make ElasticSearch process records more quickly.
+: Defaults to 100. A higher batch size can make Elasticsearch process records more quickly, with less load on the PostgreSQL database, but can increase memory pressure on the Elasticsearch nodes during indexing.
`--only INDEX`
: Specify an index name [`accounts`, `tags`, `statuses`] to create or update only that index.
diff --git a/content/en/admin/upgrading.md b/content/en/admin/upgrading.md
index 1ce883b5..296f3e4f 100644
--- a/content/en/admin/upgrading.md
+++ b/content/en/admin/upgrading.md
@@ -10,6 +10,16 @@ menu:
When a new version of Mastodon comes out, it appears on the [GitHub releases page](https://github.com/mastodon/mastodon/releases). Please mind that running unreleased code from the `main` branch, while possible, is not recommended.
{{< /hint >}}
+### Automatic update verification {#automated_checks}
+
+Since v4.2.0, Mastodon will automatically check for available updates and notify the users of your server that have the `DevOps` permission.
+
+This happens by fetching `https://api.joinmastodon.org/update-check?version=` in the background every 30 minutes. `current_version` omits the build metadata (everything after the first `+`, if there is one, in the version string). For instance, if your version is `4.3.0-beta2+my-fork`, Mastodon will query `https://api.joinmastodon.org/update-check?version=4.3.0-beta2`.
+
+You can change which URL Mastodon queries by setting the `UPDATE_CHECK_URL` environment variable. You can also completely disable this behavior by setting this environment variable to an empty string, although we strongly recommend against doing that unless you are keeping up with Mastodon updates in another way, as Mastodon occasionally releases critical security updates that must be applied in a timely fashion.
+
+### Upgrade steps
+
Mastodon releases correspond to git tags. Before attempting an upgrade, look up the desired release on the [GitHub releases page](https://github.com/mastodon/mastodon/releases). The page will contain a **changelog** describing everything you need to know about what's different, as well as **specific upgrade instructions**.
To begin, switch to the `mastodon` user:
diff --git a/content/en/api/guidelines.md b/content/en/api/guidelines.md
index ad14480b..a3a526a0 100644
--- a/content/en/api/guidelines.md
+++ b/content/en/api/guidelines.md
@@ -32,7 +32,27 @@ With that said, because IDs are string representations of numbers, they can stil
## Paginating through API responses {#pagination}
-Many API methods allow you to paginate for more information, using parameters such as `limit`, `max_id`, `min_id`, and `since_id`. However, some of these API methods operate on entity IDs that are not publicly exposed in the API response, and are only known to the backend and the database. (This is usually the case for entities that reference other entities, such as Follow entities which reference Accounts, or Favourite entities which reference Statuses, etc.)
+Many API methods allow you to paginate for more information, using parameters such as `limit`, `max_id`, `min_id`, and `since_id`.
+
+limit
+: The maximum number of results to return. Usually, there is a default limit and a maximum limit; these will vary according to the API method.
+
+max_id
+: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
+
+since_id
+: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
+
+min_id
+: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward. (Available since v2.6.0.)
+
+For example, we might fetch `https://mastodon.example/api/v1/accounts/1/statuses` with certain parameters, and we will get the following results in the following cases:
+
+- Setting `?max_id=1` will return no statuses, since there are no statuses with an ID earlier than `1`.
+- Setting `?since_id=1` will return the latest statuses, since there have been many statuses since `1`.
+- Setting `?min_id=1` will return the oldest statuses, as `min_id` sets the cursor.
+
+Some API methods operate on entity IDs that are not publicly exposed in the API response, and are only known to the backend and the database. (This is usually the case for entities that reference other entities, such as Follow entities which reference Accounts, or Favourite entities which reference Statuses, etc.)
To get around this, Mastodon may return links to a "prev" and "next" page. These links are made available via the HTTP `Link` header on the response. Consider the following fictitious API call:
@@ -40,7 +60,7 @@ To get around this, Mastodon may return links to a "prev" and "next" page. These
GET https://mastodon.example/api/v1/endpoint HTTP/1.1
Authorization: Bearer token
-Link: ; rel="next", ; rel="prev"
+Link: ; rel="next", ; rel="prev"
[
{
// some Entity
diff --git a/content/en/client/libraries.md b/content/en/client/libraries.md
index 0539d161..7fc3f124 100644
--- a/content/en/client/libraries.md
+++ b/content/en/client/libraries.md
@@ -100,6 +100,7 @@ Remember to check how recently the library was updated, and whether it includes
## PHP {#php}
+* [mastodon-api-client](https://github.com/vazaha-nl/mastodon-api-client)
* [Phediverse Mastodon REST Client](https://github.com/phediverse/mastodon-rest)
* [TootoPHP](https://framagit.org/MaxKoder/TootoPHP)
* [oauth2-mastodon](https://github.com/lrf141/oauth2-mastodon)
@@ -107,7 +108,7 @@ Remember to check how recently the library was updated, and whether it includes
* [mastodon-api-php-oauth](https://github.com/yks118/Mastodon-api-php-oauth)
* [mastodon-api-php](https://github.com/colorfield/mastodon-api-php)
* [Mastodon API for Laravel](https://github.com/kawax/laravel-mastodon-api)
-* [Mastodon for Drupal](https://github.com/colorfield/mastodon)
+* [Mastodon for Drupal](https://www.drupal.org/project/mastodon)
* [Mastodon for Socialite](https://github.com/kawax/socialite-mastodon)
## PowerShell {#powershell}
diff --git a/content/en/entities/Admin_Cohort.md b/content/en/entities/Admin_Cohort.md
index 6a79d665..739f4e32 100644
--- a/content/en/entities/Admin_Cohort.md
+++ b/content/en/entities/Admin_Cohort.md
@@ -77,7 +77,7 @@ Daily retention data for the week between 2022-09-08 and 2022-09-14, given that
"value": "1"
}
]
-},
+}
```
## Attributes
diff --git a/content/en/entities/Admin_Dimension.md b/content/en/entities/Admin_Dimension.md
index 1b4cc919..4d67e6cb 100644
--- a/content/en/entities/Admin_Dimension.md
+++ b/content/en/entities/Admin_Dimension.md
@@ -165,7 +165,7 @@ Show dimensional data about how much space is used by each software in your serv
"human_value": "0 Bytes"
}
]
-},
+}
```
### `software_versions` {#software_versions}
diff --git a/content/en/entities/FeaturedTag.md b/content/en/entities/FeaturedTag.md
index 8c245e2d..44c93a9e 100644
--- a/content/en/entities/FeaturedTag.md
+++ b/content/en/entities/FeaturedTag.md
@@ -50,7 +50,7 @@ aliases: [
### `statuses_count` {#statuses_count}
**Description:** The number of authored statuses containing this hashtag.\
-**Type:** Number\
+**Type:** Integer\
**Version history:**\
3.0.0 - added
diff --git a/content/en/entities/FilterResult.md b/content/en/entities/FilterResult.md
index d2323fbc..6b5546d1 100644
--- a/content/en/entities/FilterResult.md
+++ b/content/en/entities/FilterResult.md
@@ -53,7 +53,7 @@ aliases: [
### `status_matches` {#status_matches}
**Description:** The status ID within the filter that was matched.\
-**Type:** {{}} String, or null\
+**Type:** {{}} Array of String, or null\
**Version history:**\
4.0.0 - added
diff --git a/content/en/entities/Reaction.md b/content/en/entities/Reaction.md
index 455cec85..e45f970b 100644
--- a/content/en/entities/Reaction.md
+++ b/content/en/entities/Reaction.md
@@ -19,18 +19,20 @@ aliases: [
## Example
```json
-{
- "name": "bongoCat",
- "count": 9,
- "me": false,
- "url": "https://files.mastodon.social/custom_emojis/images/000/067/715/original/fdba57dff7576d53.png",
- "static_url": "https://files.mastodon.social/custom_emojis/images/000/067/715/static/fdba57dff7576d53.png"
-},
-{
- "name": "🤔",
- "count": 1,
- "me": true
-}
+[
+ {
+ "name": "bongoCat",
+ "count": 9,
+ "me": false,
+ "url": "https://files.mastodon.social/custom_emojis/images/000/067/715/original/fdba57dff7576d53.png",
+ "static_url": "https://files.mastodon.social/custom_emojis/images/000/067/715/static/fdba57dff7576d53.png"
+ },
+ {
+ "name": "🤔",
+ "count": 1,
+ "me": true
+ }
+]
```
## Attributes
diff --git a/content/en/entities/Role.md b/content/en/entities/Role.md
index 717093d5..679fe02a 100644
--- a/content/en/entities/Role.md
+++ b/content/en/entities/Role.md
@@ -21,7 +21,7 @@ aliases: [
"color": "#ff3838",
"permissions": 1048575,
"highlighted": true
-},
+}
```
## Attributes
diff --git a/content/en/entities/StatusEdit.md b/content/en/entities/StatusEdit.md
index bc8f8453..f58f34d3 100644
--- a/content/en/entities/StatusEdit.md
+++ b/content/en/entities/StatusEdit.md
@@ -78,7 +78,7 @@ aliases: [
### `account` {#account}
**Description:** The account that published this revision.\
-**Type:** Account\
+**Type:** [Account]({{}})\
**Version history:**\
3.5.0 - added
diff --git a/content/en/methods/accounts.md b/content/en/methods/accounts.md
index 3cee3475..5e00972f 100644
--- a/content/en/methods/accounts.md
+++ b/content/en/methods/accounts.md
@@ -745,14 +745,14 @@ Authorization
##### Query parameters
-max_id
-: String. Return results older than this ID
+max_id
+: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
since_id
-: String. Return results newer than this ID
+: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
min_id
-: String. Return results immediately newer than this ID
+: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
limit
: Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.
diff --git a/content/en/methods/admin/accounts.md b/content/en/methods/admin/accounts.md
index e15a1419..7f53ba32 100644
--- a/content/en/methods/admin/accounts.md
+++ b/content/en/methods/admin/accounts.md
@@ -83,14 +83,14 @@ ip
staff
: Boolean. Filter for staff accounts?
-max_id
-: String. Return results older than ID.
+max_id
+: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
since_id
-: String. Return results newer than ID.
+: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
min_id
-: String. Return results immediately newer than ID.
+: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
limit
: Integer. Maximum number of results to return. Defaults to 100 accounts. Max 200 accounts.
@@ -233,14 +233,14 @@ email
ip
: String. Lookup users with this IP address.
-max_id
-: String. Return results older than ID.
+max_id
+: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
since_id
-: String. Return results newer than ID.
+: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
min_id
-: String. Return results immediately newer than ID.
+: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
limit
: Integer. Maximum number of results to return. Defaults to 100 accounts. Max 200 accounts.
diff --git a/content/en/methods/admin/canonical_email_blocks.md b/content/en/methods/admin/canonical_email_blocks.md
index c8cacb95..cdf44a7d 100644
--- a/content/en/methods/admin/canonical_email_blocks.md
+++ b/content/en/methods/admin/canonical_email_blocks.md
@@ -94,6 +94,11 @@ GET /api/v1/admin/canonical_email_blocks/:id HTTP/1.1
#### Request
+##### Path parameters
+
+:id
+: {{}} String. The ID of the Admin::CanonicalEmailBlock in the database.
+
##### Headers
Authorization
@@ -262,6 +267,11 @@ DELETE /api/v1/admin/canonical_email_blocks/:id HTTP/1.1
#### Request
+##### Path parameters
+
+:id
+: {{}} String. The ID of the Admin::CanonicalEmailBlock in the database.
+
##### Headers
Authorization
diff --git a/content/en/methods/endorsements.md b/content/en/methods/endorsements.md
index bbedf350..902a313f 100644
--- a/content/en/methods/endorsements.md
+++ b/content/en/methods/endorsements.md
@@ -29,8 +29,7 @@ Accounts that the user is currently featuring on their profile.
**Returns:** Array of [Account]({{< relref "entities/account" >}})\
**OAuth:** User token + `read:accounts`\
**Version history:**\
-2.5.0 - added\
-3.3.0 - both `min_id` and `max_id` can be used at the same time now
+2.5.0 - added
#### Request
diff --git a/content/en/methods/follow_requests.md b/content/en/methods/follow_requests.md
index 0ca2d3be..88d8391d 100644
--- a/content/en/methods/follow_requests.md
+++ b/content/en/methods/follow_requests.md
@@ -27,8 +27,7 @@ GET /api/v1/follow_requests HTTP/1.1
**Returns:** Array of [Account]({{< relref "entities/account" >}})\
**OAuth:** User token + `read:follows` or `follow`\
**Version history:**\
-0.0.0 - added\
-3.3.0 - both `min_id` and `max_id` can be used at the same time now
+0.0.0 - added
#### Request
diff --git a/content/en/methods/mutes.md b/content/en/methods/mutes.md
index 6eacfbc5..7a63212d 100644
--- a/content/en/methods/mutes.md
+++ b/content/en/methods/mutes.md
@@ -30,7 +30,7 @@ Accounts the user has muted.
**OAuth:** User token + `read:mutes` or `follow`\
**Version history:**\
0.0.0 - added\
-3.3.0 - added `mute_expires_at`. both `min_id` and `max_id` can be used at the same time now
+3.3.0 - added `mute_expires_at`
#### Request
##### Headers
diff --git a/content/en/methods/notifications.md b/content/en/methods/notifications.md
index 30fc55fe..90193341 100644
--- a/content/en/methods/notifications.md
+++ b/content/en/methods/notifications.md
@@ -57,14 +57,14 @@ Authorization
##### Query parameters
-max_id
-: String. Return results older than this ID
+max_id
+: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
since_id
-: String. Return results newer than this ID
+: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
min_id
-: String. Return results immediately newer than this ID
+: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
limit
: Integer. Maximum number of results to return. Defaults to 15 notifications. Max 30 notifications.
diff --git a/content/en/methods/profile.md b/content/en/methods/profile.md
new file mode 100644
index 00000000..677d6c02
--- /dev/null
+++ b/content/en/methods/profile.md
@@ -0,0 +1,178 @@
+---
+title: profile API methods
+description: Methods concerning profiles.
+menu:
+ docs:
+ weight: 20
+ name: profile
+ parent: methods
+ identifier: methods-profile
+---
+
+
+
+## Delete profile avatar
+
+```http
+DELETE /api/v1/profile/avatar HTTP/1.1
+```
+
+**Returns:** [CredentialAccount]({{< relref "entities/Account#CredentialAccount">}})\
+**OAuth**: User token + `write:accounts`\
+**Version history:**\
+4.2.0 - added
+
+Deletes the avatar associated with the user's profile.
+
+#### Request
+
+##### Headers
+
+Authorization
+: {{}} Provide this header with `Bearer ` to gain authorized access to this API method.
+
+##### Path parameters
+
+#### Response
+
+##### 200: OK
+
+The avatar was successfully deleted from the user's profile. If there were no avatar associated with the profile, the response will still indicate a successful deletion.
+
+```json
+{
+ "id": "110357222516183152",
+ "username": "rob",
+ "acct": "rob",
+ "display_name": "",
+ "locked": false,
+ "bot": false,
+ "discoverable": false,
+ "group": false,
+ "created_at": "2023-05-12T00:00:00.000Z",
+ "note": "",
+ "url": "http://localhost:3000/@rob",
+ "uri": "http://localhost:3000/users/rob",
+ "avatar": "http://localhost:3000/avatars/original/missing.png",
+ "avatar_static": "http://localhost:3000/avatars/original/missing.png",
+ "header": "http://localhost:3000/system/accounts/headers/110/357/222/516/183/152/original/0cd99648c23005ed.png",
+ "header_static": "http://localhost:3000/system/accounts/headers/110/357/222/516/183/152/original/0cd99648c23005ed.png",
+ "followers_count": 14,
+ "following_count": 2,
+ "statuses_count": 10,
+ "last_status_at": "2023-06-26",
+ "noindex": false,
+ "source": {
+ "privacy": "public",
+ "sensitive": false,
+ "language": null,
+ "note": "",
+ "fields": [],
+ "follow_requests_count": 0
+ },
+ "emojis": [],
+ "roles": [],
+ "fields": [],
+ "role": {
+ "id": "-99",
+ "name": "",
+ "permissions": "65536",
+ "color": "",
+ "highlighted": false
+ }
+}
+```
+
+### 401: Unauthorized
+
+Invalid or missing Authorization header.
+
+```json
+{
+ "error": "The access token is invalid"
+}
+```
+
+## Delete profile header
+
+```http
+DELETE /api/v1/profile/header HTTP/1.1
+```
+
+**Returns:** [CredentialAccount]({{< relref "entities/Account#CredentialAccount">}})\
+**OAuth**: User token + `write:accounts`\
+**Version history:**\
+4.2.0 - added
+
+Deletes the header image associated with the user's profile.
+
+#### Request
+
+##### Headers
+
+Authorization
+: {{}} Provide this header with `Bearer ` to gain authorized access to this API method.
+
+##### Path parameters
+
+#### Response
+
+##### 200: OK
+
+The header was successfully deleted from the user's profile. If there were no header associated with the profile, the response will still indicate a successful deletion.
+
+```json
+{
+ "id": "110357222516183152",
+ "username": "rob",
+ "acct": "rob",
+ "display_name": "",
+ "locked": false,
+ "bot": false,
+ "discoverable": false,
+ "group": false,
+ "created_at": "2023-05-12T00:00:00.000Z",
+ "note": "",
+ "url": "http://localhost:3000/@rob",
+ "uri": "http://localhost:3000/users/rob",
+ "avatar": "http://localhost:3000/avatars/original/missing.png",
+ "avatar_static": "http://localhost:3000/avatars/original/missing.png",
+ "header": "http://localhost:3000/headers/original/missing.png",
+ "header_static": "http://localhost:3000/headers/original/missing.png",
+ "followers_count": 14,
+ "following_count": 2,
+ "statuses_count": 10,
+ "last_status_at": "2023-06-26",
+ "noindex": false,
+ "source": {
+ "privacy": "public",
+ "sensitive": false,
+ "language": null,
+ "note": "",
+ "fields": [],
+ "follow_requests_count": 0
+ },
+ "emojis": [],
+ "roles": [],
+ "fields": [],
+ "role": {
+ "id": "-99",
+ "name": "",
+ "permissions": "65536",
+ "color": "",
+ "highlighted": false
+ }
+}
+```
+
+### 401: Unauthorized
+
+Invalid or missing Authorization header.
+
+```json
+{
+ "error": "The access token is invalid"
+}
+```
diff --git a/content/en/methods/scheduled_statuses.md b/content/en/methods/scheduled_statuses.md
index 75a29ea5..8fa38269 100644
--- a/content/en/methods/scheduled_statuses.md
+++ b/content/en/methods/scheduled_statuses.md
@@ -39,14 +39,14 @@ Authorization
##### Query parameters
-max_id
-: String. Return results older than ID.
+max_id
+: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
since_id
-: String. Return results newer than ID.
+: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
min_id
-: String. Return results immediately newer than ID.
+: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
limit
: Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.
diff --git a/content/en/methods/search.md b/content/en/methods/search.md
index 5fcc8fe5..81ecac72 100644
--- a/content/en/methods/search.md
+++ b/content/en/methods/search.md
@@ -59,11 +59,11 @@ account_id
exclude_unreviewed
: Boolean. Filter out unreviewed tags? Defaults to false. Use true when trying to find trending tags.
-max_id
-: String. Return results older than this ID.
+max_id
+: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
min_id
-: String. Return results immediately newer than this ID.
+: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
limit
: Integer. Maximum number of results to return, per type. Defaults to 20 results per category. Max 40 results per category.
@@ -188,11 +188,11 @@ resolve
account_id
: String. If provided, will only return statuses authored by this account.
-max_id
-: String. Return results older than this ID.
+max_id
+: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
min_id
-: String. Return results immediately newer than this ID.
+: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
limit
: Integer. Maximum number of results to return, per type. Defaults to 20 results per category. Max 40 results per category.
diff --git a/content/en/methods/statuses.md b/content/en/methods/statuses.md
index 8b477d52..0640268a 100644
--- a/content/en/methods/statuses.md
+++ b/content/en/methods/statuses.md
@@ -622,9 +622,6 @@ max_id
since_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
-min_id
-: **Internal parameter.** Use HTTP `Link` header for pagination.
-
limit
: Integer. Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.
@@ -696,9 +693,6 @@ max_id
since_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
-min_id
-: **Internal parameter.** Use HTTP `Link` header for pagination.
-
limit
: Integer. Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.
diff --git a/content/en/methods/timelines.md b/content/en/methods/timelines.md
index 89bca4b7..954ae3f5 100644
--- a/content/en/methods/timelines.md
+++ b/content/en/methods/timelines.md
@@ -51,14 +51,14 @@ remote
only_media
: Boolean. Show only statuses with media attached? Defaults to false.
-max_id
-: String. Return results older than ID.
+max_id
+: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
since_id
-: String. Return results newer than ID.
+: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
min_id
-: String. Return results immediately newer than ID.
+: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
limit
: Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.
@@ -139,14 +139,14 @@ remote
only_media
: Boolean. Return only statuses with media attachments? Defaults to false.
-max_id
-: String. Return results older than ID.
+max_id
+: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
since_id
-: String. Return results newer than ID.
+: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
min_id
-: String. Return results immediately newer than ID.
+: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
limit
: Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.
@@ -231,7 +231,7 @@ Hashtag does not exist
GET /api/v1/timelines/home HTTP/1.1
```
-View statuses from followed users.
+View statuses from followed users and hashtags.
**Returns:** Array of [Status]({{}})\
**OAuth:** User + `read:statuses`\
@@ -239,6 +239,7 @@ View statuses from followed users.
0.0.0 - added\
2.6.0 - add `min_id`\
3.3.0 - both `min_id` and `max_id` can be used at the same time now
+4.0.0 - as users can now follow hashtags, statuses from non-followed users may appear in the timeline
#### Request
@@ -249,14 +250,14 @@ Authorization
##### Query parameters
-max_id
-: String. Return results older than ID.
+max_id
+: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
since_id
-: String. Return results newer than ID.
+: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
min_id
-: String. Return results immediately newer than ID.
+: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
limit
: Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.
@@ -325,14 +326,14 @@ Authorization
##### Query parameters
-max_id
-: String. Return results older than ID.
+max_id
+: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
since_id
-: String. Return results newer than ID.
+: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
min_id
-: String. Return results immediately newer than ID.
+: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
limit
: Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.
@@ -398,14 +399,14 @@ Authorization
##### Query parameters
-max_id
-: String. Return results older than ID.
+max_id
+: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
since_id
-: String. Return results newer than ID.
+: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
min_id
-: String. Return results immediately newer than ID.
+: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
limit
: Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.
@@ -448,4 +449,4 @@ Invalid or missing Authorization header.
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/timelines/public_controller.rb" caption="app/controllers/api/v1/timelines/public_controller.rb" >}}
-{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/timelines/tag_controller.rb" caption="app/controllers/api/v1/timelines/tag_controller.rb" >}}
\ No newline at end of file
+{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/timelines/tag_controller.rb" caption="app/controllers/api/v1/timelines/tag_controller.rb" >}}
diff --git a/content/en/user/run-your-own.md b/content/en/user/run-your-own.md
index f0bf91fa..2e43cf08 100644
--- a/content/en/user/run-your-own.md
+++ b/content/en/user/run-your-own.md
@@ -50,6 +50,8 @@ There exist a number of **dedicated Mastodon hosting providers** that take care
{{< caption-link url="https://cloudplane.org" caption="Cloudplane" >}}
+{{< caption-link url="https://ungleich.ch/u/products/mastodon-hosting/" caption="ungleich.ch" >}}
+
Managed hosting solutions are great for those who do not have experience or desire to install and maintain software. However, being in charge of all components on your own hardware gives greater control over scaling, performance and customization.
We provide a **DigitalOcean 1-Click Install Image** that you can put on a DigitalOcean droplet of your choosing which essentially gives you everything you would otherwise have after following our installation instructions through an interactive setup wizard.
diff --git a/content/zh-cn/admin/tootctl.md b/content/zh-cn/admin/tootctl.md
index bd29300d..776f1353 100644
--- a/content/zh-cn/admin/tootctl.md
+++ b/content/zh-cn/admin/tootctl.md
@@ -23,7 +23,7 @@ RAILS_ENV=production bin/tootctl help
## 基础命令
-{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/cli.rb" caption="lib/cli.rb" >}}
+{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/base.rb" caption="lib/mastodon/cli/base.rb" >}}
### `tootctl self-destruct` {#self-destruct}
@@ -51,7 +51,7 @@ RAILS_ENV=production bin/tootctl help
## 帐户相关命令 {#accounts}
-{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/accounts_cli.rb" caption="lib/mastodon/accounts_cli.rb" >}}
+{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/accounts.rb" caption="lib/mastodon/cli/accounts.rb" >}}
### `tootctl accounts rotate` {#accounts-rotate}
@@ -208,7 +208,7 @@ RAILS_ENV=production bin/tootctl help
## 缓存相关命令 {#cache}
-{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cache_cli.rb" caption="lib/mastodon/cache_cli.rb" >}}
+{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/cache.rb" caption="lib/mastodon/cli/cache.rb" >}}
### `tootctl cache clear` {#cache-clear}
@@ -232,7 +232,7 @@ RAILS_ENV=production bin/tootctl help
## 域名相关命令 {#domains}
-{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/domains_cli.rb" caption="lib/mastodon/domains_cli.rb" >}}
+{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/domains.rb" caption="lib/mastodon/cli/domains.rb" >}}
### `tootctl domains purge` {#domains-purge}
@@ -269,7 +269,7 @@ RAILS_ENV=production bin/tootctl help
## Emoji相关命令 {#emoji}
-{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/emoji_cli.rb" caption="lib/mastodon/emoji_cli.rb" >}}
+{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/emoji.rb" caption="lib/mastodon/cli/emoji.rb" >}}
### `tootctl emoji import` {#emoji-import}
@@ -301,7 +301,7 @@ RAILS_ENV=production bin/tootctl help
## 时间流（Feeds）相关命令 {#feeds}
-{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/feeds_cli.rb" caption="lib/mastodon/feeds_cli.rb" >}}
+{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/feeds.rb" caption="lib/mastodon/cli/feeds.rb" >}}
### `tootctl feeds build` {#feeds-build}
@@ -327,7 +327,7 @@ RAILS_ENV=production bin/tootctl help
## 媒体相关命令 {#media}
-{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/media_cli.rb" caption="lib/mastodon/media_cli.rb" >}}
+{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/media.rb" caption="lib/mastodon/cli/media.rb" >}}
### `tootctl media remove` {#media-remove}
@@ -390,7 +390,7 @@ RAILS_ENV=production bin/tootctl help
## 预览卡片（Preview Cards）相关命令 {#preview_cards}
-{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/preview_cards_cli.rb" caption="lib/mastodon/preview_cards_cli.rb" >}}
+{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/preview_cards.rb" caption="lib/mastodon/cli/preview_cards.rb" >}}
### `tootctl preview_cards remove` {#preview_cards-remove}
@@ -409,7 +409,7 @@ RAILS_ENV=production bin/tootctl help
## 搜索相关命令 {#search}
-{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/search_cli.rb" caption="lib/mastodon/search_cli.rb" >}}
+{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/search.rb" caption="lib/mastodon/cli/search.rb" >}}
### `tootctl search deploy` {#search-deploy}
@@ -425,7 +425,7 @@ RAILS_ENV=production bin/tootctl help
## 站点设定相关命令 {#settings}
-{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/settings_cli.rb" caption="lib/mastodon/settings_cli.rb" >}}
+{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/settings.rb" caption="lib/mastodon/cli/settings.rb" >}}
### `tootctl settings registrations open` {#settings-registrations-open}
@@ -443,7 +443,7 @@ RAILS_ENV=production bin/tootctl help
## 嘟文相关命令 {#statuses}
-{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/statuses_cli.rb" caption="lib/mastodon/statuses_cli.rb" >}}
+{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/statuses.rb" caption="lib/mastodon/cli/statuses.rb" >}}
### `tootctl statuses remove` {#statuses-remove}
+