wholetrans/docs-mastodon
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update documentation with contents by twrnh

Browse source
This commit is contained in:
Eugen Rochko 2020-01-01 22:37:59 +01:00
parent 92e8aadd7f
commit 33cb69ad07
324 changed files with 18140 additions and 9654 deletions
Download patch file Download diff file Expand all files Collapse all files

48
content/en/api/authentication.md
View file

@ -1,48 +0,0 @@
---
title: Authentication
description: How to authenticate with OAuth 2 on Mastodon
menu:
docs:
parent: api
weight: 1
---
Mastodon is federated, therefore you can't be expected to manually register your application on all potential servers your users might want to login on. For this reason, there is an open app registration API, so obtaining OAuth 2 credentials for OAuth 2 authorization can be automated.
Make sure that you allow your users to specify the domain they want to connect to before login. Use that domain to acquire a client id/secret for OAuth 2 and then proceed with normal OAuth 2 also using that domain to build the URLs.
Mastodon supports the following OAuth 2 flows:
- **Authorization code flow**: For end-users
- **Password grant flow**: For bots and other single-user applications
- **Client credentials flow**: For applications that do not act on behalf of users
## OAuth 2 endpoints
The following descriptions are taken from the [Doorkeeper documentation](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples). Mastodon uses Doorkeeper to implement OAuth 2.
### GET /oauth/authorize
Redirect here with `response_type=code`, `client_id`, `client_secret`, `redirect_uri`, `scope`, and optional `state`. Displays an authorization form to the user. If approved, it will create and return an authorization code, then redirect to the desired `redirect_uri`, or show the authorization code if `urn:ietf:wg:oauth:2.0:oob` was requested.
### POST /oauth/token
Post here with `authorization_code` for authorization code grant type or `username` and `password` for password grant type. Returns an access token. This corresponds to the token endpoint, section 3.2 of the OAuth 2 RFC.
### POST /oauth/revoke
Post here with client credentials (in basic auth or in params `client_id` and `client_secret`) to revoke an access token. This corresponds to the token endpoint, using the OAuth 2.0 Token Revocation RFC (RFC 7009).
## Example authorization code flow
1. Get `client_id` and `client_secret` from your local cache. If you don't have the two, you need to [register the application]({{< relref "api/rest/apps.md#post-api-v1-apps" >}}). Store `client_id` and `client_secret` in your local cache for next time. We actually don't need the `id` returned from this call.
1. Tell the user to visit `/oauth/authorize` with parameters `scope`, `response_type=code`, `redirect_uri`, your `client_id`, and optionally a randomly-generated `state` parameter. The user clicks on the URL and gets shown a page asking them to authorize your app for the scopes you requested. If the user clicks on the right button, they are redirected back to your `redirect_uri` with a `code` param in the query string. That is the authorization code. If you provided a `state` value in the previous step, that will be passed along as well.
1. Send a POST request to `/oauth/token` with the parameters `client_id`, `client_secret`, `grant_type=authorization_code`, `code`, `redirect_uri`. Save the `access_token` you get back in your local cache. Note that an authorization code can only be used once. If it has been used already, you need to repeat step two to get a new one.
Once you have the access token, add the HTTP header `Authorization: Bearer ...` to any API call.
## Common gotchas
- The OAuth param name is `scope`, but when registering the application using Mastodon's REST API, the param name is `scopes`. The OAuth param can be a subset of the scopes you registered initially, but cannot include anything that wasn't in the original set.
- The OAuth param name is `redirect_uri`, but when registering the application using Mastodon's REST API, the param name is `redirect_uris`. The latter can actually consist of multiple allowed URIs, separated by newlines.
- The `redirect_uri` in all OAuth requests must either be the same as the one registered with the application, or one of them, if you registered multiple URIs separated by newlines with the application.

380
content/en/api/entities.md
View file

