update for 3.1 (#785)

This commit is contained in:
trwnh 2020-06-30 19:11:40 -05:00 committed by GitHub
parent 5680e44983
commit 17143bad72
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 341 additions and 47 deletions

View File

@ -8,6 +8,12 @@ metaDataFormat = "yaml"
paginate = 100 paginate = 100
enableGitInfo = true enableGitInfo = true
[markup]
[markup.tableOfContents]
endLevel = 2
ordered = false
startLevel = 1
[languages.en.menu] [languages.en.menu]
[[languages.en.menu.docs]] [[languages.en.menu.docs]]
name = "Using Mastodon" name = "Using Mastodon"

View File

@ -147,6 +147,8 @@ For convenience, it can read them from a flat file called `.env.production` in t
* `S3_HOSTNAME` * `S3_HOSTNAME`
* `S3_ENDPOINT` * `S3_ENDPOINT`
* `S3_SIGNATURE_VERSION` * `S3_SIGNATURE_VERSION`
* `S3_OVERRIDE_PATH_STYLE`
* `S3_OPEN_TIMEOUT`
### Swift {#swift} ### Swift {#swift}
@ -177,6 +179,8 @@ For convenience, it can read them from a flat file called `.env.production` in t
* `LDAP_PASSWORD` * `LDAP_PASSWORD`
* `LDAP_UID` * `LDAP_UID`
* `LDAP_SEARCH_FILTER` * `LDAP_SEARCH_FILTER`
* `LDAP_MAIL`
* `LDAP_UID_CONVERSTION_ENABLED`
### PAM {#pam} ### PAM {#pam}

View File

@ -78,26 +78,30 @@ menu:
**Description:** The account id`header`.\ **Description:** The account id`header`.\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\ **Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Version history:** Added in 0.1.0 **Version history:**\
0.1.0 - added
### `username` {#username} ### `username` {#username}
**Description:** The username of the account, not including domain.\ **Description:** The username of the account, not including domain.\
**Type:** String\ **Type:** String\
**Version history:** Added in 0.1.0 **Version history:**\
0.1.0 - added
### `acct` {#acct} ### `acct` {#acct}
**Description:** The Webfinger account URI. **Description:** The Webfinger account URI.
Equal to `username` for local users, or `username@domain` for remote users.\ Equal to `username` for local users, or `username@domain` for remote users.\
**Type:** String\ **Type:** String\
**Version history:** Added in 0.1.0 **Version history:**\
0.1.0 - added
### `url` {#url} ### `url` {#url}
**Description:** The location of the user's profile page.\ **Description:** The location of the user's profile page.\
**Type:** String \(HTTPS URL\)\ **Type:** String \(HTTPS URL\)\
**Version history:** Added in 0.1.0 **Version history:**\
0.1.0 - added
## Display attributes ## Display attributes
@ -105,57 +109,66 @@ Equal to `username` for local users, or `username@domain` for remote users.\
**Description:** The profile's display name.\ **Description:** The profile's display name.\
**Type:** String\ **Type:** String\
**Version history:** Added in 0.1.0 **Version history:**\
0.1.0 - added
### `note` {#note} ### `note` {#note}
**Description:** The profile's bio / description.\ **Description:** The profile's bio / description.\
**Type:** String \(HTML\)\ **Type:** String \(HTML\)\
**Version history:** Added in 0.1.0 **Version history:**\
0.1.0 - added
### `avatar` {#avatar} ### `avatar` {#avatar}
**Description:** An image icon that is shown next to statuses and in the profile.\ **Description:** An image icon that is shown next to statuses and in the profile.\
**Type:** String \(URL\)\ **Type:** String \(URL\)\
**Version history:** Added in 0.1.0 **Version history:**\
0.1.0 - added
### `avatar_static` {#avatar_static} ### `avatar_static` {#avatar_static}
**Description:** A static version of the avatar. **Description:** A static version of the avatar.
Equal to `avatar` if its value is a static image; different if `avatar` is an animated GIF.\ Equal to `avatar` if its value is a static image; different if `avatar` is an animated GIF.\
**Type:** String \(URL\)\ **Type:** String \(URL\)\
**Version history:** Added in 1.1.2 **Version history:**\
1.1.2 - added
### `header` {#header} ### `header` {#header}
**Description:** An image banner that is shown above the profile and in profile cards.\ **Description:** An image banner that is shown above the profile and in profile cards.\
**Type:** String \(URL\)\ **Type:** String \(URL\)\
**Version history:** Added in 0.1.0 **Version history:**\
0.1.0 - added
### `header_static` {#header_static} ### `header_static` {#header_static}
**Description:** A static version of the header. **Description:** A static version of the header.
Equal to `header` if its value is a static image; different if `header` is an animated GIF.\ Equal to `header` if its value is a static image; different if `header` is an animated GIF.\
**Type:** String \(URL\)\ **Type:** String \(URL\)\
**Version history:** Added in 1.1.2 **Version history:**\
1.1.2 - added
### `locked` {#locked} ### `locked` {#locked}
**Description:** Whether the account manually approves follow requests.\ **Description:** Whether the account manually approves follow requests.\
**Type:** Boolean\ **Type:** Boolean\
**Version history:** Added in 0.1.0 **Version history:**\
0.1.0 - added
### `emojis` {#emojis} ### `emojis` {#emojis}
**Description:** Custom emoji entities to be used when rendering the profile. If none, an empty array will be returned.\ **Description:** Custom emoji entities to be used when rendering the profile. If none, an empty array will be returned.\
**Type:** Array of [Emoji](emoji.md)\ **Type:** Array of [Emoji](emoji.md)\
**Version history:** Added in 2.4.0 **Version history:**\
2.4.0 - added
### `discoverable` {#discoverable} ### `discoverable` {#discoverable}
**Description:** Whether the account has opted into discovery features such as the profile directory.\ **Description:** Whether the account has opted into discovery features such as the profile directory.\
**Type:** Boolean\ **Type:** Boolean\
**Version history:** Added in 3.1.0 **Version history:**\
3.1.0 - added
## Statistical attributes ## Statistical attributes
@ -163,25 +176,38 @@ Equal to `header` if its value is a static image; different if `header` is an an
**Description:** When the account was created.\ **Description:** When the account was created.\
**Type:** String \(ISO 8601 Datetime\)\ **Type:** String \(ISO 8601 Datetime\)\
**Version history:** Added in 0.1.0 **Version history:**\
0.1.0 - added
### `last_status_at` {#last_status_at}
**Description:** When the most recent status was posted.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:**\
3.0.0 - added\
3.1.0 - now returns date only, no time
### `statuses_count` {#statuses_count} ### `statuses_count` {#statuses_count}
**Description:** How many statuses are attached to this account.\ **Description:** How many statuses are attached to this account.\
**Type:** Number\ **Type:** Number\
**Version history:** Added in 0.1.0 **Version history:**\
0.1.0 - added
### `followers_count` {#followers_count} ### `followers_count` {#followers_count}
**Description:** The reported followers of this profile.\ **Description:** The reported followers of this profile.\
**Type:** Number\ **Type:** Number\
**Version history:** Added in 0.1.0 **Version history:**\
0.1.0 - added
### `following_count` {#following_count} ### `following_count` {#following_count}
**Description:** The reported follows of this profile.\ **Description:** The reported follows of this profile.\
**Type:** Number\ **Type:** Number\
**Version history:** Added in 0.1.0 **Version history:**\
0.1.0 - added
## Optional attributes ## Optional attributes
@ -189,25 +215,29 @@ Equal to `header` if its value is a static image; different if `header` is an an
**Description:** Indicates that the profile is currently inactive and that its user has moved to a new account.\ **Description:** Indicates that the profile is currently inactive and that its user has moved to a new account.\
**Type:** [Account](account.md)\ **Type:** [Account](account.md)\
**Version history:** Added in 2.1.0 **Version history:**\
2.1.0 - added
### `fields` {#fields} ### `fields` {#fields}
**Description:** Additional metadata attached to a profile as name-value pairs.\ **Description:** Additional metadata attached to a profile as name-value pairs.\
**Type:** Array of [Field]({{< relref "field.md" >}})\ **Type:** Array of [Field]({{< relref "field.md" >}})\
**Version history:** Added in 2.4.0 **Version history:**\
2.4.0 - added
### `bot` {#bot} ### `bot` {#bot}
**Description:** A presentational flag. Indicates that the account may perform automated actions, may not be monitored, or identifies as a robot.\ **Description:** A presentational flag. Indicates that the account may perform automated actions, may not be monitored, or identifies as a robot.\
**Type:** Boolean\ **Type:** Boolean\
**Version history:** Added in 2.4.0 **Version history:**\
2.4.0 - added
### `source` {#source} ### `source` {#source}
**Description:** An extra entity to be used with API methods to [verify credentials](../methods/accounts/#verify-account-credentials) and [update credentials](../methods/accounts/#update-account-credentials).\ **Description:** An extra entity to be used with API methods to [verify credentials](../methods/accounts/#verify-account-credentials) and [update credentials](../methods/accounts/#update-account-credentials).\
**Type:** [Source](source.md)\ **Type:** [Source](source.md)\
**Version history:** Added in 2.4.0 **Version history:**\
2.4.0 - added
## See also ## See also

View File

@ -0,0 +1,78 @@
---
title: Announcement
description: Represents an announcement set by an administrator.
menu:
docs:
parent: entities
---
## Example
```javascript
```
## Base attributes
### `id`
**Description:** The announcement id.\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Version history:**\
3.1.0 - added
### `text`
**Description:** The content of the announcement.\
**Type:** String\
**Version history:**\
3.1.0 - added
### `published`
**Description:** Whether the announcement is currently active.\
**Type:** Boolean\
**Version history:**\
3.1.0 - added
### `all_day`
**Description:** Whether the announcement has a start/end time.\
**Type:** Boolean\
**Version history:**\
3.1.0 - added
### `created_at`
**Description:** When the announcement was created.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:**\
3.1.0 - added
### `updated_at`
**Description:** When the announcement was last updated.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:**\
3.1.0 - added
## Optional attributes
### `scheduled_at`
**Description:** When the future announcement was scheduled.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:**\
3.1.0 - added
### `starts_at`
**Description:** When the future announcement will start.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:**\
3.1.0 - added
### `ends_at`
**Description:** When the future announcement will end.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:**\
3.1.0 - added

View File

@ -64,7 +64,8 @@ menu:
**Description:** The id of the notification in the database.\ **Description:** The id of the notification in the database.\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\ **Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Version history:** Added in 0.9.9 **Version history:**\
0.9.9 - added
### `type` {#type} ### `type` {#type}
@ -75,19 +76,24 @@ menu:
`reblog` = Someone boosted one of your statuses\ `reblog` = Someone boosted one of your statuses\
`favourite` = Someone favourited one of your statuses\ `favourite` = Someone favourited one of your statuses\
`poll` = A poll you have voted in or created has ended\ `poll` = A poll you have voted in or created has ended\
**Version history:** Added in 0.9.9. `poll` added in 2.8.0. **Version history:**\
0.9.9 - added\
2.8.0 - added `poll`\
3.1.0 - added `follow_request`
### `created_at` {#created_at} ### `created_at` {#created_at}
**Description:** The timestamp of the notification.\ **Description:** The timestamp of the notification.\
**Type:** String \(ISO 8601 Datetime\)\ **Type:** String \(ISO 8601 Datetime\)\
**Version history:** Added in 0.9.9 **Version history:**\
0.9.9 - added
### `account` {#account} ### `account` {#account}
**Description:** The account that performed the action that generated the notification.\ **Description:** The account that performed the action that generated the notification.\
**Type:** [Account](account.md)\ **Type:** [Account](account.md)\
**Version history:** Added in 0.9.9 **Version history:**\
0.9.9 - added
## Optional attributes ## Optional attributes
@ -95,7 +101,8 @@ menu:
**Description:** Status that was the object of the notification, e.g. in mentions, reblogs, favourites, or polls.\ **Description:** Status that was the object of the notification, e.g. in mentions, reblogs, favourites, or polls.\
**Type:** [Status](status.md)\ **Type:** [Status](status.md)\
**Version history:** Added in 0.9.9 **Version history:**\
0.9.9 - added
## See also ## See also

View File

@ -0,0 +1,170 @@
---
title: announcements
description: For announcements set by administration.
menu:
docs:
weight: 90
parent: methods
---
{{< api-method method="get" host="https://mastodon.example" path="/api/v1/announcements" title="View all announcements" >}}
{{< api-method-description >}}
See all currently active announcements set by admins.
**Returns:** Array of Announcement\
**OAuth:** User token\
**Version history:**\
3.1.0 - added
{{< endapi-method-description >}}
{{< api-method-spec >}}
{{< api-method-request >}}
{{< api-method-headers >}}
{{< api-method-parameter name="Authorization" type="string" required=true >}}
Bearer &lt;user token&gt;
{{< endapi-method-parameter >}}
{{< endapi-method-headers >}}
{{< api-method-query-parameters >}}
{{< api-method-parameter name="with_dismissed" type="boolean" required=false >}}
If true, response will include announcements dismissed by the user. Defaults to false.
{{< endapi-method-parameter >}}
{{< endapi-method-query-parameters >}}
{{< endapi-method-request >}}
{{< api-method-response >}}
{{< api-method-response-example httpCode=200 >}}
{{< api-method-response-example-description >}}
Currently active announcements
{{< endapi-method-response-example-description >}}
```javascript
```
{{< endapi-method-response-example >}}
{{< endapi-method-response >}}
{{< endapi-method-spec >}}
{{< endapi-method >}}
{{< api-method method="post" host="https://mastodon.example" path="/api/v1/announcements/:id/dismiss" title="Dismiss an announcement" >}}
{{< api-method-description >}}
Allows a user to mark the announcement as read.
**Returns:** Empty\
**OAuth:** User token + `write:accounts`\
**Version history:**\
3.1.0 - added
{{< endapi-method-description >}}
{{< api-method-spec >}}
{{< api-method-request >}}
{{< api-method-headers >}}
{{< api-method-parameter name="Authorization" type="string" required=true >}}
Bearer &lt;user token&gt;
{{< endapi-method-parameter >}}
{{< endapi-method-headers >}}
{{< api-method-path-parameters >}}
{{< api-method-parameter name=":id" type="string" required=true >}}
Local ID of an announcement in the database.
{{< endapi-method-parameter >}}
{{< endapi-method-path-parameters >}}
{{< endapi-method-request >}}
{{< api-method-response >}}
{{< api-method-response-example httpCode=200 >}}
{{< api-method-response-example-description >}}
{{< endapi-method-response-example-description >}}
```javascript
```
{{< endapi-method-response-example >}}
{{< endapi-method-response >}}
{{< endapi-method-spec >}}
{{< endapi-method >}}
{{< api-method method="put" host="https://mastodon.example" path="/api/v1/announcements/:id/reactions/:name" title="Add reaction" >}}
{{< api-method-description >}}
React to an announcement with an emoji.
**Returns:** Empty\
**OAuth:** User token + `write:favourites`\
**Version history:**\
3.1.0 - added
{{< endapi-method-description >}}
{{< api-method-spec >}}
{{< api-method-request >}}
{{< api-method-headers >}}
{{< api-method-parameter name="Authorization" type="string" required=true >}}
Bearer &lt;user token&gt;
{{< endapi-method-parameter >}}
{{< endapi-method-headers >}}
{{< api-method-path-parameters >}}
{{< api-method-parameter name=":id" type="string" required=true >}}
Local ID of an announcement in the database.
{{< endapi-method-parameter >}}
{{< api-method-parameter name=":name" type="string" required=true >}}
Unicode emoji, or shortcode of custom emoji
{{< endapi-method-parameter >}}
{{< endapi-method-path-parameters >}}
{{< endapi-method-request >}}
{{< api-method-response >}}
{{< api-method-response-example httpCode=200 >}}
{{< api-method-response-example-description >}}
{{< endapi-method-response-example-description >}}
```javascript
```
{{< endapi-method-response-example >}}
{{< endapi-method-response >}}
{{< endapi-method-spec >}}
{{< endapi-method >}}
{{< api-method method="delete" host="https://mastodon.example" path="/api/v1/announcements/:id/reactions/:name" title="Remove reaction" >}}
{{< api-method-description >}}
Undo a react emoji to an announcement.
**Returns:** Empty\
**OAuth:** User token + `write:favourites`\
**Version history:**\
3.1.0 - added
{{< endapi-method-description >}}
{{< api-method-spec >}}
{{< api-method-request >}}
{{< api-method-headers >}}
{{< api-method-parameter name="Authorization" type="string" required=true >}}
Bearer &lt;user token&gt;
{{< endapi-method-parameter >}}
{{< endapi-method-headers >}}
{{< api-method-path-parameters >}}
{{< api-method-parameter name=":id" type="string" required=true >}}
Local ID of an announcement in the database.
{{< endapi-method-parameter >}}
{{< api-method-parameter name=":name" type="string" required=true >}}
Unicode emoji, or shortcode of custom emoji
{{< endapi-method-parameter >}}
{{< endapi-method-path-parameters >}}
{{< endapi-method-request >}}
{{< api-method-response >}}
{{< api-method-response-example httpCode=200 >}}
{{< api-method-response-example-description >}}
{{< endapi-method-response-example-description >}}
```javascript
```
{{< endapi-method-response-example >}}
{{< endapi-method-response >}}
{{< endapi-method-spec >}}
{{< endapi-method >}}

View File

@ -15,11 +15,11 @@ Notifications concerning the user. This API returns Link headers containing link
**Returns:** Array of Notification\ **Returns:** Array of Notification\
**OAuth:** User token + `read:notifications`\ **OAuth:** User token + `read:notifications`\
**Version history:** **Version history:**\
0.0.0 - added\
- 0.0.0 - added 2.6.0 - add `min_id`\
- 2.6.0 - add min_id 2.9.0 - add `account_id`\
- 2.9.0 - add account_id 3.1.0 - add `follow_request` type
{{< endapi-method-description >}} {{< endapi-method-description >}}
{{< api-method-spec >}} {{< api-method-spec >}}
@ -43,7 +43,7 @@ Return results immediately newer than this ID
Maximum number of results to return \(default 20\) Maximum number of results to return \(default 20\)
{{< endapi-method-parameter >}} {{< endapi-method-parameter >}}
{{< api-method-parameter name="exclude_types" type="array" required=false >}} {{< api-method-parameter name="exclude_types" type="array" required=false >}}
Array of types to exclude \(`follow`, `favourite`, `reblog`, `mention`, `poll`\) Array of types to exclude \(`follow`, `favourite`, `reblog`, `mention`, `poll`, `follow_request`\)
{{< endapi-method-parameter >}} {{< endapi-method-parameter >}}
{{< api-method-parameter name="account_id" type="string" required=false >}} {{< api-method-parameter name="account_id" type="string" required=false >}}
Return only notifications received from this account Return only notifications received from this account
@ -148,9 +148,8 @@ View information about a notification with a given ID.
**Returns:** Notification\ **Returns:** Notification\
**OAuth:** User token + `read:notifications`\ **OAuth:** User token + `read:notifications`\
**Version history:** **Version history:**\
0.0.0 - added
- 0.0.0 - added
{{< endapi-method-description >}} {{< endapi-method-description >}}
{{< api-method-spec >}} {{< api-method-spec >}}
@ -236,9 +235,8 @@ Clear all notifications from the server.
**Returns:** empty object\ **Returns:** empty object\
**OAuth:** User token + `write:notifications`\ **OAuth:** User token + `write:notifications`\
**Version history:** **Version history:**\
0.0.0 - added
- 0.0.0 - added
{{< endapi-method-description >}} {{< endapi-method-description >}}
{{< api-method-spec >}} {{< api-method-spec >}}
@ -284,9 +282,8 @@ Clear a single notification from the server.
**Returns:** empty object\ **Returns:** empty object\
**OAuth:** User token + `write:notifications`\ **OAuth:** User token + `write:notifications`\
**Version history:** **Version history:**\
1.3.0 - added
- 1.3.0 - added
{{< endapi-method-description >}} {{< endapi-method-description >}}
{{< api-method-spec >}} {{< api-method-spec >}}
@ -337,9 +334,9 @@ Delete a single notification from the server.
**Returns:** empty object\ **Returns:** empty object\
**OAuth:** User token + `write:notifications`\ **OAuth:** User token + `write:notifications`\
**Version history**: **Version history**:\
- 0.0.0 - available 0.0.0 - available\
- 3.0.0 - removed 3.0.0 - removed
{{< endapi-method-description >}} {{< endapi-method-description >}}
{{< api-method-spec >}} {{< api-method-spec >}}

View File

@ -3,7 +3,7 @@ title: oembed
description: For generating OEmbed previews. description: For generating OEmbed previews.
menu: menu:
docs: docs:
weight: 100 weight: 110
parent: methods parent: methods
--- ---

View File

@ -3,7 +3,7 @@ title: proofs
description: For use by identity providers. description: For use by identity providers.
menu: menu:
docs: docs:
weight: 90 weight: 100
parent: methods parent: methods
--- ---

View File

@ -4,7 +4,9 @@
{{ with .Description }} {{ with .Description }}
<p>{{.}}</p> <p>{{.}}</p>
{{ end }} {{ end }}
<aside>
{{.TableOfContents}}
</aside>
<div class="e-content"> <div class="e-content">
{{ .Content }} {{ .Content }}