New REST APIs
The profile directory is a way to discover users who want to be discovered. To fetch the profile directory, access
GET /api/v1/directory with the possible params
local (boolean) and
active). Pagination is accomplished using
Hashtags that are used more than usual (and above a small minimal threshold) are “trending”. To fetch trending hashtags, access
GET /api/v1/trends. Only 10 results are returned maximally but you can request fewer with
Managing featured hashtags
Users can feature hashtags on their public profile, which allows visitors to easily browse their public posts filed under those hashtags. These cannot yet be arbitrarily retrieved through the API, but there is now an API for managing the featured hashtags of the current user:
GET /api/v1/featured_tagsto retrieve current user’s featured hashtags
POST /api/v1/featured_tagsto create a new featured hashtag, specified by the param
DELETE /api/v1/featured_tags/:idto delete a featured hashtag
GET /api/v1/featured_tags/suggestionsto retrieve the user’s 10 most commonly used hashtags
A featured hashtag contains the attributes
Timeline position markers
Apps can now synchronize their position in certain timelines between each other. Currently these are the home timeline and the notifications timeline. The web UI already implements this API and will save its position when closed.
To retrieve a map of markers with timeline names as keys, access
GET /api/v1/markers . You must specify the desired timelines with the array param
timeline. This is a slightly unusual structure in Mastodon’s REST API so it deserves an example:
To create a new marker, pass a map to
POST /api/v1/markers with timeline names as keys (
notifications), and an object containing the
last_read_id for each timeline. Essentially, you pass it something like this, either encoded as JSON or using nested form/query params:
If you are using the
GET /api/v2/search API for showing the user autocomplete for hashtags, you can now pass the
exclude_unreviewed boolean param to limit the results to only those hashtags that have been looked at by the server’s staff. This is a way to reduce junk and harmful results.
Sign-up API in approval-required registrations mode
You can now pass the
reason param to
POST /api/v1/accounts, containing the user’s reason for wanting to join the server, which is useful when the server is in approval-required registrations mode. You can detect when that mode is active by the
approval_required boolean attribute returned from
GET /api/v1/instance (in conjunction with the
registrations boolean attribute).
Custom emoji categories
category on custom emojis returned from
GET /api/v1/custom_emojis contains a string with which emojis are supposed to be grouped when displayed in a picker UI.
Displaying user’s own votes in polls
own_votes on polls contains an array of the user’s choices (as indices corresponding to the
New search syntax support
When ElasticSearch is enabled, you can use the following syntax to fine-tune your search:
- Surround keywords with double quotes (
") to search for the exact phrase
- Prepend a keyword (or phrase) with minus sign (
-) to exclude it from results
It should be noted that the default operator has been changed from “and” to “or”, so by searching for “foo bar” you will get results that contain both “foo” and “bar” at the top, but also those that only contain “foo” and only contain “bar”. For this reason, there is also another new operator, the plus sign (
+) which you can prepend to a keyword or phrase to make sure the results definitely contain it.
There is now
GET /health endpoint for the web process which you can use with a monitoring service. The endpoint measures not only that the web process responds to requests but can successfully connect to the database and the cache as well.
New deployment settings
Reply-to header on e-mails
If you want e-mails to be sent with a reply-to header, i.e. redirecting replies to those e-mails to a particular address, use the new
SMTP_REPLY_TO environment variable. Mind that the reply-to header on moderation warning e-mails is set to the contact address configured in the admin UI.
Normally, all public resources are available without authentication or authorization. Because of this, it is hard to know who (in particular, which server, or which person) has accessed a particular resource, and impossible to deny that access to the ones you want to avoid. Secure mode requires authentication (via HTTP signatures) on all public resources, as well as disabling public REST API access (i.e. no access without access token, and no access with app-only access tokens, there has to be a user assigned to that access token). This means you always know who is accessing any resource on your server, and can deny that access using domain blocks.
Unfortunately, secure mode is not fully backwards-compatible with previous Mastodon versions. For this reason, it cannot be enabled by default. If you want to enable it, knowing that it may negatively impact communications with other servers, set the
AUTHORIZED_FETCH=true environment variable.
Taking a step further than the secure mode, whitelist mode is meant for private servers. Our aim here are educational uses, such as schools and universities, where Mastodon could be used to provide a safe learning environment. When whitelist mode is enabled, no page is available without login, and any incoming or outgoing federation is ignored except for manually whitelisted domains. Domains can be whitelisted in the federation part of the admin UI. When whitelist mode is enabled, secure mode is also enabled.
To enable whitelist mode, set the
WHITELIST_MODE=true environment variable. Please mind that this option was not designed for being switched on on already running servers. To clean an existing database of content that is not whitelisted, run
tootctl domains purge --whitelist-mode
Because whitelist mode essentially creates a silo, not unlike Twitter, Facebook, and other centralized services, we do not recommend running public servers in whitelist mode.
New command-line tools
Please mind that if you find any of the below descriptions insufficient, you can always append
--help to whichever command you’re interested in and receive the most detailed information about the usage of that command and the available options.
Parallization and progress
Commands that used to accept a
--background flag for Sidekiq-based execution have been changed to instead support a
-c) flag specifying the number of threads to use for parallel execution.
Instead of printing dots to signal progress, real progress bars are now displayed, with the number of processed items and estimated time to completion.
Cleaning up old link preview cards
To remove thumbnails from older link preview cards, run
tootctl preview_cards remove, specifying age with
--days just like for media removal.
Re-downloading removed media attachments
If you need to re-download media attachments, run
tootctl media refresh. You can either re-download media attachments from a specific
--status, from a specific
--account, or from an entire
Sometimes various counters in Mastodon get out of sync with reality. To fix account counters (e.g. followers, following, toots), run
tootctl cache recount accounts. This should not take very long. To fix status counters (e.g. reblogs, favourites, replies), run
tootctl cache recount statuses. This may take a lot longer.
New admin UIs
Hashtags will not trend without your approval. Whenever a hashtag is beginning to trend, you receive a notification e-mail asking to review it. You can disable those e-mails from your personal e-mail notification preferences. You can disable the trends feature altogether from admin settings. Or you can choose to auto-approve hashtags instead, which may be suitable for trusted communities.
The hashtags area in the admin UI has been updated. When looking at hashtags that are pending review, you can approve or reject them in batches. From individual hashtag view, you can control whether the hashtag can trend, whether it can appear on the profile directory and in searches, or whether it can be used at all. You will also see which servers you know about are contributing how much to that hashtag’s usage to help you determine whether to let it trend or not.
Including reported toots in warning e-mails
If you want to perform an action or warning against a user related to a report, you can choose if the toots that were in that report should be included in the e-mail the user will get about that action or warning. This will provide more clarity to the user about how they broke your rules.
Table of contents on about page
The about page of your server will now auto-generate a table of contents based on the structure of your extended description HTML. It is recommended to have a
h1 tag, which will not be reflected on the table of contents, to give the entire page a title, then
h3 tags for the different sections. Make sure your HTML is valid, otherwise the table of contents may not work as expected.
Public and private domain blocks information
You can now add comments to domain blocks. Private comments are for other staff members only. From the admin settings, you can choose if domain blocks should be disclosed publicly or to logged-in users only, or not at all. If you choose to disclose them, they will appear on the about page, below your extended description. You can use the public comments to give public reasons for your decisions.
Custom emoji categories
The custom emojis area in the admin UI has been updated. You can now assign emojis to custom categories and perform batch actions on them such as copying, deleting, or unlisting.
When a user mentions someone who isn’t following them and it’s not a reply to something directed at that user, their message is run through a simplistic spam check which detects repeating messages. When spam is detected, a new report is created automatically. If that was a mistake, you can mark the report as resolved and it will exempt that user from future spam checks. You can disable the spam check feature from admin settings.