Miscellaneous fixes (#1110)

* Fix typos in method examples * Fix broken link to sanitize_config (#1115) * Add SIDEKIQ_CONCURRENCY * Fix relref to FilterResult (#1114) * Fix status_ids and rule_ids description (#1126) * fix typo (#1129) * clarify confusing example (mastodon/mastodon#22854) * fix formatting on linked headings (#1139) * fix placeholder entity names (#1157) * better wording * fix scheduledstatus#params.visibility * fix missing: tootctl accounts modify --remove-role * add: status/translate * add deprecation/removal warning to microformats page * clarify further how link verification works * clarify mastodon requirements for webfinger * fix: push param policy -> data[policy]
mastodon · Feb 7, 2023 · b458498 · b458498 · vercel · Feb 7, 2023
1 parent 5b0cd8b
commit b458498
Show file tree

Hide file tree

Showing 24 changed files with 237 additions and 44 deletions.
diff --git a/archetypes/entities.md b/archetypes/entities.md
@@ -4,6 +4,10 @@ description:
 menu:
   docs:
     parent: entities
+aliases: [
+  "/api/entities/SOMETHING",
+  "/api/entities/something",
+]
 ---
 
 ## Example

diff --git a/archetypes/methods.md b/archetypes/methods.md
@@ -4,6 +4,10 @@ description:
 menu:
   docs:
     parent: methods
+aliases: [
+  "/api/methods/SOMETHING",
+  "/api/methods/something",
+]
 ---
 
 ## What the method does {#anchor}

diff --git a/content/en/admin/config.md b/content/en/admin/config.md
@@ -250,6 +250,10 @@ This variable cannot be defined in dotenv (`.env`) files as it's used before the
 
 {{< page-ref page="admin/scaling" >}}
 
+#### `SIDEKIQ_CONCURRENCY`
+
+Added in 4.1. Specific to Sidekiq, this variable determines how many different processes Sidekiq forks into. Defaults to `5`.
+
 #### `WEB_CONCURRENCY`
 
 Specific to Puma, this variable determines how many different processes Puma forks into. Defaults to `2`.

diff --git a/content/en/admin/tootctl.md b/content/en/admin/tootctl.md
@@ -127,6 +127,9 @@ Modify a user account's role, email, active status, approval mode, or 2FA requir
 `--role ROLE`
 : Define the existing account's custom role by providing the `name` of that [Role]({{< relref "entities/Role" >}}). Default roles include `Owner`, `Admin`, and `Moderator` (case-sensitive).
 
+`--remove-role`
+: Removes the current role from the user.
+
 `--email EMAIL`
 : Update the user's email address to `EMAIL`.
 
@@ -154,7 +157,7 @@ Modify a user account's role, email, active status, approval mode, or 2FA requir
 **Version history:**\
 2.6.0 - added\
 3.1.2 - added `--reset-password`\
-4.0.0 - `--role` no longer takes hard-coded `user`, `moderator`, or `admin` roles. Specify the name of the custom Role instead (case-sensitive).
+4.0.0 - `--role` no longer takes hard-coded `user`, `moderator`, or `admin` roles. Specify the name of the custom Role instead (case-sensitive). Remove the current role with `--remove-role`.
 
 
 ---

diff --git a/content/en/entities/FilterStatus.md b/content/en/entities/FilterStatus.md
@@ -32,7 +32,7 @@ aliases: [
 
 ### `status_id` {#keyword}
 
-**Description:** The ID of the filtered Status in the database.\
+**Description:** The ID of the Status that will be filtered.\
 **Type:** String (cast from an integer, but not guaranteed to be a number)\
 **Version history:**\
 4.0.0 - added

diff --git a/content/en/entities/Report.md b/content/en/entities/Report.md
@@ -109,14 +109,14 @@ aliases: [
 
 ### `status_ids` {#status_ids}
 
-**Description:** The domain name of the instance.\
+**Description:** IDs of statuses that have been attached to this report for additional context.\
 **Type:** {{<nullable>}} Array of String (cast from integer), or null\
 **Version history:**\
 4.0.0 - added
 
 ### `rule_ids` {#rule_ids}
 
-**Description:** The domain name of the instance.\
+**Description:** IDs of the rules that have been cited as a violation by this report.\
 **Type:** {{<nullable>}} Array of String (cast from integer), or null\
 **Version history:**\
 4.0.0 - added

diff --git a/content/en/entities/ScheduledStatus.md b/content/en/entities/ScheduledStatus.md
@@ -73,7 +73,7 @@ Returned from `GET /api/v1/scheduled_statuses`:
 
 ### `scheduled_at` {#scheduled_at}
 
-**Description:** ID of the status in the database.\
+**Description:** The timestamp for when the status will be posted.\
 **Type:** String (ISO 8601 Datetime)\
 **Version history:**\
 2.7.0 - added
@@ -150,8 +150,12 @@ Returned from `GET /api/v1/scheduled_statuses`:
 
 #### `params[visibility]` {#params-visibility}
 
-**Description:** The language that will be used for the status.\
-**Type:** {{<nullable>}} String (ISO 639-1 two-letter language code)\
+**Description:** The visibility that the status will have once it is posted.\
+**Type:** String (Enumerable oneOf)\
+`public` = Visible to everyone, shown in public timelines.\
+`unlisted` = Visible to public, but not included in public timelines.\
+`private` = Visible to followers only, and to any mentioned users.\
+`direct` = Visible only to mentioned users.\
 **Version history:**\
 2.7.0 - added
 

diff --git a/content/en/entities/Status.md b/content/en/entities/Status.md
@@ -334,7 +334,7 @@ aliases: [
 ### `filtered` {{%optional%}} {#filtered}
 
 **Description:** If the current token has an authorized user: The filter and keywords that matched this status.\
-**Type:** Array of [FilterResult]({{ relref "entities/FilterResult" }})\
+**Type:** Array of [FilterResult]({{< relref "entities/FilterResult" >}})\
 **Version history:**\
 4.0.0 - added
 

diff --git a/content/en/entities/Translation.md b/content/en/entities/Translation.md
@@ -0,0 +1,50 @@
+---
+title: Translation
+description: Represents the result of machine translating some status content
+menu:
+  docs:
+    parent: entities
+aliases: [
+  "/api/entities/Translation",
+  "/api/entities/translation",
+]
+---
+
+## Example
+
+```json
+{
+  "content": "<p>Hola mundo</p>",
+  "detected_source_language": "en",
+  "provider": "DeepL.com"
+}
+```
+
+## Attributes
+
+### `content` {#content}
+
+**Description:** The translated text of the status.\
+**Type:** String (HTML)\
+**Version history:**\
+4.0.0 - added
+
+### `detected_source_language` {#detected_source_language}
+
+**Description:** The language of the source text, as auto-detected by the machine translation provider.\
+**Type:** String (ISO 639 language code)\
+**Version history:**\
+4.0.0 - added
+
+### `provider` {#provider}
+
+**Description:** The service that provided the machine translation.
+**Type:** String\
+**Version history:**\
+4.0.0 - added
+
+## See also
+
+{{< page-relref ref="methods/statuses#translate" caption="POST /api/v1/statuses/:id/translate" >}}
+
+{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/translation_serializer.rb" caption="app/serializers/rest/translation_serializer.rb" >}}
diff --git a/content/en/methods/admin/reports.md b/content/en/methods/admin/reports.md
@@ -505,7 +505,7 @@ Reopen a currently closed report, if it is closed.
 ##### Path parameters
 
 :id
-: {{<required>}} String. The ID of the SOMETHING in the database.
+: {{<required>}} String. The ID of the Report in the database.
 
 ##### Headers
 

diff --git a/content/en/methods/filters.md b/content/en/methods/filters.md
@@ -106,7 +106,7 @@ Obtain a single filter group owned by the current user.
 ##### Path parameters
 
 :id
-: {{<required>}} String. The ID of the SOMETHING in the database.
+: {{<required>}} String. The ID of the Filter in the database.
 
 ##### Headers
 
@@ -1355,7 +1355,7 @@ DELETE /api/v1/filters/:id HTTP/1.1
 ##### Path parameters
 
 :id
-: {{<required>}} String. The ID of the SOMETHING in the database.
+: {{<required>}} String. The ID of the Filter in the database.
 
 ##### Headers
 

diff --git a/content/en/methods/instance.md b/content/en/methods/instance.md
@@ -466,7 +466,7 @@ The admin has chosen to show domain blocks to no one. The response body is empty
 ## View extended description {#extended_description}
 
 ```http
-GET /api/v1/example HTTP/1.1
+GET /api/v1/instance/extended_description HTTP/1.1
 ```
 
 Obtain an extended description of this server

diff --git a/content/en/methods/lists.md b/content/en/methods/lists.md
@@ -459,7 +459,7 @@ Add accounts to the given list. Note that the user must be following these accou
 ##### Path parameters
 
 :id
-: {{<required>}} String. The ID of the SOMETHING in the database.
+: {{<required>}} String. The ID of the List in the database.
 
 ##### Headers
 
@@ -528,7 +528,7 @@ Remove accounts from the given list.
 ##### Path parameters
 
 :id
-: {{<required>}} String. The ID of the SOMETHING in the database.
+: {{<required>}} String. The ID of the List in the database.
 
 ##### Headers
 
@@ -561,7 +561,7 @@ Invalid or missing Authorization header.
 
 ##### 404: Not found
 
-SOMETHING is not owned by you or does not exist
+List is not owned by you or does not exist
 
 ```json
 {

diff --git a/content/en/methods/markers.md b/content/en/methods/markers.md
@@ -44,7 +44,7 @@ timeline[]
 #### Response
 ##### 200: OK
 
-timeline[] = ["home", "notifications"]
+A request with `?timeline[]=home&timeline[]=notifications`
 
 ```json
 {

diff --git a/content/en/methods/notifications.md b/content/en/methods/notifications.md
@@ -175,7 +175,7 @@ Invalid or missing Authorization header.
 ## Get a single notification {#get-one}
 
 ```http
-GET /api/v1/notification/:id HTTP/1.1
+GET /api/v1/notifications/:id HTTP/1.1
 ```
 
 View information about a notification with a given ID.

diff --git a/content/en/methods/oauth.md b/content/en/methods/oauth.md
@@ -102,7 +102,7 @@ client_id
 : {{<required>}} String. The client ID, obtained during app registration.
 
 client_secret
-: {{<required>}} String. The client secret, obtained durign app registration.
+: {{<required>}} String. The client secret, obtained during app registration.
 
 redirect_uri
 : {{<required>}} String. Set a URI to redirect the user to. If this parameter is set to urn:ietf:wg:oauth:2.0:oob then the token will be shown instead. Must match one of the `redirect_uris` declared during app registration.

diff --git a/content/en/methods/push.md b/content/en/methods/push.md
@@ -43,7 +43,7 @@ Add a Web Push API subscription to receive notifications. Each access token can
 **Version history:**\
 2.4.0 - added\
 3.3.0 - added `data[alerts][status]`\
-3.4.0 - added `policy`\
+3.4.0 - added `data[policy]`\
 3.5.0 - added `data[alerts][update]` and `data[alerts][admin.sign_up]`\
 4.0.0 - added `data[alerts][admin.report]`
 
@@ -95,7 +95,7 @@ data[alerts][admin.sign_up]
 data[alerts][admin.report]
 : Boolean. Receive new report notifications? Defaults to false. Must have a role with the appropriate permissions.
 
-policy
+data[policy]
 : String. Specify whether to receive push notifications from `all`, `followed`, `follower`, or `none` users.
 
 #### Response

diff --git a/content/en/methods/scheduled_statuses.md b/content/en/methods/scheduled_statuses.md
@@ -172,7 +172,7 @@ PUT /api/v1/scheduled_statuses/:id HTTP/1.1
 ##### Path parameters
 
 :id
-: {{<required>}} String. The ID of the SOMETHING in the database.
+: {{<required>}} String. The ID of the ScheduledStatus in the database.
 
 ##### Headers
 
@@ -253,7 +253,7 @@ DELETE /api/v1/scheduled_statuses/:id HTTP/1.1
 ##### Path parameters
 
 :id
-: {{<required>}} String. The ID of the SOMETHING in the database.
+: {{<required>}} String. The ID of the ScheduledStatus in the database.
 
 ##### Headers
 

diff --git a/content/en/methods/statuses.md b/content/en/methods/statuses.md
@@ -523,6 +523,71 @@ Status is private or does not exist
 
 ---
 
+## Translate a status {#translate}
+
+```http
+POST /api/v1/statuses/:id/translate HTTP/1.1
+```
+
+Translate the status content into some language.
+
+**Returns:** [Translation]({{< relref "entities/translation" >}})\
+**OAuth:** App token + `read:statuses`\
+**Version history:**\
+4.0.0 - added
+
+#### Request
+
+##### Path parameters
+
+:id
+: {{<required>}} String. The ID of the Status in the database.
+
+##### Form data parameters
+
+lang
+: String (ISO 639 language code). The status content will be translated into this language. Defaults to the user's current locale.
+
+##### Headers
+
+Authorization
+: {{<required>}} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
+
+#### Response
+##### 200: OK
+
+Translating the first "Hello world" post from mastodon.social into Spanish
+
+```json
+{
+  "content": "<p>Hola mundo</p>",
+  "detected_source_language": "en",
+  "provider": "DeepL.com"
+}
+```
+
+##### 404: Not found
+
+Status is private or does not exist
+
+```json
+{
+  "error": "Record not found"
+}
+```
+
+##### 503: Service unavailable
+
+The translation request failed
+
+```json
+{
+  "error": "Service Unavailable"
+}
+```
+
+---
+
 ## See who boosted a status {#reblogged_by}
 
 ```http
@@ -1394,7 +1459,7 @@ Edit a given status to change its text, sensitivity, media attachments, or poll.
 ##### Path parameters
 
 :id
-: {{<required>}} String. The ID of the SOMETHING in the database.
+: {{<required>}} String. The ID of the Status in the database.
 
 ##### Headers
 

diff --git a/content/en/spec/activitypub.md b/content/en/spec/activitypub.md
@@ -221,7 +221,7 @@ published
 
 ## HTML sanitization {#sanitization}
 
-{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/lib/sanitize_config.rb" caption="app/lib/sanitize_config.rb" >}}
+{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/sanitize_ext/sanitize_config.rb" caption="lib/sanitize_ext/sanitize_config.rb" >}}
 
  Mastodon sanitizes incoming HTML in order to not break assumptions for API client developers. Supported elements include `<p>`, `<span>`, `<br>`, and `<a>`. Unsupported elements will be converted to `<p>`.The sanitizer will keep classes if they begin with microformats prefixes or are semantic classes:
 

diff --git a/content/en/spec/microformats.md b/content/en/spec/microformats.md
@@ -7,6 +7,10 @@ menu:
     parent: spec
 ---
 
+{{< hint style="info" >}}
+As of v4.0.0, HTML permalinks for statuses and profiles have been deprecated and removed from Mastodon. As a result, Microformats are currently not used within nor generated by Mastodon.
+{{< /hint >}}
+
 ## What are microformats? {#intro}
 
 [Microformats 2.0](https://microformats.io/) is a standard used to embed metadata directly within an HTML document. Rather than needing to use an API for read-only purposes, a web page can be parsed for certain CSS classes in order to extract information that you have already fetched just by viewing the page, rather than having to separately request that same information from an API. The use of microformats classes allows for semantic parsing of data within a given web page, and can be used to generate feeds, cards, or representations of that data.