@ -1,380 +0,0 @@
---
title: Entities
description: Overview of entities returned from Mastodon's REST API
menu:
docs:
parent: api
weight: 3
---
- All IDs are encoded as string representations of integers.
- IDs can be sorted first by size, and then lexically, to produce a chronological ordering of resources.
- All datetimes are in ISO 8601 format
- All HTML strings are sanitized by the server
- All language codes are in ISO 6391 format
## Account
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `id` | String |{{< no >}}|0.1.0|
| `username` | String |{{< no >}}|0.1.0|
| `acct` | String |{{< no >}}|0.1.0|
| `display_name` | String |{{< no >}}|0.1.0|
| `locked` | Boolean |{{< no >}}|0.1.0|
| `created_at` | String (Datetime) |{{< no >}}|0.1.0|
| `followers_count` | Number |{{< no >}}|0.1.0|
| `following_count` | Number |{{< no >}}|0.1.0|
| `statuses_count` | Number |{{< no >}}|0.1.0|
| `note` | String |{{< no >}}|0.1.0|
| `url` | String (URL) |{{< no >}}|0.1.0|
| `avatar` | String (URL) |{{< no >}}|0.1.0|
| `avatar_static` | String (URL) |{{< no >}}|1.1.2|
| `header` | String (URL) |{{< no >}}|0.1.0|
| `header_static` | String (URL) |{{< no >}}|1.1.2|
| `emojis` | Array of [Emoji](#emoji) |{{< no >}}|2.4.0|
| `moved` | [Account](#account) |{{< yes >}}|2.1.0|
| `fields` | Array of [Hash](#field) |{{< yes >}}|2.4.0|
| `bot` | Boolean |{{< yes >}}|2.4.0|
### Field
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `name` | String |{{< no >}}|2.4.0|
| `value` | String (HTML) |{{< no >}}|2.4.0|
| `verified_at` | String (Datetime) |{{< yes >}}|2.6.0|
### Source
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `privacy` | String |{{< yes >}}|1.5.0|
| `sensitive` | Boolean |{{< yes >}}|1.5.0|
| `language` | String (ISO6391) |{{< yes >}}|2.4.2|
| `note` | String |{{< no >}}|1.5.0|
| `fields` | Array of Hash |{{< no >}}|2.4.0|
### Token
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `access_token` | String |{{< no >}}|0.1.0|
| `token_type` | String |{{< no >}}|0.1.0|
| `scope` | String |{{< no >}}|0.1.0|
| `created_at` | Number |{{< no >}}|0.1.0|
## Application
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `name` | String |{{< no >}}|0.9.9|
| `website` | String (URL) |{{< yes >}}|0.9.9|
## Attachment
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `id` | String |{{< no >}}|0.6.0|
| `type` | [String (Enum)](#type) |{{< no >}}|0.6.0|
| `url` | String (URL) |{{< no >}}|0.6.0|
| `remote_url` | String (URL) |{{< yes >}}|0.6.0|
| `preview_url` | String (URL) |{{< no >}}|0.6.0|
| `text_url` | String (URL) |{{< yes >}}|0.6.0|
| `meta` | [Hash](#meta) |{{< yes >}}|1.5.0|
| `description` | String |{{< yes >}}|2.0.0|
### Type
- `unknown`
- `image`
- `gifv`
- `video`
### Meta
May contain subtrees `small` and `original`.
Images may contain `width`, `height`, `size`, `aspect`, while videos (including GIFV) may contain `width`, `height`, `frame_rate`, `duration` and `bitrate`.
There may be another top-level object, `focus` with the coordinates `x` and `y`. These coordinates can be used for smart thumbnail cropping, [see this for reference](https://github.com/jonom/jquery-focuspoint#1-calculate-your-images-focus-point).
## Card
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `url` | String (URL) |{{< no >}}|1.0.0|
| `title` | String |{{< no >}}|1.0.0|
| `description` | String |{{< no >}}|1.0.0|
| `image` | String (URL) |{{< yes >}}|1.0.0|
| `type` | [String (Enum)](#type-1) |{{< no >}}|1.3.0|
| `author_name` | String |{{< yes >}}|1.3.0|
| `author_url` | String (URL) |{{< yes >}}|1.3.0|
| `provider_name` | String |{{< yes >}}|1.3.0|
| `provider_url` | String (URL) |{{< yes >}}|1.3.0|
| `html` | String (HTML) |{{< yes >}}|1.3.0|
| `width` | Number |{{< yes >}}|1.3.0|
| `height` | Number |{{< yes >}}|1.3.0|
### Type
- `link`
- `photo`
- `video`
- `rich`
## Context
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `ancestors` | Array of [Status](#status) |{{< no >}}|0.6.0|
| `descendants` | Array of [Status](#status) |{{< no >}}|0.6.0|
## Emoji
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `shortcode` | String |{{< no >}}|2.0.0|
| `static_url` | String (URL) |{{< no >}}|2.0.0|
| `url` | String (URL) |{{< no >}}|2.0.0|
| `visible_in_picker` | Boolean |{{< no >}}|2.1.0|
## Error
The most important part of an error response is the HTTP status code. Standard semantics are followed. The body of an error is a JSON object with this structure:
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `error` | String |{{< no >}}|0.6.0|
## Filter
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `id` | String |{{< no >}}|2.4.3|
| `phrase` | String |{{< no >}}|2.4.3|
| `context` | Array of [String (Enum)](#context-1) |{{< no >}}|2.4.3|
| `expires_at` | String (Datetime) |{{< yes >}}|2.4.3|
| `irreversible` | Boolean |{{< no >}}|2.4.3|
| `whole_word` | Boolean |{{< no >}}|2.4.3|
### Context
- `home`
- `notifications`
- `public`
- `thread`
### Implementation notes
If `whole_word` is true , client app should do:
- Define 'word constituent character' for your app. In the official implementation, it's `[A-Za-z0-9_]` in JavaScript, and `[[:word:]]` in Ruby. In Ruby case it's the POSIX character class (Letter | Mark | Decimal_Number | Connector_Punctuation).
- If the phrase starts with a word character, and if the previous character before matched range is a word character, its matched range should be treated to not match.
- If the phrase ends with a word character, and if the next character after matched range is a word character, its matched range should be treated to not match.
Please check `app/javascript/mastodon/selectors/index.js` and `app/lib/feed_manager.rb` in the Mastodon source code for more details.
## Instance
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `uri` | String |{{< no >}}|1.1.0|
| `title` | String |{{< no >}}|1.1.0|
| `description` | String |{{< no >}}|1.1.0|
| `email` | String |{{< no >}}|1.1.0|
| `version` | String |{{< no >}}|1.3.0|#
| `thumbnail` | String (URL) |{{< yes >}}|1.6.1|
| `urls` | [Hash](#urls) |{{< no >}}|1.4.2|
| `stats` | [Hash](#stats) |{{< no >}}|1.6.0|
| `languages` | Array of String (ISO 639, Part 1-5) |{{< no >}}|2.3.0|
| `contact_account` | [Account](#account) |{{< yes >}}|2.3.0|
### URLs
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
|`streaming_api`| String (URL) |{{< no >}}|1.4.2|
### Stats
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
|`user_count`| Number |{{< no >}}|1.6.0|
|`status_count`| Number |{{< no >}}|1.6.0|
|`domain_count`| Number |{{< no >}}|1.6.0|
## List
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `id` | String |{{< no >}}|2.1.0|
| `title` | String |{{< no >}}|2.1.0|
## Mention
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `url` | String (URL) |{{< no >}}|0.6.0|
| `username` | String |{{< no >}}|0.6.0|
| `acct` | String |{{< no >}}|0.6.0|
| `id` | String |{{< no >}}|0.6.0|
## Notification
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `id` | String |{{< no >}}|0.9.9|
| `type` | [String (Enum)](#type-2) |{{< no >}}|0.9.9|
| `created_at` | String (Datetime) |{{< no >}}|0.9.9|
| `account` | [Account](#account) |{{< no >}}|0.9.9|
| `status` | [Status](#status) |{{< yes >}}|0.9.9|
### Type
- `follow`
- `mention`
- `reblog`
- `favourite`
- `poll`
## Poll
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `id` | String |{{< no >}}|2.8.0|
| `expires_at` | String (Datetime) |{{< yes >}}|2.8.0|
| `expired` | Boolean |{{< no >}}|2.8.0|
| `multiple` | Boolean |{{< no >}}|2.8.0|
| `votes_count` | Number |{{< no >}}|2.8.0|
| `options` | Array of [Poll option](#poll-option) |{{< no >}}|2.8.0|
| `voted` | Boolean |{{< yes >}}|2.8.0|
### Poll option
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `title` | String |{{< no >}}|2.8.0|
| `votes_count` | Number |{{< yes >}}|2.8.0|
## Push subscription
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `id` | String |{{< no >}}|2.4.0|
| `endpoint` | String (URL) |{{< no >}}|2.4.0|
| `server_key` | String |{{< no >}}|2.4.0|
| `alerts` | [Hash](#alerts) |{{< no >}}|2.4.0|
### Alerts
???
## Relationship
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `id` | String |{{< no >}}|0.6.0|
| `following` | Boolean |{{< no >}}|0.6.0|
| `followed_by` | Boolean |{{< no >}}|0.6.0|
| `blocking` | Boolean |{{< no >}}|0.6.0|
| `muting` | Boolean |{{< no >}}|1.1.0|
| `muting_notifications` | Boolean |{{< no >}}|2.1.0|
| `requested` | Boolean |{{< no >}}|0.9.9|
| `domain_blocking` | Boolean |{{< no >}}|1.4.0|
| `showing_reblogs` | Boolean |{{< no >}}|2.1.0|
| `endorsed` | Boolean |{{< no >}}|2.5.0|
## Results
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `accounts` | Array of [Account](#account) |{{< no >}}|1.1.0|
| `statuses` | Array of [Status](#status) |{{< no >}}|1.1.0|
| `hashtags` | Array of [Tag](#tag) |{{< no >}}|1.1.0|
## Status
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `id` | String |{{< no >}}|0.1.0|
| `uri` | String |{{< no >}}|0.1.0|
| `url` | String (URL) |{{< yes >}}|0.1.0|
| `account` | [Account](#account) |{{< no >}}|0.1.0|
| `in_reply_to_id` | String |{{< yes >}}|0.1.0|
| `in_reply_to_account_id` | String |{{< yes >}}|1.0.0|
| `reblog` | [Status](#status) |{{< yes >}}|0.1.0|
| `content` | String (HTML) |{{< no >}}|0.1.0|
| `created_at` | String (Datetime) |{{< no >}}|0.1.0|
| `emojis` | Array of [Emoji](#emoji) |{{< no >}}|2.0.0|
| `replies_count` | Number |{{< no >}}|2.5.0|
| `reblogs_count` | Number |{{< no >}}|0.1.0|
| `favourites_count` | Number |{{< no >}}|0.1.0|
| `reblogged` | Boolean |{{< yes >}}|0.1.0|
| `favourited` | Boolean |{{< yes >}}|0.1.0|
| `muted` | Boolean |{{< yes >}}|1.4.0|
| `sensitive` | Boolean |{{< no >}}|0.9.9|
| `spoiler_text` | String |{{< no >}}|1.0.0|
| `visibility` | [String (Enum)](#visibility) |{{< no >}}|0.9.9|
| `media_attachments` | Array of [Attachment](#attachment) |{{< no >}}|0.6.0|
| `mentions` | Array of [Mention](#mention) |{{< no >}}|0.6.0|
| `tags` | Array of [Tag](#tag) |{{< no >}}|0.9.0|
| `card` | [Card](#card) |{{< yes >}}|2.6.0|
| `poll` | [Poll](#poll) |{{< yes >}}|2.8.0|
| `application` | [Application](#application) |{{< no >}}|0.9.9|
| `language` | String (ISO6391) |{{< yes >}}|1.4.0|
| `pinned` | Boolean |{{< yes >}}|1.6.0|
### Visibility
- `public`
- `unlisted`
- `private`
- `direct`
## ScheduledStatus
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `id` | String |{{< no >}}|2.7.0|
| `scheduled_at` | String (Datetime) |{{< no >}}|2.7.0|
| `params` | [StatusParams](#statusparams) |{{< no >}}|2.7.0|
| `media_attachments` | Array of [Attachment](#attachment) |{{< no >}}|2.7.0|
### StatusParams
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `text` | String |{{< no >}}|2.7.0|
| `in_reply_to_id` | String |{{< yes >}}|2.7.0|
| `media_ids` | Array of String |{{< yes >}}|2.7.0|
| `sensitive` | Boolean |{{< yes >}}|2.7.0|
| `spoiler_text` | String |{{< yes >}}|2.7.0|
| `visibility` | [String (Enum)](#visibility) |{{< no >}}|2.7.0|
| `scheduled_at` | String (Datetime) |{{< yes >}}|2.7.0|
| `application_id` | String |{{< no >}}|2.7.0|
## Tag
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `name` | String |{{< no >}}|0.9.0|
| `url` | String (URL) |{{< no >}}|0.9.0|
| `history` | Array of [History](#history) |{{< yes >}}|2.4.1|
### History
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `day` | String (UNIX timestamp) |{{< no >}}|2.4.1|
| `uses` | Number |{{< no >}}|2.4.1|
| `accounts` | Number |{{< no >}}|2.4.1|
## Conversation
|Attribute|Type|Nullable|Added in|
|---------|-----------|:------:|:------:|
| `id` | String |{{< no >}}|2.6.0|
| `accounts` | Array of [Account](#account) |{{< no >}}|2.6.0|
| `last_status` | [Status](#status) |{{< yes >}}|2.6.0|
| `unread` | Boolean |{{< no >}}|2.6.0|

52
content/en/api/guidelines.md
View file

@ -1,52 +0,0 @@
---
title: Guidelines
description: Guidelines that app developers for Mastodon should follow
menu:
docs:
parent: api
weight: -1
---
## Login
**The user must be able to login to any Mastodon server from the app**. This means you must ask for either the full handle, or server domain, and use the app registrations API to dynamically obtain OAuth2 credentials.
## Usernames
**Decentralization must be transparent to the user**. It should be possible to see that a given user is from another server, by e.g. displaying their `acct` (username and domain) somewhere.
## Formatting
Plain text is not available for content from remote servers, and plain text syntax rules may vary wildly between Mastodon and other fediverse applications. For certain attributes, such as the content of statuses, **Mastodon provides sanitized HTML**.
### HTML tags
You may expect these tags to appear in the content: `<p>`, `<br>`, `<span>`, `<a>`
### Mentions and hashtags
Mentions and hashtags are `<a>` tags. To give those links their semantic meaning and add special handling, such as opening a mentioned profile within your app instead of as a web page, metadata is included with the status, which can be matched to a particular tag.
### Custom emoji
Custom emoji remain in their plain text shortcode form. Metadata about the determined custom emoji is included with the status, and the shortcodes must be matched against the text to display the images.
### Other links
Links in Mastodon are not shortened using URL shorteners. However, URLs in text always count for 23 characters, and are intended to be shortened visually. For that purpose, a link is marked up like this:
```html
<a href="https://example.com/page/that/is/very/long">
<span class="invisible">https://</span>
<span class="ellipsis">example.com/page</span>
<span class="invisible">/that/is/very/long</span>
</a>
```
The spans with the `invisible` class can be hidden. The middle span is intended to remain visible. It may have no class if the URL is not very long, otherwise it will have an `ellipsis` class. No ellipsis (`…`) character is inserted in the markup, instead, you are expected to insert it yourself if you need it in your app.
## Filters
Clients must do their own text filtering based on filters returned from the API. The server will apply `irreversible` filters for home and notifications context, but anything else is still up to the client to filter!
Expired filters are not deleted by the server. They should no longer be applied but they are still stored by the server. It is up to clients to delete those filters eventually.

103
content/en/api/libraries.md
View file

@ -1,103 +0,0 @@
---
title: Libraries
description: List of libraries that work with the Mastodon API in various programming languages
menu:
docs:
parent: api
weight: -1
---
## Apex (Salesforce)
- [apex-mastodon](https://github.com/tzmfreedom/apex-mastodon)
## C# (.NET Standard)
- [Mastodot](https://github.com/yamachu/Mastodot)
- [Mastonet](https://github.com/glacasa/Mastonet)
- [TootNet](https://github.com/cucmberium/TootNet)
- [mastodon-api-cs](https://github.com/pawotter/mastodon-api-cs)
- [Mastodon.Net](https://github.com/Tlaster/Mastodon.Net)
## C++
- [mastodon-cpp](https://github.com/tastytea/mastodon-cpp)
## Crystal
- [mastodon.cr](https://github.com/decors/mastodon.cr)
## Common Lisp
- [tooter](https://github.com/Shinmera/tooter)
## Elixir
- [hunter](https://github.com/milmazz/hunter)
## Go
- [go-mastodon](https://github.com/mattn/go-mastodon)
- [madon](https://github.com/McKael/madon)
## Haskell
- [hastodon](https://github.com/syucream/hastodon)
## Java
- [mastodon4j](https://github.com/sys1yagi/mastodon4j)
## JavaScript
- [masto.js](https://github.com/neet/masto.js)
- [libodonjs](https://github.com/Zatnosk/libodonjs)
## JavaScript (Browser)
- [mastodon.js](https://github.com/Kirschn/mastodon.js)
## JavaScript (Node.js)
- [node-mastodon](https://github.com/jessicahayley/node-mastodon)
- [mastodon-api](https://github.com/vanita5/mastodon-api)
## Perl
- [Mastodon::Client](https://metacpan.org/pod/Mastodon::Client)
## PHP
- [Mastodon API for Laravel](https://github.com/kawax/laravel-mastodon-api)
- [Mastodon-api-php](https://github.com/yks118/Mastodon-api-php)
- [Composer based php API wrapper](https://github.com/r-daneelolivaw/mastodon-api-php)
- [MastodonOAuthPHP](https://github.com/TheCodingCompany/MastodonOAuthPHP)
- [Phediverse Mastodon REST Client](https://github.com/phediverse/mastodon-rest)
- [TootoPHP](https://framagit.org/MaxKoder/TootoPHP)
- [oauth2-mastodon](https://github.com/lrf141/oauth2-mastodon)
- [Mastodon Wordpress API](https://github.com/L1am0/mastodon_wordpress_api)
## Python
- [Mastodon.py](https://github.com/halcy/Mastodon.py)
## R
- [mastodon](https://github.com/ThomasChln/mastodon)
## Ruby
- [mastodon-api](https://github.com/tootsuite/mastodon-api)
## Rust
- [mammut](https://github.com/Aaronepower/mammut)
- [elefren](https://github.com/pwoolcoc/elefren)
## Scala
- [scaladon](https://github.com/schwitzerm/scaladon)
## Swift
- [MastodonKit](https://github.com/ornithocoder/MastodonKit)

89
content/en/api/oauth-scopes.md Normal file
View file

@ -0,0 +1,89 @@
---
title: OAuth Scopes
menu:
docs:
weight: 10
parent: api
---
## OAuth Scopes
The API is divided up into access scopes. The scopes are hierarchical, i.e. if you have access to `read`, you automatically have access to `read:accounts`. **It is recommended that you request as little as possible for your application.**
Multiple scopes can be requested at the same time: During app creation with the `scopes` param, and during the authorization phase with the `scope` query param \(space-separate the scopes\).
{{< hint style="info" >}}
Mind the `scope` vs `scopes` difference. This is because `scope` is a standard OAuth parameter name, so it is used in the OAuth methods. Mastodon’s own REST API uses the more appropriate `scopes`.
{{< /hint >}}
If you do not specify a `scope` in your authorization request, or a `scopes` in your app creation request, the resulting access token / app will default to `read` access.
The set of scopes saved during app creation must include all the scopes that you will request in the authorization request, otherwise authorization will fail.
### Version history
- 0.9.0 - read, write, follow
- 2.4.0 - push
- 2.4.3 - granular scopes [https://github.com/tootsuite/mastodon/pull/7929](https://github.com/tootsuite/mastodon/pull/7929)
- 2.6.0 - read:reports deprecated \(unused stub\) [https://github.com/tootsuite/mastodon/pull/8736/commits/adcf23f1d00c8ff6877ca2ee2af258f326ae4e1f](https://github.com/tootsuite/mastodon/pull/8736/commits/adcf23f1d00c8ff6877ca2ee2af258f326ae4e1f)
- 2.6.0 - write:conversations added [https://github.com/tootsuite/mastodon/pull/9009](https://github.com/tootsuite/mastodon/pull/9009)
- 2.9.1 - Admin scopes added [https://github.com/tootsuite/mastodon/pull/9387](https://github.com/tootsuite/mastodon/pull/9387)
- 3.1.0 - Bookmark scopes added
## List of scopes
### `read`
Grants access to read data. Requesting `read` will also grant child scopes shown in the left column of the table below.
### `write`
Grants access to write data. Requesting `write` will also grant child scopes shown in the right column of the table below.
### `follow`
Grants access to manage relationships. Requesting `follow` will also grant the following child scopes, shown in bold in the table:
* `read:blocks`, `write:blocks`
* `read:follows`, `write:follows`
* `read:mutes`, `write:mutes`
### `push`
Grants access to [Web Push API subscriptions.]({{< relref "../methods/notifications/push.md" >}}) Added in Mastodon 2.4.0.
### Admin scopes
Used for moderation API. Added in Mastodon 2.9.1. The following granular scopes are available \(note that there is no singular `admin` scope\):
* `admin:read`
* `admin:read:accounts`
* `admin:read:reports`
* `admin:write`
* `admin:write:accounts`
* `admin:write:reports`
## Granular scopes
| read | write |
| :--- | :--- |
| read:accounts | write:accounts |
| **read:blocks** | **write:blocks** |
| read:bookmarks | write:bookmarks |
| | write:conversations |
| read:favourites | write:favourites |
| read:filters | write:filters |
| **read:follows** | **write:follows** |
| read:lists | write:lists |
| | write:media |
| **read:mutes** | **write:mutes** |
| read:notifications | write:notifications |
| | write:reports |
| read:search | |
| read:statuses | write:statuses |
| admin:read | admin:write |
| :--- | :--- |
| admin:read:accounts | admin:write:accounts |
| admin:read:reports | admin:write:reports |

44
content/en/api/parameters.md
View file

@ -1,44 +0,0 @@
---
title: Parameters
description: Specifics of parameter passing to the Mastodon API
menu:
docs:
parent: api
weight: 3
---
## Parameter format
Query strings, form data, and JSON submitted via POST body is equally understood by the API. It is expected that query strings are used for GET requests, and form data or JSON is used for all other requests.
## Arrays
An array parameter must encoded using bracket notation, e.g. `array[0]=foo&array[1]=bar` would be translated into:
```ruby
array = [
'foo',
'bar',
]
```
## Booleans
A boolean value is considered false for the values `0`, `f`, `F`, `false`, `FALSE`, `off`, `OFF`, considered to not be provided for empty strings, and considered to be true for all other values.
## Files
File uploads must be encoded using `multipart/form-data`.
## Nested parameters
Some parameters need to be nested. For that, bracket notation must also be used. For example, `source[privacy]=public&source[language]=en` would be translated into:
```ruby
source = {
privacy: 'public',
language: 'en',
}
```
This can be combined with arrays as well.

49
content/en/api/permissions.md
View file

@ -1,49 +0,0 @@
---
title: Permissions
description: Overview of OAuth 2 access scopes in Mastodon
menu:
docs:
parent: api
weight: 2
---
The API is divided up into access scopes:
|Scope|Parent(s)|Added in|
|:----|---------|:------:|
|`write`||0.9.0|
|`write:accounts`|`write`|2.4.3|
|`write:blocks`|`write`, `follow`|2.4.3|
|`write:favourites`|`write`|2.4.3|
|`write:filters`|`write`|2.4.3|
|`write:follows`|`write`, `follow`|2.4.3|
|`write:lists`|`write`|2.4.3|
|`write:media`|`write`|2.4.3|
|`write:mutes`|`write`, `follow`|2.4.3|
|`write:notifications`|`write`|2.4.3|
|`write:reports`|`write`|2.4.3|
|`write:statuses`|`write`|2.4.3|
|`read`||0.9.0|
|`read:accounts`|`read`|2.4.3|
|`read:blocks`|`read`, `follow`|2.4.3|
|`read:favourites`|`read`|2.4.3|
|`read:filters`|`read`|2.4.3|
|`read:follows`|`read`, `follow`|2.4.3|
|`read:lists`|`read`|2.4.3|
|`read:mutes`|`read`, `follow`|2.4.3|
|`read:notifications`|`read`|2.4.3|
|`read:reports`|`read`|2.4.3|
|`read:search`|`read`|2.4.3|
|`read:statuses`|`read`|2.4.3|
|`follow`||0.9.0|
|`push`||2.4.0|
The scopes are hierarchical, i.e. if you have access to `read`, you automatically have access to `read:accounts`. **It is recommended that you request as little as possible for your application.**
Multiple scopes can be requested at the same time: During app creation with the `scopes` param, and during the authorization phase with the `scope` query param (space-separate the scopes).
> **Note:** Mind the `scope` vs `scopes` difference. This is because `scope` is a standard OAuth parameter name, so it is used in the OAuth methods. Mastodon's own REST API uses the more appropriate `scopes`.
If you do not specify a `scope` in your authorization request, or a `scopes` in your app creation request, the resulting access token / app will default to `read` access.
The set of scopes saved during app creation must include all the scopes that you will request in the authorization request, otherwise authorization will fail.

15
content/en/api/push.md
View file

@ -1,15 +0,0 @@
---
title: Web Push API
overview: How to use the Web Push API in Mastodon to receive push notifications in a native or browser app
menu:
docs:
parent: api
weight: 5
---
Mastodon natively supports the [Web Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API). You can utilize the same mechanisms for your native app. It requires running a proxy server that connects to Android's and Apple's proprietary notification gateways. However, the proxy server does not have access to the contents of the notifications. For a reference, see [Mozilla's web push server](https://github.com/mozilla-services/autopush), or more practically, see:
- [toot-relay](https://github.com/DagAgren/toot-relay)
- [PushToFCM](https://github.com/tateisu/PushToFCM)
Using the Web Push API requires your app to have the `push` scope. To create a new Web Push API subscription, use [POST /api/v1/push/subscription]({{< relref "notifications.md#post-api-v1-push-subscription" >}}).

203
content/en/api/rest/accounts.md
View file

@ -1,203 +0,0 @@
---
title: Accounts
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/accounts/:id
Returns [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="No" user="No" scope="read read:accounts" version="0.0.0" >}}
## POST /api/v1/accounts
Returns [Token]({{< relref "entities.md#token" >}})
The method is available to apps with a token obtained via the client credentials grant. It creates a user and account records, as well as an access token for the app that initiated the request. The user is unconfirmed, and an e-mail is sent as usual.
The method returns the access token, which the app should save for later. The REST API is not available to users with unconfirmed accounts, so the app must be smart to wait for the user to click a link in their e-mail inbox.
The method is rate-limited by IP to 5 requests per 30 minutes.
### Resource information
{{< api_method_info auth="Yes" user="No" scope="write write:accounts" version="2.7.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `username` | User name | Required |
| `email` | E-mail address | Required |
| `password` | Password text | Required |
| `agreement` | Agreement to local rules, terms of use, privacy policy (Bool) | Required |
| `locale` | The language of the e-mail to be sent first | Required |
The `agreement` parameter must be set to true after presenting the local rules, terms of use, privacy policy for the user and obtaining consent.
## GET /api/v1/accounts/verify_credentials
User's own account.
Returns [Account]({{< relref "entities.md#account" >}}) with an extra [`source` attribute]({{< relref "entities.md#source" >}}).
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:accounts" version="0.0.0" >}}
## PATCH /api/v1/accounts/update_credentials
Update user's own account.
Returns [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="0.0.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `display_name` | Display name | Optional |
| `note` | Biography | Optional |
| `avatar` | Avatar encoded using `multipart/form-data` | Optional |
| `header` | Header image encoded using `multipart/form-data` | Optional |
| `locked` | Enable follow requests | Optional |
| `source[privacy]` | Default post privacy preference | Optional |
| `source[sensitive]`| Whether to mark statuses as sensitive by default | Optional |
| `source[language]` | Override language on statuses by default (ISO6391) | Optional |
| `fields_attributes` | Profile metadata (max. 4) | Optional |
## GET /api/v1/accounts/:id/followers
Accounts which follow the given account.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="No" scope="read read:accounts" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 40 |
### Pagination
{{< api_pagination >}}
## GET /api/v1/accounts/:id/following
Accounts which the given account is following.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="No" scope="read read:accounts" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 40 |
### Pagination
{{< api_pagination >}}
## GET /api/v1/accounts/:id/statuses
An account's statuses.
Returns array of [Status]({{< relref "entities.md#status" >}})
### Resource information
{{< api_method_info auth="Yes" user="No" scope="read read:statuses" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|Added in|
|----|-----------|:------:|:-----:|:------:|
| `only_media` | Only return statuses that have media attachments | Optional | false | |
| `pinned` | Only return statuses that have been pinned | Optional | false | |
| `exclude_replies` | Skip statuses that reply to other statuses | Optional | false | |
| `max_id` | Return results older than ID | Optional | | |
| `since_id` | Return results newer than ID | Optional | | |
| `min_id` | Return results immediately newer than ID | Optional | | |
| `limit` | Maximum number of results | Optional | 20 | | |
| `exclude_reblogs` | Skip statuses that are reblogs of other statuses | Optional | false | 2.7.0 |
### Pagination
{{< api_dynamic_pagination >}}
## POST /api/v1/accounts/:id/follow
Follow an account.
Returns [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write:follows follow" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `reblogs` | Whether the followed account's reblogs will show up in the home timeline | Optional | true |
## POST /api/v1/accounts/:id/unfollow
Unfollow an account.
Returns [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write:follows follow" version="0.0.0" >}}
## GET /api/v1/accounts/relationships
Relationship of the user to the given accounts in regards to following, blocking, muting, etc.
Returns array of [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:follows" version="0.0.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `id` | Array of account IDs | Required |
## GET /api/v1/accounts/search
Search for matching accounts by username, domain and display name.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:accounts" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `q` | What to search for | Required ||
| `limit` | Maximum number of results | Optional | 40 |
| `resolve` | Attempt WebFinger look-up | Optional | false |
| `following` | Only who the user is following | Optional | false |

38
content/en/api/rest/apps.md
View file

@ -1,38 +0,0 @@
---
title: Apps
menu:
docs:
parent: rest-api
weight: 10
---
## POST /api/v1/apps
Create a new application to obtain OAuth2 credentials.
Returns [App]({{< relref "entities.md#app" >}}) with `client_id` and `client_secret`
### Resource information
{{< api_method_info auth="No" user="No" version="0.0.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `client_name` | Name of your application | Required |
| `redirect_uris` | Where the user should be redirected after authorization | Required |
| `scopes` | Space separated list of [scopes]({{< relref "permissions.md" >}}) | Required |
| `website` | URL to the homepage of your app | Optional |
> To display the authorization code to the end-user instead of redirecting to a web page, use `urn:ietf:wg:oauth:2.0:oob` in `redirect_uris`
## GET /api/v1/apps/verify_credentials
Confirm that the app's OAuth2 credentials work.
Returns [App]({{< relref "entities.md#app" >}})
### Resource information
{{< api_method_info auth="Yes" user="No" version="2.0.0" >}}

47
content/en/api/rest/blocks.md
View file

@ -1,47 +0,0 @@
---
title: Blocks
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/blocks
Accounts the user has blocked.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read:blocks follow" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 40 |
### Pagination
{{< api_pagination >}}
## POST /api/v1/accounts/:id/block
Block an account.
Returns [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write:blocks follow" version="0.0.0" >}}
## POST /api/v1/accounts/:id/unblock
Unblock an account.
Returns [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write:blocks follow" version="0.0.0" >}}

17
content/en/api/rest/custom-emojis.md
View file

@ -1,17 +0,0 @@
---
title: Custom emoji
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/custom_emojis
Custom emojis that are available on the server.
Returns array of [Emoji]({{< relref "entities.md#emoji" >}})
### Resource information
{{< api_method_info auth="No" user="No" version="2.0.0" >}}

55
content/en/api/rest/domain-blocks.md
View file

@ -1,55 +0,0 @@
---
title: Domain blocks
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/domain_blocks
Domains the user has blocked.
Returns array of string.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:blocks follow" version="1.4.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 40 |
### Pagination
{{< api_pagination >}}
## POST /api/v1/domain_blocks
Block a domain to hide all public posts from it, all notifications from it, and remove all followers from it.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:blocks follow" version="1.4.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `domain` | Domain to block| Required |
## DELETE /api/v1/domain_blocks
Remove a domain block.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:blocks follow" version="1.4.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `domain` | Domain to unblock| Required |

41
content/en/api/rest/endorsements.md
View file

@ -1,41 +0,0 @@
---
title: Endorsements
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/endorsements
Accounts the user chose to endorse.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:account" version="2.5.0" >}}
### Pagination
{{< api_pagination >}}
## POST /api/v1/accounts/:id/pin
Endorse an account, i.e. choose to feature the account on the user's public profile.
Returns [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="2.5.0" >}}
## POST /api/v1/accounts/:id/unpin
Undo endorse of an account.
Returns [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="2.5.0" >}}

43
content/en/api/rest/favourites.md
View file

@ -1,43 +0,0 @@
---
title: Favourites
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/favourites
Statuses the user has favourited.
Returns array of [Status]({{< relref "entities.md#status" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:favourites" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 20 |
### Pagination
{{< api_pagination >}}
## POST /api/v1/statuses/:id/favourite
Favourite a status.
Returns [Status]({{< relref "entities.md#status" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:favourites" version="0.0.0" >}}
## POST /api/v1/statuses/:id/unfavourite
Undo the favourite of a status.
Returns [Status]({{< relref "entities.md#status" >}})

75
content/en/api/rest/filters.md
View file

@ -1,75 +0,0 @@
---
title: Filters
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/filters
Text filters the user has configured that potentially must be applied client-side.
Returns array of [Filter]({{< relref "entities.md#filter" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:filters" version="2.4.3" >}}
## POST /api/v1/filters
Create a new filter.
Returns [Filter]({{< relref "entities.md#filter" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:filters" version="2.4.3" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `phrase` | Keyword or phrase to filter | Required |
| `context` | Array of strings that means filtering context. Each string is one of `home`, `notifications`, `public`, `thread`. At least one context must be specified. | Required |
| `irreversible` | Irreversible filtering will only work in `home` and `notifications` contexts by fully dropping the records. Otherwise, filtering is up to the client. | Optional |
| `whole_word` | Whether to consider word boundaries when matching | Optional |
| `expires_in` | Number that indicates seconds. Filter will be expire in seconds after API processed. Leave blank for no expiration | Optional |
## GET /api/v1/filters/:id
A text filter.
Returns [Filter]({{< relref "entities.md#filter" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:filters" version="2.4.3" >}}
## PUT /api/v1/filters/:id
Update a text filter.
Returns [Filter]({{< relref "entities.md#filter" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:filters" version="2.4.3" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `phrase` | Keyword or phrase to filter | Required |
| `context` | Array of strings that means filtering context. Each string is one of `home`, `notifications`, `public`, `thread`. At least one context must be specified. | Required |
| `irreversible` | Irreversible filtering will only work in `home` and `notifications` contexts by fully dropping the records. Otherwise, filtering is up to the client. | Optional |
| `whole_word` | Whether to consider word boundaries when matching | Optional |
| `expires_in` | Number that indicates seconds. Filter will be expire in seconds after API processed. Leave blank to not change | Optional |
## DELETE /api/v1/filters/:id
Delete a text filter.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:filters" version="2.4.3" >}}

43
content/en/api/rest/follow-requests.md
View file

@ -1,43 +0,0 @@
---
title: Follow requests
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/follow_requests
Accounts that have requested to follow the user.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:follows follow" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 40 |
### Pagination
{{< api_pagination >}}
## POST /api/v1/follow_requests/:id/authorize
Allow the account to follow the user.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write:follows follow" version="0.0.0" >}}
## POST /api/v1/follow_requests/:id/reject
Do not allow the account to follow the user.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write:follows follow" version="0.0.0" >}}

25
content/en/api/rest/follow-suggestions.md
View file

@ -1,25 +0,0 @@
---
title: Follow suggestions
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/suggestions
Accounts the user had past positive interactions with, but is not following yet.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read" version="2.4.3" >}}
## DELETE /api/v1/suggestions/:account_id
Remove account from suggestions.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read" version="2.4.3" >}}

17
content/en/api/rest/instances.md
View file

@ -1,17 +0,0 @@
---
title: Instances
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/instance
Information about the server.
Returns [Instance]({{< relref "entities.md#instance" >}})
### Resource information
{{< api_method_info auth="No" user="No" version="0.0.0" >}}

127
content/en/api/rest/lists.md
View file

@ -1,127 +0,0 @@
---
title: Lists
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/lists
User's lists.
Returns array of [List]({{< relref "entities.md#list" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:lists" version="2.1.0" >}}
## GET /api/v1/accounts/:id/lists
User's lists that a given account is part of.
Returns array of [List]({{< relref "entities.md#list" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:lists" version="2.1.0" >}}
## GET /api/v1/lists/:id/accounts
Accounts that are in a given list.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:lists" version="2.1.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 40 |
### Pagination
>If you specify a `limit` of `0` in the query, all accounts will be returned without pagination. Otherwise, standard account pagination rules apply.
{{< api_pagination >}}
## GET /api/v1/lists/:id
Returns [List]({{< relref "entities.md#list" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:lists" version="2.1.0" >}}
## POST /api/v1/lists
Create a new list.
Returns [List]({{< relref "entities.md#list" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="2.1.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `title` | The title of the list | Required |
## PUT /api/v1/lists/:id
Update a list.
Returns [List]({{< relref "entities.md#list" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="2.1.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `title` | The title of the list | Required |
## DELETE /api/v1/lists/:id
Remove a list.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="2.1.0" >}}
## POST /api/v1/lists/:id/accounts
Add accounts to a list.
> Only accounts already followed by the user can be added to a list.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="2.1.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `account_ids` | Array of account IDs | Required |
## DELETE /api/v1/lists/:id/accounts
Remove accounts from a list.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="2.1.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `account_ids` | Array of account IDs | Required |

46
content/en/api/rest/media.md
View file

@ -1,46 +0,0 @@
---
title: Media attachments
menu:
docs:
parent: rest-api
weight: 10
---
## POST /api/v1/media
Upload a media attachment that can be used with a new status.
Returns [Attachment]({{< relref "entities.md#attachment" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:media" version="0.0.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `file` | Media file encoded using `multipart/form-data` | Required |
| `description` | A plain-text description of the media for accessibility (max 420 chars) | Optional |
| `focus` | Two floating points, comma-delimited. See [focal points](#focal-points) | Optional |
## PUT /api/v1/media/:id
Update a media attachment. Can only be done before the media is attached to a status.
Returns [Attachment]({{< relref "entities.md#attachment" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:media" version="0.0.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `description` | A plain-text description of the media for accessibility (max 420 chars) | Optional |
| `focus` | Two floating points, comma-delimited. See [focal points](#focal-points) | Optional |
## Focal points
Server-side preview images are never cropped, to support a variety of apps and user interfaces. Therefore, the cropping must be done by those apps. To crop intelligently, focal points can be used to ensure a certain section of the image is always within the cropped viewport. [See this for how to let users select focal point coordinates](https://github.com/jonom/jquery-focuspoint#1-calculate-your-images-focus-point).

73
content/en/api/rest/mutes.md
View file

@ -1,73 +0,0 @@
---
title: Mutes
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/mutes
Accounts the user has muted.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read:mutes follow" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 40 |
### Pagination
{{< api_pagination >}}
## POST /api/v1/accounts/:id/mute
Mute an account.
Returns [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write:mutes follow" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `notifications` | Whether the mute will mute notifications or not | Optional | true |
## POST /api/v1/accounts/:id/unmute
Unmute an account.
Returns [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write:mutes follow" version="0.0.0" >}}
## POST /api/v1/statuses/:id/mute
Mute the conversation the status is part of, to no longer be notified about it.
Returns [Status]({{< relref "entities.md#status" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:mutes" version="1.4.2" >}}
## POST /api/v1/statuses/:id/unmute
Unmute the conversation the status is part of.
Returns [Status]({{< relref "entities.md#status" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:mutes" version="1.4.2" >}}

117
content/en/api/rest/notifications.md
View file

@ -1,117 +0,0 @@
---
title: Notifications
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/notifications
Notifications concerning the user.
Returns array of [Notification]({{< relref "entities.md#notification" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:notifications" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `max_id` | Return results older than ID | Optional ||
| `since_id` | Return results newer than ID | Optional ||
| `min_id` | Return results immediately newer than ID | Optional ||
| `limit` | Maximum number of results | Optional | 20 |
| `exclude_types` | Array of types to exclude (e.g. `follow`, `favourite`, `reblog`, `mention`) | Optional ||
| `account_id` | Return only notifications sent from given account | Optional ||
### Pagination
{{< api_dynamic_pagination >}}
## GET /api/v1/notifications/:id
Returns [Notification]({{< relref "entities.md#notification" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:notifications" version="0.0.0" >}}
## POST /api/v1/notifications/:id/dismiss
Delete a single notification from the server.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:notifications" version="0.0.0" >}}
## POST /api/v1/notifications/clear
Delete all notifications from the server.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:notifications" version="0.0.0" >}}
## POST /api/v1/push/subscription
Add a Web Push API subscription to receive notifications. See also: [Web Push API]({{< relref "push.md" >}})
> Each access token can have one push subscription. If you create a new subscription, the old subscription is deleted.
Returns [Push Subscription]({{< relref "entities.md#push-subscription" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="push" version="2.4.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `subscription[endpoint]` | Endpoint URL that called when notification is happen. | Required |
| `subscription[keys][p256dh]` | User agent public key. Base64 encoded string of public key of ECDH key using 'prime256v1' curve. | Required |
| `subscription[keys][auth]` | Auth secret. Base64 encoded string of 16 bytes of random data. | Required |
| `data[alerts][follow]` | Boolean of whether you want to receive follow notification event. | Optional |
| `data[alerts][favourite]` | Boolean of whether you want to receive favourite notification event. | Optional |
| `data[alerts][reblog]` | Boolean of whether you want to receive reblog notification event. | Optional |
| `data[alerts][mention]` | Boolean of whether you want to receive mention notification event. | Optional |
| `data[alerts][poll]` | Boolean of whether you want to receive poll result notification event. | Optional |
## GET /api/v1/push/subscription
Returns [Push Subscription]({{< relref "entities.md#push-subscription" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="push" version="2.4.0" >}}
## PUT /api/v1/push/subscription
Update current Web Push API subscription. Only the `data` part can be updated, e.g. which types of notifications are desired. To change fundamentals, a new subscription must be created instead.
Returns [Push Subscription]({{< relref "entities.md#push-subscription" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="push" version="2.4.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `data[alerts][follow]` | Boolean of whether you want to receive follow notification event. | Optional |
| `data[alerts][favourite]` | Boolean of whether you want to receive favourite notification event. | Optional |
| `data[alerts][reblog]` | Boolean of whether you want to receive reblog notification event. | Optional |
| `data[alerts][mention]` | Boolean of whether you want to receive mention notification event. | Optional |
| `data[alerts][poll]` | Boolean of whether you want to receive poll result notification event. | Optional |
## DELETE /api/v1/push/subscription
Remove the current Web Push API subscription.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="push" version="2.4.0" >}}

31
content/en/api/rest/polls.md
View file

@ -1,31 +0,0 @@
---
title: Polls
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/polls/:id
Returns [Poll]({{< relref "entities.md#poll" >}})
### Resource information
{{< api_method_info auth="No" user="No" scope="read read:statuses" version="2.8.0" >}}
## POST /api/v1/polls/:id/votes
Vote on a poll.
Returns [Poll]({{< relref "entities.md#poll" >}})
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `choices` | Array of choice indices | Required |
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="2.8.0" >}}

24
content/en/api/rest/reports.md
View file

@ -1,24 +0,0 @@
---
title: Reports
menu:
docs:
parent: rest-api
weight: 10
---
## POST /api/v1/reports
Report an account.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:reports" version="1.1.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `account_id` | The ID of the account to report | Required |
| `status_ids` | The IDs of statuses to report as array | Optional |
| `comment` | Reason for the report (up to 1,000 characters) | Optional |
| `forward` | Whether to forward to the remote admin (in case of a remote account) | Optional |

51
content/en/api/rest/scheduled-statuses.md
View file

@ -1,51 +0,0 @@
---
title: Scheduled Statuses
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/scheduled_statuses
Get scheduled statuses.
Returns array of [ScheduledStatus]({{< relref "entities.md#scheduledstatus" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:statuses" version="2.7.0" >}}
## GET /api/v1/scheduled_statuses/:id
Get scheduled status.
Returns [ScheduledStatus]({{< relref "entities.md#scheduledstatus" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:statuses" version="2.7.0" >}}
## PUT /api/v1/scheduled_statuses/:id
Update Scheduled status. Only `scheduled_at` can be changed. To change the content, delete it and post a new status.
Returns [ScheduledStatus]({{< relref "entities.md#scheduledstatus" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="2.7.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `scheduled_at` | Timestamp string to schedule posting of status (ISO 8601) | Optional |
## DELETE /api/v1/scheduled_statuses/:id
Remove Scheduled status.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="2.7.0" >}}

27
content/en/api/rest/search.md
View file

@ -1,27 +0,0 @@
---
title: Search
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v2/search
Search for content in accounts, statuses and hashtags.
Returns [Results]({{< relref "entities.md#results" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:search" version="2.4.1" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `q` | The search query | Required ||
| `resolve` | Attempt WebFinger look-up | Optional |false|
| `limit` | Maximum number of results | Optional | 40 |
| `offset` | Offset in the search results | Optional | 0 |
| `following` | Only include accounts the user is following | Optional | false |

177
content/en/api/rest/statuses.md
View file

@ -1,177 +0,0 @@
---
title: Statuses
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/statuses/:id
Returns [Status]({{< relref "entities.md#status" >}})
### Resource information
{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}
## GET /api/v1/statuses/:id/context
What the status replies to, and replies to it.
Returns [Context]({{< relref "entities.md#context" >}})
### Resource information
{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}
## GET /api/v1/statuses/:id/card
Link preview card for a status, if available.
Returns [Card]({{< relref "entities.md#card" >}})
### Resource information
{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}
## GET /api/v1/statuses/:id/reblogged_by
Accounts that reblogged the status.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 40 |
### Pagination
{{< api_pagination >}}
## GET /api/v1/statuses/:id/favourited_by
Accounts that favourited the status.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 40 |
### Pagination
{{< api_pagination >}}
## POST /api/v1/statuses
Publish a new status.
Returns [Status]({{< relref "entities.md#status" >}})
When `scheduled_at` option is present,
Returns [ScheduledStatus]({{< relref "entities.md#scheduledstatus" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Added in|
|----|-----------|:------:|:------:|
| `status` | The text of the status | Optional\* |
| `in_reply_to_id` | ID of the status you want to reply to | Optional |
| `media_ids` | Array of media IDs to attach to the status | Optional\* |
| `poll` | Nested parameters to attach a poll to the status | Optional\* |2.8.0|
| `sensitive` | Mark the media in the status as sensitive | Optional |
| `spoiler_text` | Text to be shown as a warning before the actual content | Optional |
| `visibility` | One of `direct`, `private`, `unlisted` `public` | Optional |
| `scheduled_at` | Timestamp string to schedule posting of status (ISO 8601) | Optional |2.7.0|
| `language` | Override language code of the toot (ISO 639-2) | Optional |
> You must provide either `status` or `media_ids`, completely empty statuses are not allowed. Polls require a `status` and cannot be combined with `media_ids`.
Poll parameters:
|Name|Description|Required|
|----|-----------|:------:|
| `poll[options]` | Array of poll answer strings | Required |
| `poll[expires_in]` | Duration the poll should be open for in seconds | Required |
| `poll[multiple]` | Whether multiple choices should be allowed | Optional |
| `poll[hide_totals]` | Whether to hide totals until the poll ends | Optional |
### Idempotency
In order to prevent duplicate statuses, this endpoint accepts an `Idempotency-Key` header, which should be set to a unique string for each new status. In the event of a network error, a request can be retried with the same `Idempotency-Key`. Only one status will be created regardless of how many requests with the same `Idempotency-Key` did go through.
See <https://stripe.com/blog/idempotency> for more on idempotency and idempotency keys.
### Scheduled status
Allows users to schedule a toot (with media attachments) to be published at a certain future date.
The scheduled date must be at least 5 minutes into the future. At most, 300 toots can be scheduled at the same time. Only 50 toots can be scheduled for any given day.
When `scheduled_at` option is present, instead of creating a status, we only run status validation, and if it passes, we create an entry in scheduled_statuses which encodes the status attributes. Every 5 minutes, a scheduler iterates over the scheduled_statuses table to fetch the ones due in the next 5 minutes, and push them into a more precise Sidekiq queue. In Sidekiq, the individual statuses are created, with media attachments being unassigned from the scheduled status and assigned to the real one.
This option was added since v2.7.0.
## DELETE /api/v1/statuses/:id
Remove a status. The status may still be available a short while after the call.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="0.0.0" >}}
## POST /api/v1/statuses/:id/reblog
Reblog a status.
Returns [Status]({{< relref "entities.md#status" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="0.0.0" >}}
## POST /api/v1/statuses/:id/unreblog
Undo the reblog of a status.
Returns [Status]({{< relref "entities.md#status" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="0.0.0" >}}
## POST /api/v1/statuses/:id/pin
Pin user's own status to user's profile.
Returns [Status]({{< relref "entities.md#status" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="1.6.0" >}}
## POST /api/v1/statuses/:id/unpin
Remove pinned status from user's profile.
Returns [Status]({{< relref "entities.md#status" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="1.6.0" >}}

123
content/en/api/rest/timelines.md
View file

@ -1,123 +0,0 @@
---
title: Timelines
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/timelines/home
Statuses from accounts the user follows.
Returns array of [Status]({{< relref "entities.md#status" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:statuses" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `max_id` | Return results older than ID | Optional ||
| `since_id` | Return results newer than ID | Optional ||
| `min_id` | Return results immediately newer than ID | Optional ||
| `limit` | Maximum number of results | Optional | 20 |
## GET /api/v1/conversations
Conversations for an account
Returns array of [Conversation]({{< relref "entities.md#conversation" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:statuses" version="2.6.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `max_id` | Return results older than ID | Optional ||
| `since_id` | Return results newer than ID | Optional ||
| `min_id` | Return results immediately newer than ID | Optional ||
| `limit` | Maximum number of results | Optional | 20 |
### Pagination
{{< api_dynamic_pagination >}}
## GET /api/v1/timelines/public
Public statuses known to the server.
Returns array of [Status]({{< relref "entities.md#status" >}})
### Resource information
{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `local` | Only local statuses | Optional |false|
| `only_media` | Only statuses with media attachments | Optional |false|
| `max_id` | Return results older than ID | Optional ||
| `since_id` | Return results newer than ID | Optional ||
| `min_id` | Return results immediately newer than ID | Optional ||
| `limit` | Maximum number of results | Optional | 20 |
### Pagination
{{< api_dynamic_pagination >}}
## GET /api/v1/timelines/tag/:hashtag
Public statuses known to the server marked with a given hashtag.
Returns array of [Status]({{< relref "entities.md#status" >}})
### Resource information
{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `local` | Only local statuses | Optional |false|
| `only_media` | Only statuses with media attachments | Optional |false|
| `max_id` | Return results older than ID | Optional ||
| `since_id` | Return results newer than ID | Optional ||
| `min_id` | Return results immediately newer than ID | Optional ||
| `limit` | Maximum number of results | Optional | 20 |
### Pagination
{{< api_dynamic_pagination >}}
## GET /api/v1/timelines/list/:list_id
Statuses from accounts on a given list.
Returns array of [Status]({{< relref "entities.md#status" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:statuses" version="2.1.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `max_id` | Return results older than ID | Optional ||
| `since_id` | Return results newer than ID | Optional ||
| `min_id` | Return results immediately newer than ID | Optional ||
| `limit` | Maximum number of results | Optional | 20 |
### Pagination
{{< api_dynamic_pagination >}}

82
content/en/api/streaming.md
View file

@ -1,82 +0,0 @@
---
title: Streaming API
description: How to use Mastodon's streaming API for live, real-time updates
menu:
docs:
parent: api
weight: 4
---
Your application can use a [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) endpoint to receive updates in real-time. Server-sent events is an incredibly simple transport method that relies entirely on chunked-encoding transfer, i.e. the HTTP connection is kept open and receives new data periodically.
Alternatively, a WebSocket connection can also be established.
## Server-sent events (HTTP)
### Endpoints
#### GET /api/v1/streaming/health
Returns `OK` when streaming service is fine
#### GET /api/v1/streaming/user
Returns events that are relevant to the authorized user, i.e. home timeline and notifications
#### GET /api/v1/streaming/public
Returns all public statuses
#### GET /api/v1/streaming/public/local
Returns all local statuses
#### GET /api/v1/streaming/hashtag?tag=:hashtag
Returns all public statuses for a particular hashtag
#### GET /api/v1/streaming/hashtag/local?tag=:hashtag
Returns all local statuses for a particular hashtag
#### GET /api/v1/streaming/list?list=:list_id
Returns statuses for a list
#### GET /api/v1/streaming/direct
Returns all direct messages
### Stream contents
The stream will contain events as well as heartbeat comments. Lines that begin with a colon (`:`) can be ignored by parsers, they are simply there to keep the connection open. Events have this structure:
```
event: name
data: payload
```
## WebSocket
For WebSockets, there is only one URL path (`/api/v1/streaming`). The access token as well as the endpoint you are interested in must be provided with query params, respectively `access_token` and `stream`. Query params `list` and `tag` are likewise supported for relevant endpoints.
Possible `stream` values:
- `user`
- `public`
- `public:local`
- `hashtag`
- `hashtag:local`
- `list`
- `direct`
## Event types
|Event|Description|What's in the payload|
|-----|-----------|---------------------|
|`update`|A new status has appeared|[Status]({{< relref "entities.md#status" >}})|
|`notification`|A new notification has appeared|[Notification]({{< relref "entities.md#notification" >}})|
|`delete`|A status has been deleted|ID of the deleted status|
|`filters_changed`|Keyword filters have been changed||
The payload is JSON-encoded.
> **Note:** In case of `filters_changed` event, `payload` is not defined.