Update content for 4.0, part 2 (#1060)

* fix relrefs around trends and related entities

* revert moving caption-links to middle of page

* hide empty menu in table of contents

* clarify edit notifs are only for boosted statuses

* following/followers no longer need auth

* fix typo

* specify cooldown period for account Move

* use the correct cooldown

* add missing parameters to accounts/id/statuses

* link to account_statuses_filter.rb

* fix typo (#1072)

* fix typo (#1073)

* fix link to http sig spec (#1067)

* simply HTTP request examples in api methods docs

* add missing client_secret to oauth/token (#1062)

* Add any, all, none to hashtag timeline

* minor formatting changes

* Update signature requirements and advice

* fix public key -> private key

* clarify use of RSA with SHA256

* Add note about saving your profile after adding rel-me link

* v2 filters api

* comment out params that shouldn't be used in v2 filter api

* admin trends

* remove old todo

* canonical email blocks + scheduled statuses

* remove under-construction warnings from finished pages

* verify api method params with source code

* fix typo (#1088)

* fix broken caption-links (#1100)

* fix formatting of entities (#1094)

* Remove keybase section from user guide (#1093)

* fix typos (#1092)

* Verify limits are accurate (#1086)

* add mention of iframe limitation (#1084)

* Add CORS header to WEB_DOMAIN example (#1083)

* Fix typo (#1081)

* pin http sigs spec at draft 8

* Revert "pin http sigs spec at draft 8"

This reverts commit 9fd5f7032b.

* add case sensitivity warning to 4.0 roles

* Add url length note to bio (#1087)

* remove follow scope from examples (#1103)

* clarify usage of update_credentials to update profile fields

* add noindex to Account entitity

* remove required hint from technically not required property
This commit is contained in:
trwnh 2022-12-14 15:55:30 -06:00 committed by GitHub
parent 1dad33b87b
commit ffbe66a389
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
90 changed files with 2217 additions and 637 deletions

View File

@ -9,7 +9,7 @@ menu:
## What the method does {#anchor}
```http
GET https://mastodon.example/api/v1/example HTTP/1.1
GET /api/v1/example HTTP/1.1
```
**Returns:** [SOMETHING]({{< relref "entities/SOMETHING" >}})\
@ -44,7 +44,7 @@ min_id
: String. Return results immediately newer than ID.
limit
: Integer. Maximum number of results to return. Defaults to 20. Max 40.
: Integer. Maximum number of results to return. Defaults to 20 statuses or 40 accounts. Max twice the default limit.
##### Form data parameters
@ -57,7 +57,7 @@ limit
Because SOMETHING IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link:
Link: <https://mastodon.example/api/v1/SOMETHING?max_id=441449>; rel="next", <https://mastodon.example/api/v1/SOMETHING?since_id=444808>; rel="prev"
```
##### 401: Unauthorized

View File

@ -38,7 +38,7 @@ Application secrets are the easiest to backup, since they never change. You only
## Backing up PostgreSQL {#postgresql}
PostgreSQL is at risk of data corruption from power cuts, hard disk drive failure, and botched schema migrations. For that reason, occassionally making a backup with `pg_dump` or `pg_dumpall` is recommended.
PostgreSQL is at risk of data corruption from power cuts, hard disk drive failure, and botched schema migrations. For that reason, occasionally making a backup with `pg_dump` or `pg_dumpall` is recommended.
For high-availability setups, it is possible to use hot streaming replication to have a second PostgreSQL server with always up-to-date data, ready to be switched over to if the other server goes down.

View File

@ -23,12 +23,13 @@ This is the unique identifier of your server in the network. It cannot be safely
`WEB_DOMAIN` is an optional environment variable allowing to install Mastodon on one domain, while having the users' handles on a different domain, e.g. addressing users as `@alice@example.com` but accessing Mastodon on `mastodon.example.com`. This may be useful if your domain name is already used for a different website but you still want to use it as a Mastodon identifier because it looks better or shorter.
As with `LOCAL_DOMAIN`, `WEB_DOMAIN` cannot be safely changed once set, as this will confuse remote servers that knew of your previous settings and may break communication with them or make it unreliable. As the issues lie with remote servers' understanding of your accounts, re-installing Mastodon from scratch will not fix the issue. Therefore, please be extremelly cautious when setting up `LOCAL_DOMAIN` and `WEB_DOMAIN`.
As with `LOCAL_DOMAIN`, `WEB_DOMAIN` cannot be safely changed once set, as this will confuse remote servers that knew of your previous settings and may break communication with them or make it unreliable. As the issues lie with remote servers' understanding of your accounts, re-installing Mastodon from scratch will not fix the issue. Therefore, please be extremely cautious when setting up `LOCAL_DOMAIN` and `WEB_DOMAIN`.
To install Mastodon on `mastodon.example.com` in such a way it can serve `@alice@example.com`, set `LOCAL_DOMAIN` to `example.com` and `WEB_DOMAIN` to `mastodon.example.com`. This also requires additional configuration on the server hosting `example.com` to redirect or proxy requests to `https://example.com/.well-known/webfinger` to `https://mastodon.example.com/.well-known/webfinger`. For instance, with nginx, the configuration could look like the following:
```
location /.well-known/webfinger {
add_header Access-Control-Allow-Origin '*';
return 301 https://mastodon.example.com$request_uri;
}
```

View File

@ -34,7 +34,7 @@ This guide was written with Ubuntu Server in mind; your mileage may vary for oth
At a high level, youll need to copy over the following:
* The `~/live/public/system` directory, which contains user-uploaded images and videos (if using S3, you dont need this)
* The Postgres database (using [pg\_dump](https://www.postgresql.org/docs/9.1/static/backup-dump.html))
* The Postgres database (using [pg_dump](https://www.postgresql.org/docs/9.1/static/backup-dump.html))
* The `~/live/.env.production` file, which contains server config and secrets
Less crucially, youll probably also want to copy the following for convenience:
@ -45,7 +45,7 @@ Less crucially, youll probably also want to copy the following for convenienc
### Dump and load Postgres {#dump-and-load-postgres}
Instead of running `mastodon:setup`, were going to create an empty Postgres database using the `template0` database (which is useful when restoring a Postgres dump, [as described in the pg\_dump documentation](https://www.postgresql.org/docs/9.1/static/backup-dump.html#BACKUP-DUMP-RESTORE)).
Instead of running `mastodon:setup`, were going to create an empty Postgres database using the `template0` database (which is useful when restoring a Postgres dump, [as described in the pg_dump documentation](https://www.postgresql.org/docs/9.1/static/backup-dump.html#BACKUP-DUMP-RESTORE)).
Run this as the `mastodon` user on your old system:

View File

@ -37,9 +37,9 @@ At this moment, limit does not affect federation. A locally limited account is *
A Mastodon suspension means the account is effectively deleted. The account no longer appears in search, the profile page is gone, all of the posts, uploads, followers, and all other data is removed publicly. However, all the data is available in the admin back-end for a period of 30 days from suspension. This is to give the user an opportunity to work with instance admins to resolve any potential issues and have the account re-instated.
If the account is reinstated within the 30 day period, all data is once again accessible publicly without any adverse affects. If the 30 day period lapses, **all** that user's data is purged from the instance. Admins also have the option to immediately delete the user's account data at any point during the 30 days.
If the account is reinstated within the 30 day period, all data is once again accessible publicly without any adverse effects. If the 30 day period lapses, **all** that user's data is purged from the instance. Admins also have the option to immediately delete the user's account data at any point during the 30 days.
Once the data has been deleted, whether than be after the 30 day period, or if an admin has force deleted it, the account can still be un-suspended. However, the account will have no data (statuses, profile information, avatar or header image) associated with it.
Once the data has been deleted, whether that is after the 30 day period, or if an admin has force deleted it, the account can still be un-suspended. However, the account will have no data (statuses, profile information, avatar or header image) associated with it.
## Moderating entire websites {#server-wide-moderation}

View File

@ -7,7 +7,7 @@ menu:
parent: admin-optional
---
Mastodon can be served through Tor as an onion service. This will give you a \*.onion address that can only be used while connected to the Tor network.
Mastodon can be served through Tor as an onion service. This will give you a `*.onion` address that can only be used while connected to the Tor network.
## Installing Tor {#install}

View File

@ -88,7 +88,7 @@ Edit `/etc/iptables/rules.v4` and put this inside:
# Allow ping
-A INPUT -p icmp -m icmp --icmp-type 8 -j ACCEPT
# Allow destination unreachable messages, espacally code 4 (fragmentation required) is required or PMTUD breaks
# Allow destination unreachable messages, especially code 4 (fragmentation required) is required or PMTUD breaks
-A INPUT -p icmp -m icmp --icmp-type 3 -j ACCEPT
# Log iptables denied calls
@ -141,7 +141,7 @@ If your server is also reachable over IPv6, edit `/etc/iptables/rules.v6` and ad
COMMIT
```
Simmilar to the IPv4 rules, you can load it manually like this:
Similar to the IPv4 rules, you can load it manually like this:
```bash
ip6tables-restore < /etc/iptables/rules.v6
```

View File

@ -101,7 +101,7 @@ sudo apt install pgbouncer
#### Setting a password {#pgbouncer-password}
First off, if your `mastodon` user in Postgres is set up wthout a password, you will need to set a password.
First off, if your `mastodon` user in Postgres is set up without a password, you will need to set a password.
Heres how you might reset the password:
@ -279,7 +279,7 @@ production:
url: postgresql://db_user:db_password@db_host:db_port/db_name
```
Make sure the URLs point to wherever your PostgreSQL servers are. You can add multiple replicas. You could have a locally installed pgBouncer with configuration to connect to two different servers based on database name, e.g. “mastodon” going to master, “mastodon\_replica” going to the replica, so in the file above both URLs would point to the local pgBouncer with the same user, password, host and port, but different database name. There are many possibilities how this could be setup! For more information on Makara, [see their documentation](https://github.com/taskrabbit/makara#databaseyml).
Make sure the URLs point to wherever your PostgreSQL servers are. You can add multiple replicas. You could have a locally installed pgBouncer with configuration to connect to two different servers based on database name, e.g. “mastodon” going to master, “mastodon_replica” going to the replica, so in the file above both URLs would point to the local pgBouncer with the same user, password, host and port, but different database name. There are many possibilities how this could be setup! For more information on Makara, [see their documentation](https://github.com/taskrabbit/makara#databaseyml).
{{< hint style="warning" >}}
Sidekiq cannot reliably use read-replicas because even the tiniest replication lag leads to failing jobs due to queued up records not being found.

View File

@ -98,7 +98,7 @@ Create a new user account with given `USERNAME` and provided `--email`.
: Skip sending the confirmation email and activate the account immediately.
`--role ROLE`
: Define the new account's custom role by providing the `name` of that [Role]({{< relref "entities/Role" >}}). Default roles include `Owner`, `Admin`, and `Moderator`.
: Define the new account's custom role by providing the `name` of that [Role]({{< relref "entities/Role" >}}). Default roles include `Owner`, `Admin`, and `Moderator` (case-sensitive).
`--reattach`
: Reuse an old USERNAME after its account has been deleted.
@ -111,7 +111,7 @@ Forcefully delete any existing account with this `USERNAME` and reattach the new
**Version history:**\
2.6.0 - added\
4.0.0 - `--role` no longer takes hard-coded `user`, `moderator`, or `admin` roles. Specify the name of the custom Role instead.
4.0.0 - `--role` no longer takes hard-coded `user`, `moderator`, or `admin` roles. Specify the name of the custom Role instead (case-sensitive).
---
@ -125,7 +125,7 @@ Modify a user account's role, email, active status, approval mode, or 2FA requir
: Local username for the account. {{<required>}}
`--role ROLE`
: Define the existing account's custom role by providing the `name` of that [Role]({{< relref "entities/Role" >}}). Default roles include `Owner`, `Admin`, and `Moderator`.
: Define the existing account's custom role by providing the `name` of that [Role]({{< relref "entities/Role" >}}). Default roles include `Owner`, `Admin`, and `Moderator` (case-sensitive).
`--email EMAIL`
: Update the user's email address to `EMAIL`.
@ -154,7 +154,7 @@ Modify a user account's role, email, active status, approval mode, or 2FA requir
**Version history:**\
2.6.0 - added\
3.1.2 - added `--reset-password`\
4.0.0 - `--role` no longer takes hard-coded `user`, `moderator`, or `admin` roles. Specify the name of the custom Role instead.
4.0.0 - `--role` no longer takes hard-coded `user`, `moderator`, or `admin` roles. Specify the name of the custom Role instead (case-sensitive).
---

View File

@ -37,10 +37,10 @@ Many API methods allow you to paginate for more information, using parameters su
To get around this, Mastodon may return links to a "prev" and "next" page. These links are made available via the HTTP `Link` header on the response. Consider the following fictitious API call:
```http
GET https://mastodon.social/api/v1/endpoint HTTP/1.1
GET https://mastodon.example/api/v1/endpoint HTTP/1.1
Authorization: Bearer token
Link: <https://mastodon.social/api/v1/endpoint?max_id=7163058>; rel="next", <https://mastodon.social/api/v1/endpoint?since_id=7275607>; rel="prev"
Link: <https://mastodon.example/api/v1/endpoint?max_id=7163058>; rel="next", <https://mastodon.example/api/v1/endpoint?since_id=7275607>; rel="prev"
[
{
// some Entity

View File

@ -30,7 +30,7 @@ The set of scopes saved during app creation must include all the scopes that you
- 2.6.0 - write:conversations added [#9009](https://github.com/mastodon/mastodon/pull/9009)
- 2.9.1 - Admin scopes added [#9387](https://github.com/mastodon/mastodon/pull/9387)
- 3.1.0 - Bookmark scopes added [#7107](https://github.com/mastodon/mastodon/pull/7107)
- 4.0.3 - Added admin scopes for blocks and allows [#20918](https://github.com/mastodon/mastodon/pull/20918)
- 4.1.0 - Added admin scopes for blocks and allows [#20918](https://github.com/mastodon/mastodon/pull/20918)
## List of scopes

View File

@ -11,7 +11,7 @@ menu:
When we registered our app and when we will authorize our user, we need to define what exactly our generated token will have permission to do. This is done through the use of OAuth scopes. Each API method has an associated scope, and can only be called if the token being used for authorization has been generated with the corresponding scope.
Scopes must be a subset. When we created our app, we specified `read write follow push` -- we could request all available scopes by specifying `read write follow push`, but it is a better idea to only request what your app will actually need through granular scopes. See [OAuth Scopes]({{< relref "api/oauth-scopes" >}}) for a full list of scopes. Each API method's documentation will also specify the OAuth access level and scope required to call it.
Scopes must be a subset. When we created our app, we specified `read write push` -- we could request all available scopes by specifying `read write push`, but it is a better idea to only request what your app will actually need through granular scopes. See [OAuth Scopes]({{< relref "api/oauth-scopes" >}}) for a full list of scopes. Each API method's documentation will also specify the OAuth access level and scope required to call it.
## **Example authorization code flow** {#flow}
@ -28,7 +28,7 @@ To authorize a user, request [GET /oauth/authorize]({{< relref "methods/oauth#au
```bash
https://mastodon.example/oauth/authorize
?client_id=CLIENT_ID
&scope=read+write+follow+push
&scope=read+write+push
&redirect_uri=urn:ietf:wg:oauth:2.0:oob
&response_type=code
```
@ -50,7 +50,7 @@ curl -X POST \
-F 'redirect_uri=urn:ietf:wg:oauth:2.0:oob' \
-F 'grant_type=authorization_code' \
-F 'code=user_authzcode_here' \
-F 'scope=read write follow push' \
-F 'scope=read write push' \
https://mastodon.example/oauth/token
```
@ -61,7 +61,7 @@ Note the following:
* We are requesting a `grant_type` of `authorization_code`, which still defaults to giving us the `read` scope. However, while authorizing our user, we requested a certain `scope` -- pass the exact same value here.
* The `code` can only be used once. If you need to obtain a new token, you will need to have the user authorize again by repeating the above [Authorize the user]({{< relref "client/authorized#authorize-the-user" >}}) step.
The response of this method is a [Token]({{< relref "entities/token" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. To use it in requests, add the HTTP header `Authorization: Bearer ...` to any API call that requires OAuth (i.e., one that is not publicly accessible). Let's verify that our obtained credentials are working by calling [GET /api/v1/accounts/verify\_credentials]({{< relref "methods/accounts#verify_credentials" >}}):
The response of this method is a [Token]({{< relref "entities/token" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. To use it in requests, add the HTTP header `Authorization: Bearer ...` to any API call that requires OAuth (i.e., one that is not publicly accessible). Let's verify that our obtained credentials are working by calling [GET /api/v1/accounts/verify_credentials]({{< relref "methods/accounts#verify_credentials" >}}):
```bash
curl \
@ -79,7 +79,7 @@ With our OAuth token for the authorized user, we can now perform any action as t
* See [POST /api/v1/statuses]({{< relref "methods/statuses#create" >}}) for how to create statuses.
* See [/api/v1/media]({{< relref "methods/media" >}}) for creating media attachments.
* See [/api/v1/scheduled\_statuses]({{< relref "methods/scheduled_statuses" >}}) for managing scheduled statuses.
* See [/api/v1/scheduled_statuses]({{< relref "methods/scheduled_statuses" >}}) for managing scheduled statuses.
### Interact with timelines {#timelines}
@ -87,7 +87,7 @@ With our OAuth token for the authorized user, we can now perform any action as t
* See [/api/v1/markers]({{< relref "methods/markers" >}}) for saving and loading positions in timelines.
* See [/api/v1/statuses]({{< relref "methods/statuses" >}}) for performing actions on statuses.
* See [/api/v1/polls]({{< relref "methods/polls" >}}) for viewing and voting on polls.
* See [/api/v1/lists]({{< relref "methods/lists" >}}) for obtaining list IDs to use with [GET /api/v1/timelines/list/:list\_id]({{< relref "methods/timelines#list" >}}).
* See [/api/v1/lists]({{< relref "methods/lists" >}}) for obtaining list IDs to use with [GET /api/v1/timelines/list/:list_id]({{< relref "methods/timelines#list" >}}).
* See [/api/v1/conversations]({{< relref "methods/conversations" >}}) for obtaining direct conversations.
* See [/api/v1/favourites]({{< relref "methods/favourites" >}}) for listing favourites.
* See [/api/v1/bookmarks]({{< relref "methods/bookmarks" >}}) for listing bookmarks.
@ -95,7 +95,7 @@ With our OAuth token for the authorized user, we can now perform any action as t
### Interact with other users {#accounts}
* See [/api/v1/accounts]({{< relref "methods/accounts" >}}) for performing actions on other users.
* See [/api/v1/follow\_requests]({{< relref "methods/follow_requests" >}}) for handling follow requests.
* See [/api/v1/follow_requests]({{< relref "methods/follow_requests" >}}) for handling follow requests.
* See [/api/v1/mutes]({{< relref "methods/mutes" >}}) for listing mutes.
* See [/api/v1/blocks]({{< relref "methods/blocks" >}}) for listing blocks.
@ -112,13 +112,13 @@ With our OAuth token for the authorized user, we can now perform any action as t
### Use safety features {#safety}
* See [/api/v1/filters]({{< relref "methods/filters" >}}) for managing filtered keywords.
* See [/api/v1/domain\_blocks]({{< relref "methods/domain_blocks" >}}) for managing blocked domains.
* See [/api/v1/domain_blocks]({{< relref "methods/domain_blocks" >}}) for managing blocked domains.
* See [/api/v1/reports]({{< relref "methods/reports" >}}) for creating reports.
* See [/api/v1/admin]({{< relref "methods/admin" >}}) for moderator actions.
### Manage account info {#manage}
* See [/api/v1/endorsements]({{< relref "methods/endorsements" >}}) for managing a user profile's featured accounts.
* See [/api/v1/featured\_tags]({{< relref "methods/featured_tags" >}}) for managing a user profile's featured hashtags.
* See [/api/v1/featured_tags]({{< relref "methods/featured_tags" >}}) for managing a user profile's featured hashtags.
* See [/api/v1/preferences]({{< relref "methods/preferences" >}}) for reading user preferences.

View File

@ -11,7 +11,7 @@ menu:
* [apex-mastodon](https://github.com/tzmfreedom/apex-mastodon)
## C\# (.NET Standard) {#c-net-standard}
## C# (.NET Standard) {#c-net-standard}
* [Mastodot](https://github.com/yamachu/Mastodot)
* [Mastonet](https://github.com/glacasa/Mastonet)

View File

@ -85,8 +85,8 @@ Now that we are familiar with how to make requests and how to handle responses,
* Once you know an account's id, you can use [GET /api/v1/accounts/:id]({{< relref "methods/accounts" >}}) to view the [Account]({{< relref "entities/account" >}}) entity.
* To view public statuses posted by that account, you can use [GET /api/v1/accounts/:id/statuses]({{< relref "methods/statuses" >}}) and parse the resulting array of [Status]({{< relref "entities/status" >}}) entities.
* Once you know a status's id, you can use [GET /api/v1/statuses/:id]({{< relref "methods/statuses#get-one" >}}) to view the Status entity.
* You can also use [GET /api/v1/statuses/:id/reblogged\_by]({{< relref "methods/statuses#boosted_by" >}}) to view who boosted that status,
* or [GET /api/v1/statuses/:id/favourited\_by]({{< relref "methods/statuses#favourited_by" >}}) to view who favourited that status.
* You can also use [GET /api/v1/statuses/:id/reblogged_by]({{< relref "methods/statuses#boosted_by" >}}) to view who boosted that status,
* or [GET /api/v1/statuses/:id/favourited_by]({{< relref "methods/statuses#favourited_by" >}}) to view who favourited that status.
* Requesting [GET /api/v1/statuses/:id/context]({{< relref "methods/statuses#context" >}}) will show you the ancestors and descendants of that status in the tree that is the conversational thread.
* If the status has a poll attached, you can use [GET /api/v1/polls/:id]({{< relref "methods/polls" >}}) to view the poll separately.
@ -99,7 +99,7 @@ One last thing you can do with anonymous requests is to view information about t
* View general information with [GET /api/v1/instance]({{< relref "methods/instance#fetch-instance" >}}),
* view its peers with [GET /api/v1/instance/peers]({{< relref "methods/instance#peers" >}}) or
* its weekly activity with [GET /api/v1/instance/activity]({{< relref "methods/instance#activity" >}}), or to
* list all custom emoji available with [GET /api/v1/custom\_emojis]({{< relref "methods/custom_emojis" >}}).
* list all custom emoji available with [GET /api/v1/custom_emojis]({{< relref "methods/custom_emojis" >}}).
* See [GET /api/v1/directory]({{< relref "methods/directory" >}}) for a directory of all available profiles.
* See [GET /api/v1/trends]({{< relref "methods/trends" >}}) for currently trending hashtags.

View File

@ -21,7 +21,7 @@ The first thing we will need to do is to register an application, in order to be
curl -X POST \
-F 'client_name=Test Application' \
-F 'redirect_uris=urn:ietf:wg:oauth:2.0:oob' \
-F 'scopes=read write follow push' \
-F 'scopes=read write push' \
-F 'website=https://myapp.example' \
https://mastodon.example/api/v1/apps
```
@ -31,7 +31,7 @@ In the above example, we specify the client name and website, which will be show
* `redirect_uris` has been set to the "out of band" token generation, which means that any generated tokens will have to be copied and pasted manually. The parameter is called `redirect_uris` because it is possible to define more than one redirect URI, but when generating the token, we will need to provide a URI that is included within this list.
* `scopes` allow us to define what permissions we can request later. However, the requested scope later can be a subset of these registered scopes. See [OAuth Scopes]({{< relref "api/oauth-scopes" >}}) for more information.
We should see an Application entity returned, but for now we only care about client\_id and client\_secret. These values will be used to generate access tokens, so they should be cached for later use. See [POST /api/v1/apps]({{< relref "methods/apps#create" >}}) for more details on registering applications.
We should see an Application entity returned, but for now we only care about client_id and client_secret. These values will be used to generate access tokens, so they should be cached for later use. See [POST /api/v1/apps]({{< relref "methods/apps#create" >}}) for more details on registering applications.
## Example authentication code flow {#flow}
@ -52,7 +52,7 @@ Note the following:
* `redirect_uri` must be one of the URIs defined when registering the application.
* We are requesting a `grant_type` of `client_credentials`, which defaults to giving us the `read` scope.
The response of this method is a [Token]({{< relref "entities/token" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. To use it in requests, add the HTTP header `Authorization: Bearer ...` to any API call that requires OAuth (i.e., one that is not publicly accessible). Let's verify that our obtained credentials are working by calling [GET /api/v1/apps/verify\_credentials]({{< relref "methods/apps#verify_credentials" >}}):
The response of this method is a [Token]({{< relref "entities/token" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. To use it in requests, add the HTTP header `Authorization: Bearer ...` to any API call that requires OAuth (i.e., one that is not publicly accessible). Let's verify that our obtained credentials are working by calling [GET /api/v1/apps/verify_credentials]({{< relref "methods/apps#verify_credentials" >}}):
```bash
curl \

View File

@ -7,10 +7,6 @@ menu:
parent: dev
---
{{< hint style="danger" >}}
This page is under construction.
{{< /hint >}}
### Code structure {#structure}
The following overview should not be seen as complete or authoritative, but as a rough guidance to help you find your way in the application.

View File

@ -7,10 +7,6 @@ menu:
parent: dev
---
{{< hint style="warning" >}}
This page is under construction.
{{< /hint >}}
Mastodon is a Ruby on Rails application with a React.js front-end. It follows standard practices of those frameworks, so if you are already familiar with Rails or React.js, you will not find any surprises here.
The best way of working with Mastodon in a development environment is installing all the dependencies on your system, rather than using Docker or Vagrant. You need Ruby, Node.js, PostgreSQL and Redis, which is a pretty standard set of dependencies for Rails applications.

View File

@ -37,7 +37,7 @@ end
The first available resource is :statuses, which is nested under the :api and :v1 namespaces. Thus, the resulting HTTP route will be /api/v1/statuses. The `only` defines certain allowed methods, which are to be defined in the controller at `app/controllers/api/v1/statuses_controller.rb`.
Within /api/v1/statuses, there is a scope for a module :statuses, where additional resources are defined. The controllers for these resources live in `app/controllers/api/v1/statuses/`. For example, :favourite will be handled by the \#create action within `app/controllers/api/v1/statuses/favourites_controller.rb` and :unfavourite will be handled within the same controller, but by the \#destroy action.
Within /api/v1/statuses, there is a scope for a module :statuses, where additional resources are defined. The controllers for these resources live in `app/controllers/api/v1/statuses/`. For example, :favourite will be handled by the #create action within `app/controllers/api/v1/statuses/favourites_controller.rb` and :unfavourite will be handled within the same controller, but by the #destroy action.
There is also a custom method defined for any `member` within this scope, or in other words, for any status to be controlled by `app/controllers/api/v1/statuses_controller.rb`, which is mapped to GET /api/v1/statuses/:id/context and handled by the :context action defined within that controller.
@ -45,23 +45,23 @@ There is also a custom method defined for any `member` within this scope, or in
#### :index
Maps to HTTP GET, for a list. Handled by the \#index action in a controller.
Maps to HTTP GET, for a list. Handled by the #index action in a controller.
#### :show
Maps to HTTP GET, for a single view. Handled by the \#show action in a controller.
Maps to HTTP GET, for a single view. Handled by the #show action in a controller.
#### :create
Maps to HTTP POST. Handled by the \#create action in a controller.
Maps to HTTP POST. Handled by the #create action in a controller.
#### :update
Maps to HTTP PUT. Handled by the \#update action in a controller.
Maps to HTTP PUT. Handled by the #update action in a controller.
#### :destroy
Maps to HTTP DELETE. Handled by the \#destroy action in a controller.
Maps to HTTP DELETE. Handled by the #destroy action in a controller.
## .well-known {#well-known}
@ -73,7 +73,7 @@ Extensible Resource Descriptor (XRD). Advertises existence of Webfinger.
Maps to NodeInfo 2.0 endpoint at `/nodeinfo/2.0`, used for advertising software name and version, protocols, usage statistics, and whether registrations are open.
### /.well-know/webfinger {#webfinger}
### /.well-known/webfinger {#webfinger}
Used for discovering ActivityPub actor id. See [Spec compliance &gt; WebFinger]({{< relref "spec/webfinger" >}}) for more information.
@ -114,18 +114,18 @@ The sections below this point are under construction.
* /api/proofs
* /api/v1
* [statuses]({{< relref "methods/statuses" >}}) [create, show, destroy]
* reblogged\_by [index]
* favourited\_by [index]
* reblogged_by [index]
* favourited_by [index]
* reblog [create]
* unreblog [POST reblog\#destroy]
* unreblog [POST reblog#destroy]
* favourite [create]
* unfavourite [POST favourites\#destroy]
* unfavourite [POST favourites#destroy]
* bookmark [create]
* unbookmark [POST bookmarks\#destroy]
* unbookmark [POST bookmarks#destroy]
* mute [create]
* unmute [POST mutes\#destroy]
* unmute [POST mutes#destroy]
* pin [create]
* unpin [POST pins\#destroy]
* unpin [POST pins#destroy]
* context [GET]
* [timelines]({{< relref "methods/timelines" >}})
* home [show]
@ -133,9 +133,9 @@ The sections below this point are under construction.
* tag [show]
* list [show]
* [streaming]({{< relref "methods/streaming" >}}) [index]
* [custom\_emojis]({{< relref "methods/custom_emojis" >}}) [index]
* [custom_emojis]({{< relref "methods/custom_emojis" >}}) [index]
* [suggestions]({{< relref "methods/suggestions" >}}) [index, destroy]
* [scheduled\_statuses]({{< relref "methods/scheduled_statuses" >}}) [index, show, update, destroy]
* [scheduled_statuses]({{< relref "methods/scheduled_statuses" >}}) [index, show, update, destroy]
* [preferences]({{< relref "methods/preferences" >}}) [index]
* [conversations]({{< relref "methods/conversations" >}}) [index, destroy]
* read [POST]
@ -150,29 +150,29 @@ The sections below this point are under construction.
* [endorsements]({{< relref "methods/endorsements" >}}) [index]
* [markers]({{< relref "methods/markers" >}}) [index, create]
* [apps]({{< relref "methods/apps" >}}) [create]
* verify\_credentials [credentials\#show]
* verify_credentials [credentials#show]
* [instance]({{< relref "methods/instance" >}}) [show]
* peers [index]
* activity [show]
* [domain\_blocks]({{< relref "methods/domain_blocks" >}}) [show, create, destroy]
* [domain_blocks]({{< relref "methods/domain_blocks" >}}) [show, create, destroy]
* [directory]({{< relref "methods/directory" >}}) [show]
* [follow\_requests]({{< relref "methods/follow_requests" >}}) [index]
* [follow_requests]({{< relref "methods/follow_requests" >}}) [index]
* authorize [POST]
* reject [POST]
* [notifications]({{< relref "methods/notifications" >}}) [index, show]
* clear [POST]
* dismiss [POST]
* [accounts]({{< relref "methods/accounts" >}})
* verify\_credentials [GET credentials\#show]
* update\_credentials [PATCH credentials\#update]
* search [show (search\#index)]
* verify_credentials [GET credentials#show]
* update_credentials [PATCH credentials#update]
* search [show (search#index)]
* relationships [index]
* [accounts]({{< relref "methods/accounts" >}}) [create, show]
* statuses [index accounts/statuses]
* followers [index accounts/follower\_accounts]
* following [index accounts/following\_accounts]
* followers [index accounts/follower_accounts]
* following [index accounts/following_accounts]
* lists [index accounts/lists]
* identity\_proofs [index accounts/identity\_proofs]
* identity_proofs [index accounts/identity_proofs]
* follow [POST]
* unfollow [POST]
* block [POST]
@ -182,9 +182,9 @@ The sections below this point are under construction.
* pin [POST]
* unpin [POST]
* [lists]({{< relref "methods/lists" >}}) [index, create, show, update, destroy]
* accounts [POST accounts/pins\#destroy]
* [featured\_tags]({{< relref "methods/featured_tags" >}}) [index, create, destroy]
* suggestions [GET suggestions\#index]
* accounts [POST accounts/pins#destroy]
* [featured_tags]({{< relref "methods/featured_tags" >}}) [index, create, destroy]
* suggestions [GET suggestions#index]
* [polls]({{< relref "methods/polls" >}}) [create, show]
* votes [create polls/votes]
* [push]({{< relref "methods/push" >}})
@ -196,12 +196,12 @@ The sections below this point are under construction.
* unsuspend [POST]
* approve [POST]
* reject [POST]
* action [create account\_actions]
* action [create account_actions]
* reports [index, show]
* assign\_to\_self [POST]
* assign_to_self [POST]
* unassign [POST]
* reopen [POST]
* resolve [POST]
* /api/v2
* [search]({{< relref "methods/search" >}}) [GET search\#index]
* [search]({{< relref "methods/search" >}}) [GET search#index]

View File

@ -208,10 +208,17 @@ aliases: [
**Version history:**\
3.1.0 - added
### `noindex` {{%optional%}} {#noindex}
**Description:** Whether the local user has opted out of being indexed by search engines.\
**Type:** {{<nullable>}} Boolean\
**Version history:**\
4.0.0 - added
### `moved` {{%optional%}} {#moved}
**Description:** Indicates that the profile is currently inactive and that its user has moved to a new account.\
**Type:** {{<nullable>}} [Account]({{< relref "entities/Account" >}}), or null if the profile is supended.\
**Type:** {{<nullable>}} [Account]({{< relref "entities/Account" >}}), or null if the profile is suspended.\
**Version history:**\
2.1.0 - added
@ -224,7 +231,7 @@ aliases: [
### `limited` {{%optional%}} {#limited}
**Description:** An extra attribute returned only when an account is silenced. If true, indicates that the account should be hidden behing a warning screen.\
**Description:** An extra attribute returned only when an account is silenced. If true, indicates that the account should be hidden behind a warning screen.\
**Type:** Boolean\
**Version history:**\
3.5.3 - added
@ -234,7 +241,7 @@ aliases: [
**Description:** When the account was created.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
0.1.0 - added
0.1.0 - added\
3.4.0 - now resolves to midnight instead of an exact time
### `last_status_at` {#last_status_at}

View File

@ -117,8 +117,8 @@ aliases: [
**Description:** The IP address last used to login to this account.\
**Type:** {{<nullable>}} String\
**Version history:**\
2.9.1 - added
3.5.0 - return type changed from String to [Admin::Ip]({{< relref "entities/Admin_Ip" >}}) due to a bug
2.9.1 - added\
3.5.0 - return type changed from String to [Admin::Ip]({{< relref "entities/Admin_Ip" >}}) due to a bug\
4.0.0 - bug fixed, return type is now a String again
### `ips` {#ip}
@ -147,7 +147,7 @@ aliases: [
**Description:** The current role of the account.\
**Type:** [Role]({{<relref "entities/role">}})\
**Version history:**\
2.9.1 - added, returns a String (enumerable, oneOf `user` `moderator` `admin`)
2.9.1 - added, returns a String (enumerable, oneOf `user` `moderator` `admin`)\
4.0.0 - now uses Role entity
### `confirmed` {#confirmed}

View File

@ -16,10 +16,6 @@ aliases: [
]
---
{{< hint style="danger" >}}
This page is under construction.
{{< /hint >}}
## Example
```json

View File

@ -101,14 +101,14 @@ aliases: [
4.0.0 - added
#### `history[][accounts]` {#history-accounts}
<!-- TODO: verify -->
**Description:** The counted accounts signup attempts using that email domain within that day.\
**Type:** String (cast from an integer)\
**Version history:**\
4.0.0 - added
#### `history[][uses]` {#history-uses}
<!-- TODO: verify -->
**Description:** The counted IP signup attempts of that email domain within that day.\
**Type:** String (cast from an integer)\
**Version history:**\

View File

@ -36,7 +36,7 @@ aliases: [
**Description:** The website associated with your application.\
**Type:** {{<nullable>}} String (URL)\
**Version history:**\
0.9.9 - added
0.9.9 - added\
3.5.1 - this property is now nullable
### `vapid_key` {#vapid_key}

View File

@ -21,7 +21,7 @@ aliases: [
}
```
## Required attributes
## Attributes
### `id` {#id}

View File

@ -12,8 +12,6 @@ aliases: [
]
---
## Attributes
### `id` {#id}

View File

@ -185,9 +185,98 @@ aliases: [
**Version history:**\
3.2.0 - added
## Trends::Link entity attributes {#trends-link}
```json
{
"url": "https://www.nbcnews.com/specials/plan-your-vote-2022-elections/index.html",
"title": "Plan Your Vote: 2022 Elections",
"description": "Everything you need to know about the voting rules where you live, including registration, mail-in voting, changes since 2020, and more.",
"type": "link",
"author_name": "NBC News",
"author_url": "",
"provider_name": "NBC News",
"provider_url": "",
"html": "",
"width": 400,
"height": 225,
"image": "https://files.mastodon.social/cache/preview_cards/images/045/027/478/original/0783d5e91a14fd49.jpeg",
"embed_url": "",
"blurhash": "UcQmF#ay~qofj[WBj[j[~qof9Fayofofayay",
"history": [
{
"day": "1661817600",
"accounts": "7",
"uses": "7"
},
{
"day": "1661731200",
"accounts": "23",
"uses": "23"
},
{
"day": "1661644800",
"accounts": "0",
"uses": "0"
},
{
"day": "1661558400",
"accounts": "0",
"uses": "0"
},
{
"day": "1661472000",
"accounts": "0",
"uses": "0"
},
{
"day": "1661385600",
"accounts": "0",
"uses": "0"
},
{
"day": "1661299200",
"accounts": "0",
"uses": "0"
}
]
}
```
### `history` {#history}
**Description:** Usage statistics for given days (typically the past week).\
**Type:** Array of Hash\
**Version history:**\
3.5.0 - added
#### `history[][day]` {#history-day}
**Description:** UNIX timestamp on midnight of the given day.\
**Type:** String (UNIX timestamp)\
**Version history:**\
3.5.0 - added
#### `history[][accounts]` {#history-accounts}
**Description:** The counted accounts using the link within that day.\
**Type:** String (cast from an integer)\
**Version history:**\
3.5.0 - added
#### `history[][uses]` {#history-uses}
**Description:** The counted statuses using the link within that day.\
**Type:** String (cast from an integer)\
**Version history:**\
3.5.0 - added
## See also
{{< page-relref ref="entities/Status#card" caption="Status (`card` attribute)" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/preview_card_serializer.rb" caption="app/serializers/rest/preview_card_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/trends/link_serializer.rb" caption="app/serializers/rest/trends/link_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/trends/links.rb" caption="app/models/trends/links.rb" >}}

View File

@ -21,7 +21,7 @@ aliases: [
}
```
## Base attributes
## Attributes
### `id` {#name}

View File

@ -14,10 +14,6 @@ aliases: [
## Example
<!--
TODO: figure out where params are coming from and in what order
-->
Returned from `POST /api/v1/statuses?status=test post&scheduled_at=2022-09-29`
```json
@ -66,7 +62,7 @@ Returned from `GET /api/v1/scheduled_statuses`:
}
```
## Required attributes
## Attributes
### `id` {#id}
@ -84,11 +80,123 @@ Returned from `GET /api/v1/scheduled_statuses`:
### `params` {#params}
**Description:** The parameters to be used when the status is posted.\
**Description:** The parameters that were used when scheduling the status, to be used when the status is posted.\
**Type:** Hash\
**Version history:**\
2.7.0 - added
#### `params[text]` {#params-text}
**Description:** Text to be used as status content.\
**Type:** String\
**Version history:**\
2.7.0 - added
#### `params[poll]` {#params-poll}
**Description:** Poll to be attached to the status.\
**Type:** {{<nullable>}} Hash\
**Version history:**\
2.8.0 - added
##### `params[poll][options[]]` {#params-poll-options}
**Description:** The poll options to be used.\
**Type:** Array of String\
**Version history:**\
2.8.0 - added
##### `params[poll][expires_in]` {#params-poll-expires_in}
**Description:** How many seconds the poll should last before closing.\
**Type:** String (cast from integer)\
**Version history:**\
2.8.0 - added
##### `params[poll][multiple]` {#params-poll-multiple}
**Description:** Whether the poll allows multiple choices.\
**Type:** {{<optional>}} Boolean\
**Version history:**\
2.8.0 - added
##### `params[poll][hide_totals]` {#params-poll-hide_totals}
**Description:** Whether the poll should hide total votes until after voting has ended.\
**Type:** {{<optional>}} Boolean\
**Version history:**\
2.8.0 - added
#### `params[media_ids]` {#params-media_ids}
**Description:** IDs of the MediaAttachments that will be attached to the status.\
**Type:** {{<nullable>}} Array of String\
**Version history:**\
2.7.0 - added
#### `params[sensitive]` {#params-sensitive}
**Description:** Whether the status will be marked as sensitive.\
**Type:** {{<nullable>}} Boolean\
**Version history:**\
2.7.0 - added
#### `params[spoiler_text]` {#params-spoiler_text}
**Description:** The text of the content warning or summary for the status.\
**Type:** {{<nullable>}} String\
**Version history:**\
2.7.0 - added
#### `params[visibility]` {#params-visibility}
**Description:** The language that will be used for the status.\
**Type:** {{<nullable>}} String (ISO 639-1 two-letter language code)\
**Version history:**\
2.7.0 - added
#### `params[in_reply_to_id]` {#params-in_reply_to_id}
**Description:** ID of the Status that will be replied to.\
**Type:** {{<nullable>}} Integer\
**Version history:**\
2.7.0 - added
#### `params[language]` {#params-language}
**Description:** The language that will be used for the status.\
**Type:** {{<nullable>}} String (ISO 639-1 two-letter language code)\
**Version history:**\
2.7.0 - added
#### `params[application_id]` {#params-application_id}
**Description:** ID of the Application that posted the status.\
**Type:** Integer\
**Version history:**\
2.7.0 - added
#### `params[scheduled_at]` {#params-scheduled_at}
**Description:** When the status will be scheduled. This will be null because the status is only scheduled once.\
**Type:** {{<nullable>}} Null\
**Version history:**\
2.7.0 - added
#### `params[idempotency]` {#params-idempotency}
**Description:** Idempotency key to prevent duplicate statuses.\
**Type:** {{<nullable>}} String\
**Version history:**\
2.7.0 - added
#### `params[with_rate_limit]` {#params-with_rate_limit}
**Description:** Whether the status should be rate limited <!-- TODO: What does this mean -->.\
**Type:** Boolean\
**Version history:**\
2.7.0 - added
### `media_attachments` {#media_attachments}
**Description:** Media that will be attached when the status is posted.\

View File

@ -92,13 +92,15 @@ Truncated sample search for q=cats limit=2
**Description:** Accounts which match the given query\
**Type:** Array of [Account]({{< relref "entities/Account" >}})\
**Version history:** Added in x.x.x
**Version history:**\
1.1.0 - added
### `statuses` {#statuses}
**Description:** Statuses which match the given query\
**Type:** Array of [Status]({{< relref "entities/Status" >}})\
**Version history:** Added in x.x.x
**Version history:**\
1.1.0 - added
### `hashtags` {#hashtags}
@ -106,7 +108,7 @@ Truncated sample search for q=cats limit=2
**Type:** Array of [Tag]({{< relref "entities/Tag" >}})\
**Version history:**\
1.1.0 - added\
2.4.1 - v1 deprecated because it returns Array of String. v2 added which returns Array of Tag.\
2.4.1 - v1/search deprecated because it returns Array of String. v2/search added which returns Array of Tag.\
3.0.0 - v1 removed
## See also

View File

@ -188,7 +188,7 @@ aliases: [
**Description:** The website associated with the application that posted this status.\
**Type:** {{<nullable>}} String (URL) or null\
**Version history:**\
0.9.9 - added
0.9.9 - added\
3.5.1 - this property is now nullable
### `mentions` {#mentions}

View File

@ -85,7 +85,21 @@ aliases: [
### `poll` {{%optional%}} {#poll}
**Description:** The current state of the poll options at this revision. Note that edits changing the poll options will be collapsed together into one edit, since this action resets the poll.\
**Type:** Hash with `options` (Array of Hash with `title`)\
**Type:** Hash\
**Version history:**\
3.5.0 - added
#### `poll.options[]` {#poll-options}
**Description:** The poll options at this revision.\
**Type:** Array of Hash\
**Version history:**\
3.5.0 - added
#### `poll.options[].title` {#poll-options-title}
**Description:** The text for a poll option.\
**Type:** String\
**Version history:**\
3.5.0 - added

View File

@ -34,7 +34,7 @@ aliases: [
**Type:** String (Enumerable oneOf)\
`staff` = This account was manually recommended by your administration team\
`past_interactions` = You have interacted with this account previously\
`global` = This account has many reblogs, favourites, and active local followers within the last 30 days
`global` = This account has many reblogs, favourites, and active local followers within the last 30 days\
**Version history:**\
3.4.0 - added

View File

@ -5,12 +5,8 @@ menu:
docs:
parent: entities
aliases: [
"/entities/history",
"/entities/History",
"/entities/tag",
"/entities/Tag",
"/api/entities/history",
"/api/entities/History",
"/api/entities/tag",
"/api/entities/Tag",
]
@ -67,7 +63,7 @@ aliases: [
### `name` {#name}
**Description:** The value of the hashtag after the \# sign.\
**Description:** The value of the hashtag after the # sign.\
**Type:** String\
**Version history:**\
0.9.0 - added
@ -114,19 +110,96 @@ aliases: [
**Version history:**\
4.0.0 - added
## Admin::Tag attributes {#admin}
```json
{
"name": "caturday",
"url": "https://mastodon.example/tags/caturday",
"history": [
{
"day": "1669507200",
"accounts": "53",
"uses": "56"
},
{
"day": "1669420800",
"accounts": "142",
"uses": "171"
},
{
"day": "1669334400",
"accounts": "11",
"uses": "11"
},
{
"day": "1669248000",
"accounts": "8",
"uses": "9"
},
{
"day": "1669161600",
"accounts": "8",
"uses": "20"
},
{
"day": "1669075200",
"accounts": "11",
"uses": "11"
},
{
"day": "1668988800",
"accounts": "17",
"uses": "22"
}
],
"id": "802",
"trendable": true,
"usable": true,
"requires_review": false
}
```
### `id` {#id}
**Description:** The ID of the Tag in the database.\
**Type:** String (cast from integer, but not guaranteed to be a number)\
**Version history:**\
3.5.0 - added
### `trendable` {#trendable}
**Description:** Whether the hashtag has been approved to trend.\
**Type:** Boolean\
**Version history:**\
3.5.0 - added
### `usable` {#usable}
**Description:** Whether the hashtag has not been disabled from auto-linking.\
**Type:** Boolean\
**Version history:**\
3.5.0 - added
### `requires_review` {#requires_review}
**Description:** Whether the hashtag has not been reviewed yet to approve or deny its trending.\
**Type:** Boolean\
**Version history:**\
3.5.0 - added
## See also
{{< page-relref ref="entities/Search#tags" caption="Search (`tags` attribute)" >}}
{{< page-relref ref="methods/tags" caption="tags API methods" >}}
<!--
TODO: This one may be replaced with FeaturedTag
https://github.com/mastodon/mastodon/pull/19221
-->
{{< page-relref ref="methods/featured_tags#suggestions" caption="GET /api/v1/featured_tags/suggestions" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/tag_serializer.rb" caption="app/serializers/rest/tag_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/tag_serializer.rb" caption="app/serializers/rest/admin/tag_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/tag.rb" caption="app/models/tag.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/trends/history.rb" caption="app/models/trends/history.rb" >}}

View File

@ -20,7 +20,7 @@ aliases: [
## Register an account {#create}
```http
POST https://mastodon.example/api/v1/accounts HTTP/1.1
POST /api/v1/accounts HTTP/1.1
```
Creates a user and account records. Returns an account access token for the app that initiated the request. The app should save this token for later, and should wait for the user to confirm their account by clicking a link in their email inbox.
@ -151,12 +151,12 @@ ERR_INCLUSION
## Verify account credentials {#verify_credentials}
```http
GET https://mastodon.example/api/v1/accounts/verify_credentials HTTP/1.1
GET /api/v1/accounts/verify_credentials HTTP/1.1
```
Test to make sure that the user token works.
**Returns:** the user's own [Account]({{< relref "entities/Account">}}) with [`source`]({{< relref "entities/Account#source">}}) attribute\
**Returns:** [CredentialAccount]({{< relref "entities/Account#CredentialAccount">}})\
**OAuth**: User token + `read:accounts`\
**Version history:**\
0.0.0 - added
@ -302,7 +302,7 @@ Token does not have an authorized user
## Update account credentials {#update_credentials}
```http
PATCH https://mastodon.example/api/v1/accounts/update_credentials HTTP/1.1
PATCH /api/v1/accounts/update_credentials HTTP/1.1
```
Update the user's display and preferences.
@ -324,12 +324,6 @@ Authorization
##### Form data parameters
discoverable
: Boolean. Whether the account should be shown in the profile directory.
bot
: Boolean. Whether the account has a bot flag.
display_name
: String. The display name to use for the profile.
@ -345,6 +339,21 @@ header
locked
: Boolean. Whether manual approval of follow requests is required.
bot
: Boolean. Whether the account has a bot flag.
discoverable
: Boolean. Whether the account should be shown in the profile directory.
fields_attributes
: Hash. The profile fields to be set. Inside this hash, the key is an integer cast to a string (although the exact integer does not matter), and the value is another hash including `name` and `value`. By default, max 4 fields.
fields_attributes[:index][name]
: String. The name of the profile field. By default, max 255 characters.
fields_attributes[:index][value]
: String. The value of the profile field. By default, max 255 characters.
source[privacy]
: String. Default post privacy for authored statuses. Can be `public`, `unlisted`, or `private`.
@ -354,13 +363,64 @@ source[sensitive]
source[language]
: String. Default language to use for authored statuses (ISO 6391)
fields_attributes[]
: Array. Profile metadata `name` and `value`. By default, max 4 fields and 255 characters per property/value.
#### Response
##### 200: OK
To update account fields, you will need to construct your hash like so for example:
```json
{
"fields_attributes": {
"0": {
"name": "Website",
"value": "https://trwnh.com"
},
"1": {
"name": "Sponsor",
"value": "https://liberapay.com/at"
},
// ...
}
}
```
As query parameters, your request may look something like this:
```http
PATCH https://mastodon.example/api/v1/accounts/update_credentials
?fields_attributes[0][name]=Website
&fields_attributes[0][value]=https://trwnh.com
&fields_attributes[1][name]=Sponsor
&fields_attributes[1][value]=https://liberapay.com/at
&...
```
Note that the integer index does not actually matter -- fields will be populated by the order in which they are provided. For example:
```json
{
"fields_attributes": {
"420": {
"name": "1st",
"value": "field"
},
"69": {
"name": "2nd",
"value": "field"
},
"1312": {
"name": "3rd",
"value": "field"
},
"-99999999999999999999999999999999": {
"name": "4th",
"value": "field"
},
}
}
```
You should use accounts/verify_credentials to first obtain plaintext representations from within the `source` parameter, then allow the user to edit these plaintext representations before submitting them through this API. The server will generate the corresponding HTML.
```json
@ -467,7 +527,7 @@ Token does not have an authorized user
## Get account {#get}
```http
GET https://mastodon.example/api/v1/accounts/:id HTTP/1.1
GET /api/v1/accounts/:id HTTP/1.1
```
View information about a profile.
@ -656,7 +716,7 @@ Account is suspended (since 2.4.0 and until 3.3.0)
## Get account's statuses {#statuses}
```http
GET https://mastodon.example/api/v1/accounts/:id/statuses HTTP/1.1
GET /api/v1/accounts/:id/statuses HTTP/1.1
```
Statuses posted to the given account.
@ -665,6 +725,8 @@ Statuses posted to the given account.
**OAuth:** Public (for public statuses only), or user token + `read:statuses` (for private statuses the user is authorized to see)\
**Version history:**\
0.0.0 - added\
1.4.2 - add `only_media` and `exclude_replies`\
1.6.0 - add `pinned`\
2.6.0 - add `min_id`\
2.7.0 - add `exclude_reblogs` and allow unauthed use\
2.8.0 - add `tagged` parameter\
@ -693,10 +755,19 @@ min_id
: String. Return results immediately newer than this ID
limit
: Integer. Maximum number of results to return. Default: 20.
: Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.
only_media
: Boolean. Filter out statuses without attachments.
exclude_replies
: Boolean. Filter out statuses in reply to a different account.
exclude_reblogs
: Boolean. Whether to filter out boosts from the response.
: Boolean. Filter out boosts from the response.
pinned
: Boolean. Filter for pinned statuses only.
tagged
: String. Filter for statuses using a specific hashtag.
@ -757,16 +828,17 @@ Account is suspended (since 2.4.0 and until 3.3.0)
## Get account's followers {#followers}
```http
GET https://mastodon.example/api/v1/accounts/:id/followers HTTP/1.1
GET /api/v1/accounts/:id/followers HTTP/1.1
```
Accounts which follow the given account, if network is not hidden by the account owner.
**Returns:** Array of [Account]({{< relref "entities/Account">}})\
**OAuth:** App token + `read:accounts`\
**OAuth:** Public\
**Version history:**\
0.0.0 - added\
3.3.0 - both `min_id` and `max_id` can be used at the same time now
3.3.0 - both `min_id` and `max_id` can be used at the same time now\
4.0.0 - no longer requires an app token + `read:accounts`
#### Request
##### Path parameters
@ -791,7 +863,7 @@ min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 40.
: Integer. Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.
#### Response
##### 200: OK
@ -820,7 +892,7 @@ Sample output with limit=2.
Because Follow IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link: <https://mastodon.social/api/v1/accounts/14715/followers?limit=2&max_id=7486869>; rel="next", <https://mastodon.social/api/v1/accounts/14715/followers?limit=2&since_id=7489740>; rel="prev"
Link: <https://mastodon.example/api/v1/accounts/14715/followers?limit=2&max_id=7486869>; rel="next", <https://mastodon.example/api/v1/accounts/14715/followers?limit=2&since_id=7489740>; rel="prev"
```
##### 401: Unauthorized
@ -862,16 +934,17 @@ Account is suspended (since 2.4.0 and until 3.3.0)
## Get account's following {#following}
```http
GET https://mastodon.example/api/v1/accounts/:id/following HTTP/1.1
GET /api/v1/accounts/:id/following HTTP/1.1
```
Accounts which the given account is following, if network is not hidden by the account owner.
**Returns:** Array of [Account]({{< relref "entities/Account">}})\
**OAuth:** App token + `read:accounts`\
**OAuth:** Public\
**Version history:**\
0.0.0 - added\
3.3.0 - both `min_id` and `max_id` can be used at the same time now
3.3.0 - both `min_id` and `max_id` can be used at the same time now\
4.0.0 - no longer requires an app token + `read:accounts`
#### Request
##### Path parameters
@ -896,7 +969,7 @@ min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 40.
: Integer. Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.
#### Response
##### 200: OK
@ -924,7 +997,7 @@ Sample output with limit=2.
Because Follow IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link: <https://mastodon.social/api/v1/accounts/1/followers?limit=2&max_id=7628164>; rel="next", <https://mastodon.social/api/v1/accounts/1/followers?limit=2&since_id=7628165>; rel="prev"
Link: <https://mastodon.example/api/v1/accounts/1/followers?limit=2&max_id=7628164>; rel="next", <https://mastodon.example/api/v1/accounts/1/followers?limit=2&since_id=7628165>; rel="prev"
```
##### 401: Unauthorized
@ -966,7 +1039,7 @@ Account is suspended (since 2.4.0 and until 3.3.0)
## Get account's featured tags {#featured_tags}
```http
GET https://mastodon.example/api/v1/accounts/:id/featured_tags HTTP/1.1
GET /api/v1/accounts/:id/featured_tags HTTP/1.1
```
Tags featured by this account.
@ -1006,7 +1079,7 @@ Authorization
## Get lists containing this account {#lists}
```http
GET https://mastodon.example/api/v1/accounts/:id/lists HTTP/1.1
GET /api/v1/accounts/:id/lists HTTP/1.1
```
User lists that you have added this account to.
@ -1094,7 +1167,7 @@ Token does not have an authorized user
## Follow account {#follow}
```http
POST https://mastodon.example/api/v1/accounts/:id/follow HTTP/1.1
POST /api/v1/accounts/:id/follow HTTP/1.1
```
Follow the given account. Can also be used to update whether to show reblogs or enable notifications.
@ -1176,7 +1249,7 @@ Token does not have an authorized user
## Unfollow account {#unfollow}
```http
POST https://mastodon.example/api/v1/accounts/:id/unfollow HTTP/1.1
POST /api/v1/accounts/:id/unfollow HTTP/1.1
```
Unfollow the given account.
@ -1245,7 +1318,7 @@ Token does not have an authorized user
## Remove account from followers {#remove_from_followers}
```http
POST https://mastodon.example/api/v1/accounts/:id/remove_from_followers HTTP/1.1
POST /api/v1/accounts/:id/remove_from_followers HTTP/1.1
```
Remove the given account from your followers.
@ -1313,7 +1386,7 @@ Token does not have an authorized user
## Block account {#block}
```http
POST https://mastodon.example/api/v1/accounts/:id/block HTTP/1.1
POST /api/v1/accounts/:id/block HTTP/1.1
```
Block the given account. Clients should filter statuses from this account if received (e.g. due to a boost in the Home timeline)
@ -1382,7 +1455,7 @@ Token does not have an authorized user
## Unblock account {#unblock}
```http
POST https://mastodon.example/api/v1/accounts/:id/unblock HTTP/1.1
POST /api/v1/accounts/:id/unblock HTTP/1.1
```
Unblock the given account.
@ -1451,7 +1524,7 @@ Token does not have an authorized user
## Mute account {#mute}
```http
POST https://mastodon.example/api/v1/accounts/:id/mute HTTP/1.1
POST /api/v1/accounts/:id/mute HTTP/1.1
```
Mute the given account. Clients should filter statuses and notifications from this account, if received (e.g. due to a boost in the Home timeline).
@ -1529,7 +1602,7 @@ Token does not have an authorized user
## Unmute account {#unmute}
```http
POST https://mastodon.example/api/v1/accounts/:id/unmute HTTP/1.1
POST /api/v1/accounts/:id/unmute HTTP/1.1
```
Unmute the given account.
@ -1598,7 +1671,7 @@ Token does not have an authorized user
## Feature account on your profile {#pin}
```http
POST https://mastodon.example/api/v1/accounts/:id/pin HTTP/1.1
POST /api/v1/accounts/:id/pin HTTP/1.1
```
Add the given account to the user's featured profiles. (Featured profiles are currently shown on the user's own public profile.)
@ -1697,7 +1770,7 @@ Can sometimes be returned if the account already endorsed.
## Unfeature account from profile {#unpin}
```http
POST https://mastodon.example/api/v1/accounts/:id/unpin HTTP/1.1
POST /api/v1/accounts/:id/unpin HTTP/1.1
```
Remove the given account from the user's featured profiles.
@ -1765,7 +1838,7 @@ Token does not have an authorized user
## Set private note on profile {#note}
```http
POST https://mastodon.example/api/v1/accounts/:id/note HTTP/1.1
POST /api/v1/accounts/:id/note HTTP/1.1
```
Sets a private note on a user.
@ -1859,12 +1932,12 @@ Token does not have an authorized user
## Check relationships to other accounts {#relationships}
```http
GET https://mastodon.example/api/v1/accounts/relationships HTTP/1.1
GET /api/v1/accounts/relationships HTTP/1.1
```
Find out whether a given account is followed, blocked, muted, etc.
**Returns:** Array of [Relationship]({{< relref "entities/relationship">}})\
**Returns:** Array of [Relationship]({{< relref "entities/Relationship">}})\
**OAuth:** User token + `read:follows`\
**Version history:**\
0.0.0 - added
@ -1943,7 +2016,7 @@ Token does not have an authorized user
## Find familiar followers {#familiar_followers}
```http
GET https://mastodon.example/api/v1/accounts/familiar_followers HTTP/1.1
GET /api/v1/accounts/familiar_followers HTTP/1.1
```
Obtain a list of all accounts that follow a given account, filtered for accounts you follow.
@ -2021,7 +2094,7 @@ Token does not have an authorized user
## Search for matching accounts {#search}
```http
GET https://mastodon.example/api/v1/accounts/search HTTP/1.1
GET /api/v1/accounts/search HTTP/1.1
```
Search for matching accounts by username or display name.
@ -2029,7 +2102,8 @@ Search for matching accounts by username or display name.
**Returns:** Array of [Account]({{< relref "entities/Account">}})\
**OAuth:** User token + `read:accounts`\
**Version history:**\
0.0.0 - added
0.0.0 - added\
2.8.0 - add `limit`, `offset` and `following`
#### Request
##### Headers
@ -2043,7 +2117,10 @@ q
: {{<required>}} String. Search query for accounts.
limit
: Maximum number of results. Defaults to 40.
: Integer. Maximum number of results. Defaults to 40 accounts. Max 80 accounts.
offset
: Integer. Skip the first n results.
resolve
: Boolean. Attempt WebFinger lookup. Defaults to false. Use this when `q` is an exact address.
@ -2098,10 +2175,10 @@ resolve=true, but the domain part of the user@domain address is not a currently
## Lookup account ID from Webfinger address {#lookup}
```http
GET https://mastodon.example/api/v1/accounts/lookup HTTP/1.1
GET /api/v1/accounts/lookup HTTP/1.1
```
Quickly lookup a username to see if it is available, or quickly resolve a Webfinger address to an account ID.
Quickly lookup a username to see if it is available, skipping WebFinger resolution.
**Returns:** [Account]({{< relref "entities/Account">}})\
**OAuth:** Public\
@ -2114,9 +2191,6 @@ Quickly lookup a username to see if it is available, or quickly resolve a Webfin
acct
: {{<required>}} String. The username or Webfinger address to lookup.
skip_webfinger
: Boolean. Whether to use the locally cached result instead of performing full Webfinger resolution. Defaults to true.
#### Response
##### 200: OK
@ -2161,7 +2235,7 @@ Username or address does not map to an account
## (DEPRECATED) Identity proofs {#identity_proofs}
```http
GET https://mastodon.example/api/v1/accounts/:id/identity_proofs HTTP/1.1
GET /api/v1/accounts/:id/identity_proofs HTTP/1.1
```
**Returns:** Array of [IdentityProof]({{< relref "entities/identityproof">}})\
@ -2246,4 +2320,6 @@ Token does not have an authorized user
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/search_controller.rb" caption="app/controllers/api/v1/accounts/search_controller.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/statuses_controller.rb" caption="app/controllers/api/v1/accounts/statuses_controller.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/statuses_controller.rb" caption="app/controllers/api/v1/accounts/statuses_controller.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/account_statuses_filter.rb" caption="app/models/account_statuses_filter.rb" >}}

View File

@ -19,7 +19,7 @@ aliases: [
## View accounts (v1) {#v1}
```http
GET https://mastodon.example/api/v1/admin/accounts HTTP/1.1
GET /api/v1/admin/accounts HTTP/1.1
```
View all accounts, optionally matching certain criteria for filtering, up to 100 at a time. Pagination may be done with the HTTP Link header in the response. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
@ -93,7 +93,7 @@ min_id
: String. Return results immediately newer than ID.
limit
: Integer. Maximum number of results to return. Defaults to 100.
: Integer. Maximum number of results to return. Defaults to 100 accounts. Max 200 accounts.
#### Response
##### 200: OK
@ -182,7 +182,7 @@ Authorized user is missing a permission, or invalid or missing Authorization hea
## View accounts (v2) {#v2}
```http
GET https://mastodon.example/api/v2/admin/accounts HTTP/1.1
GET /api/v2/admin/accounts HTTP/1.1
```
View all accounts, optionally matching certain criteria for filtering, up to 100 at a time. Pagination may be done with the HTTP Link header in the response. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
@ -212,8 +212,8 @@ status
permissions
: String. Filter for accounts with `staff` permissions (users that can manage reports).
role_ids
: String. Filter for users with these roles.
role_ids[]
: Array of String. Filter for users with these roles.
invited_by
: String. Lookup users invited by the account with this ID.
@ -243,7 +243,7 @@ min_id
: String. Return results immediately newer than ID.
limit
: Integer. Maximum number of results to return. Defaults to 100.
: Integer. Maximum number of results to return. Defaults to 100 accounts. Max 200 accounts.
#### Response
##### 200: OK
@ -309,7 +309,7 @@ Authorized user is missing a permission, or invalid or missing Authorization hea
## View a specific account {#get-one}
```http
GET https://mastodon.example/api/v1/admin/accounts/:id HTTP/1.1
GET /api/v1/admin/accounts/:id HTTP/1.1
```
View admin-level information about the given account.
@ -405,7 +405,7 @@ Account does not exist
## Approve a pending account {#approve}
```http
POST https://mastodon.example/api/v1/admin/accounts/:id/approve HTTP/1.1
POST /api/v1/admin/accounts/:id/approve HTTP/1.1
```
Approve the given local account if it is currently pending approval.
@ -471,7 +471,7 @@ Account does not exist
## Reject a pending account {#reject}
```http
POST https://mastodon.example/api/v1/admin/accounts/:id/reject HTTP/1.1
POST /api/v1/admin/accounts/:id/reject HTTP/1.1
```
Reject the given local account if it is currently pending approval.
@ -575,7 +575,7 @@ Account does not exist
## Delete an account {#delete}
```http
DELETE https://mastodon.example/api/v1/admin/accounts/:id HTTP/1.1
DELETE /api/v1/admin/accounts/:id HTTP/1.1
```
Permanently delete data for a suspended account.
@ -681,7 +681,7 @@ Authorized user is missing a permission, or invalid or missing Authorization hea
## Perform an action against an account {#action}
```http
POST https://mastodon.example/api/v1/admin/accounts/:id/action HTTP/1.1
POST /api/v1/admin/accounts/:id/action HTTP/1.1
```
Perform an action against an account and log this action in the moderation history. Also resolves any open reports against this account.
@ -767,7 +767,7 @@ Account or Report with given ID does not exist
## Enable a currently disabled account {#enable}
```http
POST https://mastodon.example/api/v1/admin/accounts/:id/enable HTTP/1.1
POST /api/v1/admin/accounts/:id/enable HTTP/1.1
```
Re-enable a local account whose login is currently disabled.
@ -833,7 +833,7 @@ Account does not exist
## Unsilence an account {#unsilence}
```http
POST https://mastodon.example/api/v1/admin/accounts/:id/unsilence HTTP/1.1
POST /api/v1/admin/accounts/:id/unsilence HTTP/1.1
```
Unsilence an account if it is currently silenced.
@ -899,7 +899,7 @@ Account does not exist
## Unsuspend an account {#unsuspend}
```http
POST https://mastodon.example/api/v1/admin/accounts/:id/unsuspend HTTP/1.1
POST /api/v1/admin/accounts/:id/unsuspend HTTP/1.1
```
Unsuspend a currently suspended account.
@ -965,7 +965,7 @@ Account does not exist
## Unmark an account as sensitive {#unsensitive}
```http
POST https://mastodon.example/api/v1/admin/accounts/:id/unsensitive HTTP/1.1
POST /api/v1/admin/accounts/:id/unsensitive HTTP/1.1
```
Stops marking an account's posts as sensitive, if it was previously flagged as sensitive.

View File

@ -16,14 +16,10 @@ aliases: [
#TableOfContents ul ul ul {display: none}
</style>
{{< hint style="danger" >}}
This page is under construction.
{{< /hint >}}
## List all canonical email blocks {#get}
```http
GET https://mastodon.example/api/v1/admin/canonical_email_blocks HTTP/1.1
GET /api/v1/admin/canonical_email_blocks HTTP/1.1
```
**Returns:** Array of [Admin::CanonicalEmailBlock]({{< relref "entities/Admin_CanonicalEmailBlock" >}})\
@ -41,15 +37,35 @@ Authorization
##### Query parameters
max_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
since_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 100.
: Integer. Maximum number of results to return. Defaults to 100 blocks. Max 200 blocks.
#### Response
##### 200: OK
<!-- TODO: -->
```json
[
{
"id": "1",
"canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c"
},
// ...
]
```
Because CanonicalEmailBlock IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link: <http://mastodon.example/api/v1/admin/canonical_email_blocks?limit=2&max_id=2>; rel="next", <http://mastodon.example/api/v1/admin/canonical_email_blocks?limit=2&since_id=1>; rel="prev"
```
##### 403: Forbidden
@ -67,7 +83,7 @@ Authorized user is missing a permission, or invalid or missing Authorization hea
## Show a single canonical email block {#get-one}
```http
GET https://mastodon.example/api/v1/admin/canonical_email_blocks/:id HTTP/1.1
GET /api/v1/admin/canonical_email_blocks/:id HTTP/1.1
```
**Returns:** [Admin::CanonicalEmailBlock]({{< relref "entities/Admin_CanonicalEmailBlock" >}})\
@ -86,9 +102,11 @@ Authorization
#### Response
##### 200: OK
<!-- TODO: -->
```json
{
"id": "1",
"canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c"
}
```
##### 403: Forbidden
@ -101,15 +119,27 @@ Authorized user is missing a permission, or invalid or missing Authorization hea
}
```
##### 404: Not found
Canonical email block does not exist or was already deleted
```json
{
"error": "Record not found"
}
```
---
## Test {#test}
```http
POST https://mastodon.example/api/v1/admin/canonical_email_blocks/test HTTP/1.1
POST /api/v1/admin/canonical_email_blocks/test HTTP/1.1
```
**Returns:** [Admin::CanonicalEmailBlock]({{< relref "entities/Admin_CanonicalEmailBlock" >}})\
Canoniocalize and hash an email address.
**Returns:** Array of [Admin::CanonicalEmailBlock]({{< relref "entities/Admin_CanonicalEmailBlock" >}})\
**OAuth:** User token + `admin:read:canonical_email_blocks`\
**Permissions:** Manage Blocks\
**Version history:**\
@ -124,15 +154,21 @@ Authorization
##### Form data parameters
parameter
: TODO:
email
: {{<required>}} String. The email to canonicalize and hash.
#### Response
##### 200: OK
<!-- TODO: -->
All matching canonical email blocks are returned.
```json
[
{
"id": "1",
"canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c"
}
]
```
##### 403: Forbidden
@ -145,12 +181,16 @@ Authorized user is missing a permission, or invalid or missing Authorization hea
}
```
##### 500: Server error
<!-- TODO: remove when https://github.com/mastodon/mastodon/issues/21774 is fixed -->
No email was provided
---
## Block a canonical email {#create}
```http
POST https://mastodon.example/api/v1/admin/canonical_email_blocks HTTP/1.1
POST /api/v1/admin/canonical_email_blocks HTTP/1.1
```
**Returns:** [Admin::CanonicalEmailBlock]({{< relref "entities/Admin_CanonicalEmailBlock" >}})\
@ -169,17 +209,21 @@ Authorization
##### Form data parameters
email
: TODO:
: {{<required>}} String. The email to canonicalize, hash, and block. If this parameter is provided, `canonical_email_hash` will be ignored.
canonical_email_hash
: TODO:
: String. The hash to test against. If `email` is not provided, this parameter is required.
#### Response
##### 200: OK
<!-- TODO: -->
Canonical email has been successfully blocked
```json
{
"id": "1",
"canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c"
}
```
##### 403: Forbidden
@ -192,12 +236,22 @@ Authorized user is missing a permission, or invalid or missing Authorization hea
}
```
##### 422: Unprocessable entity
Canonical email hash is already blocked
```json
{
"error":"Validation failed: Canonical email hash has already been taken"
}
```
---
## Delete a canonical email block {#delete}
```http
DELETE https://mastodon.example/api/v1/admin/canonical_email_blocks/:id HTTP/1.1
DELETE /api/v1/admin/canonical_email_blocks/:id HTTP/1.1
```
**Returns:** [Admin::CanonicalEmailBlock]({{< relref "entities/Admin_CanonicalEmailBlock" >}})\
@ -216,9 +270,10 @@ Authorization
#### Response
##### 200: OK
<!-- TODO: -->
Canonical email block successfully deleted.
```json
{}
```
##### 403: Forbidden
@ -231,6 +286,16 @@ Authorized user is missing a permission, or invalid or missing Authorization hea
}
```
##### 404: Not found
Canonical email block does not exist or was already deleted
```json
{
"error": "Record not found"
}
```
---
## See also

View File

@ -19,7 +19,7 @@ aliases: [
## Get dimensional data {#get}
```http
POST https://mastodon.example/api/v1/admin/dimensions HTTP/1.1
POST /api/v1/admin/dimensions HTTP/1.1
```
Obtain information about popularity of certain accounts, servers, languages, etc.

View File

@ -19,7 +19,7 @@ aliases: [
## List all allowed domains {#get}
```http
GET https://mastodon.example/api/v1/admin/domain_allows HTTP/1.1
GET /api/v1/admin/domain_allows HTTP/1.1
```
Show information about all allowed domains.
@ -39,8 +39,17 @@ Authorization
##### Query parameters
max_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
since_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 100.
: Integer. Maximum number of results to return. Defaults to 100 allows. Max 200 allows.
#### Response
@ -61,6 +70,12 @@ limit
]
```
Because DomainAllow IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link: <http://mastodon.example/api/v1/admin/domain_allows?limit=2&max_id=2>; rel="next", <http://mastodon.example/api/v1/admin/domain_allows?limit=2&since_id=1>; rel="prev"
```
##### 403: Forbidden
Authorized user is not allowed to perform this action, or invalid or missing Authorization header
@ -76,7 +91,7 @@ Authorized user is not allowed to perform this action, or invalid or missing Aut
## Get a single allowed domain {#get-one}
```http
GET https://mastodon.example/api/v1/admin/domain_allows/:id HTTP/1.1
GET /api/v1/admin/domain_allows/:id HTTP/1.1
```
Show information about a single allowed domain.
@ -132,7 +147,7 @@ DomainAllow with the given ID does not exist
## Allow a domain to federate {#create}
```http
POST https://mastodon.example/api/v1/admin/domain_allows HTTP/1.1
POST /api/v1/admin/domain_allows HTTP/1.1
```
Add a domain to the list of domains allowed to federate, to be used when the instance is in allow-list federation mode.
@ -193,7 +208,7 @@ The domain parameter was not provided or was invalid
## Delete an allowed domain {#delete}
```http
DELETE https://mastodon.example/api/v1/admin/domain_allows/:id HTTP/1.1
DELETE /api/v1/admin/domain_allows/:id HTTP/1.1
```
Delete a domain from the allowed domains list.

View File

@ -16,14 +16,10 @@ aliases: [
#TableOfContents ul ul ul {display: none}
</style>
{{< hint style="danger" >}}
This page is under construction.
{{< /hint >}}
## List all blocked domains {#get}
```http
GET https://mastodon.example/api/v1/admin/domain_blocks HTTP/1.1
GET /api/v1/admin/domain_blocks HTTP/1.1
```
Show information about all blocked domains.
@ -43,8 +39,17 @@ Authorization
##### Query parameters
max_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
since_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 100.
: Integer. Maximum number of results to return. Defaults to 100 blocks. Max 200 blocks.
#### Response
@ -67,6 +72,12 @@ limit
]
```
Because DomainBlock IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link: <http://mastodon.example/api/v1/admin/domain_blocks?limit=2&max_id=2>; rel="next", <http://mastodon.example/api/v1/admin/domain_blocks?limit=2&since_id=1>; rel="prev"
```
##### 403: Forbidden
Authorized user is not allowed to perform this action, or invalid or missing Authorization header
@ -82,7 +93,7 @@ Authorized user is not allowed to perform this action, or invalid or missing Aut
## Get a single blocked domain {#get-one}
```http
GET https://mastodon.example/api/v1/admin/domain_blocks/:id HTTP/1.1
GET /api/v1/admin/domain_blocks/:id HTTP/1.1
```
Show information about a single blocked domain.
@ -144,7 +155,7 @@ DomainBlock with the given ID does not exist
## Block a domain from federating {#create}
```http
POST https://mastodon.example/api/v1/admin/domain_blocks HTTP/1.1
POST /api/v1/admin/domain_blocks HTTP/1.1
```
Add a domain to the list of domains blocked from federating.
@ -229,7 +240,7 @@ The domain parameter was not provided
## Update a domain block {#update}
```http
PUT https://mastodon.example/api/v1/admin/domain_blocks/:id HTTP/1.1
PUT /api/v1/admin/domain_blocks/:id HTTP/1.1
```
Change parameters for an existing domain block.
@ -302,7 +313,7 @@ Authorized user is not allowed to perform this action, or invalid or missing Aut
```
##### 500: Server error
<!-- TODO: remove when fixed -->
<!-- TODO: remove when https://github.com/mastodon/mastodon/issues/21775 is fixed -->
Invalid severity
---
@ -310,7 +321,7 @@ Invalid severity
## Remove a domain block {#delete}
```http
DELETE https://mastodon.example/api/v1/admin/domain_blocks/:id HTTP/1.1
DELETE /api/v1/admin/domain_blocks/:id HTTP/1.1
```
Lift a block against a domain.

View File

@ -16,14 +16,10 @@ aliases: [
#TableOfContents ul ul ul {display: none}
</style>
{{< hint style="danger" >}}
This page is under construction.
{{< /hint >}}
## List all blocked email domains {#get}
```http
GET https://mastodon.example/api/v1/admin/email_domain_blocks HTTP/1.1
GET /api/v1/admin/email_domain_blocks HTTP/1.1
```
Show information about all email domains blocked from signing up.
@ -43,8 +39,17 @@ Authorization
##### Query parameters
max_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
since_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 100.
: Integer. Maximum number of results to return. Defaults to 100 blocks. Max 200 blocks.
#### Response
@ -113,7 +118,7 @@ Authorized user is not allowed to perform this action, or invalid or missing Aut
## Get a single blocked email domain {#get-one}
```http
GET https://mastodon.example/api/v1/admin/email_domain_blocks/:id HTTP/1.1
GET /api/v1/admin/email_domain_blocks/:id HTTP/1.1
```
Show information about a single email domain that is blocked from signups.
@ -121,7 +126,7 @@ Show information about a single email domain that is blocked from signups.
**OAuth:** User token + `admin:read:email_domain_blocks`\
**Permissions:** Manage Blocks\
**Version history:**\
4.0.3 - added
4.1.0 - added
##### Path parameters
@ -206,7 +211,7 @@ EmailDomainBlock with the given ID does not exist
## Block an email domain from signups {#create}
```http
POST https://mastodon.example/api/v1/admin/email_domain_blocks HTTP/1.1
POST /api/v1/admin/email_domain_blocks HTTP/1.1
```
Add a domain to the list of email domains blocked from signups.
@ -312,7 +317,7 @@ Alternatively, the domain provided contains an invalid character
## Delete an email domain block {#delete}
```http
DELETE https://mastodon.example/api/v1/admin/email_domain_blocks/:id HTTP/1.1
DELETE /api/v1/admin/email_domain_blocks/:id HTTP/1.1
```
Lift a block against an email domain.

View File

@ -16,14 +16,10 @@ aliases: [
#TableOfContents ul ul ul {display: none}
</style>
{{< hint style="danger" >}}
This page is under construction.
{{< /hint >}}
## List all IP blocks {#get}
```http
GET https://mastodon.example/api/v1/admin/ip_blocks HTTP/1.1
GET /api/v1/admin/ip_blocks HTTP/1.1
```
Show information about all blocked IP ranges.
@ -43,8 +39,17 @@ Authorization
##### Query parameters
max_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
since_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 100.
: Integer. Maximum number of results to return. Defaults to 100 blocks. Max 200 blocks.
#### Response
@ -64,6 +69,12 @@ limit
]
```
Because IpBlock IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link: <http://mastodon.example/api/v1/admin/ip_blocks?limit=2&max_id=2>; rel="next", <http://mastodon.example/api/v1/admin/ip_blocks?limit=2&since_id=1>; rel="prev"
```
##### 403: Forbidden
Authorized user is not allowed to perform this action, or invalid or missing Authorization header
@ -79,7 +90,7 @@ Authorized user is not allowed to perform this action, or invalid or missing Aut
## Get a single IP block {#get-one}
```http
GET https://mastodon.example/api/v1/admin/ip_blocks/:id HTTP/1.1
GET /api/v1/admin/ip_blocks/:id HTTP/1.1
```
Show information about a single IP block.
@ -139,7 +150,7 @@ IpBlock with the given ID does not exist
## Block an IP address range from signing up {#create}
```http
POST https://mastodon.example/api/v1/admin/ip_blocks HTTP/1.1
POST /api/v1/admin/ip_blocks HTTP/1.1
```
Add an IP address range to the list of IP blocks.
@ -212,7 +223,7 @@ IP has already been blocked, and/or no severity was provided
## Update a domain block {#update}
```http
PUT https://mastodon.example/api/v1/admin/ip_blocks/:id HTTP/1.1
PUT /api/v1/admin/ip_blocks/:id HTTP/1.1
```
Change parameters for an existing IP block.
@ -280,7 +291,7 @@ Authorized user is not allowed to perform this action, or invalid or missing Aut
## Delete an IP block {#delete}
```http
DELETE https://mastodon.example/api/v1/admin/ip_blocks/:id HTTP/1.1
DELETE /api/v1/admin/ip_blocks/:id HTTP/1.1
```
Lift a block against an IP range.

View File

@ -19,7 +19,7 @@ aliases: [
## Get measurable data {#get}
```http
POST https://mastodon.example/api/v1/admin/measures HTTP/1.1
POST /api/v1/admin/measures HTTP/1.1
```
Obtain statistical measures for your server.

View File

@ -19,7 +19,7 @@ aliases: [
## View all reports {#get}
```http
GET https://mastodon.example/api/v1/admin/reports HTTP/1.1
GET /api/v1/admin/reports HTTP/1.1
```
View information about all reports.
@ -49,6 +49,18 @@ account_id
target_account_id
: String. Filter for reports targeting this account.
max_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
since_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 100 reports. Max 200 reports.
#### Response
##### 200: OK
@ -100,6 +112,12 @@ target_account_id
]
```
Because Report IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link: <http://mastodon.example/api/v1/admin/reports?limit=2&max_id=2>; rel="next", <http://mastodon.example/api/v1/admin/reports?limit=2&since_id=1>; rel="prev"
```
##### 403: Forbidden
Authorized user is not allowed to perform this action, or invalid or missing Authorization header
@ -115,7 +133,7 @@ Authorized user is not allowed to perform this action, or invalid or missing Aut
## View a single report {#get-one}
```http
GET https://mastodon.example/api/v1/admin/reports/:id HTTP/1.1
GET /api/v1/admin/reports/:id HTTP/1.1
```
**Returns:** [Admin::Report]({{< relref "entities/Admin_Report" >}})\
@ -213,7 +231,7 @@ Authorized user is not allowed to perform this action, or invalid or missing Aut
## Update a report {#update}
```http
PUT https://mastodon.example/api/v1/admin/reports/:id HTTP/1.1
PUT /api/v1/admin/reports/:id HTTP/1.1
```
Change metadata for a report.
@ -276,7 +294,7 @@ Authorized user is not allowed to perform this action, or invalid or missing Aut
## Assign report to self {#assign_to_self}
```http
POST https://mastodon.example/api/v1/admin/reports/:id/assign_to_self HTTP/1.1
POST /api/v1/admin/reports/:id/assign_to_self HTTP/1.1
```
Claim the handling of this report to yourself.
@ -351,7 +369,7 @@ Authorized user is not allowed to perform this action, or invalid or missing Aut
## Unassign report {#unassign}
```http
POST https://mastodon.example/api/v1/admin/reports/:id/unassign HTTP/1.1
POST /api/v1/admin/reports/:id/unassign HTTP/1.1
```
Unassign a report so that someone else can claim it.
@ -413,7 +431,7 @@ Authorized user is not allowed to perform this action, or invalid or missing Aut
## Mark report as resolved {#resolve}
```http
POST https://mastodon.example/api/v1/admin/reports/:id/resolve HTTP/1.1
POST /api/v1/admin/reports/:id/resolve HTTP/1.1
```
Mark a report as resolved with no further action taken.
@ -470,7 +488,7 @@ Authorized user is not allowed to perform this action, or invalid or missing Aut
## Reopen a closed report {#reopen}
```http
POST https://mastodon.example/api/v1/admin/reports/:id/reopen HTTP/1.1
POST /api/v1/admin/reports/:id/reopen HTTP/1.1
```
Reopen a currently closed report, if it is closed.

View File

@ -19,7 +19,7 @@ aliases: [
## Calculate retention data {#create}
```http
POST https://mastodon.example/api/v1/admin/retention HTTP/1.1
POST /api/v1/admin/retention HTTP/1.1
```
Generate a retention data report for a given time period and bucket.

View File

@ -16,17 +16,15 @@ aliases: [
#TableOfContents ul ul ul {display: none}
</style>
{{< hint style="danger" >}}
This page is under construction.
{{< /hint >}}
## View trending links {#links}
```http
GET https://mastodon.example/api/v1/admin/trends/links HTTP/1.1
GET /api/v1/admin/trends/links HTTP/1.1
```
**Returns:** [???]({{< relref "entities/???" >}})\
Links that have been shared more than others, including unapproved and unreviewed links.
**Returns:** Array of [Trends::Link]({{< relref "entities/PreviewCard#trends-link" >}})\
**OAuth:** User token + `admin:read`\
**Permissions:** Manage Taxonomies\
**Version history:**\
@ -42,8 +40,63 @@ Authorization
#### Response
##### 200: OK
<!-- TODO: -->
```json
[
{
"url": "https://twitter.com/arufa_faru/status/1594262272007753728",
"title": "ARuFa on Twitter",
"description": "“言葉をマネするぬいぐるみを改造してエレキギターを直接繋いでみました”",
"type": "link",
"author_name": "",
"author_url": "",
"provider_name": "Twitter",
"provider_url": "",
"html": "",
"width": 400,
"height": 225,
"image": "https://media.chitter.xyz/cache/preview_cards/images/002/162/720/original/b5360261e8ce17fc.jpeg",
"embed_url": "",
"blurhash": "UNFiDM~o-oD%x[xtaxM|xaNHRkjsoft7ofWB",
"history": [
{
"day": "1669507200",
"accounts": "9",
"uses": "9"
},
{
"day": "1669420800",
"accounts": "0",
"uses": "0"
},
{
"day": "1669334400",
"accounts": "0",
"uses": "0"
},
{
"day": "1669248000",
"accounts": "0",
"uses": "0"
},
{
"day": "1669161600",
"accounts": "0",
"uses": "0"
},
{
"day": "1669075200",
"accounts": "0",
"uses": "0"
},
{
"day": "1668988800",
"accounts": "0",
"uses": "0"
}
]
},
// ...
]
```
##### 403: Forbidden
@ -59,10 +112,12 @@ Authorized user is missing a permission, or invalid or missing Authorization hea
## View trending statuses {#statuses}
```http
GET https://mastodon.example/api/v1/admin/trends/statuses HTTP/1.1
GET /api/v1/admin/trends/statuses HTTP/1.1
```
**Returns:** [???]({{< relref "entities/???" >}})\
Statuses that have been interacted with more than others, including unapproved and unreviewed statuses.
**Returns:** Array of [Status]({{< relref "entities/Status" >}})\
**OAuth:** User token + `admin:read`\
**Permissions:** Manage Taxonomies\
**Version history:**\
@ -78,8 +133,27 @@ Authorization
#### Response
##### 200: OK
<!-- TODO: -->
```json
[
{
"id": "109415512969053017",
"created_at": "2022-11-27T11:23:52.000Z",
"in_reply_to_id": null,
"in_reply_to_account_id": null,
// ...
"account": {
"id": "109332240210946752",
// ...
},
"media_attachments": [],
"mentions": [],
"tags": [],
"emojis": [],
"card": null,
"poll": null
},
// ...
]
```
##### 403: Forbidden
@ -95,14 +169,18 @@ Authorized user is missing a permission, or invalid or missing Authorization hea
## View trending tags {#tags}
```http
GET https://mastodon.example/api/v1/admin/trends/tags HTTP/1.1
GET /api/v1/admin/trends/tags HTTP/1.1
```
**Returns:** [???]({{< relref "entities/???" >}})\
Tags that are being used more frequently within the past week, including unapproved and unreviewed tags.
**Returns:** Array of [Admin::Tag]({{< relref "entities/Tag#admin" >}})\
**OAuth:** User token + `admin:read`\
**Permissions:** Manage Taxonomies\
**Version history:**\
3.5.0 - added
3.5.0 - added\
4.0.0 - Returns an array of Tag due to a bug\
4.1.0 - Bug fixed <!-- TODO: https://github.com/mastodon/mastodon/pull/18943 -->
#### Request
@ -114,8 +192,54 @@ Authorization
#### Response
##### 200: OK
<!-- TODO: -->
```json
[
{
"name": "caturday",
"url": "https://mastodon.example/tags/caturday",
"history": [
{
"day": "1669507200",
"accounts": "53",
"uses": "56"
},
{
"day": "1669420800",
"accounts": "142",
"uses": "171"
},
{
"day": "1669334400",
"accounts": "11",
"uses": "11"
},
{
"day": "1669248000",
"accounts": "8",
"uses": "9"
},
{
"day": "1669161600",
"accounts": "8",
"uses": "20"
},
{
"day": "1669075200",
"accounts": "11",
"uses": "11"
},
{
"day": "1668988800",
"accounts": "17",
"uses": "22"
}
],
"id": "802",
"trendable": true,
"usable": true,
"requires_review": false
},
]
```
##### 403: Forbidden

View File

@ -21,7 +21,7 @@ aliases: [
## View all announcements {#get}
```http
GET https://mastodon.example/api/v1/announcements HTTP/1.1
GET /api/v1/announcements HTTP/1.1
```
See all currently active announcements set by admins.
@ -110,7 +110,7 @@ Invalid or missing Authorization header.
## Dismiss an announcement {#dismiss}
```http
POST https://mastodon.example/api/v1/announcements/:id/dismiss HTTP/1.1
POST /api/v1/announcements/:id/dismiss HTTP/1.1
```
Allows a user to mark the announcement as read.
@ -163,7 +163,7 @@ Announcement with given ID does not exist
## Add a reaction to an announcement {#put-reactions}
```http
PUT https://mastodon.example/api/v1/announcements/:id/reactions/:name HTTP/1.1
PUT /api/v1/announcements/:id/reactions/:name HTTP/1.1
```
React to an announcement with an emoji.
@ -228,7 +228,7 @@ Announcement with given ID does not exist
## Remove a reaction from an announcement {#delete-reactions}
```http
DELETE https://mastodon.example/api/v1/announcements/:id/reactions/:name HTTP/1.1
DELETE /api/v1/announcements/:id/reactions/:name HTTP/1.1
```
Undo a react emoji to an announcement.

View File

@ -20,7 +20,7 @@ aliases: [
## Create an application {#create}
```http
POST https://mastodon.example/api/v1/apps HTTP/1.1
POST /api/v1/apps HTTP/1.1
```
Create a new application to obtain OAuth2 credentials.
@ -78,7 +78,7 @@ If a required parameter is missing or improperly formatted, the request will fai
## Verify your app works {#verify_credentials}
```http
GET https://mastodon.example/api/v1/apps/verify_credentials HTTP/1.1
GET /api/v1/apps/verify_credentials HTTP/1.1
```
Confirm that the app's OAuth2 credentials work.

View File

@ -21,7 +21,7 @@ aliases: [
## View blocked users {#get}
```http
GET https://mastodon.example/api/v1/blocks HTTP/1.1
GET /api/v1/blocks HTTP/1.1
```
**Returns:** Array of [Account]({{< relref "entities/account" >}})\
@ -49,7 +49,7 @@ min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 40.
: Integer. Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.
#### Response
##### 200: OK
@ -78,7 +78,7 @@ Sample call with limit=2.
Because Block IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link: <https://mastodon.social/api/v1/blocks?limit=2&max_id=441449>; rel="next", <https://mastodon.social/api/v1/blocks?limit=2&since_id=444808>; rel="prev"
Link: <https://mastodon.example/api/v1/blocks?limit=2&max_id=441449>; rel="next", <https://mastodon.example/api/v1/blocks?limit=2&since_id=444808>; rel="prev"
```
##### 401: Unauthorized

View File

@ -21,7 +21,7 @@ aliases: [
## View bookmarked statuses {#get}
```http
GET https://mastodon.example/api/v1/bookmarks HTTP/1.1
GET /api/v1/bookmarks HTTP/1.1
```
Statuses the user has bookmarked.
@ -50,7 +50,7 @@ min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 40.
: Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.
#### Response
##### 200: OK
@ -84,7 +84,7 @@ limit
Because Bookmark IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link: <https://mastodon.social/api/v1/bookmarks?max_id=23771>; rel="next", <https://mastodon.social/api/v1/bookmarks?min_id=370065>; rel="prev"
Link: <https://mastodon.example/api/v1/bookmarks?max_id=23771>; rel="next", <https://mastodon.example/api/v1/bookmarks?min_id=370065>; rel="prev"
```
##### 401: Unauthorized

View File

@ -23,7 +23,7 @@ aliases: [
## View all conversations {#get}
```http
GET https://mastodon.example/api/v1/conversations HTTP/1.1
GET /api/v1/conversations HTTP/1.1
```
**Returns:** Array of [Conversation]({{< relref "entities/conversation" >}})\
@ -51,7 +51,7 @@ min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 20. Max 40.
: Integer. Maximum number of results to return. Defaults to 20 conversations. Max 40 conversations.
#### Response
@ -105,7 +105,7 @@ Truncated sample results of an API call with limit=2
Because AccountConversation IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link: <https://mastodon.social/api/v1/conversations?limit=2&max_id=108835003356700379>; rel="next", <https://mastodon.social/api/v1/conversations?limit=2&min_id=108888782724768580>; rel="prev"
Link: <https://mastodon.example/api/v1/conversations?limit=2&max_id=108835003356700379>; rel="next", <https://mastodon.example/api/v1/conversations?limit=2&min_id=108888782724768580>; rel="prev"
```
##### 401: Unauthorized
@ -123,7 +123,7 @@ Invalid or missing Authorization header.
## Remove a conversation {#delete}
```http
DELETE https://mastodon.example/api/v1/conversations/:id HTTP/1.1
DELETE /api/v1/conversations/:id HTTP/1.1
```
Removes a conversation from your list of conversations.
@ -177,7 +177,7 @@ The conversation does not exist, or is not owned by you.
## Mark a conversation as read {#read}
```http
POST https://mastodon.example/api/v1/conversations/:id/read HTTP/1.1
POST /api/v1/conversations/:id/read HTTP/1.1
```
**Returns:** [Conversation]({{< relref "entities/conversation" >}})\

View File

@ -23,7 +23,7 @@ aliases: [
## View all custom emoji {#get}
```http
GET https://mastodon.example/api/v1/custom_emojis HTTP/1.1
GET /api/v1/custom_emojis HTTP/1.1
```
Returns custom emojis that are available on the server.

View File

@ -21,7 +21,7 @@ aliases: [
## View profile directory {#get}
```http
GET https://mastodon.example/api/v1/directory HTTP/1.1
GET /api/v1/directory HTTP/1.1
```
List accounts visible in the directory.
@ -36,10 +36,10 @@ List accounts visible in the directory.
##### Query parameters
offset
: Number. How many accounts to skip before returning results. Default 0.
: Number. Skip the first n results.
limit
: Number. How many accounts to load. Default 40.
: Number. How many accounts to load. Defaults to 40 accounts. Max 80 accounts.
order
: String. Use `active` to sort by most recently posted statuses (default) or `new` to sort by most recently created profiles.

View File

@ -20,7 +20,7 @@ aliases: [
## Get domain blocks {#get}
```http
GET https://mastodon.example/api/v1/domain_blocks HTTP/1.1
GET /api/v1/domain_blocks HTTP/1.1
```
View domains the user has blocked.
@ -49,7 +49,7 @@ min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 40.
: Integer. Maximum number of results to return. Defaults to 100 domain blocks. Max 200 domain blocks.
#### Response
##### 200: OK
@ -63,7 +63,7 @@ Sample call with limit=2.
Because AccountDomainBlock IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link: <https://mastodon.social/api/v1/domain_blocks?limit=2&max_id=16194>; rel="next", <https://mastodon.social/api/v1/domain_blocks?limit=2&since_id=16337>; rel="prev"
Link: <https://mastodon.example/api/v1/domain_blocks?limit=2&max_id=16194>; rel="next", <https://mastodon.example/api/v1/domain_blocks?limit=2&since_id=16337>; rel="prev"
```
##### 401: Unauthorized
@ -81,7 +81,7 @@ Invalid or missing Authorization header.
## Block a domain {#block}
```http
POST https://mastodon.example/api/v1/domain_blocks HTTP/1.1
POST /api/v1/domain_blocks HTTP/1.1
```
Block a domain to:
@ -149,7 +149,7 @@ If `domain` contains spaces, the request will fail.
## Unblock a domain {#unblock}
```http
DELETE https://mastodon.example/api/v1/domain_blocks HTTP/1.1
DELETE /api/v1/domain_blocks HTTP/1.1
```
Remove a domain block, if it exists in the user's array of blocked domains.

View File

@ -21,7 +21,7 @@ aliases: [
## Resend confirmation email {#confirmation}
```http
POST https://mastodon.example/api/v1/emails/confirmation HTTP/1.1
POST /api/v1/emails/confirmation HTTP/1.1
```
**Returns:** Empty object\
@ -48,6 +48,7 @@ email
```
##### 403: Forbidden
The client associated with the token does not own the unconfirmed user.
```json
@ -56,6 +57,14 @@ The client associated with the token does not own the unconfirmed user.
}
```
Alternatively, the user has already confirmed their email.
```json
{
"error": "This method is only available while the e-mail is awaiting confirmation"
}
```
---
## See also

View File

@ -21,7 +21,7 @@ aliases: [
## View currently featured profiles {#get}
```http
GET https://mastodon.example/api/v1/endorsements HTTP/1.1
GET /api/v1/endorsements HTTP/1.1
```
Accounts that the user is currently featuring on their profile.
@ -47,11 +47,8 @@ max_id
since_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 40.
: Integer. Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.
#### Response
##### 200: OK
@ -115,7 +112,7 @@ Sample call with limit=2.
Because AccountPin IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link: <https://mastodon.social/api/v1/endorsements?limit=2&max_id=832844>; rel="next", <https://mastodon.social/api/v1/endorsements?limit=2&since_id=952529>; rel="prev"
Link: <https://mastodon.example/api/v1/endorsements?limit=2&max_id=832844>; rel="next", <https://mastodon.example/api/v1/endorsements?limit=2&since_id=952529>; rel="prev"
```
##### 401: Unauthorized

View File

@ -21,7 +21,7 @@ aliases: [
## View favourited statuses {#get}
```http
GET https://mastodon.example/api/v1/favourites HTTP/1.1
GET /api/v1/favourites HTTP/1.1
```
Statuses the user has favourited.
@ -51,7 +51,7 @@ min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 40.
: Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.
#### Response
##### 200: OK
@ -117,7 +117,7 @@ An example call with limit=2.
Because Favourite IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link: <https://mastodon.social/api/v1/favourites?limit=2&max_id=23716836>; rel="next", <https://mastodon.social/api/v1/favourites?limit=2&min_id=23716978>; rel="prev"
Link: <https://mastodon.example/api/v1/favourites?limit=2&max_id=23716836>; rel="next", <https://mastodon.example/api/v1/favourites?limit=2&min_id=23716978>; rel="prev"
```
##### 401: Unauthorized

View File

@ -21,7 +21,7 @@ aliases: [
## View your featured tags {#get}
```http
GET https://mastodon.example/api/v1/featured_tags HTTP/1.1
GET /api/v1/featured_tags HTTP/1.1
```
List all hashtags featured on your profile.
@ -67,7 +67,7 @@ Invalid or missing Authorization header.
## Feature a tag {#feature}
```http
POST https://mastodon.example/api/v1/featured_tags HTTP/1.1
POST /api/v1/featured_tags HTTP/1.1
```
Promote a hashtag on your profile.
@ -128,7 +128,7 @@ If `name` is not a valid hashtag, e.g. contains illegal characters or only numbe
## Unfeature a tag {unfeature}
```http
DELETE https://mastodon.example/api/v1/featured_tags/:id HTTP/1.1
DELETE /api/v1/featured_tags/:id HTTP/1.1
```
Stop promoting a hashtag on your profile.
@ -184,7 +184,7 @@ FeaturedTag is not owned by you or does not exist
## View suggested tags to feature {#suggestions}
```http
GET https://mastodon.example/api/v1/featured_tags/suggestions HTTP/1.1
GET /api/v1/featured_tags/suggestions HTTP/1.1
```
Shows up to 10 recently-used tags.

File diff suppressed because it is too large Load Diff

View File

@ -21,7 +21,7 @@ aliases: [
## View pending follow requests {#get}
```http
GET https://mastodon.example/api/v1/follow_requests HTTP/1.1
GET /api/v1/follow_requests HTTP/1.1
```
**Returns:** Array of [Account]({{< relref "entities/account" >}})\
@ -45,11 +45,8 @@ max_id
since_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 40. Paginate using the HTTP Link header.
: Integer. Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.
#### Response
##### 200: OK
@ -78,7 +75,7 @@ Sample call for Accounts that are requesting a follow, with limit=2
Because FollowRequest IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link: <https://mastodon.social/api/v1/follow_requests?limit=2&max_id=7163058>; rel="next", <https://mastodon.social/api/v1/follow_requests?limit=2&since_id=7275607>; rel="prev"
Link: <https://mastodon.example/api/v1/follow_requests?limit=2&max_id=7163058>; rel="next", <https://mastodon.example/api/v1/follow_requests?limit=2&since_id=7275607>; rel="prev"
```
##### 401: Unauthorized
@ -96,7 +93,7 @@ Invalid or missing Authorization header.
## Accept follow request {#accept}
```http
POST https://mastodon.example/api/v1/follow_requests/:account_id/authorize HTTP/1.1
POST /api/v1/follow_requests/:account_id/authorize HTTP/1.1
```
**Returns:** [Relationship]({{< relref "entities/relationship" >}})\
@ -163,7 +160,7 @@ No pending follow request from that account ID
## Reject follow request {#reject}
```http
POST https://mastodon.example/api/v1/follow_requests/:account_id/reject HTTP/1.1
POST /api/v1/follow_requests/:account_id/reject HTTP/1.1
```
**Returns:** [Relationship]({{< relref "entities/relationship" >}})\

View File

@ -13,17 +13,21 @@ aliases: [
]
---
<style>
#TableOfContents ul ul ul {display: none}
</style>
## View all followed tags {#get}
```http
GET https://mastodon.example/api/v1/followed_tags HTTP/1.1
GET /api/v1/followed_tags HTTP/1.1
```
**Returns:** Array of [Tag]({{< relref "entities/Tag" >}})\
**OAuth:** User token + `read:follows`\
**Version history:**\
4.0.0 - added\
4.0.3 - add pagination headers
4.1.0 - add pagination headers
#### Request
@ -44,7 +48,7 @@ min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 100.
: Integer. Maximum number of results to return. Defaults to 100 tags. Max 200 tags.
#### Response
##### 200: OK

View File

@ -20,7 +20,7 @@ aliases: [
## View server information {#v2}
```http
GET https://mastodon.example/api/v2/instance
GET /api/v2/instance
```
Obtain general information about the server.
@ -188,7 +188,7 @@ Obtain general information about the server.
## List of connected domains {#peers}
```http
GET https://mastodon.example/api/v1/instance/peers HTTP/1.1
GET /api/v1/instance/peers HTTP/1.1
```
Domains that this instance is aware of.
@ -229,7 +229,7 @@ If the instance is in whitelist mode and the Authorization header is missing or
## Weekly activity {#activity}
```http
GET https://mastodon.example/api/v1/instance/activity HTTP/1.1
GET /api/v1/instance/activity HTTP/1.1
```
Instance activity over the last 3 months, binned weekly.
@ -357,7 +357,7 @@ If the instance is in whitelist mode and the Authorization header is missing or
```http
GET https://mastodon.example/api/v1/instance/rules HTTP/1.1
GET /api/v1/instance/rules HTTP/1.1
```
Rules that the users of this service should follow.
@ -404,7 +404,7 @@ Rules that the users of this service should follow.
## View moderated servers {#domain_blocks}
```http
GET https://mastodon.example/api/v1/instance/domain_block HTTP/1.1
GET /api/v1/instance/domain_blocks HTTP/1.1
```
Obtain a list of domains that have been blocked.
@ -466,7 +466,7 @@ The admin has chosen to show domain blocks to no one. The response body is empty
## View extended description {#extended_description}
```http
GET https://mastodon.example/api/v1/example HTTP/1.1
GET /api/v1/example HTTP/1.1
```
Obtain an extended description of this server
@ -491,7 +491,7 @@ Obtain an extended description of this server
## (DEPRECATED) View server information (V1) {#v1}
```http
GET https://mastodon.example/api/v1/instance HTTP/1.1
GET /api/v1/instance HTTP/1.1
```
Obtain general information about the server.

View File

@ -23,7 +23,7 @@ aliases: [
## View your lists {#get}
```http
GET https://mastodon.example/api/v1/lists HTTP/1.1
GET /api/v1/lists HTTP/1.1
```
Fetch all lists that the user owns.
@ -75,7 +75,7 @@ Invalid or missing Authorization header.
## Show a single list {#get-one}
```http
GET https://mastodon.example/api/v1/lists/:id HTTP/1.1
GET /api/v1/lists/:id HTTP/1.1
```
Fetch the list with the given ID. Used for verifying the title of a list, and which replies to show within that list.
@ -135,7 +135,7 @@ List does not exist or is not owned by you
## Create a list {#create}
```http
POST https://mastodon.example/api/v1/lists HTTP/1.1
POST /api/v1/lists HTTP/1.1
```
Create a new list.
@ -207,7 +207,7 @@ If the replies_policy is not understood:
## Update a list {#update}
```http
PUT https://mastodon.example/api/v1/lists/:id HTTP/1.1
PUT /api/v1/lists/:id HTTP/1.1
```
Change the title of a list, or which replies to show.
@ -284,7 +284,7 @@ If the `replies_policy` is not understood:
## Delete a list {#delete}
```http
DELETE https://mastodon.example/api/v1/lists/:id HTTP/1.1
DELETE /api/v1/lists/:id HTTP/1.1
```
**Returns:** empty object\
@ -339,7 +339,7 @@ List does not exist or is not owned by you
## View accounts in a list {#accounts}
```http
GET https://mastodon.example/api/v1/lists/:id/accounts HTTP/1.1
GET /api/v1/lists/:id/accounts HTTP/1.1
```
**Returns:** Array of [Account]({{< relref "entities/account" >}})\
@ -372,7 +372,7 @@ min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results. Defaults to 40. Max 40. Set to 0 in order to get all accounts without pagination.
: Integer. Maximum number of results. Defaults to 40 accounts. Max 80 accounts. Set to 0 in order to get all accounts without pagination.
#### Response
##### 200: OK
@ -415,7 +415,7 @@ limit
Because you do not know beforehand which Accounts are included in a List, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link: <https://mastodon.social/api/v1/lists/12249/accounts?max_id=106931203247163945>; rel="next", <https://mastodon.social/api/v1/lists/12249/accounts?since_id=108632085572655915>; rel="prev"
Link: <https://mastodon.example/api/v1/lists/12249/accounts?max_id=106931203247163945>; rel="next", <https://mastodon.example/api/v1/lists/12249/accounts?since_id=108632085572655915>; rel="prev"
```
##### 401: Unauthorized
@ -444,7 +444,7 @@ List does not exist or is not owned by you.
## Add accounts to a list {#accounts-add}
```http
POST https://mastodon.example/api/v1/lists/:id/accounts HTTP/1.1
POST /api/v1/lists/:id/accounts HTTP/1.1
```
Add accounts to the given list. Note that the user must be following these accounts.
@ -513,7 +513,7 @@ An Account with one of the provided IDs is already in the list
## Remove accounts from list {#accounts-remove}
```http
DELETE https://mastodon.example/api/v1/lists/:id/accounts HTTP/1.1
DELETE /api/v1/lists/:id/accounts HTTP/1.1
```
Remove accounts from the given list.

View File

@ -21,7 +21,7 @@ aliases: [
## Get saved timeline positions {#get}
```http
GET https://mastodon.example/api/v1/markers HTTP/1.1
GET /api/v1/markers HTTP/1.1
```
**Returns:** Hash of timeline key and associated [Marker]({{< relref "entities/Marker" >}})\
@ -39,7 +39,7 @@ Authorization
##### Query parameters
timeline[]
: {{<required>}} Array of String. Specify the timeline(s) for which markers should be fetched. Possible values: `home`, `notifications`. If not provided, an empty object will be returned.
: Array of String. Specify the timeline(s) for which markers should be fetched. Possible values: `home`, `notifications`. If not provided, an empty object will be returned.
#### Response
##### 200: OK
@ -76,7 +76,7 @@ Invalid or missing Authorization header.
## Save your position in a timeline {#create}
```http
POST https://mastodon.example/api/v1/markers HTTP/1.1
POST /api/v1/markers HTTP/1.1
```
**Returns:** [Marker]({{< relref "entities/marker" >}})\

View File

@ -23,7 +23,7 @@ aliases: [
## Upload media as an attachment (async) {#v2}
```http
POST https://mastodon.example/api/v2/media HTTP/1.1
POST /api/v2/media HTTP/1.1
```
Creates a media attachment to be used with a new status. The full sized media will be processed asynchronously in the background for large uploads.
@ -162,7 +162,7 @@ Could not generate a thumbnail for the attachment
## Get media attachment {#get}
```http
GET https://mastodon.example/api/v1/media/:id HTTP/1.1
GET /api/v1/media/:id HTTP/1.1
```
Get a media attachment, before it is attached to a status and posted, but after it is accepted for processing. Use this method to check that the full-sized media has finished processing.
@ -264,7 +264,7 @@ There was an error processing the media attachment
## Update media attachment {#update}
```http
PUT https://mastodon.example/api/v1/media/:id HTTP/1.1
PUT /api/v1/media/:id HTTP/1.1
```
Update a MediaAttachment's parameters, before it is attached to a status and posted.
@ -369,7 +369,7 @@ Attachment is not owned by you or does not exist
## (DEPRECATED) Upload media as an attachment {#v1}
```http
POST https://mastodon.example/api/v1/media HTTP/1.1
POST /api/v1/media HTTP/1.1
```
Creates an attachment to be used with a new status. This method will return after the full sized media is done processing.

View File

@ -21,7 +21,7 @@ aliases: [
## View muted accounts {#get}
```http
GET https://mastodon.example/api/v1/mutes HTTP/1.1
GET /api/v1/mutes HTTP/1.1
```
Accounts the user has muted.
@ -46,11 +46,8 @@ max_id
since_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 40.
: Integer. Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.
#### Response
##### 200: OK
@ -79,7 +76,7 @@ Sample response with limit=2.
Because Mute IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link: <https://mastodon.social/api/v1/mutes?limit=2&max_id=317646>; rel="next", <https://mastodon.social/api/v1/mutes?limit=2&since_id=317647>; rel="prev"
Link: <https://mastodon.example/api/v1/mutes?limit=2&max_id=317646>; rel="next", <https://mastodon.example/api/v1/mutes?limit=2&since_id=317647>; rel="prev"
```
##### 401: Unauthorized

View File

@ -20,7 +20,7 @@ aliases: [
## Get all notifications {#get}
```http
GET https://mastodon.example/api/v1/notifications HTTP/1.1
GET /api/v1/notifications HTTP/1.1
```
Notifications concerning the user. This API returns Link headers containing links to the next/previous page. However, the links can also be constructed dynamically using query params and `id` values.
@ -33,7 +33,7 @@ Types to filter include:
- `follow_request` = Someone requested to follow you
- `favourite` = Someone favourited one of your statuses
- `poll` = A poll you have voted in or created has ended
- `update` = A status you interacted with has been edited
- `update` = A status you boosted with has been edited
- `admin.sign_up` = Someone signed up (optionally sent to admins)
- `admin.report` = A new report has been filed
@ -67,7 +67,7 @@ min_id
: String. Return results immediately newer than this ID
limit
: Integer. Maximum number of results to return. Default: 20.
: Integer. Maximum number of results to return. Defaults to 15 notifications. Max 30 notifications.
types[]
: Array of String. Types to include in the result.
@ -92,7 +92,7 @@ Authorization: Bearer xxx
The response body contains one page of notifications. You can use the HTTP Link header for further pagination.
```http
Link: <https://mastodon.social/api/v1/notifications?max_id=34975535>; rel="next", <https://mastodon.social/api/v1/notifications?min_id=34975861>;
Link: <https://mastodon.example/api/v1/notifications?max_id=34975535>; rel="next", <https://mastodon.example/api/v1/notifications?min_id=34975861>;
```
```json
@ -175,7 +175,7 @@ Invalid or missing Authorization header.
## Get a single notification {#get-one}
```http
GET https://mastodon.example/api/v1/notification/:id HTTP/1.1
GET /api/v1/notification/:id HTTP/1.1
```
View information about a notification with a given ID.
@ -257,7 +257,7 @@ Invalid or missing Authorization header.
## Dismiss all notifications {#clear}
```http
POST https://mastodon.example/api/v1/notifications/clear HTTP/1.1
POST /api/v1/notifications/clear HTTP/1.1
```
Clear all notifications from the server.
@ -298,7 +298,7 @@ Invalid or missing Authorization header.
## Dismiss a single notification {#dismiss}
```http
POST https://mastodon.example/api/v1/notifications/:id/dismiss HTTP/1.1
POST /api/v1/notifications/:id/dismiss HTTP/1.1
```
Dismiss a single notification from the server.
@ -345,7 +345,7 @@ Invalid or missing Authorization header.
## (REMOVED) Dismiss a single notification {#dismiss-deprecated}
```http
POST https://mastodon.example/api/v1/notifications/dismiss HTTP/1.1
POST /api/v1/notifications/dismiss HTTP/1.1
```
Dismiss a single notification from the server.

View File

@ -21,7 +21,7 @@ aliases: [
## Authorize a user {#authorize}
```http
GET https://mastodon.example/oauth/authorize HTTP/1.1
GET /oauth/authorize HTTP/1.1
```
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. The authorization code can be used while requesting a token to obtain access to user-level methods.
@ -79,7 +79,7 @@ If the authorization code is incorrect or has been used already, the request wil
## Obtain a token {#token}
```http
POST https://mastodon.example/oauth/token HTTP/1.1
POST /oauth/token HTTP/1.1
```
Obtain an access token, to be used during API calls that are not public.
@ -101,6 +101,9 @@ code
client_id
: {{<required>}} String. The client ID, obtained during app registration.
client_secret
: {{<required>}} String. The client secret, obtained durign app registration.
redirect_uri
: {{<required>}} String. Set a URI to redirect the user to. If this parameter is set to urn:ietf:wg:oauth:2.0:oob then the token will be shown instead. Must match one of the `redirect_uris` declared during app registration.
@ -148,7 +151,7 @@ If client_id and client_secret do not match or are invalid, the request will fai
## Revoke a token {#revoke}
```http
POST https://mastodon.example/oauth/revoke HTTP/1.1
POST /oauth/revoke HTTP/1.1
```
Revoke an access token to make it no longer valid for use.
@ -165,7 +168,7 @@ client_id
: {{<required>}} String. The client ID, obtained during app registration.
client_secret
: {{<required>}} String. The client secret, obtained durign app registration.
: {{<required>}} String. The client secret, obtained during app registration.
token
: {{<required>}} String. The previously obtained token, to be invalidated.

View File

@ -20,7 +20,7 @@ aliases: [
## Get OEmbed info as JSON {#get}
```http
GET https://mastodon.example/api/oembed HTTP/1.1
GET /api/oembed HTTP/1.1
```
**Returns:** OEmbed metadata\

View File

@ -23,7 +23,7 @@ aliases: [
## View a poll {#get}
```http
GET https://mastodon.example/api/v1/polls/:id HTTP/1.1
GET /api/v1/polls/:id HTTP/1.1
```
**Returns:** [Poll]({{< relref "entities/poll" >}})\
@ -87,7 +87,7 @@ Poll does not exist, or poll's parent status is private
## Vote on a poll {#vote}
```http
POST https://mastodon.example/api/v1/polls/:id/votes HTTP/1.1
POST /api/v1/polls/:id/votes HTTP/1.1
```
**Returns:** [Poll]({{< relref "entities/poll" >}})\

View File

@ -21,7 +21,7 @@ aliases: [
## View user preferences {#get}
```http
GET https://mastodon.example/api/v1/preferences HTTP/1.1
GET /api/v1/preferences HTTP/1.1
```
Preferences defined by the user in their account settings.

View File

@ -26,7 +26,7 @@ Identity proofs have been deprecated in 3.5.0 and newer. Previously, the only pr
## (REMOVED) View identity proofs {#get}
```http
GET https://mastodon.example/api/proofs HTTP/1.1
GET /api/proofs HTTP/1.1
```
**Returns:** custom response defined by provider\

View File

@ -33,7 +33,7 @@ Mastodon natively supports the [Web Push API](https://developer.mozilla.org/en-U
## Subscribe to push notifications {#create}
```http
POST https://mastodon.example/api/v1/push/subscription HTTP/1.1
POST /api/v1/push/subscription HTTP/1.1
```
Add a Web Push API subscription to receive notifications. Each access token can have one push subscription. If you create a new subscription, the old subscription is deleted.
@ -65,24 +65,27 @@ subscription[keys][p256dh]
subscription[keys][auth]
: {{<required>}} String. Auth secret. Base64 encoded string of 16 bytes of random data.
data[alerts][follow]
: Boolean. Receive follow notifications? Defaults to false.
data[alerts][mention]
: Boolean. Receive mention notifications? Defaults to false.
data[alerts][favourite]
: Boolean. Receive favourite notifications? Defaults to false.
data[alerts][status]
: Boolean. Receive new subscribed account notifications? Defaults to false.
data[alerts][reblog]
: Boolean. Receive reblog notifications? Defaults to false.
data[alerts][mention]
: Boolean. Receive mention notifications? Defaults to false.
data[alerts][follow]
: Boolean. Receive follow notifications? Defaults to false.
data[alerts][follow_request]
: Boolean. Receive follow request notifications? Defaults to false.
data[alerts][favourite]
: Boolean. Receive favourite notifications? Defaults to false.
data[alerts][poll]
: Boolean. Receive poll notifications? Defaults to false.
data[alerts][status]
: Boolean. Receive new subscribed account notifications? Defaults to false.
data[alerts][update]
: Boolean. Receive status edited notifications? Defaults to false.
@ -130,7 +133,7 @@ Invalid or missing Authorization header.
## Get current subscription {#get}
```http
GET https://mastodon.example/api/v1/push/subscription HTTP/1.1
GET /api/v1/push/subscription HTTP/1.1
```
View the PushSubscription currently associated with this access token.
@ -189,7 +192,7 @@ A PushSubscription does not exist for this token.
## Change types of notifications {#update}
```http
PUT https://mastodon.example/api/v1/push/subscription HTTP/1.1
PUT /api/v1/push/subscription HTTP/1.1
```
Updates the current push subscription. Only the data part can be updated. To change fundamentals, a new subscription must be created instead.
@ -212,24 +215,27 @@ Authorization
##### Form data parameters
data[alerts][follow]
: Boolean. Receive follow notifications? Defaults to false.
data[alerts][mention]
: Boolean. Receive mention notifications? Defaults to false.
data[alerts][favourite]
: Boolean. Receive favourite notifications? Defaults to false.
data[alerts][status]
: Boolean. Receive new subscribed account notifications? Defaults to false.
data[alerts][reblog]
: Boolean. Receive reblog notifications? Defaults to false.
data[alerts][mention]
: Boolean. Receive mention notifications? Defaults to false.
data[alerts][follow]
: Boolean. Receive follow notifications? Defaults to false.
data[alerts][follow_request]
: Boolean. Receive follow request notifications? Defaults to false.
data[alerts][favourite]
: Boolean. Receive favourite notifications? Defaults to false.
data[alerts][poll]
: Boolean. Receive poll notifications? Defaults to false.
data[alerts][status]
: Boolean. Receive new subscribed account notifications? Defaults to false.
data[alerts][update]
: Boolean. Receive status edited notifications? Defaults to false.
@ -287,7 +293,7 @@ No existing PushSubscription for this token
## Remove current subscription {#delete}
```http
DELETE https://mastodon.example/api/v1/push/subscription HTTP/1.1
DELETE /api/v1/push/subscription HTTP/1.1
```
Removes the current Web Push API subscription.

View File

@ -21,7 +21,7 @@ aliases: [
## File a report {#post}
```http
POST https://mastodon.example/api/v1/reports HTTP/1.1
POST /api/v1/reports HTTP/1.1
```
**Returns:** [Report]({{< relref "entities/report" >}})\

View File

@ -21,7 +21,7 @@ aliases: [
## View scheduled statuses {#get}
```http
GET https://mastodon.example/api/v1/scheduled_statuses HTTP/1.1
GET /api/v1/scheduled_statuses HTTP/1.1
```
**Returns:** Array of [ScheduledStatus]({{< relref "entities/scheduledstatus" >}})\
@ -49,7 +49,7 @@ min_id
: String. Return results immediately newer than ID.
limit
: Integer. Maximum number of results to return. Defaults to 20. Max 40.
: Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.
#### Response
##### 200: OK
@ -91,7 +91,7 @@ Invalid or missing Authorization header.
## View a single scheduled status {#get-one}
```http
GET https://mastodon.example/api/v1/scheduled_statuses/:id HTTP/1.1
GET /api/v1/scheduled_statuses/:id HTTP/1.1
```
**Returns:** [ScheduledStatus]({{< relref "entities/scheduledstatus" >}})\
@ -159,7 +159,7 @@ ScheduledStatus is not owned by you or does not exist
## Update a scheduled status's publishing date {#update}
```http
PUT https://mastodon.example/api/v1/scheduled_statuses/:id HTTP/1.1
PUT /api/v1/scheduled_statuses/:id HTTP/1.1
```
**Returns:** [ScheduledStatus]({{< relref "entities/scheduledstatus" >}})\
@ -240,7 +240,7 @@ ScheduledStatus is not owned by you or does not exist
## Cancel a scheduled status {#cancel}
```http
DELETE https://mastodon.example/api/v1/scheduled_statuses/:id HTTP/1.1
DELETE /api/v1/scheduled_statuses/:id HTTP/1.1
```
**Returns:** empty object\

View File

@ -20,7 +20,7 @@ aliases: [
## Perform a search {#v2}
```http
GET https://mastodon.example/api/v2/search HTTP/1.1
GET /api/v2/search HTTP/1.1
```
**Returns:** [Search]({{< relref "entities/Search" >}})\
@ -66,10 +66,10 @@ min_id
: String. Return results immediately newer than this ID.
limit
: Integer. Maximum number of results to return, per type. Defaults to 20. Max 40.
: Integer. Maximum number of results to return, per type. Defaults to 20 results per category. Max 40 results per category.
offset
: Integer. Offset in search results, used for pagination. Defaults to 0.
: Integer. Skip the first n results.
#### Response
##### 200: OK
@ -155,7 +155,7 @@ Invalid or missing Authorization header.
## (REMOVED) Search results (v1) {#v1}
```http
GET https://mastodon.example/api/v1/search HTTP/1.1
GET /api/v1/search HTTP/1.1
```
**Returns:** [Search]({{< relref "entities/Search" >}}), but `hashtags` is an array of strings instead of an array of Tag.\
@ -195,7 +195,7 @@ min_id
: String. Return results immediately newer than this ID.
limit
: Integer. Maximum number of results to return, per type. Defaults to 20. Max 40.
: Integer. Maximum number of results to return, per type. Defaults to 20 results per category. Max 40 results per category.
offset
: Integer. Offset in search results, used for pagination. Defaults to 0.

View File

@ -17,13 +17,13 @@ aliases: [
#TableOfContents ul ul ul {display: none}
</style>
## Publish new status {#create}
## Post a new status {#create}
```http
POST https://mastodon.example/api/v1/statuses HTTP/1.1
POST /api/v1/statuses HTTP/1.1
```
Post a new status.
Publish a status with the given parameters.
**Returns:** [Status]({{<relref "entities/status">}}). When `scheduled_at` is present, [ScheduledStatus]({{<relref "entities/scheduledstatus">}}) is returned instead.\
**OAuth:** User + `write:statuses`\
@ -78,7 +78,7 @@ language
: String. ISO 639 language code for this status.
scheduled_at
: String. ISO 8601 Datetime at which to schedule a status. Providing this paramter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future.
: String. ISO 8601 Datetime at which to schedule a status. Providing this parameter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future.
#### Response
##### 200: OK
@ -145,7 +145,7 @@ Invalid or missing Authorization header.
## View a single status {#get}
```http
GET https://mastodon.example/api/v1/statuses/:id HTTP/1.1
GET /api/v1/statuses/:id HTTP/1.1
```
Obtain information about a status.
@ -259,7 +259,7 @@ Status does not exist or is private.
## Delete a status {#delete}
```http
DELETE https://mastodon.example/api/v1/statuses/:id HTTP/1.1
DELETE /api/v1/statuses/:id HTTP/1.1
```
Delete one of your own statuses.
@ -449,7 +449,7 @@ Status is not owned by you or does not exist
## Get parent and child statuses in context {#context}
```http
GET https://mastodon.example/api/v1/statuses/:id/context HTTP/1.1
GET /api/v1/statuses/:id/context HTTP/1.1
```
View statuses above and below this status in the thread.
@ -526,7 +526,7 @@ Status is private or does not exist
## See who boosted a status {#reblogged_by}
```http
GET https://mastodon.example/api/v1/statuses/:id/reblogged_by HTTP/1.1
GET /api/v1/statuses/:id/reblogged_by HTTP/1.1
```
View who boosted a given status.
@ -548,6 +548,20 @@ View who boosted a given status.
Authorization
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
##### Query parameters
max_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
since_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.
#### Response
##### 200: OK
@ -565,6 +579,12 @@ A list of statuses that boosted the status
]
```
Because reblogged Status IDs are generally not known ahead of time, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link: <https://mastodon.example/api/v1/statuses/109404970108594430/reblogged_by?limit=2&max_id=109406336446186031>; rel="next", <https://mastodon.example/api/v1/statuses/109404970108594430/reblogged_by?limit=2&since_id=109408462939099398>; rel="prev"
```
##### 404: Not found
Status does not exist or is private
@ -580,7 +600,7 @@ Status does not exist or is private
## See who favourited a status {#favourited_by}
```http
GET https://mastodon.example/api/v1/statuses/:id/favourited_by HTTP/1.1
GET /api/v1/statuses/:id/favourited_by HTTP/1.1
```
View who favourited a given status.
@ -602,6 +622,20 @@ View who favourited a given status.
Authorization
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
##### Query parameters
max_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
since_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
min_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.
#### Response
##### 200: OK
@ -619,6 +653,12 @@ A list of accounts who favourited the status
]
```
Because Favourite IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link: <https://mastodon.example/api/v1/statuses/109419880690343548/favourited_by?limit=1&max_id=53286827>; rel="next", <https://mastodon.example/api/v1/statuses/109419880690343548/favourited_by?limit=1&since_id=53286827>; rel="prev"
```
##### 404: Not found
Status does not exist or is private
@ -634,7 +674,7 @@ Status does not exist or is private
## Favourite a status {#favourite}
```http
POST https://mastodon.example/api/v1/statuses/:id/favourite HTTP/1.1
POST /api/v1/statuses/:id/favourite HTTP/1.1
```
Add a status to your favourites list.
@ -700,7 +740,7 @@ Status does not exist or is private
## Undo favourite of a status {#unfavourite}
```http
POST https://mastodon.example/api/v1/statuses/:id/unfavourite HTTP/1.1
POST /api/v1/statuses/:id/unfavourite HTTP/1.1
```
Remove a status from your favourites list.
@ -766,7 +806,7 @@ Status does not exist or is private
## Boost a status {#boost}
```http
POST https://mastodon.example/api/v1/statuses/:id/reblog HTTP/1.1
POST /api/v1/statuses/:id/reblog HTTP/1.1
```
Reshare a status on your own profile.
@ -849,7 +889,7 @@ Status does not exist or is private
## Undo boost of a status {#unreblog}
```http
POST https://mastodon.example/api/v1/statuses/:id/unreblog HTTP/1.1
POST /api/v1/statuses/:id/unreblog HTTP/1.1
```
Undo a reshare of a status.
@ -915,7 +955,7 @@ Status does not exist or is private
## Bookmark a status {#bookmark}
```http
POST https://mastodon.example/api/v1/statuses/:id/bookmark HTTP/1.1
POST /api/v1/statuses/:id/bookmark HTTP/1.1
```
Privately bookmark a status.
@ -971,7 +1011,7 @@ Invalid or missing Authorization header.
## Undo bookmark of a status {#unbookmark}
```http
POST https://mastodon.example/api/v1/statuses/:id/unbookmark HTTP/1.1
POST /api/v1/statuses/:id/unbookmark HTTP/1.1
```
Remove a status from your private bookmarks.
@ -1037,7 +1077,7 @@ Status does not exist or is private.
## Mute a conversation {#mute}
```http
POST https://mastodon.example/api/v1/statuses/:id/mute HTTP/1.1
POST /api/v1/statuses/:id/mute HTTP/1.1
```
Do not receive notifications for the thread that this status is part of. Must be a thread in which you are a participant.
@ -1103,7 +1143,7 @@ Status does not exist or is private.
## Unmute a conversation {#unmute}
```http
POST https://mastodon.example/api/v1/statuses/:id/unmute HTTP/1.1
POST /api/v1/statuses/:id/unmute HTTP/1.1
```
Start receiving notifications again for the thread that this status is part of.
@ -1169,7 +1209,7 @@ Status does not exist or is private.
## Pin status to profile {#pin}
```http
POST https://mastodon.example/api/v1/statuses/:id/pin HTTP/1.1
POST /api/v1/statuses/:id/pin HTTP/1.1
```
Feature one of your own public statuses at the top of your profile.
@ -1263,7 +1303,7 @@ Prior to 3.5.0, you could not pin one of your private statuses because private s
## Unpin status from profile {#unpin}
```http
POST https://mastodon.example/api/v1/statuses/:id/unpin HTTP/1.1
POST /api/v1/statuses/:id/unpin HTTP/1.1
```
Unfeature a status from the top of your profile.
@ -1338,7 +1378,7 @@ Status does not exist or is private.
## Edit a status {#edit}
```http
PUT https://mastodon.example/api/v1/statuses/:id HTTP/1.1
PUT /api/v1/statuses/:id HTTP/1.1
```
Edit a given status to change its text, sensitivity, media attachments, or poll. Note that editing a poll's options will reset the votes.
@ -1346,7 +1386,8 @@ Edit a given status to change its text, sensitivity, media attachments, or poll.
**Returns:** [Status]({{< relref "entities/status" >}})\
**OAuth:** User token + `write:statuses`\
**Version history:**\
3.5.0 - added
3.5.0 - added\
4.0.0 - add `language`
#### Request
@ -1371,6 +1412,9 @@ spoiler_text
sensitive
: Boolean. Whether the status should be marked as sensitive.
language
: String. ISO 639 language code for the status.
media_ids[]
: Array of String. Include Attachment IDs to be attached as media. If provided, `status` becomes optional, and `poll` cannot be used.
@ -1468,7 +1512,7 @@ Status does not exist, is private, or is not owned by you.
## View edit history of a status {#history}
```http
GET https://mastodon.example/api/v1/statuses/:id/history HTTP/1.1
GET /api/v1/statuses/:id/history HTTP/1.1
```
Get all known versions of a status, including the initial and current states.
@ -1614,7 +1658,7 @@ Status does not exist or is private.
## View status source {#source}
```http
GET https://mastodon.example/api/v1/statuses/:id/source HTTP/1.1
GET /api/v1/statuses/:id/source HTTP/1.1
```
Obtain the source properties for a status so that it can be edited.
@ -1672,7 +1716,7 @@ Status does not exist or is private.
## (DEPRECATED) Fetch preview card {#card}
```http
GET https://mastodon.example/api/v1/statuses/:id/card HTTP/1.1
GET /api/v1/statuses/:id/card HTTP/1.1
```
**Returns:** [PreviewCard]({{< relref "entities/PreviewCard" >}})\

View File

@ -114,7 +114,7 @@ data: <payload>
## Check if the server is alive {#health}
```http
GET https://mastodon.example/api/v1/streaming/health HTTP/1.1
GET /api/v1/streaming/health HTTP/1.1
```
Verify that the streaming service is alive before connecting to it
@ -138,7 +138,7 @@ OK
## Watch your home timeline and notifications {#user}
```http
GET https://mastodon.example/api/v1/streaming/user HTTP/1.1
GET /api/v1/streaming/user HTTP/1.1
```
Returns events that are relevant to the authorized user, i.e. home timeline and notifications
@ -215,7 +215,7 @@ data: {"id":"109348677773283527","created_at":"2022-11-15T16:06:48.410Z","in_rep
## Watch your notifications {#notification}
```http
GET https://mastodon.example/api/v1/streaming/user/notification HTTP/1.1
GET /api/v1/streaming/user/notification HTTP/1.1
```
Returns events for received notifications
@ -245,7 +245,7 @@ data: {"id":"68739215","type":"mention","created_at":"2022-08-30T23:09:54.070Z",
## Watch the federated timeline {#public}
```http
GET https://mastodon.example/api/v1/streaming/public HTTP/1.1
GET /api/v1/streaming/public HTTP/1.1
```
Returns all public statuses
@ -296,7 +296,7 @@ data: {"id":"109348684737626801","created_at":"2022-11-15T16:08:30.000Z","in_rep
## Watch the local timeline {#public-local}
```http
GET https://mastodon.example/api/v1/streaming/public/local HTTP/1.1
GET /api/v1/streaming/public/local HTTP/1.1
```
Returns all local public statuses
@ -347,7 +347,7 @@ data: {"id":"109348699525106378","created_at":"2022-11-15T16:12:20.310Z","in_rep
## Watch for remote statuses {#public-remote}
```http
GET https://mastodon.example/api/v1/streaming/public/remote HTTP/1.1
GET /api/v1/streaming/public/remote HTTP/1.1
```
Returns all public statuses from remote servers.
@ -397,7 +397,7 @@ data: {"id":"109348684737626801","created_at":"2022-11-15T16:08:30.000Z","in_rep
## Watch the public timeline for a hashtag {#hashtag}
```http
GET https://mastodon.example/api/v1/streaming/hashtag HTTP/1.1
GET /api/v1/streaming/hashtag HTTP/1.1
```
Returns all public statuses for a particular hashtag
@ -447,7 +447,7 @@ data: {"id":"109348684737626801","created_at":"2022-11-15T16:08:30.000Z","in_rep
## Watch the local timeline for a hashtag {#hashtag-local}
```http
GET https://mastodon.example/api/v1/streaming/hashtag/local HTTP/1.1
GET /api/v1/streaming/hashtag/local HTTP/1.1
```
Returns all local public statuses for a particular hashtag
@ -497,7 +497,7 @@ data: {"id":"108914430312582020","created_at":"2022-08-30T23:32:12.006Z","in_rep
## Watch for list updates {#list}
```http
GET https://mastodon.example/api/v1/streaming/list HTTP/1.1
GET /api/v1/streaming/list HTTP/1.1
```
Returns statuses for a list
@ -547,7 +547,7 @@ data: {"id":"108914327388663283","created_at":"2022-08-30T23:05:53.839Z","in_rep
## Watch for direct messages {#direct}
```http
GET https://mastodon.example/api/v1/streaming/direct HTTP/1.1
GET /api/v1/streaming/direct HTTP/1.1
```
Returns events for received direct messages.
@ -675,7 +675,7 @@ Note that the `payload` property is not present for `filters_changed` events.
### Streaming server
{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/streaming/index.js" caption="streaming/index.js" }}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/streaming/index.js" caption="streaming/index.js" >}}
### Backend event publishing
@ -683,34 +683,34 @@ Streaming timelines are maintained in Redis, and are published to Redis via `red
#### Status events
{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/services/fan_out_on_write_service.rb" caption="app/services/fan_out_on_write_service.rb" }}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/services/fan_out_on_write_service.rb" caption="app/services/fan_out_on_write_service.rb" >}}
{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/services/remove_status_service.rb" caption="app/services/remove_status_service.rb" }}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/services/remove_status_service.rb" caption="app/services/remove_status_service.rb" >}}
{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/services/batched_remove_status_service.rb" caption="app/services/batched_remove_status_service.rb" }}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/services/batched_remove_status_service.rb" caption="app/services/batched_remove_status_service.rb" >}}
{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/push_conversation_worker.rb" caption="app/workers/push_conversation_worker.rb" }}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/push_conversation_worker.rb" caption="app/workers/push_conversation_worker.rb" >}}
#### User events
{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/feed_manager.rb" caption="app/lib/feed_manager.rb" }}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/feed_manager.rb" caption="app/lib/feed_manager.rb" >}}
{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/push_update_worker.rb" caption="app/workers/push_update_worker.rb" }}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/push_update_worker.rb" caption="app/workers/push_update_worker.rb" >}}
{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/services/notify_service.rb" caption="app/services/notify_service.rb" }}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/services/notify_service.rb" caption="app/services/notify_service.rb" >}}
{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/custom_filter.rb" caption="app/models/custom_filter.rb" }}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/custom_filter.rb" caption="app/models/custom_filter.rb" >}}
{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/publish_scheduled_announcement_worker.rb" caption="app/workers/publish_scheduled_announcement_worker.rb" }}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/publish_scheduled_announcement_worker.rb" caption="app/workers/publish_scheduled_announcement_worker.rb" >}}
{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/publish_announcement_reaction_worker.rb" caption="app/workers/publish_announcement_reaction_worker.rb" }}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/publish_announcement_reaction_worker.rb" caption="app/workers/publish_announcement_reaction_worker.rb" >}}
{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/unpublish_announcement_worker.rb" caption="app/workers/unpublish_announcement_worker.rb" }}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/unpublish_announcement_worker.rb" caption="app/workers/unpublish_announcement_worker.rb" >}}
{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/push_encrypted_message_worker.rb" caption="app/workers/push_encrypted_message_worker.rb" }}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/push_encrypted_message_worker.rb" caption="app/workers/push_encrypted_message_worker.rb" >}}
### Streaming client
{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/javascript/mastodon/stream.js" caption="app/javascript/mastodon/stream.js" }}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/javascript/mastodon/stream.js" caption="app/javascript/mastodon/stream.js" >}}
{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/javascript/mastodon/actions/streaming.js" caption="app/javascript/mastodon/actions/streaming.js" }}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/javascript/mastodon/actions/streaming.js" caption="app/javascript/mastodon/actions/streaming.js" >}}

View File

@ -23,7 +23,7 @@ aliases: [
## View follow suggestions (v2) {#v2}
```http
GET https://mastodon.example/api/v2/suggestions HTTP/1.1
GET /api/v2/suggestions HTTP/1.1
```
Accounts that are promoted by staff, or that the user has had past positive interactions with, but is not yet following.
@ -42,7 +42,7 @@ Authorization
##### Query parameters
limit
: Integer. Maximum number of results to return. Defaults to 40.
: Integer. Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.
#### Response
##### 200: OK
@ -84,7 +84,7 @@ Invalid or missing Authorization header.
## Remove a suggestion {#remove}
```http
DELETE https://mastodon.example/api/v1/suggestions/:account_id HTTP/1.1
DELETE /api/v1/suggestions/:account_id HTTP/1.1
```
Remove an account from follow suggestions.
@ -130,7 +130,7 @@ Invalid or missing Authorization header.
## (DEPRECATED) View follow suggestions (v1) {#v1}
```http
GET https://mastodon.example/api/v1/suggestions HTTP/1.1
GET /api/v1/suggestions HTTP/1.1
```
Accounts the user has had past positive interactions with, but is not yet following.
@ -150,7 +150,7 @@ Authorization
##### Query parameters
limit
: Integer. Maximum number of results to return. Defaults to 40.
: Integer. Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.
#### Response
##### 200: OK

View File

@ -13,10 +13,14 @@ aliases: [
]
---
<style>
#TableOfContents ul ul ul {display: none}
</style>
## View information about a single tag {#get}
```http
GET https://mastodon.example/api/v1/tags/:id HTTP/1.1
GET /api/v1/tags/:id HTTP/1.1
```
Show a hashtag and its associated information
@ -91,7 +95,7 @@ Authorization
## Follow a hashtag {#follow}
```http
POST https://mastodon.example/api/v1/tags/:id/follow HTTP/1.1
POST /api/v1/tags/:id/follow HTTP/1.1
```
Follow a hashtag. Posts containing a followed hashtag will be inserted into your home timeline.
@ -100,7 +104,7 @@ Follow a hashtag. Posts containing a followed hashtag will be inserted into your
**OAuth:** User token + `write:follows`\
**Version history:**\
4.0.0 - added\
4.0.3 - this action is now idempotent
4.1.0 - this action is now idempotent
#### Request
@ -176,7 +180,7 @@ Invalid or missing Authorization header.
##### 422: Unprocessable entity
Prior to 4.0.3: Tag was already followed
Prior to 4.1.0: Tag was already followed
```json
{
@ -189,7 +193,7 @@ Prior to 4.0.3: Tag was already followed
## Unfollow a hashtag {#unfollow}
```http
POST https://mastodon.example/api/v1/tags/:id/unfollow HTTP/1.1
POST /api/v1/tags/:id/unfollow HTTP/1.1
```
Unfollow a hashtag. Posts containing this hashtag will no longer be inserted into your home timeline.

View File

@ -20,7 +20,7 @@ aliases: [
## View public timeline {#public}
```http
GET https://mastodon.example/api/v1/timelines/public HTTP/1.1
GET /api/v1/timelines/public HTTP/1.1
```
**Returns:** Array of [Status]({{<relref "entities/status">}})\
@ -61,7 +61,7 @@ min_id
: String. Return results immediately newer than ID.
limit
: Integer. Maximum number of results to return. Defaults to 20. Max 40.
: Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.
#### Response
##### 200: OK
@ -92,7 +92,7 @@ Sample API call with limit=2
## View hashtag timeline {#tag}
```http
GET https://mastodon.example/api/v1/timelines/tag/:hashtag HTTP/1.1
GET /api/v1/timelines/tag/:hashtag HTTP/1.1
```
View public statuses containing the given hashtag.
@ -103,15 +103,16 @@ View public statuses containing the given hashtag.
0.0.0 - added\
2.3.0 - added `only_media`\
2.6.0 - add `min_id`\
2.7.0 - add `any[]`, `all[]`, `none[]` for additional tags\
3.0.0 - auth is required if public preview is disabled\
3.3.0 - both `min_id` and `max_id` can be used at the same time now
3.3.0 - both `min_id` and `max_id` can be used at the same time now. add `remote`
#### Request
##### Path parameters
:hashtag
: {{<required>}} String. The name of the hashtag (not including the \# symbol).
: {{<required>}} String. The name of the hashtag (not including the # symbol).
##### Headers
@ -120,9 +121,21 @@ Authorization
##### Query parameters
any[]
: Array of String. Return statuses that contain any of these additional tags.
all[]
: Array of String. Return statuses that contain all of these additional tags.
none[]
: Array of String. Return statuses that contain none of these additional tags.
local
: Boolean. Return only local statuses? Defaults to false.
remote
: Boolean. Return only remote statuses? Defaults to false.
only_media
: Boolean. Return only statuses with media attachments? Defaults to false.
@ -136,12 +149,12 @@ min_id
: String. Return results immediately newer than ID.
limit
: Integer. Maximum number of results to return. Defaults to 20. Max 40.
: Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.
#### Response
##### 200: OK
Sample timeline for the hashtag \#cats and limit=2
Sample timeline for the hashtag #cats and limit=2
```json
[
@ -215,7 +228,7 @@ Hashtag does not exist
## View home timeline {#home}
```http
GET https://mastodon.example/api/v1/timelines/home HTTP/1.1
GET /api/v1/timelines/home HTTP/1.1
```
View statuses from followed users.
@ -246,7 +259,7 @@ min_id
: String. Return results immediately newer than ID.
limit
: Integer. Maximum number of results to return. Defaults to 20. Max 40.
: Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.
#### Response
##### 200: OK
@ -286,7 +299,7 @@ Invalid or missing Authorization header.
## View list timeline {#list}
```http
GET https://mastodon.example/api/v1/timelines/list/:list_id HTTP/1.1
GET /api/v1/timelines/list/:list_id HTTP/1.1
```
View statuses in the given list timeline.
@ -322,7 +335,7 @@ min_id
: String. Return results immediately newer than ID.
limit
: Integer. Maximum number of results to return. Defaults to 20. Max 40.
: Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.
#### Response
##### 200: OK
@ -365,7 +378,7 @@ List is not owned by you or does not exist
## (DEPRECATED) View direct timeline {#direct}
```http
GET https://mastodon.example/api/v1/timelines/direct HTTP/1.1
GET /api/v1/timelines/direct HTTP/1.1
```
View statuses with a "direct" privacy, from your account or in your notifications.
@ -395,7 +408,7 @@ min_id
: String. Return results immediately newer than ID.
limit
: Integer. Maximum number of results to return. Defaults to 20. Max 40.
: Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.
#### Response
##### 200: OK

View File

@ -21,12 +21,12 @@ aliases: [
## View trending tags {#tags}
```http
GET https://mastodon.example/api/v1/trends/tags HTTP/1.1
GET /api/v1/trends/tags HTTP/1.1
```
Tags that are being used more frequently within the past week.
**Returns:** Array of [REST::Tag]({{< relref "entities/tag" >}})\
**Returns:** Array of [Tag]({{< relref "entities/Tag" >}})\
**OAuth:** Public\
**Version history:**\
3.0.0 - added\
@ -37,7 +37,10 @@ Tags that are being used more frequently within the past week.
##### Query parameters
limit
: Integer. Maximum number of results to return. Defaults to 10.
: Integer. Maximum number of results to return. Defaults to 10 tags. Max 20 tags.
offset
: Integer. Skip the first n results.
#### Response
##### 200: OK
@ -89,12 +92,12 @@ limit
## View trending statuses {#statuses}
```http
GET https://mastodon.example/api/v1/trends/statuses HTTP/1.1
GET /api/v1/trends/statuses HTTP/1.1
```
Statuses that have been interacted with more than others.
**Returns:** Array of [Status]({{< relref "entities/status" >}})\
**Returns:** Array of [Status]({{< relref "entities/Status" >}})\
**OAuth:** Public\
**Version history:**\
3.5.0 - added
@ -103,7 +106,10 @@ Statuses that have been interacted with more than others.
##### Query parameters
limit
: Integer. Maximum number of results to return. Defaults to 10.
: Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.
offset
: Integer. Skip the first n results.
#### Response
##### 200: OK
@ -129,7 +135,7 @@ limit
## View trending links {#links}
```http
GET https://mastodon.example/api/v1/trends/links HTTP/1.1
GET /api/v1/trends/links HTTP/1.1
```
Links that have been shared more than others.
@ -143,7 +149,10 @@ Links that have been shared more than others.
##### Query parameters
limit
: Integer. Maximum number of results to return. Defaults to 10.
: Integer. Maximum number of results to return. Defaults to 10 links. Max 20 links.
offset
: Integer. Skip the first n results.
#### Response
##### 200: OK

View File

@ -42,17 +42,17 @@ Undo
The first-class Object types supported by Mastodon are `Note` and `Question`.
* Notes are transformed into regular statuses.
* Questions are transformed into a poll status.
- Notes are transformed into regular statuses.
- Questions are transformed into a poll status.
Some other Object types are converted as best as possible:
* Article
* Page
* Image
* Audio
* Video
* Event
- Article
- Page
- Image
- Audio
- Video
- Event
The transformer uses `content` if available, or `name` if not, in order to generate status text. The `url` will be appended. The `summary` property will be used as the CW text. The `icon` will be used as a thumbnail.
@ -218,19 +218,19 @@ published
## HTML sanitization {#sanitization}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/lib/sanitize_config.rb" caption="app/lib/sanitize\_config.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/lib/sanitize_config.rb" caption="app/lib/sanitize_config.rb" >}}
Mastodon sanitizes incoming HTML in order to not break assumptions for API client developers. Supported elements include `<p>`, `<span>`, `<br>`, and `<a>`. Unsupported elements will be converted to `<p>`.The sanitizer will keep classes if they begin with microformats prefixes or are semantic classes:
* h-\*
* p-\*
* u-\*
* dt-\*
* e-\*
* mention
* hashtag
* ellipsis
* invisible
- h-*
- p-*
- u-*
- dt-*
- e-*
- mention
- hashtag
- ellipsis
- invisible
## JSON-LD Namespacing {#namespaces}
@ -240,51 +240,51 @@ published
Contains definitions for Mastodon features.
* toot:Emoji
* toot:IdentityProof
* toot:blurhash
* toot:focalPoint
* toot:featured
* toot:featuredTags
* toot:discoverable
* toot:suspended
* toot:votersCount
- toot:Emoji
- toot:IdentityProof
- toot:blurhash
- toot:focalPoint
- toot:featured
- toot:featuredTags
- toot:discoverable
- toot:suspended
- toot:votersCount
### ActivityStreams extensions (`as:`) {#as}
Contains ActivityStreams extended properties that have been proposed but not officially adopted yet.
* as:Hashtag
* as:alsoKnownAs
* as:manuallyApprovesFollowers
* as:movedTo
* as:sensitive
- as:Hashtag
- as:alsoKnownAs
- as:manuallyApprovesFollowers
- as:movedTo
- as:sensitive
### W3ID Security Vocabulary (`sec:`) {#sec}
Contains properties used for HTTPS Signatures and Linked Data Signatures. Also used for identity proofs. See [Security]({{< relref "spec/security" >}}) for more information.
* sec:publicKey
* sec:publicKeyPem
* sec:owner
* sec:signature
* sec:signatureValue
- sec:publicKey
- sec:publicKeyPem
- sec:owner
- sec:signature
- sec:signatureValue
#### W3ID Identity
Contains a collection of terms from various namespaces, used for Linked Data Signatures.
* dc:creator
* dc:created
* sec:signature
* sec:signatureValue
- dc:creator
- dc:created
- sec:signature
- sec:signatureValue
### schema.org extensions (`schema:`) {#schema}
Contains properties used for profile metadata.
* schema:PropertyValue
* schema:value
- schema:PropertyValue
- schema:value
## Extensions

View File

@ -11,9 +11,9 @@ menu:
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/lib/request.rb" caption="app/lib/request.rb" >}}
[HTTP Signatures](https://w3c-dvcg.github.io/http-signatures/) is a specification for signing HTTP messages by using a \`Signature:\` header with your HTTP request. Mastodon requires the use of HTTP Signatures in order to validate that any activity received was authored by the actor generating it. When secure mode is enabled, all GET requests require HTTP signatures as well.
[HTTP Signatures](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures) is a specification for signing HTTP messages by using a `Signature:` header with your HTTP request. Mastodon requires the use of HTTP Signatures in order to validate that any activity received was authored by the actor generating it. When secure mode is enabled, all GET requests require HTTP signatures as well.
For any HTTP request incoming to Mastodon, the following header should be attached:
For any HTTP request incoming to Mastodon, the Signature header should be attached:
```http
Signature: keyId="https://my-example.com/actor#main-key",headers="(request-target) host date",signature="Y2FiYW...IxNGRiZDk4ZA=="
@ -28,7 +28,7 @@ Signature:
signature="Y2FiYW...IxNGRiZDk4ZA=="
```
The `keyId` should correspond to the actor and the key being used to generate the `signature`, whose value is equal to all parameters in `headers` concatenated together and signed by the key, then Base64-encoded. See [ActivityPub &gt; Public key]({{< relref "activitypub#publicKey" >}}) for more information on actor keys. An example key looks like this:
The `keyId` should correspond to the actor and the key being used to generate the `signature`, whose value is equal to all parameters in `headers` concatenated together and signed by the key, then Base64-encoded. See [ActivityPub > Public key]({{< relref "activitypub#publicKey" >}}) for more information on actor keys. An example key looks like this:
```json
"publicKey": {
@ -42,49 +42,85 @@ See also: [https://blog.joinmastodon.org/2018/07/how-to-make-friends-and-verify-
### Creating HTTP signatures {#http-sign}
To create an HTTP signature, you will have to define which headers are being hashed and signed. For example, consider the following request being sent out:
To create an HTTP signature, you will have to define which headers are being hashed and signed. For example, consider the following GET request:
```http
GET /users/username/inbox HTTP/1.1
GET /users/username/outbox HTTP/1.1
Host: mastodon.example
Date: 18 Dec 2019 10:08:46 GMT
Accept: application/activity+json
Accept: application/ld+json; profile="http://www.w3.org/ns/activitystreams"
```
The signature string is constructed using the values of the HTTP headers defined in `headers`, joined by newlines. Typically, you will want to include the request target, as well as the host and the date. Mastodon assumes `Date:` header if none are provided. For the above request, to generate a `Signature:` with `headers="(request-target) host date"` we would generate the following string:
The signature string is constructed using the values of the HTTP headers defined in `headers`, joined by newlines. Typically, you will want to include the request target, as well as the host and the date. Mastodon assumes `Date:` header if none are provided. For the above GET request, to generate a `Signature:` with `headers="(request-target) host date"` we would generate the following string:
```text
(request-target): get /users/username/inbox
(request-target): get /users/username/outbox
host: mastodon.example
date: 18 Dec 2019 10:08:46 GMT
```
Note that we don't care about the `Accept:` header because we won't be specifying it in `headers`.
The signature string is then hashed with SHA256 and signed with the actor's public key. The resulting value is attached as `signature` within the Signature: header. The final request looks like this:
The signature string is then hashed with RSA-SHA256 (RSASSA-PKCS1-v1_5 with SHA-256) and signed with the actor's private key. The resulting value is attached as `signature` within the `Signature:` header. The final request looks like this:
```http
GET /users/username/inbox HTTP/1.1
Host: mastodon.example
Date: 18 Dec 2019 10:08:46 GMT
Accept: application/activity+json
Accept: application/ld+json; profile="http://www.w3.org/ns/activitystreams"
Signature: keyId="https://my-example.com/actor#main-key",headers="(request-target) host date",signature="Y2FiYW...IxNGRiZDk4ZA=="
```
This request is functionally equivalent to saying that `https://my-example.com/actor` is requesting `https://mastodon.example/users/username/inbox` and is proving that they sent this request by signing `(request-target)`, `Host:`, and `Date:` with their public key linked at `keyId`, resulting in the provided `signature`.
This request is functionally equivalent to saying that `https://my-example.com/actor` is requesting `https://mastodon.example/users/username/inbox` and is proving that they sent this request by signing `(request-target)`, `Host:`, and `Date:` with their private key linked at `keyId`, resulting in the provided `signature`.
#### Signing POST requests and the Digest header {#digest}
When making a POST request to Mastodon, you must calculate the RSA-SHA256 digest hash of your request's body and include this hash within the `Digest:` header. The `Digest:` header must also be included within the `headers` parameter of the `Signature:` header. For example:
```http
POST /users/username/inbox HTTP/1.1
HOST: mastodon.example
Date: 18 Dec 2019 10:08:46 GMT
Digest: e37e179c75071a291f90a5fd4f848da87b491f1282f7bb8509ef2115b81ee0f4
Signature: keyId="https://my-example.com/actor#main-key",headers="(request-target) host date digest",signature="Y2FiYW...IxNGRiZDk4ZA=="
Content-Type: application/ld+json; profile="http://www.w3.org/ns/activitystreams"
{
"@context": "https://www.w3.org/ns/activitystreams",
"actor": "https://example.com/actor",
"type": "Create",
"object": {
"type": "Note",
"content": "Hello!"
}
"to": "https://mastodon.example/users/username"
}
```
### Verifying HTTP signatures {#http-verify}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/controllers/concerns/signature_verification.rb" caption="app/controllers/concerns/signature\_verification.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/controllers/concerns/signature_verification.rb" caption="app/controllers/concerns/signature_verification.rb" >}}
Consider the following request:
```http
GET /users/username/inbox HTTP/1.1
POST /users/username/inbox HTTP/1.1
Host: mastodon.example
Date: 18 Dec 2019 10:08:46 GMT
Accept: application/activity+json
Signature: keyId="https://my-example.com/actor#main-key",headers="(request-target) host date",signature="Y2FiYW...IxNGRiZDk4ZA=="
Digest: e37e179c75071a291f90a5fd4f848da87b491f1282f7bb8509ef2115b81ee0f4
Signature: keyId="https://my-example.com/actor#main-key",headers="(request-target) host date digest",signature="Y2FiYW...IxNGRiZDk4ZA=="
Content-Type: application/ld+json; profile="http://www.w3.org/ns/activitystreams"
{
"@context": "https://www.w3.org/ns/activitystreams",
"actor": "https://example.com/actor",
"type": "Create",
"object": {
"type": "Note",
"content": "Hello!"
}
"to": "https://mastodon.example/users/username"
}
```
Mastodon verifies the signature using the following algorithm:
@ -92,21 +128,25 @@ Mastodon verifies the signature using the following algorithm:
* Split `Signature:` into its separate parameters.
* Construct the signature string from the value of `headers`.
* Fetch the `keyId` and resolve to an actor's `publicKey`.
* SHA256 hash the signature string and compare to the Base64-decoded `signature` as decrypted by `publicKey[publicKeyPem]`.
* Use the Date: header to check that the signed request was made within the past 12 hours.
* RSA-SHA256 hash the signature string and compare to the Base64-decoded `signature` as decrypted by `publicKey[publicKeyPem]`.
* Use the `Date:` header to check that the signed request was made within the past 12 hours.
## Linked Data Signatures {#ld}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/lib/activitypub/linked_data_signature.rb" caption="app/lib/activitypub/linked\_data\_signature.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/lib/activitypub/linked_data_signature.rb" caption="app/lib/activitypub/linked_data_signature.rb" >}}
[Linked Data Signatures 1.0](https://w3c-dvcg.github.io/ld-signatures/) is a specification for attaching cryptographic signatures to JSON-LD documents. LD Signatures are not used widely within Mastodon, but they are used in the following situations:
{{< hint style="warning" >}}
Mastodon's current implementation of LD Signatures is outdated due to a change in the JSON-LD `@context` between the drafting stage and finalization stage of the specification. Mastodon expects a `type` of `RsaSignature2017` while later drafts instead define `RsaSignature2018` via the namespace `https://w3id.org/security/v2`. Furthermore, the LD Signatures specification as a whole has been superseded by the [Verifiable Credential Data Integrity 1.0](https://w3c.github.io/vc-data-integrity/) specification, which is largely incompatible with the earlier LD Signature spec. For this reason, it is not advised to implement support for LD Signatures.
{{< /hint >}}
* When running a [self-destruct]({{< relref "admin/tootctl#tootctl-self-destruct" >}}) sequence to send Delete activities to all known peers, the payload will use LD Signatures because HTTP Signatures will not be available. Receiving servers will process the signature by validating it against the locally cached actor key, since the HTTP server will no longer be hosting old actor information.
* When accepting activities from a relay. Public activities can optionally be sent to a relay with LD Signatures, and any server subscribing to a relay does not have to manually refetch the activity from the origin. This prevents having potentially infinite servers attempt to load the status from your instance.
[Linked Data Signatures 1.0](https://web.archive.org/web/20170923124140/https://w3c-dvcg.github.io/ld-signatures/) was a draft specification for attaching cryptographic signatures to JSON-LD documents. LD Signatures are not used widely within Mastodon, but they are used in the following situations:
- When running a [self-destruct]({{< relref "admin/tootctl#tootctl-self-destruct" >}}) sequence to send Delete activities to all known peers, the payload will use LD Signatures because HTTP Signatures will not be available. Receiving servers will process the signature by validating it against the locally cached actor key, since the HTTP server will no longer be hosting old actor information.
- When accepting activities from a relay. Public activities can optionally be sent to a relay with LD Signatures, and any server subscribing to a relay does not have to manually refetch the activity from the origin. This prevents having potentially infinite servers attempt to load the status from your instance.
### Creating LD signatures {#ld-sign}
To create a signature, Mastodon uses the keypair attached to an actor at `https://mastodon.example/users/username#main-key`. It then creates an SHA256 hash of the document, signs it with the keypair, and Base64-strict-encodes the resulting output to derive a `signatureValue`. The following hash is merged into the JSON-LD document:
To create a signature, Mastodon uses the keypair attached to an actor at `https://mastodon.example/users/username#main-key`. It then creates an RSA-SHA256 hash of the document, signs it with the keypair, and Base64-strict-encodes the resulting output to derive a `signatureValue`. The following hash is merged into the JSON-LD document:
```json
"signature": {
@ -117,10 +157,6 @@ To create a signature, Mastodon uses the keypair attached to an actor at `https:
}
```
{{< hint style="warning" >}}
Mastodon's current implementation of LD Signatures is somewhat outdated due to a change in the JSON-LD @context between the drafting stage and finalization stage of the specification. Mastodon expects a `type` of `RsaSignature2017` while the current specification instead defines `RsaSignature2018` via the namespace `https://w3id.org/security/v2`.
{{< /hint >}}
### Verifying LD signatures {#ld-verify}
To verify a signature, Mastodon uses the following algorithm:

View File

@ -27,19 +27,4 @@ You can select certain users to unfollow, or to remove from your followers, by c
## Account settings {#account}
From the account settings, you can change your email address, set a new password, revoke active sessions or authorized apps, and enable two-factor authentication.
## Identity proofs {#proofs}
[Link verification](../profile#verification) of profile metadata fields is one way to prove your identity by using rel=me links, but Mastodon also supports a more generalized proof provider subsystem. Currently, the only supported identity provider for this subsystem is Keybase.
### Keybase identity verification {#keybase}
{{< figure src="/assets/keybase.jpg" caption="An identity proof on a profile" >}}
First, sign up for Keybase and generate or upload a GPG public key to your Keybase account. Next, go to "prove more identities". Find your instance if it is available, and if not, contact Keybase for help. Select your Mastodon domain and enter your username. You will be able to prove your identity by authorizing with your Mastodon account and posting a proof message. Once you do this, the identity proof will be established, and your profile will show Keybase as a proven identity.
{{< hint style="danger" >}}
**Keybase verification is irreversible.** Keybase uses an immutable signature chain for its identity proofs, so once you prove your identity on Keybase, you cannot remove it. You can only revoke your proof by signing a revocation message with your associated private key.
{{< /hint >}}
From the account settings, you can change your email address, set a new password, revoke active sessions or authorized apps, and enable two-factor authentication.

View File

@ -29,7 +29,7 @@ Redirecting your account disables posting from that account and displays a "prof
{{< figure src="/assets/account-move.jpg" caption="Profile move form" >}}
Moving your account is the same as redirecting your account, but it will also irreversibly force everyone to unfollow your current account and follow your new account, if their software supports the Move activity. Your posts will not be moved, due to technical limitations. There is also a very heavy cooldown period in which you cannot migrate again, so be very careful before using this option!
Moving your account is the same as redirecting your account, but it will also irreversibly force everyone to unfollow your current account and follow your new account, if their software supports the Move activity. Your posts will not be moved, due to technical limitations. There is also a 30 day cooldown period in which you cannot migrate again, so be very careful before using this option!
### Account aliases {#aliases}

View File

@ -19,7 +19,7 @@ Your display name is shown to other users before your address. You can set a dis
### Bio {#bio}
Your bio is a short description of yourself that is displayed as a note on your profile. You can set a bio of up to 500 characters by default.
Your bio is a short description of yourself that is displayed as a note on your profile. You can set a bio of up to 500 characters by default. All links are counted as 23 characters, no matter how long they actually are, so there is no need to use a link shortener to save characters. In fact, using a link shortener is actively discouraged.
### Avatar {#avatar}
@ -78,9 +78,14 @@ If you put an HTTPS link in your profile metadata, Mastodon checks if that link
```
More precisely, Mastodon will validate the link under the following conditions:
- It is not within an `iframe` (note that some "block-based" CMS software may wrap block elements within iframes)
- Since 4.0: the hostname does not change after IDN normalization
- it starts with HTTPS
- the resolved page contains at least one `a` or `link` tag with a `rel="me"`
- the `href` attribute on one of those elements is equal to the URL for your Mastodon profile
Alternatively, validation will occur if the resolved page's *first* link has an `href` value that redirects to your Mastodon profile's URL (such as through a link shortener).
Alternatively, validation will occur if the resolved page's *first* link has an `href` value that redirects to your Mastodon profile's URL (such as through a link shortener).
{{< hint style="info" >}}
Make sure to save your profile *after* adding the rel-me link to your web page! The verification process is triggered when you save your profile, and may take some time before completing. If you have added the rel-me link and verification is not working, then try deleting the link, saving, re-adding the link, and saving again.
{{< /hint >}}

View File

@ -34,7 +34,7 @@ menu:
你必须需要复制如下内容:
* `~/live/public/system`目录里面包含了用户上传的图片与视频如果使用S3可跳过此步
* Postgres数据库使用[pg\_dump](https://www.postgresql.org/docs/9.1/static/backup-dump.html)
* Postgres数据库使用[pg_dump](https://www.postgresql.org/docs/9.1/static/backup-dump.html)
* `~/live/.env.production`文件,里面包含了服务器配置与密钥
不太重要的部分,为了方便起见,你也可以复制如下内容:
@ -45,7 +45,7 @@ menu:
### 导出并导入Postgres数据库 {#dump-and-load-postgres}
不要运行`mastodon:setup`,而是创建一个名为`template0`的空白Postgres数据库当导入Postgres导出文件时这是很有用的参见[pg\_dump文档](https://www.postgresql.org/docs/9.1/static/backup-dump.html#BACKUP-DUMP-RESTORE))。
不要运行`mastodon:setup`,而是创建一个名为`template0`的空白Postgres数据库当导入Postgres导出文件时这是很有用的参见[pg_dump文档](https://www.postgresql.org/docs/9.1/static/backup-dump.html#BACKUP-DUMP-RESTORE))。
在你的旧系统,使用`mastodon`用户运行如下命令:

View File

@ -7,7 +7,7 @@ menu:
parent: admin-optional
---
可以通过TOR的匿名服务来访问Mastodon。这将给你一个只能通过 TOR 网络连接的 \*.onion 地址。
可以通过TOR的匿名服务来访问Mastodon。这将给你一个只能通过 TOR 网络连接的 *.onion 地址。
## 安装 Tor {#install}

View File

@ -101,7 +101,7 @@ sudo apt install pgbouncer
#### 设置密码 {#pgbouncer-password}
首先如果你的Postgres中`mastodon`帐户没有设置密码的话,你需要设置一个密码。
First off, if your `mastodon` user in Postgres is set up wthout a password, you will need to set a password.
First off, if your `mastodon` user in Postgres is set up without a password, you will need to set a password.
下面是如何重置密码:
@ -279,7 +279,7 @@ production:
url: postgresql://db_user:db_password@db_host:db_port/db_name
```
确保URL指向PostgreSQL服务器所在位置。你可以添加多个副本replica。你可以本地安装一个pgBouncer该pgBouncer可被配置为根据数据库名称连接两个不同服务器例如“mastodon”连接主服务器“mastodon\_replica”连接副本服务器这样上面文件中的两个URL可以使用同样用户名、密码、主机、端口不同数据库名称。可能的设置有很多有关Makara的更多信息请参阅[其文档](https://github.com/taskrabbit/makara#databaseyml)。
确保URL指向PostgreSQL服务器所在位置。你可以添加多个副本replica。你可以本地安装一个pgBouncer该pgBouncer可被配置为根据数据库名称连接两个不同服务器例如“mastodon”连接主服务器“mastodon_replica”连接副本服务器这样上面文件中的两个URL可以使用同样用户名、密码、主机、端口不同数据库名称。可能的设置有很多有关Makara的更多信息请参阅[其文档](https://github.com/taskrabbit/makara#databaseyml)。
{{< hint style="warning" >}}
Sidekiq无法可靠的使用只读副本read-replicas因为即使是最微小的复制延迟也会导致查询不到相关纪录所致的任务失败。

View File

@ -51,7 +51,7 @@ RAILS_ENV=production bin/tootctl help
## 帐户相关命令 {#accounts}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/accounts_cli.rb" caption="lib/mastodon/accounts\_cli.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/accounts_cli.rb" caption="lib/mastodon/accounts_cli.rb" >}}
### `tootctl accounts rotate` {#accounts-rotate}
@ -208,7 +208,7 @@ RAILS_ENV=production bin/tootctl help
## 缓存相关命令 {#cache}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/cache_cli.rb" caption="lib/mastodon/cache\_cli.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/cache_cli.rb" caption="lib/mastodon/cache_cli.rb" >}}
### `tootctl cache clear` {#cache-clear}
@ -232,7 +232,7 @@ RAILS_ENV=production bin/tootctl help
## 域名相关命令 {#domains}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/domains_cli.rb" caption="lib/mastodon/domains\_cli.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/domains_cli.rb" caption="lib/mastodon/domains_cli.rb" >}}
### `tootctl domains purge` {#domains-purge}
@ -269,7 +269,7 @@ RAILS_ENV=production bin/tootctl help
## Emoji相关命令 {#emoji}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/emoji_cli.rb" caption="lib/mastodon/emoji\_cli.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/emoji_cli.rb" caption="lib/mastodon/emoji_cli.rb" >}}
### `tootctl emoji import` {#emoji-import}
@ -301,7 +301,7 @@ RAILS_ENV=production bin/tootctl help
## 时间流Feeds相关命令 {#feeds}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/feeds_cli.rb" caption="lib/mastodon/feeds\_cli.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/feeds_cli.rb" caption="lib/mastodon/feeds_cli.rb" >}}
### `tootctl feeds build` {#feeds-build}
@ -327,7 +327,7 @@ RAILS_ENV=production bin/tootctl help
## 媒体相关命令 {#media}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/media_cli.rb" caption="lib/mastodon/media\_cli.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/media_cli.rb" caption="lib/mastodon/media_cli.rb" >}}
### `tootctl media remove` {#media-remove}
@ -390,7 +390,7 @@ RAILS_ENV=production bin/tootctl help
## 预览卡片Preview Cards相关命令 {#preview_cards}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/preview_cards_cli.rb" caption="lib/mastodon/preview\_cards\_cli.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/preview_cards_cli.rb" caption="lib/mastodon/preview_cards_cli.rb" >}}
### `tootctl preview_cards remove` {#preview_cards-remove}
@ -409,7 +409,7 @@ RAILS_ENV=production bin/tootctl help
## 搜索相关命令 {#search}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/search_cli.rb" caption="lib/mastodon/search\_cli.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/search_cli.rb" caption="lib/mastodon/search_cli.rb" >}}
### `tootctl search deploy` {#search-deploy}
@ -425,7 +425,7 @@ RAILS_ENV=production bin/tootctl help
## 站点设定相关命令 {#settings}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/settings_cli.rb" caption="lib/mastodon/settings\_cli.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/settings_cli.rb" caption="lib/mastodon/settings_cli.rb" >}}
### `tootctl settings registrations open` {#settings-registrations-open}
@ -443,7 +443,7 @@ RAILS_ENV=production bin/tootctl help
## 嘟文相关命令 {#statuses}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/statuses_cli.rb" caption="lib/mastodon/statuses\_cli.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/statuses_cli.rb" caption="lib/mastodon/statuses_cli.rb" >}}
### `tootctl statuses remove` {#statuses-remove}