zelo72
/
documentation
mirror of https://github.com/mastodon/documentation
1
0
Fork 0
Code Issues 6 Releases Wiki Activity

Update anchors, line breaks, tootctl options (#745) 

* update anchors

* remove extraneous anchors

* fix line breaks

* wrap tootctl tokens in code blocks

* change anchors to hugo format

* fix mistaken search-and-replace

* fix mistaken search-and-replace
This commit is contained in:
trwnh 2020-01-12 07:11:56 -06:00 committed by Eugen Rochko
parent 32d4dd5803
commit 7ceae9fe36
72 changed files with 1219 additions and 1223 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
assets/style.scss
View File

@ -436,6 +436,7 @@ main {
background-color: lighten($darkest, 8%);
border-radius: 3px;
hyphens: none;
white-space: pre;
}
pre code {

2
config.toml
View File

@ -54,4 +54,4 @@ enableGitInfo = true
[languages.en]
contentDir = "content/en"
languageName = "English"
weight = -99
weight = -99

18
content/en/_index.md
View File

@ -8,11 +8,11 @@ menu:
{{< youtube id="IPSbNdBmWKE" caption="An introductory video explaining basic Mastodon concepts with visual animations" >}}
## What is a microblog?
## What is a microblog? {#microblogging}
Similar to how blogging is the act of publishing updates to a website, **microblogging** is the act of publishing small updates to a stream of updates on your profile. You can publish text posts and optionally attach media such as pictures, audio, video, or polls. Mastodon lets you follow friends and discover new ones.
## What is federation? <a id="what-is-federation"></a>
## What is federation? {#federation}
**Federation** is a form of decentralization. Instead of a single central service that all people use, there are multiple services, that any number of people can use.
@ -28,7 +28,7 @@ A Mastodon website can operate alone. Just like a traditional website, people si
## What is ActivityPub? <a id="the-fediverse"></a>
## What is ActivityPub? {#fediverse}
Mastodon uses a standardized, open protocol to implement federation. It is called **ActivityPub**. Any software that likewise implements federation via ActivityPub can seamlessly communicate with Mastodon, just like Mastodon websites communicate with one another.
@ -43,9 +43,9 @@ The **fediverse** \(“federated universe”\) is the name for all websites that
The fediverse does not have its own brand, so you might more often hear “follow me on Mastodon” than “follow me on the fediverse”, but technically the latter is more correct.
## Practical implications <a id="practical-implications"></a>
## Practical implications {#implications}
### Choice of service provider and policy
### Choice of service provider and policy {#choice}
Because Mastodon is simply software that can be used to power any website, potential users of Mastodon have the option of choosing a service provider from already-existing Mastodon websites, or to create their own Mastodon website if they wish. The Mastodon project maintains a list of recommended service providers at [joinmastodon.org](https://joinmastodon.org), sortable by category and/or language. Some websites may have moderation policies that go beyond this, such as requiring the use of certain tags on potentially sensitive content, and some websites may have more relaxed moderation policies, but websites listed in the picker all agree to adopt the [Mastodon Server Covenant](https://joinmastodon.org/covenant), meaning that they pledge to actively moderate against hate speech, to take daily backups, to have at least one emergency admin, and to provide at least 3 months advance notice in case of shutdown.
@ -57,7 +57,7 @@ Because Mastodon is simply software that can be used to power any website, poten
>
> -- Eugen Rochko, Dec 30 2018, ["Why does decentralization matter?"](https://blog.joinmastodon.org/2018/12/why-does-decentralization-matter/)
### Funding and monetization <a id="funding-and-monetization"></a>
### Funding and monetization {#monetization}
Mastodon websites are operated by different people or organizations completely independently. Mastodon does not implement any monetization strategies in the software.
@ -69,7 +69,7 @@ Mastodon development is likewise crowdfunded via [Patreon](https://patreon.com/m
>
> -- Eugen Rochko, Mar 3 2018, ["Twitter is not a public utility"](https://blog.joinmastodon.org/2018/03/twitter-is-not-a-public-utility/)
### Interoperability between different software <a id="impersonation-and-verification"></a>
### Interoperability between different software {#interoperability}
In practical terms: Imagine if you could follow an Instagram user from your Twitter account and comment on their photos without leaving your account. If Twitter and Instagram were federated services that used the same protocol, that would be possible. With a Mastodon account, **you can communicate with any other compatible website,** _**even if it is not running on Mastodon**_. All that is necessary is that the software support the same subset of the ActivityPub protocol that allows for creating and interacting with status updates. To find out more about the technical specifications required to interoperate with Mastodon, see [ActivityPub](spec/activitypub.md), [WebFinger](spec/webfinger.md), and [Security](spec/security.md). To read more about what ActivityPub allows us to do, see [Why ActivityPub is the future](https://blog.joinmastodon.org/2018/06/why-activitypub-is-the-future/).
@ -77,7 +77,7 @@ In practical terms: Imagine if you could follow an Instagram user from your Twit
>
> -- Eugen Rochko, Jun 27 2018, ["Why ActivityPub is the future"](https://blog.joinmastodon.org/2018/06/why-activitypub-is-the-future/)
### Free/libre software
### Free/libre software {#libre}
Unlike proprietary services, **anyone has the complete freedom to run, examine, inspect, copy, modify, distribute, and reuse the Mastodon source code, provided they guarantee the same freedoms for any derivative work.** Just like how users of Mastodon can choose their service provider, you as an individual are free to contribute features to Mastodon or publish a modified version of Mastodon that includes different features. These modified versions, also known as software forks, are required to also uphold the same freedoms as the original Mastodon project. For example, [glitch-soc](https://glitch-soc.github.io/docs/) is a software distribution that adds various experimental features. Many individual forks exist as well, perhaps themed slightly differently or including small modifications to the codebase. Because Mastodon is libre software that respects your freedom, personalizations like this are not only allowed but encouraged.
@ -89,7 +89,7 @@ Unlike proprietary services, **anyone has the complete freedom to run, examine,
>
> -- Eugen Rochko, Dec 30 2018, ["Why does decentralization matter?"](https://blog.joinmastodon.org/2018/12/why-does-decentralization-matter/)
## Choose your path
## Choose your path {#next-steps}
Learn how to use Mastodon:

15
content/en/admin/backups.md
View File

@ -1,16 +1,15 @@
---
title: Backing up your server
description: Setting up regular backups (optional, but not really)
menu:
docs:
weight: 80
parent: admin
---
## Setting up regular backups \(optional, but not really\) <a id="setting-up-regular-backups-optional-but-not-really"></a>
For any real-world use, you should make sure to regularly backup your Mastodon server.
### Overview <a id="overview"></a>
## Overview {#overview}
Things that need to be backed up in order of importance:
@ -19,7 +18,7 @@ Things that need to be backed up in order of importance:
3. User-uploaded files
4. Redis database
### Failure modes <a id="failure-modes"></a>
## Failure modes {#failure}
There are two failure types that people in general may guard for: The failure of the hardware, such as data corruption on the disk; and human and software error, such as wrongful deletion of particular piece of data. In this documentation, only the former type is considered.
@ -33,23 +32,23 @@ Losing the Redis database is almost harmless: The only irrecoverable data will b
The best backups are so-called off-site backups, i.e. ones that are not stored on the same machine as Mastodon itself. If the server you are hosted on goes on fire and the hard disk drive explodes, backups stored on that same hard drive won’t be of much use.
### Backing up application secrets <a id="backing-up-application-secrets"></a>
## Backing up application secrets {#env}
Application secrets are the easiest to backup, since they never change. You only need to store `.env.production` somewhere safe.
### Backing up PostgreSQL <a id="backing-up-postgresql"></a>
## 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.
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.
### Backing up user-uploaded files <a id="backing-up-user-uploaded-files"></a>
## Backing up user-uploaded files {#media}
If you are using an external object storage provider such as Amazon S3, Google Cloud or Wasabi, then you don’t need to worry about backing those up. The respective companies are responsible for handling hardware failures.
If you are using local file storage, then it’s up to you to make copies of the sizeable `public/system` directory, where uploaded files are stored by default.
### Backing up Redis <a id="backing-up-redis"></a>
## Backing up Redis {#redis}
Backing up Redis is easy. Redis regularly writes to `/var/lib/redis/dump.rdb` which is the only file you need to make a copy of.

49
content/en/admin/config.md
View File

@ -1,5 +1,6 @@
---
title: Configuring variables
title: Configuring your environment
description: Setting environment variables for your Mastodon installation.
menu:
docs:
weight: 30
@ -14,22 +15,22 @@ Mastodon uses environment variables as its configuration.
For convenience, it can read them from a flat file called `.env.production` in the Mastodon directory, but they can always be overridden by a specific process. For example, systemd service files can read environment variables from an `EnvironmentFile` or from inline definitions with `Environment`, so you can have different configuration parameters for specific services. They can also be specified when calling Mastodon from the command line.
### Basic <a id="basic"></a>
## Basic {#basic}
#### Federation <a id="federation"></a>
### Federation {#federation}
* `LOCAL_DOMAIN`
* `WEB_DOMAIN`
* `ALTERNATE_DOMAINS`
#### Secrets <a id="secrets"></a>
### Secrets {#secrets}
* `SECRET_KEY_BASE`
* `OTP_SECRET`
* `VAPID_PRIVATE_KEY`
* `VAPID_PUBLIC_KEY`
#### Deployment <a id="deployment"></a>
### Deployment {#deployment}
* `RAILS_ENV`
* `RAILS_SERVE_STATIC_FILES`
@ -40,7 +41,7 @@ For convenience, it can read them from a flat file called `.env.production` in t
* `NODE_ENV`
* `BIND`
#### Scaling options <a id="scaling-options"></a>
### Scaling options {#scaling}
* `WEB_CONCURRENCY`
* `MAX_THREADS`
@ -48,9 +49,9 @@ For convenience, it can read them from a flat file called `.env.production` in t
* `STREAMING_API_BASE_URL`
* `STREAMING_CLUSTER_NUM`
### Database connections <a id="database-connections"></a>
## Database connections {#connections}
#### PostgreSQL <a id="postgresql"></a>
### PostgreSQL {#postgresql}
* `DB_HOST`
* `DB_USER`
@ -59,7 +60,7 @@ For convenience, it can read them from a flat file called `.env.production` in t
* `DB_PORT`
* `DATABASE_URL`
#### Redis <a id="redis"></a>
### Redis {#redis}
* `REDIS_HOST`
* `REDIS_PORT`
@ -70,19 +71,19 @@ For convenience, it can read them from a flat file called `.env.production` in t
* `CACHE_REDIS_URL`
* `CACHE_REDIS_NAMESPACE`
#### ElasticSearch <a id="elasticsearch"></a>
### ElasticSearch {#elasticsearch}
* `ES_ENABLED`
* `ES_HOST`
* `ES_PORT`
* `ES_PREFIX`
#### StatsD <a id="statsd"></a>
### StatsD {#statsd}
* `STATSD_ADDR`
* `STATSD_NAMESPACE`
### Limits <a id="limits"></a>
## Limits {#limits}
* `SINGLE_USER_MODE`
* `EMAIL_DOMAIN_WHITELIST`
@ -90,7 +91,7 @@ For convenience, it can read them from a flat file called `.env.production` in t
* `MAX_SESSION_ACTIVATIONS`
* `USER_ACTIVE_DAYS`
### E-mail <a id="e-mail"></a>
## E-mail {#email}
* `SMTP_SERVER`
* `SMTP_PORT`
@ -105,17 +106,17 @@ For convenience, it can read them from a flat file called `.env.production` in t
* `SMTP_ENABLE_STARTTLS_AUTO`
* `SMTP_TLS`
### File storage <a id="file-storage"></a>
## File storage {#cdn}
* `CDN_HOST`
* `S3_ALIAS_HOST`
#### Local file storage <a id="local-file-storage"></a>
### Local file storage {#paperclip}
* `PAPERCLIP_ROOT_PATH`
* `PAPERCLIP_ROOT_URL`
#### Amazon S3 and compatible <a id="amazon-s3-and-compatible"></a>
### Amazon S3 and compatible {#s3}
* `S3_ENABLED`
* `S3_BUCKET`
@ -127,7 +128,7 @@ For convenience, it can read them from a flat file called `.env.production` in t
* `S3_ENDPOINT`
* `S3_SIGNATURE_VERSION`
#### Swift <a id="swift"></a>
### Swift {#swift}
* `SWIFT_ENABLED`
* `SWIFT_USERNAME`
@ -141,11 +142,11 @@ For convenience, it can read them from a flat file called `.env.production` in t
* `SWIFT_DOMAIN_NAME`
* `SWIFT_CACHE_TTL`
### External authentication <a id="external-authentication"></a>
## External authentication {#external-authentication}
* `OAUTH_REDIRECT_AT_SIGN_IN`
#### LDAP <a id="ldap"></a>
### LDAP {#ldap}
* `LDAP_ENABLED`
* `LDAP_HOST`
@ -157,14 +158,14 @@ For convenience, it can read them from a flat file called `.env.production` in t
* `LDAP_UID`
* `LDAP_SEARCH_FILTER`
#### PAM <a id="pam"></a>
### PAM {#pam}
* `PAM_ENABLED`
* `PAM_EMAIL_DOMAIN`
* `PAM_DEFAULT_SERVICE`
* `PAM_CONTROLLED_SERVICE`
#### CAS <a id="cas"></a>
### CAS {#cas}
* `CAS_ENABLED`
* `CAS_URL`
@ -188,7 +189,7 @@ For convenience, it can read them from a flat file called `.env.production` in t
* `CAS_IMAGE_KEY`
* `CAS_PHONE_KEY`
#### SAML <a id="saml"></a>
### SAML {#saml}
* `SAML_ENABLED`
* `SAML_ACS_URL`
@ -211,12 +212,12 @@ For convenience, it can read them from a flat file called `.env.production` in t
* `SAML_ATTRIBUTES_STATEMENTS_VERIFIED`
* `SAML_ATTRIBUTES_STATEMENTS_VERIFIED_EMAIL`
### Hidden services <a id="hidden-services"></a>
## Hidden services {#hidden-services}
* `http_proxy`
* `ALLOW_ACCESS_TO_HIDDEN_SERVICE`
### Other <a id="other"></a>
## Other {#other}
* `SKIP_POST_DEPLOYMENT_MIGRATIONS`

35
content/en/admin/install.md
View File

@ -1,12 +1,13 @@
---
title: Installing from source
description: Instructional guide on creating your own Mastodon-powered website.
menu:
docs:
weight: 20
parent: admin
---
## Pre-requisites <a id="pre-requisites"></a>
## Pre-requisites {#pre-requisites}
* A machine running **Ubuntu 18.04** that you have root access to
* A **domain name** \(or a subdomain\) for the Mastodon server, e.g. `example.com`
@ -14,24 +15,24 @@ menu:
You will be running the commands as root. If you aren’t already root, switch to root:
### System repositories <a id="system-repositories"></a>
### System repositories {#system-repositories}
Make sure curl is installed first:
#### Node.js <a id="node-js"></a>
#### Node.js {#node-js}
```bash
curl -sL https://deb.nodesource.com/setup_8.x | bash -
```
#### Yarn <a id="yarn"></a>
#### Yarn {#yarn}
```bash
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list
```
### System packages <a id="system-packages"></a>
### System packages {#system-packages}
```bash
apt update
@ -44,7 +45,7 @@ apt install -y \
certbot python-certbot-nginx yarn libidn11-dev libicu-dev libjemalloc-dev
```
### Installing Ruby <a id="installing-ruby"></a>
### Installing Ruby {#installing-ruby}
We will be using rbenv to manage Ruby versions, because it’s easier to get the right versions and to update once a newer release comes out. rbenv must be installed for a single Linux user, therefore, first we must create the user Mastodon will be running as:
@ -94,15 +95,15 @@ Return to the root user:
exit
```
## Setup <a id="setup"></a>
## Setup {#setup}
### Setting up PostgreSQL <a id="setting-up-postgresql"></a>
### Setting up PostgreSQL {#setting-up-postgresql}
#### Performance configuration \(optional\) <a id="performance-configuration-optional"></a>
#### Performance configuration \(optional\) {#performance-configuration-optional}
For optimal performance, you may use [pgTune](https://pgtune.leopard.in.ua/#/) to generate an appropriate configuration and edit values in `/etc/postgresql/9.6/main/postgresql.conf` before restarting PostgreSQL with `systemctl restart postgresql`
#### Creating a user <a id="creating-a-user"></a>
#### Creating a user {#creating-a-user}
You will need to create a PostgreSQL user that Mastodon could use. It is easiest to go with “ident” authentication in a simple setup, i.e. the PostgreSQL user does not have a separate password and can be used by the Linux user with the same username.
@ -121,7 +122,7 @@ CREATE USER mastodon CREATEDB;
Done!
### Setting up Mastodon <a id="setting-up-mastodon"></a>
### Setting up Mastodon {#setting-up-mastodon}
It is time to download the Mastodon code. Switch to the mastodon user:
@ -129,7 +130,7 @@ It is time to download the Mastodon code. Switch to the mastodon user:
su - mastodon
```
#### Checking out the code <a id="checking-out-the-code"></a>
#### Checking out the code {#checking-out-the-code}
Use git to download the latest stable release of Mastodon:
@ -138,7 +139,7 @@ git clone https://github.com/tootsuite/mastodon.git live && cd live
git checkout $(git tag -l | grep -v 'rc[0-9]*$' | sort -V | tail -n 1)
```
#### Installing the last dependencies <a id="installing-the-last-dependencies"></a>
#### Installing the last dependencies {#installing-the-last-dependencies}
Now to install Ruby and JavaScript dependencies:
@ -149,7 +150,7 @@ bundle install \
yarn install --pure-lockfile
```
#### Generating a configuration <a id="generating-a-configuration"></a>
#### Generating a configuration {#generating-a-configuration}
Run the interactive setup wizard:
@ -171,7 +172,7 @@ You’re done with the mastodon user for now, so switch back to root:
exit
```
### Setting up nginx <a id="setting-up-nginx"></a>
### Setting up nginx {#setting-up-nginx}
Copy the configuration template for nginx from the Mastodon directory:
@ -184,7 +185,7 @@ Then edit `/etc/nginx/sites-available/mastodon` to replace `example.com` with yo
Reload nginx for the changes to take effect:
### Acquiring a SSL certificate <a id="acquiring-a-ssl-certificate"></a>
### Acquiring a SSL certificate {#acquiring-a-ssl-certificate}
We’ll use Let’s Encrypt to get a free SSL certificate:
@ -196,7 +197,7 @@ This will obtain the certificate, automatically update `/etc/nginx/sites-availab
At this point you should be able to visit your domain in the browser and see the elephant hitting the computer screen error page. This is because we haven’t started the Mastodon process yet.
### Setting up systemd services <a id="setting-up-systemd-services"></a>
### Setting up systemd services {#setting-up-systemd-services}
Copy the systemd service templates from the Mastodon directory:

15
content/en/admin/migrating.md
View File

@ -1,5 +1,6 @@
---
title: Migrating to a new machine
description: Copying your Mastodon installation to a new server without losing anything.
menu:
docs:
weight: 90
@ -12,7 +13,7 @@ Sometimes, for various reasons, you may want to migrate your Mastodon instance f
This guide was written with Ubuntu Server in mind; your mileage may vary for other setups.
{{< /hint >}}
## Basic steps <a id="basic-steps"></a>
## Basic steps {#basic-steps}
1. Set up a new Mastodon server using the [Production Guide]({{< relref "install.md" >}}) \(however, don’t run `mastodon:setup`\).
2. Stop Mastodon on the old server \(e.g. `systemctl stop 'mastodon-*.service'`\).
@ -26,9 +27,9 @@ This guide was written with Ubuntu Server in mind; your mileage may vary for oth
10. Update or copy your Nginx configuration, re-run LetsEncrypt as necessary.
11. Enjoy your new server!
## Detailed steps <a id="detailed-steps"></a>
## Detailed steps {#detailed-steps}
### What data needs to be migrated <a id="what-data-needs-to-be-migrated"></a>
### What data needs to be migrated {#what-data-needs-to-be-migrated}
At a high level, you’ll need to copy over the following:
@ -42,7 +43,7 @@ Less crucially, you’ll probably also want to copy the following for convenienc
* The systemd config files \(`/etc/systemd/system/mastodon-*.service`\), which may contain your server tweaks and customizations
* The pgbouncer configuration under `/etc/pgbouncer` \(if you’re using it\)
### Dump and load Postgres <a id="dump-and-load-postgres"></a>
### Dump and load Postgres {#dump-and-load-postgres}
Instead of running `mastodon:setup`, we’re 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)\).
@ -67,7 +68,7 @@ pg_restore -U mastodon -n public --no-owner --role=mastodon \
\(Note that if the username is not `mastodon` on the new server, you should change the `-U` AND `--role` values above. It’s okay if the username is different between the two servers.\)
### Copy files <a id="copy-files"></a>
### Copy files {#copy-files}
This will probably take some time, and you’ll want to avoid re-copying unnecessarily, so using `rsync` is recommended. On your old machine, as the `mastodon` user, run:
@ -81,13 +82,13 @@ You should also copy over the `.env.production` file, which contains secrets.
Optionally, you may copy over the nginx, systemd, and pgbouncer config files, or rewrite them from scratch.
### During migration <a id="during-migration"></a>
### During migration {#during-migration}
You can edit the `~/live/public/500.html` page on the old machine if you want to show a nice error message to let existing users know that a migration is in progress.
You’ll probably also want to set the DNS TTL to something small \(30-60 minutes\) about a day in advance, so that DNS can propagate quickly once you point it to the new IP address.
### After migrating <a id="after-migrating"></a>
### After migrating {#after-migrating}
You can check [whatsmydns.net](https://whatsmydns.net/) to see the progress of DNS propagation. To jumpstart the process, you can always edit your own `/etc/hosts` file to point to your new server so you can start playing around with it early.

23
content/en/admin/moderation.md
View File

@ -1,20 +1,21 @@
---
title: Moderation actions
description: Actions that can be taken against unwanted users or domains.
menu:
docs:
weight: 110
parent: admin
---
## Individual moderation <a id="individual-moderation"></a>
## Individual moderation {#individual-moderation}
Moderation in Mastodon is always applied locally, i.e. as seen from the particular server. An admin or moderator on one server cannot affect a user on another server, they can only affect the local copy on their own server.
### Disable login <a id="disable-login"></a>
### Disable login {#disable-login}
A Mastodon account can be disabled. This prevents the user from doing anything with the account, but all of the content is still there untouched. This limitation is reversible, the account can be re-enabled at any time. This limitation is only available for local users on your server.
### Silence <a id="silence"></a>
### Silence {#silence-user}
A Mastodon silence is synonymous with sandbox. A silenced account does not appear to users who are not already following it. All of the content is still there, and it can still be found via search, mentioned, and followed, but the content is invisible.
@ -22,27 +23,27 @@ At this moment, silence does not affect federation. A locally silenced account i
This limitation is reversible, the account can be unsilenced at any time.
### Suspend <a id="suspend"></a>
### Suspend {#suspend-user}
A Mastodon suspension is synonymous with deletion. The account no longer appears in search, the profile page is gone, all of the posts, uploads, followers, and all other data is removed. This limitation is **irreversible**. While the account can be unsuspended, allowing the user to take control of it again, the old data is gone for good.
## Server-wide moderation <a id="server-wide-moderation"></a>
## Server-wide moderation {#server-wide-moderation}
Because individually moderating a large volume of users from a misbehaving server can be exhausting, it is possible to pre-emptively moderate against all users from that particular server using a so-called **domain block**, which comes with several different levels of severity.
### Reject media <a id="reject-media"></a>
### Reject media {#reject-media}
With this option active, no files from the server will be processed locally. That includes avatars, headers, emojis and media attachments.
### Silence <a id="silence-1"></a>
### Silence {#silence-server}
Applies a silence to all past and future accounts from the server.
### Suspend <a id="suspend-1"></a>
### Suspend {#suspend-server}
Applies a suspension to all past and future accounts from the server. No content from the server will be stored locally except for usernames.
## Spam-fighting measures <a id="spam-fighting-measures"></a>
## Spam-fighting measures {#spam-fighting-measures}
There are a few baseline measures for preventing spam in Mastodon:
@ -51,11 +52,11 @@ There are a few baseline measures for preventing spam in Mastodon:
However, dedicated spammers will get through that. The other measure you can employ is **e-mail domain blacklisting**. During sign up, Mastodon resolves the given e-mail address for an A or MX record, i.e. the IP address of the e-mail server, and checks that IP address against a dynamically stored blacklist.
### Blocking by e-mail server <a id="blocking-by-e-mail-server"></a>
### Blocking by e-mail server {#blocking-by-e-mail-server}
Spammers will often use different e-mail domains so it looks like they are using a lot of different e-mail servers that would all be difficult to blacklist separately. However, sometimes all of those domains resolve to a single e-mail server IP. If you see a lot of spammers signing up at the same time, you can check for this, either using an online DNS lookup tool, or the Linux `dig` utility, e.g. `dig 1.2.3.4` will return all DNS records for that IP. If you notice the IP is the same for all domains, you can add it to the e-mail domain blacklist.
### Blocking by IP <a id="blocking-by-ip"></a>
### Blocking by IP {#blocking-by-ip}
It is not possible to block visitors by IP address in Mastodon itself, and it is not a fool-proof strategy. IPs are sometimes shared by a lot of different people, and sometimes change hands. But it is possible to block visitors by IP address in Linux using a firewall. Here is an example using `iptables` and `ipset`:

5
content/en/admin/optional/elasticsearch.md
View File

@ -1,5 +1,6 @@
---
title: Full-text search
description: Setting up ElasticSearch to search for statuses authored, favourited, or mentioned in.
menu:
docs:
weight: 10
@ -8,7 +9,7 @@ menu:
Mastodon supports full-text search when it ElasticSearch is available. Mastodon’s full-text search allows logged in users to find results from their own toots, their favourites, and their mentions. It deliberately does not allow searching for arbitrary strings in the entire database.
### Installing ElasticSearch <a id="install-elasticsearch"></a>
## Installing ElasticSearch {#install}
ElasticSearch requires a Java runtime. If you don’t have Java already installed, do it now. Assuming you are logged in as `root`:
@ -41,7 +42,7 @@ systemctl enable elasticsearch
systemctl start elasticsearch
```
### Configuring Mastodon <a id="setup-mastodon"></a>
## Configuring Mastodon {#config}
Edit `.env.production` to add the following variables:

11
content/en/admin/optional/tor.md
View File

@ -1,5 +1,6 @@
---
title: Hidden services
description: Serving Mastodon through TOR hidden services.
menu:
docs:
weight: 20
@ -8,7 +9,7 @@ menu:
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
## Installing Tor {#install}
First Tor’s Debian archive needs to be added to apt.
@ -29,7 +30,7 @@ Finally install the required packages.
apt install tor deb.torproject.org-keyring
```
## Configure Tor
## Configure Tor {#configure}
Edit the file at `/etc/tor/torrc` and add the following configuration.
@ -47,7 +48,7 @@ sudo service tor restart
Your tor hostname can now be found at `/var/lib/tor/hidden_service/hostname`.
## Move your Mastodon configuration
## Move your Mastodon configuration {#nginx}
We will need to tell Nginx about your Mastodon configuration twice. To keep things [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) we need to move the Mastodon configuration into its own file that can be referenced.
@ -95,7 +96,7 @@ server {
}
```
## Serve Tor over http
## Serve Tor over http {#http}
While it may be tempting to serve your Tor version of Mastodon over https it is not a good idea for most people. See [this](https://blog.torproject.org/facebook-hidden-services-and-https-certs) blog post from the Tor Project about why https certificates do not add value. Since you cannot get an SSL cert for an onion domain, you will also be plagued with certificate errors when trying to use your Mastodon instance. A Tor developer has more recently spelled out the reasons why serving a Tor service over https is not beneficial for most use cases [here](https://matt.traudt.xyz/p/o44SnkW2.html).
@ -142,7 +143,7 @@ Restart your web server.
service nginx restart
```
## Gotchas
## Gotchas {#gotchas}
There are a few things you will need to be aware of. Certain redirects will push your users to https. They will have to manually replace the URL with http to continue.

37
content/en/admin/scaling.md
View File

@ -1,12 +1,13 @@
---
title: Scaling up your server
descriptions: Optimizations that can be done to serve more users.
menu:
docs:
weight: 100
parent: admin
---
## Managing concurrency <a id="managing-concurrency"></a>
## Managing concurrency {#concurrency}
Mastodon has three types of processes:
@ -14,7 +15,7 @@ Mastodon has three types of processes:
* Streaming API
* Background processing \(Sidekiq\)
### Web \(Puma\) <a id="web-puma"></a>
### Web \(Puma\) {#web}
The web process serves short-lived HTTP requests for most of the application. The following environment variables control it:
@ -27,7 +28,7 @@ These values affect how many HTTP requests can be served at the same time.
In terms of throughput, more processes are better than more threads.
### Streaming API <a id="streaming-api"></a>
### Streaming API {#streaming}
The streaming API handles long-lived HTTP and WebSockets connections, through which clients receive real-time updates. The following environment variables control it:
@ -36,11 +37,11 @@ The streaming API handles long-lived HTTP and WebSockets connections, through wh
One process can handle a reasonably high number of connections. The streaming API can be hosted on a different subdomain if you want to e.g. avoid the overhead of nginx proxying the connections.
### Background processing \(Sidekiq\) <a id="background-processing-sidekiq"></a>
### Background processing \(Sidekiq\) {#sidekiq}
Many tasks in Mastodon are delegated to background processing to ensure the HTTP requests are fast, and to prevent HTTP request aborts from affecting the execution of those tasks. Sidekiq is a single process, with a configurable number of threads.
#### Number of threads <a id="number-of-threads"></a>
#### Number of threads {#sidekiq-threads}
While the amount of threads in the web process affects the responsiveness of the Mastodon instance to the end-user, the amount of threads allocated to background processing affects how quickly posts can be delivered from the author to anyone else, how soon e-mails are sent out, etc.
@ -52,7 +53,7 @@ bundle exec sidekiq -c 15
Would start the sidekiq process with 15 threads. Please mind that each threads needs to be able to connect to the database, which means that the database pool needs to be large enough to support all the threads. The database pool size is controlled with the `DB_POOL` environment variable and must be at least the same as the number of threads.
#### Queues <a id="queues"></a>
#### Queues {#sidekiq-queues}
Sidekiq uses different queues for tasks of varying importance, where importance is defined by how much it would impact the user experience of your server’s local users if the queue wasn’t working, in order of descending importance:
@ -75,15 +76,15 @@ The way Sidekiq works with queues, it first checks for tasks from the first queu
As a solution, it is possible to start different Sidekiq processes for the queues to ensure truly parallel execution, by e.g. creating multiple systemd services for Sidekiq with different arguments.
## Transaction pooling with pgBouncer <a id="transaction-pooling-with-pgbouncer"></a>
## Transaction pooling with pgBouncer {#pgbouncer}
### Why you might need PgBouncer <a id="why-you-might-need-pgbouncer"></a>
### Why you might need PgBouncer {#pgbouncer-why}
If you start running out of available Postgres connections \(the default is 100\) then you may find PgBouncer to be a good solution. This document describes some common gotchas as well as good configuration defaults for Mastodon.
Note that you can check “PgHero” in the administration view to see how many Postgres connections are currently being used. Typically Mastodon uses as many connections as there are threads both in Puma, Sidekiq and the streaming API combined.
### Installing PgBouncer <a id="installing-pgbouncer"></a>
### Installing PgBouncer {#pgbouncer-install}
On Debian and Ubuntu:
@ -91,9 +92,9 @@ On Debian and Ubuntu:
sudo apt install pgbouncer
```
### Configuring PgBouncer <a id="configuring-pgbouncer"></a>
### Configuring PgBouncer {#pgbouncer-config}
#### Setting a password <a id="setting-a-password"></a>
#### 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.
@ -111,7 +112,7 @@ ALTER USER mastodon WITH PASSWORD 'password';
Then `\q` to quit.
#### Configuring userlist.txt <a id="configuring-userlist-txt"></a>
#### Configuring userlist.txt {#pgbouncer-userlist}
Edit `/etc/pgbouncer/userlist.txt`
@ -141,7 +142,7 @@ You’ll also want to create a `pgbouncer` admin user to log in to the PgBouncer
In both cases the password is just `password`.
#### Configuring pgbouncer.ini <a id="configuring-pgbouncer-ini"></a>
#### Configuring pgbouncer.ini {#pgbouncer-ini}
Edit `/etc/pgbouncer/pgbouncer.ini`
@ -180,7 +181,7 @@ Don’t forget to reload or restart pgbouncer after making your changes:
sudo systemctl reload pgbouncer
```
#### Debugging that it all works <a id="debugging-that-it-all-works"></a>
#### Debugging that it all works {#pgbouncer-debug}
You should be able to connect to PgBouncer just like you would with Postgres:
@ -196,7 +197,7 @@ You can also check the PgBouncer logs like so:
tail -f /var/log/postgresql/pgbouncer.log
```
#### Configuring Mastodon to talk to PgBouncer <a id="configuring-mastodon-to-talk-to-pgbouncer"></a>
#### Configuring Mastodon to talk to PgBouncer {#pgbouncer-mastodon}
In your `.env.production` file, first off make sure that this is set:
@ -220,7 +221,7 @@ DB_PORT=6432
You cannot use pgBouncer to perform `db:migrate` tasks. But this is easy to work around. If your postgres and pgbouncer are on the same host, it can be as simple as defining `DB_PORT=5432` together with `RAILS_ENV=production` when calling the task, for example: `RAILS_ENV=production DB_PORT=5432 bundle exec rails db:migrate` \(you can specify `DB_HOST` too if it’s different, etc\)
{{< /hint >}}
#### Administering PgBouncer <a id="administering-pgbouncer"></a>
#### Administering PgBouncer {#pgbouncer-admin}
The easiest way to reboot is:
@ -242,13 +243,13 @@ RELOAD;
Then use `\q` to quit.
## Separate Redis for cache <a id="separate-redis-for-cache"></a>
## Separate Redis for cache {#redis}
Redis is used widely throughout the application, but some uses are more important than others. Home feeds, list feeds, and Sidekiq queues as well as the streaming API are backed by Redis and that’s important data you wouldn’t want to lose \(even though the loss can be survived, unlike the loss of the PostgreSQL database - never lose that!\). However, Redis is also used for volatile cache. If you are at a stage of scaling up where you are worried if your Redis can handle everything, you can use a different Redis database for the cache. In the environment, you can specify `CACHE_REDIS_URL` or individual parts like `CACHE_REDIS_HOST`, `CACHE_REDIS_PORT` etc. Unspecified parts fallback to the same values as without the cache prefix.
As far as configuring the Redis database goes, basically you can get rid of background saving to disk, since it doesn’t matter if the data gets lost on restart and you can save some disk I/O on that. You can also add a maximum memory limit and a key eviction policy, for that, see this guide: [Using Redis as an LRU cache](https://redis.io/topics/lru-cache)
## Read-replicas <a id="read-replicas"></a>
## Read-replicas {#read-replicas}
To reduce the load on your Postgresql server, you may wish to setup hot streaming replication \(read replica\). [See this guide for an example](https://cloud.google.com/community/tutorials/setting-up-postgres-hot-standby). You can make use of the replica in Mastodon in these ways:

9
content/en/admin/setup.md
View File

@ -1,14 +1,15 @@
---
title: Setting up your new instance
description: Things to do after installing Mastodon
menu:
docs:
weight: 50
parent: admin
---
## Creating an admin account
## Creating an admin account {#admin}
### In the browser <a id="in-the-browser"></a>
### In the browser {#admin-gui}
After signing up in the browser, you will need to use the command line to give your newly created account admin privileges. Assuming your username is `alice`:
@ -16,7 +17,7 @@ After signing up in the browser, you will need to use the command line to give y
RAILS_ENV=production bin/tootctl accounts modify alice --role admin
```
### From the command line <a id="from-the-command-line"></a>
### From the command line {#admin-cli}
You can create a new account using the command-line interface.
@ -30,7 +31,7 @@ RAILS_ENV=production bin/tootctl accounts create \
A randomly generated password will be shown in the terminal.
## Filling in server information <a id="filling-in-server-information"></a>
## Filling in server information {#info}
After logging in, navigate to the **Site settings** page. While there are no technical requirements for filling in this information, it is considered crucial for operating a server for humans.

244
content/en/admin/tootctl.md
View File

@ -25,7 +25,7 @@ RAILS_ENV=production bin/tootctl help
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/cli.rb" caption="lib/cli.rb" >}}
### `tootctl self-destruct`
### `tootctl self-destruct` {#self-destruct}
Erase this server from the federation by broadcasting account Delete activities to all known other servers. This allows a "clean exit" from running a Mastodon server, as it leaves next to no cache behind on other servers. This command is always interactive and requires confirmation twice.
@ -40,20 +40,20 @@ No local data is actually deleted, because emptying the database or deleting the
| Option | Description |
| :--- | :--- |
| --dry\_run | Print expected results only, without performing any actions. |
| `--dry_run` | Print expected results only, without performing any actions. |
### `tootctl --version`
### `tootctl --version` {#version}
Show the version of the currently running Mastodon instance.
**Version history:**
2.7.0 - added
## Accounts CLI
## Accounts CLI {#accounts}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/accounts_cli.rb" caption="lib/mastodon/accounts\_cli.rb" >}}
### `tootctl accounts rotate`
### `tootctl accounts rotate` {#accounts-rotate}
Generate and broadcast new RSA keys, as part of security maintenance.
@ -62,10 +62,10 @@ Generate and broadcast new RSA keys, as part of security maintenance.
| Option | Description |
| :--- | :--- |
| USERNAME | Local username for an account. |
| --all | Can be provided instead of USERNAME to rotate keys for all local accounts. |
| `USERNAME` | Local username for an account. |
| `--all` | Can be provided instead of USERNAME to rotate keys for all local accounts. |
### `tootctl accounts create`
### `tootctl accounts create` {#accounts-create}
Create a new user account with given USERNAME and provided --email.
@ -74,14 +74,14 @@ Create a new user account with given USERNAME and provided --email.
| Option | Description |
| :--- | :--- |
| USERNAME | Local username for the new account. Required. |
| --email EMAIL | Email address to be attached to the user. Required. |
| --confirmed | Skip sending the confirmation email and activate the account immediately. |
| --role ROLE | Define the new account as a `user`, `moderator`, or `admin`. Defaults to `user`. |
| --reattach | Reuse an old USERNAME after its account has been deleted. |
| --force | Forcefully delete any existing account with this USERNAME and reattach the new account in place of the \(just-deleted\) account. |
| `USERNAME` | Local username for the new account. Required. |
| `--email EMAIL` | Email address to be attached to the user. Required. |
| `--confirmed` | Skip sending the confirmation email and activate the account immediately. |
| `--role ROLE` | Define the new account as a `user`, `moderator`, or `admin`. Defaults to `user`. |
| `--reattach` | Reuse an old USERNAME after its account has been deleted. |
| `--force` | Forcefully delete any existing account with this USERNAME and reattach the new account in place of the \(just-deleted\) account. |
### `tootctl accounts modify`
### `tootctl accounts modify` {#accounts-modify}
Modify a user account's role, email, active status, approval mode, or 2FA requirement.
@ -90,16 +90,16 @@ Modify a user account's role, email, active status, approval mode, or 2FA requir
| Option | Description |
| :--- | :--- |
| USERNAME | Local username for the new account. Required. |
| --role ROLE | Define the account as a `user`, `moderator`, or `admin`. |
| --email EMAIL | Update the user's email address to EMAIL. |
| --confirm | Skip confirmation email, when used with --email. |
| --disable | Lock USERNAME out of their account. |
| --enable | Unlock USERNAME's account if it is currently disabled. |
| --approve | Approve the account, if you are/were in approval mode. |
| --disable\_2fa | Remove additional factors and allow login with password. |
| `USERNAME` | Local username for the new account. Required. |
| `--role ROLE` | Define the account as a `user`, `moderator`, or `admin`. |
| `--email EMAIL` | Update the user's email address to EMAIL. |
| `--confirm` | Skip confirmation email, when used with --email. |
| `--disable` | Lock USERNAME out of their account. |
| `--enable` | Unlock USERNAME's account if it is currently disabled. |
| `--approve` | Approve the account, if you are/were in approval mode. |
| `--disable_2fa` | Remove additional factors and allow login with password. |
### `tootctl accounts delete`
### `tootctl accounts delete` {#accounts-delete}
Delete a user account with given USERNAME.
@ -108,9 +108,9 @@ Delete a user account with given USERNAME.
| Option | Description |
| :--- | :--- |
| USERNAME | Local username for the account. Required. |
| `USERNAME` | Local username for the account. Required. |
### `tootctl accounts backup`
### `tootctl accounts backup` {#accounts-backup}
Request a backup for a user account with given USERNAME. The backup will be created in Sidekiq asynchronously, and the user will receive an email with a link to it once it's done.
@ -119,9 +119,9 @@ Request a backup for a user account with given USERNAME. The backup will be crea
| Option | Description |
| :--- | :--- |
| USERNAME | Local username for the account. Required. |
| `USERNAME` | Local username for the account. Required. |
### `tootctl accounts cull`
### `tootctl accounts cull` {#accounts-cull}
Remove remote accounts that no longer exist. Queries every single remote account in the database to determine if it still exists on the origin server, and if it doesn't, then remove it from the database. Accounts that have had confirmed activity within the last week are excluded from the checks, in case the server is just down.
@ -131,10 +131,10 @@ Remove remote accounts that no longer exist. Queries every single remote account
| Option | Description |
| :--- | :--- |
| --concurrency N | The number of workers to use for this task. Defaults to N=5. |
| --dry\_run | Print expected results only, without performing any actions. |
| `--concurrency N` | The number of workers to use for this task. Defaults to N=5. |
| `--dry_run` | Print expected results only, without performing any actions. |
### `tootctl accounts refresh`
### `tootctl accounts refresh` {#accounts-refresh}
Refetch remote user data and files for one or multiple accounts.
@ -143,14 +143,14 @@ Refetch remote user data and files for one or multiple accounts.
| Option | Description |
| :--- | :--- |
| USERNAME | Local username |
| --all | Can be provided instead of USERNAME to refresh all remote accounts. |
| --domain DOMAIN | Can be provided instead of USERNAME. Operate only on remote accounts from this DOMAIN. |
| --concurrency N | The number of workers to use for this task. Defaults to N=5. |
| --verbose | Print additional information while task is processing. |
| --dry\_run | Print expected results only, without performing any actions. |
| `USERNAME` | Local username |
| `--all` | Can be provided instead of USERNAME to refresh all remote accounts. |
| `--domain DOMAIN` | Can be provided instead of USERNAME. Operate only on remote accounts from this DOMAIN. |
| `--concurrency N` | The number of workers to use for this task. Defaults to N=5. |
| `--verbose` | Print additional information while task is processing. |
| `--dry_run` | Print expected results only, without performing any actions. |
### `tootctl accounts follow`
### `tootctl accounts follow` {#accounts-follow}
Force all local accounts to follow a local account specified by username.
@ -160,11 +160,11 @@ Force all local accounts to follow a local account specified by username.
| Option | Description |
| :--- | :--- |
| USERNAME | Local username |
| --concurrency N | The number of workers to use for this task. Defaults to N=5. |
| --verbose | Print additional information while task is processing. |
| `USERNAME` | Local username |
| `--concurrency N` | The number of workers to use for this task. Defaults to N=5. |
| `--verbose` | Print additional information while task is processing. |
### `tootctl accounts unfollow`
### `tootctl accounts unfollow` {#accounts-unfollow}
Force all local accounts to unfollow an account specified by their address.
@ -173,11 +173,11 @@ Force all local accounts to unfollow an account specified by their address.
| Option | Description |
| :--- | :--- |
| ACCT | `username@domain` address |
| --concurrency N | The number of workers to use for this task. Defaults to N=5. |
| --verbose | Print additional information while task is processing. |
| `ACCT` | `username@domain` address |
| `--concurrency N` | The number of workers to use for this task. Defaults to N=5. |
| `--verbose` | Print additional information while task is processing. |
### `tootctl accounts reset-relationships`
### `tootctl accounts reset-relationships` {#accounts-reset-relationships}
Reset all follow and/or follower relationships for a local account.
@ -186,11 +186,11 @@ Reset all follow and/or follower relationships for a local account.
| Option | Description |
| :--- | :--- |
| USERNAME | Local username |
| --follows | Force USERNAME to unfollow everyone, then re-follow them. |
| --followers | Remove all of USERNAME's followers. |
| `USERNAME` | Local username |
| `--follows` | Force USERNAME to unfollow everyone, then re-follow them. |
| `--followers` | Remove all of USERNAME's followers. |
### `tootctl accounts approve`
### `tootctl accounts approve` {#accounts-approve}
Approve new registrations when instance is in approval mode.
@ -199,22 +199,22 @@ Approve new registrations when instance is in approval mode.
| Option | Description |
| :--- | :--- |
| USERNAME | Approve the pending account with this username |
| --number N | Approve the N most recent registrations. |
| --all | Approve all pending registrations. |
| `USERNAME` | Approve the pending account with this username |
| `--number N` | Approve the N most recent registrations. |
| `--all` | Approve all pending registrations. |
## Cache CLI
## Cache CLI {#cache}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/cache_cli.rb" caption="lib/mastodon/cache\_cli.rb" >}}
### `tootctl cache clear`
### `tootctl cache clear` {#cache-clear}
Clear out the cache storage.
**Version history:**
2.8.1 - added
### `tootctl cache recount`
### `tootctl cache recount` {#cache-recount}
Update hard-cached counters of TYPE by counting referenced records from scratch. It may take a very long time to finish, depending on the size of the database. Accounts will have their follower, following, and status counts refreshed. Statuses will have their reply, boost, and favourite counts refreshed.
@ -224,14 +224,14 @@ Update hard-cached counters of TYPE by counting referenced records from scratch.
| Option | Description |
| :--- | :--- |
| TYPE | Either `accounts` or `statuses` |
| --concurrency N | The number of workers to use for this task. Defaults to N=5. |
| --verbose | Print additional information while task is processing. |
| `--concurrency N` | The number of workers to use for this task. Defaults to N=5. |
| `--verbose` | Print additional information while task is processing. |
## Domains CLI
## Domains CLI {#domains}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/domains_cli.rb" caption="lib/mastodon/domains\_cli.rb" >}}
### `tootctl domains purge`
### `tootctl domains purge` {#domains-purge}
Remove all accounts from a given DOMAIN without leaving behind any records. Unlike a suspension, if the DOMAIN still exists in the wild, it means the accounts could return if they are resolved again.
@ -243,13 +243,13 @@ Remove all accounts from a given DOMAIN without leaving behind any records. Unli
| Option | Description |
| :--- | :--- |
| DOMAIN\[...\] | Domains to purge, separated by space. |
| --whitelist\_mode | Can be provided instead of DOMAIN. Instead of purging from a single domain, all accounts from domains that are not whitelisted will be removed from the database. Use this after enabling whitelist mode and defining your whitelist. |
| --concurrency N | The number of workers to use for this task. Defaults to 5. |
| --verbose | Print additional information while task is processing. |
| --dry\_run | Print expected results only, without performing any actions. |
| `DOMAIN[...]` | Domains to purge, separated by space. |
| `--whitelist_mode` | Can be provided instead of DOMAIN. Instead of purging from a single domain, all accounts from domains that are not whitelisted will be removed from the database. Use this after enabling whitelist mode and defining your whitelist. |
| `--concurrency N` | The number of workers to use for this task. Defaults to 5. |
| `--verbose` | Print additional information while task is processing. |
| `--dry_run` | Print expected results only, without performing any actions. |
### `tootctl domains crawl`
### `tootctl domains crawl` {#domains-crawl}
Crawl the known fediverse by using Mastodon REST API endpoints that expose all known peers, and collect statistics from those peers, as long as those peers support those API endpoints. When no START is given, the command uses the server's own database of known peers to seed the crawl. Returns total servers, total registered users, total active users in the last week, and total users joined in the last week.
@ -260,15 +260,15 @@ Crawl the known fediverse by using Mastodon REST API endpoints that expose all k
| Option | Description |
| :--- | :--- |
| START | Optionally start from a different domain name. |
| --concurrency N | The number of workers to use for this task. Defaults to 50. |
| --format FORMAT | Control how results are returned. `summary` will print a summary. `domains` will return a newline-delimited list of all discovered peers. `json` will dump aggregated raw data. Defaults to `summary`. |
| --exclude\_suspended | Do not include instances that you have suspended in the output. Also includes any subdomains. |
| `--concurrency N` | The number of workers to use for this task. Defaults to 50. |
| `--format FORMAT` | Control how results are returned. `summary` will print a summary. `domains` will return a newline-delimited list of all discovered peers. `json` will dump aggregated raw data. Defaults to `summary`. |
| `--exclude_suspended` | Do not include instances that you have suspended in the output. Also includes any subdomains. |
## Emoji CLI
## Emoji CLI {#emoji}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/emoji_cli.rb" caption="lib/mastodon/emoji\_cli.rb" >}}
### `tootctl emoji import`
### `tootctl emoji import` {#emoji-import}
Imports custom emoji from a .tar.gz archive at a given path. The archive should contain PNG or GIF files no larger than 50KB, and the shortcode will be set equal to the filename minus the extension, with optional prefixes and/or suffixes.
@ -277,14 +277,14 @@ Imports custom emoji from a .tar.gz archive at a given path. The archive should
| Option | Description |
| :--- | :--- |
| PATH | Path to a .tar.gz archive containing pictures. |
| --prefix PREFIX | Add PREFIX to the beginning of generated shortcodes. |
| --suffix SUFFIX | Add SUFFIX to the end of generated shortcodes. |
| --overwrite | Instead of skipping existing emoji, replace them with any discovered emoji with the same shortcode. |
| --unlisted | Processed emoji will not be shown in the emoji picker, but will be usable only by their direct shortcode. |
| --category CATEGORY | Group the processed emoji under CATEGORY in the picker. |
| `PATH` | Path to a .tar.gz archive containing pictures. |
| `--prefix PREFIX` | Add PREFIX to the beginning of generated shortcodes. |
| `--suffix SUFFIX` | Add SUFFIX to the end of generated shortcodes. |
| `--overwrite` | Instead of skipping existing emoji, replace them with any discovered emoji with the same shortcode. |
| `--unlisted` | Processed emoji will not be shown in the emoji picker, but will be usable only by their direct shortcode. |
| `--category CATEGORY` | Group the processed emoji under CATEGORY in the picker. |
### `tootctl emoji purge`
### `tootctl emoji purge` {#emoji-purge}
Remove all custom emoji.
@ -293,17 +293,17 @@ Remove all custom emoji.
| Option | Description |
| :--- | :--- |
| --remote_only | If provided, remove only from remote domains. |
| `--remote_only` | If provided, remove only from remote domains. |
**Version history:**
2.8.0 - added
## Feeds CLI
## Feeds CLI {#feeds}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/feeds_cli.rb" caption="lib/mastodon/feeds\_cli.rb" >}}
### `tootctl feeds build`
### `tootctl feeds build` {#feeds-build}
Build home and list feeds for one or all users. Feeds will be built from the database and cached in-memory with Redis. Mastodon manages home feeds for active users automatically.
@ -312,24 +312,24 @@ Build home and list feeds for one or all users. Feeds will be built from the dat
| Option | Description |
| :--- | :--- |
| USERNAME | Local username whose feeds will be regenerated. |
| --all | Can be provided instead of USERNAME to refresh all local accounts' feeds. |
| --concurrency N | The number of workers to use for this task. Defaults to N=5. |
| --verbose | Print additional information while task is processing. |
| --dry\_run | Print expected results only, without performing any actions. |
| `USERNAME` | Local username whose feeds will be regenerated. |
| `--all` | Can be provided instead of USERNAME to refresh all local accounts' feeds. |
| `--concurrency N` | The number of workers to use for this task. Defaults to N=5. |
| `--verbose` | Print additional information while task is processing. |
| `--dry_run` | Print expected results only, without performing any actions. |
### `tootctl feeds clear`
### `tootctl feeds clear` {#feeds-clear}
Remove all home and list feeds from Redis.
**Version history:**
2.6.0 - added
## Media CLI
## Media CLI {#media}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/media_cli.rb" caption="lib/mastodon/media\_cli.rb" >}}
### `tootctl media remove`
### `tootctl media remove` {#media-remove}
Remove locally cached copies of media attachments from other servers.
@ -339,12 +339,12 @@ Remove locally cached copies of media attachments from other servers.
| Option | Description |
| :--- | :--- |
| --days | How old media attachments have to be before they are removed. Defaults to 7. |
| --concurrency N | The number of workers to use for this task. Defaults to 5. |
| --verbose | Print additional information while task is processing. |
| --dry\_run | Print expected results only, without performing any actions. |
| `--days` | How old media attachments have to be before they are removed. Defaults to 7. |
| `--concurrency N` | The number of workers to use for this task. Defaults to 5. |
| `--verbose` | Print additional information while task is processing. |
| `--dry_run` | Print expected results only, without performing any actions. |
### `tootctl media remove-orphans`
### `tootctl media remove-orphans` {#media-remove-orphans}
Scans for files that do not belong to existing media attachments, and remove them. Please mind that some storage providers charge for the necessary API requests to list objects. Also, this operation requires iterating over every single file individually, so it will be slow.
@ -353,10 +353,10 @@ Scans for files that do not belong to existing media attachments, and remove the
| Option | Description |
| :--- | :--- |
| --start\_after | The Paperclip attachment key where the loop will start. Use this option if the command was interrupted before. |
| --dry\_run | Print expected results only, without performing any actions. |
| `--start_after` | The Paperclip attachment key where the loop will start. Use this option if the command was interrupted before. |
| `--dry_run` | Print expected results only, without performing any actions. |
### `tootctl media refresh`
### `tootctl media refresh` {#media-refresh}
Refetch remote media attachments from other servers. You must specify the source of media attachments with either --status, --account, or --domain. If an attachment already exists in the database, it will not be overwritten unless you use --force.
@ -366,33 +366,33 @@ Refetch remote media attachments from other servers. You must specify the source
| Option | Description |
| :--- | :--- |
| --account ACCT | String `username@domain` handle of the account |
| --domain DOMAIN | FQDN string |
| --status ID | Local numeric ID of the status in the database. |
| --concurrency N | The number of workers to use for this task. Defaults to 5. |
| --verbose | Print additional information while task is processing. |
| --dry\_run | Print expected results only, without performing any actions. |
| --force | Force redownload the remote resource and overwrite the local attachment. |
| `--account ACCT` | String `username@domain` handle of the account |
| `--domain DOMAIN` | FQDN string |
| `--status ID` | Local numeric ID of the status in the database. |
| `--concurrency N` | The number of workers to use for this task. Defaults to 5. |
| `--verbose` | Print additional information while task is processing. |
| `--dry_run` | Print expected results only, without performing any actions. |
| `--force` | Force redownload the remote resource and overwrite the local attachment. |
### `tootctl media usage`
### `tootctl media usage` {#media-usage}
Calculate disk space consumed by Mastodon.
**Version history:**
3.0.1 - added
### `tootctl media lookup`
### `tootctl media lookup` {#media-lookup}
Prompts for a media URL, then looks up where the media is displayed.
**Version history:**
3.1.0 - added
## Preview Cards CLI
## Preview Cards CLI {#preview_cards}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/preview_cards_cli.rb" caption="lib/mastodon/preview\_cards\_cli.rb" >}}
### `tootctl preview_cards remove`
### `tootctl preview_cards remove` {#preview_cards-remove}
Remove local thumbnails for preview cards.
@ -401,17 +401,17 @@ Remove local thumbnails for preview cards.
| Option | Description |
| :--- | :--- |
| --days | How old media attachments have to be before they are removed. Defaults to 180. \(NOTE: it is not recommended to delete preview cards within the last 14 days, because preview cards will not be refetched unless the link is reposted after 2 weeks from last time.\) |
| --concurrency N | The number of workers to use for this task. Defaults to 5. |
| --verbose | Print additional information while task is processing. |
| --dry\_run | Print expected results only, without performing any actions. |
| --link | Only delete link-type preview cards; leave video and photo cards untouched. |
| `--days` | How old media attachments have to be before they are removed. Defaults to 180. \(NOTE: it is not recommended to delete preview cards within the last 14 days, because preview cards will not be refetched unless the link is reposted after 2 weeks from last time.\) |
| `--concurrency N` | The number of workers to use for this task. Defaults to 5. |
| `--verbose` | Print additional information while task is processing. |
| `--dry_run` | Print expected results only, without performing any actions. |
| `--link` | Only delete link-type preview cards; leave video and photo cards untouched. |
## Search CLI
## Search CLI {#search}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/search_cli.rb" caption="lib/mastodon/search\_cli.rb" >}}
### `tootctl search deploy`
### `tootctl search deploy` {#search-deploy}
Create or update an ElasticSearch index and populate it. If ElasticSearch is empty, this command will create the necessary indices and then import data from the database into those indices. This command will also upgrade indices if the underlying schema has been changed since the last run.
@ -421,31 +421,31 @@ Create or update an ElasticSearch index and populate it. If ElasticSearch is emp
| Option | Description |
| :--- | :--- |
| --processes N | Parallelize execution of the command. Defaults to N=2. Can also specify `auto` to derive a number based on available CPUs. |
| `--processes N` | Parallelize execution of the command. Defaults to N=2. Can also specify `auto` to derive a number based on available CPUs. |
## Settings CLI
## Settings CLI {#settings}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/settings_cli.rb" caption="lib/mastodon/settings\_cli.rb" >}}
### `tootctl settings registrations open`
### `tootctl settings registrations open` {#settings-registrations-open}
Opens registrations.
**Version history:**
2.6.0 - added
### `tootctl settings registrations close`
### `tootctl settings registrations close` {#settings-registrations-close}
Closes registrations.
**Version history:**
2.6.0 - added
## Statuses CLI
## Statuses CLI {#statuses}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/statuses_cli.rb" caption="lib/mastodon/statuses\_cli.rb" >}}
### `tootctl statuses remove`
### `tootctl statuses remove` {#statuses-remove}
Remove unreferenced statuses from the database, such as statuses that came from relays or from users who are no longer followed by any local accounts, and have not been replied to or otherwise interacted with.
@ -456,5 +456,5 @@ This is a computationally heavy procedure that creates extra database indices be
| Option | Description |
| :--- | :--- |
| --days | How old statuses have to be before they are removed. Defaults to 90. |
| `--days` | How old statuses have to be before they are removed. Defaults to 90. |

15
content/en/api/oauth-scopes.md
View File

@ -1,5 +1,6 @@
---
title: OAuth Scopes
description: Defining what you have permission to do with the API
menu:
docs:
weight: 10
@ -20,7 +21,7 @@ If you do not specify a `scope` in your authorization request, or a `scopes` in
The set of scopes saved during app creation must include all the scopes that you will request in the authorization request, otherwise authorization will fail.
### Version history
### Version history {#versions}
- 0.9.0 - read, write, follow
- 2.4.0 - push
@ -32,15 +33,15 @@ The set of scopes saved during app creation must include all the scopes that you
## List of scopes
### `read`
### `read` {#read}
Grants access to read data. Requesting `read` will also grant child scopes shown in the left column of the table below.
### `write`
### `write` {#write}
Grants access to write data. Requesting `write` will also grant child scopes shown in the right column of the table below.
### `follow`
### `follow` {#follow}
Grants access to manage relationships. Requesting `follow` will also grant the following child scopes, shown in bold in the table:
@ -48,11 +49,11 @@ Grants access to manage relationships. Requesting `follow` will also grant the f
* `read:follows`, `write:follows`
* `read:mutes`, `write:mutes`
### `push`
### `push` {#push}
Grants access to [Web Push API subscriptions.]({{< relref "../methods/notifications/push.md" >}}) Added in Mastodon 2.4.0.
### Admin scopes
### Admin scopes {#admin}
Used for moderation API. Added in Mastodon 2.9.1. The following granular scopes are available \(note that there is no singular `admin` scope\):
@ -63,7 +64,7 @@ Used for moderation API. Added in Mastodon 2.9.1. The following granular scopes
* `admin:write:accounts`
* `admin:write:reports`
## Granular scopes
## Granular scopes {#granular}
| read | write |
| :--- | :--- |

26
content/en/client/authorized.md
View File

@ -7,21 +7,21 @@ menu:
parent: user
---
## Scopes explained
## Scopes explained {#scopes}
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 simply 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](../api/oauth-scopes.md) 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**
## **Example authorization code flow** {#flow}
This is similar to the authentication flow from before, but this time, we need to obtain authorization from a user as well.
### Client ID and secret
### Client ID and secret {#client}
First, if you have not already registered a client application, then see [Creating our application](token.md#creating-our-application) on the previous page or go directly to [POST /api/v1/apps](../methods/apps/#create-an-application) for the full documentation of that method. We will need the `client_id` and `client_secret` for our application.
### Authorize the user
### Authorize the user {#login}
To authorize a user, request [GET /oauth/authorize](../methods/apps/oauth.md#authorize-a-user) in a browser with the following query parameters:
@ -39,7 +39,7 @@ Note the following:
* `scope` must be a subset of our registered app's registered scopes. It is a good idea to only request what you need. See [OAuth Scopes](../api/oauth-scopes.md) for more information.
* `redirect_uri` is one of the URIs we registered with our app. We are still using "out of band" for this example, which means we will have to manually copy and paste the resulting code, but if you registered your application with a URI that you control, then the code will be returned as a query parameter `code` and can be logged by your request handler. See the response section of the API method documentation for more information on this.
### Obtain the token
### Obtain the token {#token}
Now that we have an authorization `code`, let's obtain an access token that will authenticate our requests as the authorized user. To do so, use [POST /oauth/token](../methods/apps/oauth.md#obtain-a-token) like before, but pass the authorization code we just obtained:
@ -71,17 +71,17 @@ curl \
If we've obtained our token and formatted our request correctly, we should see our details returned to us as an [Account]({{< relref "../entities/account.md" >}}) entity, with the `source` parameter included.
## Performing actions as the authorized user
## Performing actions as the authorized user {#actions}
With our OAuth token for the authorized user, we can now perform any action as that user that is within our token's scope.
### Publish and delete statuses
### Publish and delete statuses {#statuses}
* See [POST /api/v1/statuses](../methods/statuses/#publish-new-status) for how to create statuses.
* See [/api/v1/media]({{< relref "../methods/statuses/media.md" >}}) for creating media attachments.
* See [/api/v1/scheduled\_statuses]({{< relref "../methods/statuses/scheduled_statuses.md" >}}) for managing scheduled statuses.
### Interact with timelines
### Interact with timelines {#timelines}
* See [/api/v1/timelines]({{< relref "../methods/timelines/" >}}) for accessing timelines.
* See [/api/v1/markers]({{< relref "../methods/timelines/markers.md" >}}) for saving and loading positions in timelines.
@ -92,31 +92,31 @@ With our OAuth token for the authorized user, we can now perform any action as t
* See [/api/v1/favourites]({{< relref "../methods/accounts/favourites.md" >}}) for listing favourites.
* See [/api/v1/bookmarks]({{< relref "../methods/accounts/bookmarks.md" >}}) for listing bookmarks.
### Interact with other users
### 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/accounts/follow_requests.md" >}}) for handling follow requests.
* See [/api/v1/mutes]({{< relref "../methods/accounts/mutes.md" >}}) for listing mutes.
* See [/api/v1/blocks]({{< relref "../methods/accounts/blocks.md" >}}) for listing blocks.
### Receive notifications
### Receive notifications {#notifications}
* See [/api/v1/notifications]({{< relref "../methods/notifications/" >}}) for managing a user's notifications.
* See [/api/v1/push]({{< relref "../methods/notifications/push.md" >}}) for subscribing to push notifications.
### Discovery features
### Discovery features {#discovery}
* See [/api/v2/search]({{< relref "../methods/search.md" >}}) for querying resources.
* See [/api/v1/suggestions]({{< relref "../methods/accounts/suggestions.md" >}}) for suggested accounts to follow.
### Use safety features
### Use safety features {#safety}
* See [/api/v1/filters]({{< relref "../methods/accounts/filters.md" >}}) for managing filtered keywords.
* See [/api/v1/domain\_blocks]({{< relref "../methods/accounts/domain_blocks.md" >}}) for managing blocked domains.
* See [/api/v1/reports]({{< relref "../methods/accounts/reports.md" >}}) for creating reports.
* See [/api/v1/admin]({{< relref "../methods/admin.md" >}}) for moderator actions.
### Manage account info
### Manage account info {#manage}
* See [/api/v1/endorsements]({{< relref "../methods/accounts/endorsements.md" >}}) for managing a user profile's featured accounts.
* See [/api/v1/featured\_tags]({{< relref "../methods/accounts/featured_tags.md" >}}) for managing a user profile's featured hashtags.

15
content/en/client/guidelines.md
View File

@ -1,20 +1,21 @@
---
title: Guidelines and best practices
description: Things to keep in mind when implementing a Mastodon app.
menu:
docs:
weight: 50
parent: client
---
## Login <a id="login"></a>
## Login {#login}
**The user must be able to login to any Mastodon server from the app**. This means you must ask for the server's domain and use the app registrations API to dynamically obtain OAuth2 credentials.
## Usernames <a id="usernames"></a>
## Usernames {#username}
**Decentralization must be transparent to the user**. It should be possible to see that a given user is from another server, by e.g. displaying their `acct` somewhere. Note that `acct` is equal to username for local users, and equal to username@domain for remote users.
## Handling and sorting IDs
## Handling and sorting IDs {#id}
Vanilla Mastodon entity IDs are generated as integers and cast to string. However, this does not mean that IDs _are_ integers, nor should they be cast to integer! Doing so can lead to broken client apps due to integer overflow, so **always treat IDs as strings.**
@ -23,15 +24,15 @@ With that said, because IDs are string representations of numbers, they can stil
1. Sort by size. Newer statuses will have longer IDs.
2. Sort lexically. Newer statuses will have at least one digit that is higher when compared positionally.
## Formatting <a id="formatting"></a>
## Formatting {#formatting}
Plain text is not available for content from remote servers, and plain text syntax rules may vary wildly between Mastodon and other fediverse applications. For certain attributes, such as the content of statuses, **Mastodon provides sanitized HTML**. You may expect these tags to appear in the content: `<p>`, `<br>`, `<span>`, `<a>`. See [HTML Sanitization](../spec/activitypub.md#html-sanitization) for more details.
### Mentions, hashtags, and custom emoji <a id="mentions-and-hashtags"></a>
### Mentions, hashtags, and custom emoji {#tags}
Mentions and hashtags are `<a>` tags. Custom emoji remain in their plain text shortcode form. To give those entities their semantic meaning and add special handling, such as opening a mentioned profile within your app instead of as a web page, metadata is included with the [Status]({{< relref "../entities/status.md" >}}), which can be matched to a particular tag. See [Status &gt; Rendering attributes](../entities/status.md#rendering-attributes) for more information.
### Link shortening <a id="other-links"></a>
### Link shortening {#links}
Links in Mastodon are not shortened using URL shorteners, and the usage of URL shorteners is heavily discouraged. URLs in text always count for 23 characters, and are intended to be shortened visually. For that purpose, a link is marked up like this:
@ -45,7 +46,7 @@ Links in Mastodon are not shortened using URL shorteners, and the usage of URL s
The spans with the `invisible` class can be hidden. The middle span is intended to remain visible. It may have no class if the URL is not very long, otherwise it will have an `ellipsis` class. No ellipsis \(`…`\) character is inserted in the markup, instead, you are expected to insert it yourself if you need it in your app.
## Filters <a id="filters"></a>
## Filters {#filters}
Clients must do their own text filtering based on filters returned from the API. The server will apply `irreversible` filters for home and notifications context, but anything else is still up to the client to filter!

26
content/en/client/intro.md
View File

@ -7,11 +7,11 @@ menu:
parent: client
---
## An introduction to REST
## An introduction to REST {#rest}
Mastodon provides access to its data over a REST API. REST stands for REpresentational State Transfer, but for our purposes, just think of it as sending and receiving information about various resources based on the request. The Mastodon REST API uses HTTP for its requests, and JSON for its payloads.
## Understanding HTTP requests and responses
## Understanding HTTP requests and responses {#http}
REST API endpoints can be called with certain HTTP methods, and more than one method can be used on the same endpoint. The Mastodon API will generally use the following HTTP methods:
@ -24,7 +24,7 @@ Your favorite programming language probably has a utility or library to make HTT
With cURL, the default HTTP method is GET, but you can specify the type of request to make by using the `--request` or `-X` flag; for example, `curl -X POST` will send a POST request instead of a GET request. You may also want to use the `-i` flag to include additional HTTP headers that may be returned as part of the response where relevant.
## Providing parameters
## Providing parameters {#parameters}
HTTP requests can include additional parameters in various different ways, but most notably, the Mastodon API understands query strings, form data, and JSON.
@ -32,7 +32,7 @@ HTTP requests can include additional parameters in various different ways, but m
Query strings, form data, and JSON submitted via POST body are equally understood by the API. It is expected that query strings are used for GET requests, and form data or JSON is used for all other requests.
{{< /hint >}}
### Query strings
### Query strings {#query-strings}
Simply request the URL, but append query strings to the end. Query strings can be appended by first typing ? and then appending them in the form of parameter=value. Multiple query strings can be appended by separating them with &. For example:
@ -40,7 +40,7 @@ Simply request the URL, but append query strings to the end. Query strings can b
curl https://mastodon.example/endpoint?q=test&n=0
```
### Form data
### Form data {#form-data}
Instead of mutating the URL with query strings, you can send the data separately. With cURL, this is done by passing it with the `--data` or `-d` flag. Data may be sent together similar to query strings, or it may be sent separately as key-value pairs with multiple data flags. You may also use the `--form` or `-F` flag for key-value pairs, which also allows sending multipart data such as files. For example:
@ -62,20 +62,20 @@ curl -X POST \
https://mastodon.example/endpoint
```
### JSON
### JSON {#json}
Similar to sending form data, but with an additional header to specify that the data is in JSON format. To send a JSON request with cURL, specify the JSON content type with a header, then send the JSON data as form data:
```bash
curl -X POST \
-H 'Content-Type: application/json' \
-d '{"parameter": "value"}' \
-d '{"parameter": "value}' \
https://mastodon.example/endpoint
```
## Data types
## Data types {#types}
### Multiple values \(Array\)
### Multiple values \(Array\) {#array}
An array parameter must encoded using bracket notation, e.g. `array[]=foo&array[]=bar` would be translated into the following:
@ -94,7 +94,7 @@ As JSON, arrays are formatted like so:
}
```
### Nested parameters \(Hash\)
### Nested parameters \(Hash\) {#hash}
Some parameters need to be nested. For that, bracket notation must also be used. For example, `source[privacy]=public&source[language]=en` would be translated into:
@ -116,17 +116,17 @@ As JSON, hashes are formatted like so:
}
```
### True-or-false \(Booleans\)
### True-or-false \(Booleans\) {#boolean}
A boolean value is considered false for the values `0`, `f`, `F`, `false`, `FALSE`, `off`, `OFF`, considered to not be provided for empty strings, and considered to be true for all other values. When using JSON data, use the literals `true`, `false`, and `null` instead.
### Files
### Files {#file}
File uploads must be encoded using `multipart/form-data`.
This can be combined with arrays as well.
## How to use API response data
## How to use API response data {#responses}
The Mastodon REST API will return JSON as the response text. It also returns HTTP headers which may be useful in handling the response, as well as an HTTP status code which should let you know how the server handled the request. The following HTTP status codes may be expected:

40
content/en/client/libraries.md
View File

@ -7,11 +7,11 @@ menu:
parent: client
---
## Apex \(Salesforce\) <a id="apex-salesforce"></a>
## Apex \(Salesforce\) {#apex-salesforce}
* [apex-mastodon](https://github.com/tzmfreedom/apex-mastodon)
## C\# \(.NET Standard\) <a id="c-net-standard"></a>
## C\# \(.NET Standard\) {#c-net-standard}
* [Mastodot](https://github.com/yamachu/Mastodot)
* [Mastonet](https://github.com/glacasa/Mastonet)
@ -19,54 +19,54 @@ menu:
* [mastodon-api-cs](https://github.com/pawotter/mastodon-api-cs)
* [Mastodon.Net](https://github.com/Tlaster/Mastodon.Net)
## C++ <a id="c"></a>
## C++ {#c}
* [mastodon-cpp](https://github.com/tastytea/mastodon-cpp)
## Crystal <a id="crystal"></a>
## Crystal {#crystal}
* [mastodon.cr](https://github.com/decors/mastodon.cr)
## Common Lisp <a id="common-lisp"></a>
## Common Lisp {#common-lisp}
* [tooter](https://github.com/Shinmera/tooter)
## Elixir <a id="elixir"></a>
## Elixir {#elixir}
* [hunter](https://github.com/milmazz/hunter)
## Go <a id="go"></a>
## Go {#go}
* [go-mastodon](https://github.com/mattn/go-mastodon)
* [madon](https://github.com/McKael/madon)
## Haskell <a id="haskell"></a>
## Haskell {#haskell}
* [hastodon](https://github.com/syucream/hastodon)
## Java <a id="java"></a>
## Java {#java}
* [mastodon4j](https://github.com/sys1yagi/mastodon4j)
## JavaScript <a id="javascript"></a>
## JavaScript {#javascript}
* [masto.js](https://github.com/neet/masto.js)
* [libodonjs](https://github.com/Zatnosk/libodonjs)
## JavaScript \(Browser\) <a id="javascript-browser"></a>
## JavaScript \(Browser\) {#javascript-browser}
* [mastodon.js](https://github.com/Kirschn/mastodon.js)
## JavaScript \(Node.js\) <a id="javascript-node-js"></a>
## JavaScript \(Node.js\) {#javascript-node-js}
* [node-mastodon](https://github.com/jessicahayley/node-mastodon)
* [mastodon-api](https://github.com/vanita5/mastodon-api)
## Perl <a id="perl"></a>
## Perl {#perl}
* [Mastodon::Client](https://metacpan.org/pod/Mastodon::Client)
## PHP <a id="php"></a>
## PHP {#php}
* [Mastodon API for Laravel](https://github.com/kawax/laravel-mastodon-api)
* [Mastodon-api-php](https://github.com/yks118/Mastodon-api-php)
@ -77,28 +77,28 @@ menu:
* [oauth2-mastodon](https://github.com/lrf141/oauth2-mastodon)
* [Mastodon Wordpress API](https://github.com/L1am0/mastodon_wordpress_api)
## Python <a id="python"></a>
## Python {#python}
* [Mastodon.py](https://github.com/halcy/Mastodon.py)
## R <a id="r"></a>
## R {#r}
* [mastodon](https://github.com/ThomasChln/mastodon)
## Ruby <a id="ruby"></a>
## Ruby {#ruby}
* [mastodon-api](https://github.com/tootsuite/mastodon-api)
## Rust <a id="rust"></a>
## Rust {#rust}
* [mammut](https://github.com/Aaronepower/mammut)
* [elefren](https://github.com/pwoolcoc/elefren)
## Scala <a id="scala"></a>
## Scala {#scala}
* [scaladon](https://github.com/schwitzerm/scaladon)
## Swift <a id="swift"></a>
## Swift {#swift}
* [MastodonKit](https://github.com/ornithocoder/MastodonKit)

8
content/en/client/public.md
View File

@ -9,13 +9,13 @@ menu:
Now that you know how to construct HTTP requests using cURL or your favorite programming language's HTTP utility or library, it is time to learn about endpoints and responses.
## Endpoints explained
## Endpoints explained {#endpoints}
All HTTP requests are made against a target URL. When you request data to or from a website, you do so by using a specific URL. Depending on the URL, your request will be interpreted by the HTTP server and the appropriate response will be returned to you.
Examples will be written using the fictional Mastodon website, mastodon.example, which is hosted at `https://mastodon.example`. The root of this website is `/`, and specific subdirectories and paths are known as endpoints. Mastodon's API endpoints are nested under the `/api` namespace, and most methods currently have their endpoints under `/api/v1`. Requests will be listed by their HTTP method and their endpoint; for example, GET /api/v1/endpoint should be interpreted as a GET request made to that endpoint on your domain, or in other words, `https://mastodon.example/api/v1/endpoint`.
## Fetching public timelines
## Fetching public timelines {#timelines}
Let's take a look at one of the most basic use cases for public data from Mastodon -- the public timelines.
@ -78,7 +78,7 @@ Parsing JSON and using it in your program is outside of the scope of this tutori
[MastoVue](https://mastovue.glitch.me) is an example of an application that lets you browse public timelines.
{{< /hint >}}
## Fetching public accounts and statuses
## Fetching public accounts and statuses {#toots}
Now that we are familiar with how to make requests and how to handle responses, you can experiment with more public data. The following methods may be of interest:
@ -92,7 +92,7 @@ Now that we are familiar with how to make requests and how to handle responses,
IDs of accounts and statuses are local to the Mastodon website's database and will differ for each Mastodon website.
## Fetching public instance data
## Fetching public instance data {#instance}
One last thing you can do with anonymous requests is to view information about the Mastodon website.

8
content/en/client/token.md
View File

@ -7,13 +7,13 @@ menu:
parent: client
---
## Authentication and authorization
## Authentication and authorization {#auth}
Up until this point, we've been working with publicly available information, but not all information is public. Some information requires permission before viewing it, in order to audit who is requesting that information \(and to potentially revoke or deny access\).
This is where [OAuth]({{< relref "../spec/oauth.md" >}}) comes in. OAuth is a mechanism for generating access tokens which can be used to _authenticate \(verify\)_ that a request is coming from a specific client, and ensure that the requested action is _authorized \(allowed\)_ by the server's access control policies.
## **Creating our application**
## Creating our application {#app}
The first thing we will need to do is to register an application, in order to be able to generate access tokens later. The application can be created like so:
@ -33,7 +33,7 @@ In the above example, we specify the client name and website, which will be show
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](../methods/apps/#create-an-application) for more details on registering applications.
## **Example authentication code flow**
## Example authentication code flow {#flow}
Now that we have an application, let's obtain an access token that will authenticate our requests as that client application. To do so, use [POST /oauth/token](../methods/apps/oauth.md#obtain-a-token) like so:
@ -62,7 +62,7 @@ curl \
If we've obtained our token and formatted our request correctly, we should see our details returned to us as an [Application]({{< relref "../entities/application.md" >}}) entity.
## What we can do with authentication
## What we can do with authentication {#methods}
With our authenticated client application, we can view relations of an account with [GET /api/v1/accounts/:id/following](../methods/accounts/#following) and [GET /api/v1/accounts/:id/followers](../methods/accounts/#followers). Also, some instances may require authentication for methods that would otherwise be public, so if you encountered any authentication errors while playing around with public methods, then those methods should now work.

13
content/en/dev/code.md
View File

@ -1,5 +1,6 @@
---
title: Code structure
description: Where to find certain parts of the codebase.
menu:
docs:
weight: 30
@ -10,11 +11,11 @@ menu:
This page is under construction.
{{< /hint >}}
### Code structure <a id="code-structure"></a>
### 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.
#### Ruby <a id="ruby-1"></a>
#### Ruby {#ruby}
| Path | Description |
| :--- | :--- |
@ -28,28 +29,28 @@ The following overview should not be seen as complete or authoritative, but as a
| `app/workers` | Code that executes outside the request-response cycle |
| `spec` | Automated test suite |
#### JavaScript <a id="javascript-1"></a>
#### JavaScript {#javascript}
| Path | Description |
| :--- | :--- |
| `app/javascript/mastodon` | Code for the multi-column React.js application |
| `app/javascript/packs` | Code for non-React.js pages |
#### CSS and other assets <a id="css-and-other-assets"></a>
#### CSS and other assets {#assets}
| Path | Description |
| :--- | :--- |
| `app/javascript/images` | Images |
| `app/javascript/styles` | Code that turns into CSS via Sass |
#### Localizations <a id="localizations"></a>
#### Localizations {#localizations}
| Path | Description |
| :--- | :--- |
| `config/locales` | Server-side localizations in the YML format |
| `app/javascript/mastodon/locales` | Client-side localizations in the JSON format |
### Localization maintenance <a id="localization-maintenance"></a>
### Localization maintenance {#localization-maintenance}
All locale files are normalized to ensure consistent formatting and key order, which minimizes changesets in version control.

3
content/en/dev/overview.md
View File

@ -1,5 +1,6 @@
---
title: Technical overview
description: A description of Mastodon's architecture.
menu:
docs:
weight: 10
@ -14,7 +15,7 @@ Mastodon is a Ruby on Rails application with a React.js front-end. It follows s
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.
### Environments <a id="environments"></a>
### Environments {#environments}
An “environment” is a set of configuration values intended for a specific use case. Some environments could be: development, in which you intend to change the code; test, in which you intend to run the automated test suite; staging, which is meant to preview the code to end-users; and production, which is intended to face end-users. Mastodon comes with configurations for development, test and production.

24
content/en/dev/routes.md
View File

@ -7,15 +7,13 @@ menu:
parent: dev
---
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/config/routes.rb" caption="config/routes.rb" >}}
## Explanation of routes
## Explanation of routes {#routes}
Mastodon uses Ruby on Rails, which defines its router configuration at config/routes.rb. You may view the [Ruby on Rails routing guide](https://guides.rubyonrails.org/routing.html) for more detailed information, but this page will explain the basics of how Mastodon handles routing.
### How routes are constructed
### How routes are constructed {#router}
`namespace` is a prefix for routes mapped to a certain controller directory. `resources` are mapped to controllers within that namespace directory. `scope` passes to the `module`'s controller. For example, consider the following abbreviated code:
@ -43,7 +41,7 @@ Within /api/v1/statuses, there is a scope for a module :statuses, where addition
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.
### Available methods
### Available methods {#methods}
#### :index
@ -65,25 +63,25 @@ Maps to HTTP PUT. Handled by the \#update action in a controller.
Maps to HTTP DELETE. Handled by the \#destroy action in a controller.
## .well-known
## .well-known {#well-known}
### /.well-known/host-meta
### /.well-known/host-meta {#host-meta}
Extensible Resource Descriptor \(XRD\). Advertises existence of Webfinger.
### /.well-known/nodeinfo
### /.well-known/nodeinfo {#nodeinfo}
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
### /.well-know/webfinger {#webfinger}
Used for discovering ActivityPub actor id. See [Spec compliance &gt; WebFinger]({{< relref "../spec/webfinger.md" >}}) for more information.
### /.well-known/change-password
### /.well-known/change-password {#change-password}
Maps to account settings page.
### /.well-known/keybase-proof-config
### /.well-known/keybase-proof-config {#keybase}
Used for integration with Keybase, defining which usernames are acceptable and where proofs may be checked.
@ -91,7 +89,7 @@ Used for integration with Keybase, defining which usernames are acceptable and w
The sections below this point are under construction.
{{< /hint >}}
## Public URIs
## Public URIs {#public}
* `/users/username` = user URI
* `/users/username/remote_follow` = remote follow dialog
@ -110,7 +108,7 @@ The sections below this point are under construction.
* `/about/more` = extended description
* `/terms` = terms of service
## API
## API {#api}
* /api/oembed
* /api/proofs

7
content/en/dev/setup.md
View File

@ -1,5 +1,6 @@
---
title: Setting up a dev environment
description: Instructions on how to start developing for Mastodon.
menu:
docs:
weight: 20
@ -10,7 +11,7 @@ menu:
This page is under construction.
{{< /hint >}}
### Setup <a id="setup"></a>
### Setup {#setup}
Run following commands in the project directory `bundle install`, `yarn install`.
@ -18,7 +19,7 @@ In the development environment, Mastodon will use PostgreSQL as the currently si
> Please keep in mind, by default Mastodon will run on port 3000. If you configure a different port for it, the generated admin account will use that number.
### Running <a id="running"></a>
### Running {#running}
There are multiple processes that need to be run for the full set of Mastodon’s functionality, although they can be selectively omitted. To run all of them with just one command, you can install Foreman with `gem install foreman --no-document` and then use:
@ -28,7 +29,7 @@ foreman start
In the Mastodon directory. This will start processes defined in `Procfile.dev`, which will give you: A Rails server, a Webpack server, a streaming API server, and Sidekiq. Of course, you can run any of those things stand-alone depending on your needs.
### Testing <a id="testing"></a>
### Testing {#testing}
| Command | Description |
| :--- | :--- |

136
content/en/entities/account.md
View File

@ -17,7 +17,7 @@ menu:
"locked": false,
"bot": false,
"created_at": "2017-02-08T02:00:53.274Z",
"note": "<p>:ms_rainbow_flag:​ :ms_bisexual_flagweb:​ :ms_nonbinary_flag:​ <a href=\"https://awoo.space/tags/awoo\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>awoo</span></a>.space <a href=\"https://awoo.space/tags/admin\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>admin</span></a> ~ <a href=\"https://awoo.space/tags/bi\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>bi</span></a> ~ <a href=\"https://awoo.space/tags/nonbinary\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>nonbinary</span></a> ~ compsci student ~ likes video <a href=\"https://awoo.space/tags/games\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>games</span></a> and weird/ old electronics and will post obsessively about both ~ avatar by <span class=\"h-card\"><a href=\"https://weirder.earth/@dzuk\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>dzuk</span></a></span></p>",
"note": "<p>:ms_rainbow_flag:​ :ms_bisexual_flagweb:​ :ms_nonbinary_flag:​ <a href=\"https://awoo.space/tags/awoo\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>awoo</span}.space <a href=\"https://awoo.space/tags/admin\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>admin</span} ~ <a href=\"https://awoo.space/tags/bi\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>bi</span} ~ <a href=\"https://awoo.space/tags/nonbinary\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>nonbinary</span} ~ compsci student ~ likes video <a href=\"https://awoo.space/tags/games\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>games</span} and weird/ old electronics and will post obsessively about both ~ avatar by <span class=\"h-card\"><a href=\"https://weirder.earth/@dzuk\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>dzuk</span}</span></p>",
"url": "https://awoo.space/@noiob",
"avatar": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png",
"avatar_static": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png",
@ -55,17 +55,17 @@ menu:
},
{
"name": "Alt",
"value": "<span class=\"h-card\"><a href=\"https://cybre.space/@noiob\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>noiob</span></a></span>",
"value": "<span class=\"h-card\"><a href=\"https://cybre.space/@noiob\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>noiob</span}</span>",
"verified_at": null
},
{
"name": "Bots",
"value": "<span class=\"h-card\"><a href=\"https://botsin.space/@darksouls\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>darksouls</span></a></span>, <span class=\"h-card\"><a href=\"https://botsin.space/@nierautomata\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>nierautomata</span></a></span>, <span class=\"h-card\"><a href=\"https://mastodon.social/@fedi\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>fedi</span></a></span>, code for <span class=\"h-card\"><a href=\"https://botsin.space/@awoobot\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>awoobot</span></a></span>",
"value": "<span class=\"h-card\"><a href=\"https://botsin.space/@darksouls\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>darksouls</span}</span>, <span class=\"h-card\"><a href=\"https://botsin.space/@nierautomata\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>nierautomata</span}</span>, <span class=\"h-card\"><a href=\"https://mastodon.social/@fedi\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>fedi</span}</span>, code for <span class=\"h-card\"><a href=\"https://botsin.space/@awoobot\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>awoobot</span}</span>",
"verified_at": null
},
{
"name": "Website",
"value": "<a href=\"http://shork.xyz\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">http://</span><span class=\"\">shork.xyz</span><span class=\"invisible\"></span></a>",
"value": "<a href=\"http://shork.xyz\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">http://</span><span class=\"\">shork.xyz</span><span class=\"invisible\"></span}",
"verified_at": "2019-11-10T10:31:10.744+00:00"
}
]
@ -74,139 +74,139 @@ menu:
## Base attributes
### **`id`**
### **`id`** {#id}
**Description:** The account id`header`.
**Type:** String \(cast from an integer, but not guaranteed to be a number\)
**Description:** The account id`header`.\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Version history:** Added in 0.1.0
### `username`
### `username` {#username}
**Description:** The username of the account, not including domain.
**Type:** String
**Description:** The username of the account, not including domain.\
**Type:** String\
**Version history:** Added in 0.1.0
### `acct`
### `acct` {#acct}
**Description:** The Webfinger account URI.
Equal to `username` for local users, or `username@domain` for remote users.
**Type:** String
Equal to `username` for local users, or `username@domain` for remote users.\
**Type:** String\
**Version history:** Added in 0.1.0
### `url`
### `url` {#url}
**Description:** The location of the user's profile page.
**Type:** String \(HTTPS URL\)
**Description:** The location of the user's profile page.\
**Type:** String \(HTTPS URL\)\
**Version history:** Added in 0.1.0
## Display attributes
### `display_name`
### `display_name` {#display_name}
**Description:** The profile's display name.
**Type:** String
**Description:** The profile's display name.\
**Type:** String\
**Version history:** Added in 0.1.0
### `note`
### `note` {#note}
**Description:** The profile's bio / description.
**Type:** String
**Description:** The profile's bio / description.\
**Type:** String\
**Version history:** Added in 0.1.0
### `avatar`
### `avatar` {#avatar}
**Description:** An image icon that is shown next to statuses and in the profile.
**Type:** String \(URL\)
**Description:** An image icon that is shown next to statuses and in the profile.\
**Type:** String \(URL\)\
**Version history:** Added in 0.1.0
### `avatar_static`
### `avatar_static` {#avatar_static}
**Description:** A static version of the avatar.
Equal to `avatar` if its value is a static image; different if `avatar` is an animated GIF.
**Type:** String \(URL\)
Equal to `avatar` if its value is a static image; different if `avatar` is an animated GIF.\
**Type:** String \(URL\)\
**Version history:** Added in 1.1.2
### `header`
### `header` {#header}
**Description:** An image banner that is shown above the profile and in profile cards.
**Type:** String \(URL\)
**Description:** An image banner that is shown above the profile and in profile cards.\
**Type:** String \(URL\)\
**Version history:** Added in 0.1.0
### `header_static`
### `header_static` {#header_static}
**Description:** A static version of the header.
Equal to `header` if its value is a static image; different if `header` is an animated GIF.
**Type:** String \(URL\)
Equal to `header` if its value is a static image; different if `header` is an animated GIF.\
**Type:** String \(URL\)\
**Version history:** Added in 1.1.2
### `locked`
### `locked` {#locked}
**Description:** Whether the account manually approves follow requests.
**Type:** Boolean
**Description:** Whether the account manually approves follow requests.\
**Type:** Boolean\
**Version history:** Added in 0.1.0
### `emojis`
### `emojis` {#emojis}
**Description:** Custom emoji entities to be used when rendering the profile. If none, an empty array will be returned.
**Type:** Array of [Emoji](emoji.md)
**Description:** Custom emoji entities to be used when rendering the profile. If none, an empty array will be returned.\
**Type:** Array of [Emoji](emoji.md)\
**Version history:** Added in 2.4.0
### `discoverable`
### `discoverable` {#discoverable}
**Description:** Whether the account has opted into discovery features such as the profile directory.
**Type:** Boolean
**Description:** Whether the account has opted into discovery features such as the profile directory.\
**Type:** Boolean\
**Version history:** Added in 3.1.0
## Statistical attributes
## Statistical attributes
### `created_at`
### `created_at` {#created_at}
**Description:** When the account was created.
**Type:** String \(ISO 8601 Datetime\)
**Description:** When the account was created.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:** Added in 0.1.0
### `statuses_count`
### `statuses_count` {#statuses_count}
**Description:** How many statuses are attached to this account.
**Type:** Number
**Description:** How many statuses are attached to this account.\
**Type:** Number\
**Version history:** Added in 0.1.0
### `followers_count`
### `followers_count` {#followers_count}
**Description:** The reported followers of this profile.
**Type:** Number
**Description:** The reported followers of this profile.\
**Type:** Number\
**Version history:** Added in 0.1.0
### `following_count`
### `following_count` {#following_count}
**Description:** The reported follows of this profile.
**Type:** Number
**Description:** The reported follows of this profile.\
**Type:** Number\
**Version history:** Added in 0.1.0
## Optional attributes
### `moved`
### `moved` {#moved}
**Description:** Indicates that the profile is currently inactive and that its user has moved to a new account.
**Type:** [Account](account.md)
**Description:** Indicates that the profile is currently inactive and that its user has moved to a new account.\
**Type:** [Account](account.md)\
**Version history:** Added in 2.1.0
### `fields`
### `fields` {#fields}
**Description:** Additional metadata attached to a profile as name-value pairs.
**Type:** Array of [Field]({{< relref "field.md" >}})
**Description:** Additional metadata attached to a profile as name-value pairs.\
**Type:** Array of [Field]({{< relref "field.md" >}})\
**Version history:** Added in 2.4.0
### `bot`
### `bot` {#bot}
**Description:** A presentational flag. Indicates that the account may perform automated actions, may not be monitored, or identifies as a robot.
**Type:** Boolean
**Description:** A presentational flag. Indicates that the account may perform automated actions, may not be monitored, or identifies as a robot.\
**Type:** Boolean\
**Version history:** Added in 2.4.0
### `source`
### `source` {#source}
**Description:** An extra entity to be used with API methods to [verify credentials](../methods/accounts/#verify-account-credentials) and [update credentials](../methods/accounts/#update-account-credentials).
**Type:** [Source](source.md)
**Description:** An extra entity to be used with API methods to [verify credentials](../methods/accounts/#verify-account-credentials) and [update credentials](../methods/accounts/#update-account-credentials).\
**Type:** [Source](source.md)\
**Version history:** Added in 2.4.0
## See also

24
content/en/entities/activity.md
View File

@ -19,28 +19,28 @@ menu:
## Attributes
### `week`
### `week` {#week}
**Description:** Midnight at the first day of the week.
**Type:** String \(UNIX Timestamp\)
**Description:** Midnight at the first day of the week.\
**Type:** String \(UNIX Timestamp\)\
**Version history:** Added in 2.1.2
### `statuses`
### `statuses` {#statuses}
**Description:** Statuses created since the week began.
**Type:** String \(cast from an integer\)
**Description:** Statuses created since the week began.\
**Type:** String \(cast from an integer\)\
**Version history:** Added in 2.1.2
### `logins`
### `logins` {#logins}
**Description:** User logins since the week began.
**Type:** String \(cast from an integer\)
**Description:** User logins since the week began.\
**Type:** String \(cast from an integer\)\
**Version history:** Added in 2.1.2
### `registrations`
### `registrations` {#registrations}
**Description:** User registrations since the week began.
**Type:** String \(cast from an integer\)
**Description:** User registrations since the week began.\
**Type:** String \(cast from an integer\)\
**Version history:** Added in 2.1.2
## See also

100
content/en/entities/admin-account.md
View File

@ -14,110 +14,110 @@ menu:
## Attributes
### `id`
### `id` {#id"></a>
**Description:** The ID of the account in the database.
**Type:** String \(cast from an integer, but not guaranteed to be a number\)
**Description:** The ID of the account in the database.\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Version history:** Added in 2.9.1
### `username`
### `username` {#username"></a>
**Description:** The username of the account.
**Type:** String
**Description:** The username of the account.\
**Type:** String\
**Version history:** Added in 2.9.1
### `domain`
### `domain` {#domain"></a>
**Description:** The domain of the account.
**Type:** String
**Description:** The domain of the account.\
**Type:** String\
**Version history:** Added in 2.9.1
### `created_at`
### `created_at` {#created_at"></a>
**Description:** When the account was first discovered.
**Type:** String \(ISO 8601 Datetime\)
**Description:** When the account was first discovered.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:** Added in 2.9.1
### `email`
### `email` {#email"></a>
**Description:** The email address associated with the account.
**Type:** String
**Description:** The email address associated with the account.\
**Type:** String\
**Version history:** Added in 2.9.1
### `ip`
### `ip` {#ip"></a>
**Description:** The IP address last used to login to this account.
**Type:** String
**Description:** The IP address last used to login to this account.\
**Type:** String\
**Version history:** Added in 2.9.1
### `locale`
### `locale` {#locale"></a>
**Description:** The locale of the account.
**Type:** String \(ISO 639 Part 1 two-letter language code\)
**Description:** The locale of the account.\
**Type:** String \(ISO 639 Part 1 two-letter language code\)\
**Version history:** Added in 2.9.1
### `invite_request`
### `invite_request` {#invite_request"></a>
**Description:** Invite request text ???
**Type:** String
**Description:** Invite request text ???\
**Type:** String\
**Version history:** Added in 2.9.1
## State attributes
### `role`
### `role` {#role"></a>
**Description:** The current role of the account.
**Type:** String \(Enumerable oneOf\)
**Description:** The current role of the account.\
**Type:** String \(Enumerable oneOf\)\
**Version history:** Added in 2.9.1
### `confirmed`
### `confirmed` {#confirmed"></a>
**Description:** Whether the account has confirmed their email address.
**Type:** Boolean
**Description:** Whether the account has confirmed their email address.\
**Type:** Boolean\
**Version history:** Added in 2.9.1
### `approved`
### `approved` {#approved"></a>
**Description:** Whether the account is currently approved.
**Type:** Boolean
**Description:** Whether the account is currently approved.\
**Type:** Boolean\
**Version history:** Added in 2.9.1
### `disabled`
### `disabled` {#disabled"></a>
**Description:** Whether the account is currently disabled.
**Type:** Boolean
**Description:** Whether the account is currently disabled.\
**Type:** Boolean\
**Version history:** Added in 2.9.1
### `silenced`
### `silenced` {#silenced"></a>
**Description:** Whether the account is currently silenced.
**Type:** Boolean
**Type:** Boolean\
**Version history:** Added in 2.9.1
### `suspended`
### `suspended` {#suspended"></a>
**Description:** Whether the account is currently suspended.
**Type:** Boolean
**Description:** Whether the account is currently suspended.\
**Type:** Boolean\
**Version history:** Added in 2.9.1
### `account`
### `account` {#account"></a>
**Description:** User-level information about the account.
**Type:** Account
**Description:** User-level information about the account.\
**Type:** Account\
**Version history:** Added in 2.9.1
## Nullable attributes
### `created_by_application_id`
### `created_by_application_id` {#created_by_application_id"></a>
**Description:** The ID of the application that created this account.
**Type:** String \(cast from an integer, but not guaranteed to be a number\)
**Description:** The ID of the application that created this account.\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Version history:** Added in 2.9.1
### `invited_by_account_id`
### `invited_by_account_id` {#invited_by_account_id"></a>
**Description:** The ID of the account that invited this user
**Type:** String \(cast from an integer, but not guaranteed to be a number\)
**Description:** The ID of the account that invited this user\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Version history:** Added in 2.9.1
## See also

60
content/en/entities/admin-report.md
View File

@ -14,64 +14,64 @@ menu:
## Attributes
### `id`
### `id` {#id}
**Description:** The ID of the report in the database.
**Type:** String \(cast from an integer, but not guaranteed to be a number\)
**Description:** The ID of the report in the database.\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Version history:** Added in 2.9.1
### `action_taken`
### `action_taken` {#action_taken}
**Description:** The action
**Type:** String \(Enumerable oneOf\)
**Description:** The action taken to resolve this report.\
**Type:** String \(Enumerable oneOf\)\
**Version history:** Added in 2.9.1
### `comment`
### `comment` {#comment}
**Description:** An optional reason for reporting.
**Type:** String
**Description:** An optional reason for reporting.\
**Type:** String\
**Version history:** Added in 2.9.1
### `created_at`
### `created_at` {#created_at}
**Description:** The time the report was filed.
**Type:** String \(ISO 8601 Datetime\)
**Description:** The time the report was filed.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:** Added in 2.9.1
### `updated_at`
### `updated_at` {#updated_at}
**Description:** The time of last action on this report.
**Type:** String \(ISO 8601 Datetime\)
**Description:** The time of last action on this report.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:** Added in 2.9.1
### `account`
### `account` {#account}
**Description:** The account which filed the report.
**Type:** [Account](account.md)
**Description:** The account which filed the report.\
**Type:** [Account](account.md)\
**Version history:** Added in 2.9.1
### `target_account`
### `target_account` {#target_account}
**Description:** The account being reported.
**Type:** [Account](account.md)
**Description:** The account being reported.\
**Type:** [Account](account.md)\
**Version history:** Added in 2.9.1
### `assigned_account`
### `assigned_account` {#assigned_account}
**Description:** The account of the moderator assigned to this report.
**Type:** [Account](account.md)
**Description:** The account of the moderator assigned to this report.\
**Type:** [Account](account.md)\
**Version history:** Added in 2.9.1
### `action_taken_by_account`
### `action_taken_by_account` {#action_taken_by_account}
**Description:** The action taken by the moderator who handled the report.
**Type:** String \(Enumerable oneOf\)
**Description:** The action taken by the moderator who handled the report.\
**Type:** String \(Enumerable oneOf\)\
**Version history:** Added in 2.9.1
### `statuses`
### `statuses` {#statuses}
**Description:** Statuses attached to the report, for context.
**Type:** Array of [Status](status.md)
**Description:** Statuses attached to the report, for context.\
**Type:** Array of [Status](status.md)\
**Version history:** Added in 2.9.1
## See also

34
content/en/entities/application.md
View File

@ -1,8 +1,6 @@
---
title: Application
description: >-
Represents an application that interfaces with the REST API to access accounts
or post statuses.
description: Represents an application that interfaces with the REST API to access accounts or post statuses.
menu:
docs:
parent: entities
@ -20,38 +18,38 @@ menu:
## Required attributes
### `name`
### `name` {#name}
**Description:** The name of your application.
**Type:** String
**Description:** The name of your application.\
**Type:** String\
**Version history:** Added in 0.9.9
## Optional attributes
### `website`
### `website` {#website}
**Description:** The website associated with your application.
**Type:** String \(URL\)
**Description:** The website associated with your application.\
**Type:** String \(URL\)\
**Version history:** Added in 0.9.9
### `vapid_key`
### `vapid_key` {#vapid_key}
**Description:** Used for Push Streaming API. Returned with [POST /api/v1/apps](../methods/apps/#create-an-application). Equivalent to [PushSubscription\#server\_key](push-subscription.md#server_key)
**Type:** String
**Description:** Used for Push Streaming API. Returned with [POST /api/v1/apps](../methods/apps/#create-an-application). Equivalent to [PushSubscription\#server\_key](push-subscription.md#server_key)\
**Type:** String\
**Version history:** Added in 2.8.0
## Client attributes
### client\_id
### `client_id` {#client_id}
**Description:** Client ID key, to be used for obtaining OAuth tokens
**Type:** String
**Description:** Client ID key, to be used for obtaining OAuth tokens\
**Type:** String\
**Version history:** Added in 0.9.9
### client\_secret
### `client_secret` {#client_secret}
**Description:** Client secret key, to be used for obtaining OAuth tokens
**Type:** String
**Description:** Client secret key, to be used for obtaining OAuth tokens\
**Type:** String\
**Version history:** Added in 0.9.9
## See also

64
content/en/entities/attachment.md
View File

@ -148,69 +148,69 @@ menu:
## Required attributes
### `id`
### `id` {#id}
**Description:** The ID of the attachment in the database.
**Type:** String \(cast from an integer but not guaranteed to be a number\)
**Description:** The ID of the attachment in the database.\
**Type:** String \(cast from an integer but not guaranteed to be a number\)\
**Version history:** Added in 0.6.0.
### `type`
### `type` {#type}
**Description:** The type of the attachment.
**Type:** String \(Enumerable, oneOf\)
- `unknown` = unsupported or unrecognized file type
- `image` = Static image
- `gifv` = Looping, soundless animation
- `video` = Video clip
- `audio` = Audio track
**Description:** The type of the attachment.\
**Type:** String \(Enumerable, oneOf\)\
`unknown` = unsupported or unrecognized file type\
`image` = Static image\
`gifv` = Looping, soundless animation\
`video` = Video clip\
`audio` = Audio track\
**Version history:** Added in 0.6.0. Audio added in 2.9.1.
### `url`
### `url` {#url}
**Description:** The location of the original full-size attachment.
**Type:** String \(URL\)
**Description:** The location of the original full-size attachment.\
**Type:** String \(URL\)\
**Version history:** Added in 0.6.0.
### `preview_url`
### `preview_url` {#preview_url}
**Description:** The location of a scaled-down preview of the attachment.
**Type:** String \(URL\)
**Description:** The location of a scaled-down preview of the attachment.\
**Type:** String \(URL\)\
**Version history:** Added in 0.6.0.
## Optional attributes
### `remote_url`
### `remote_url` {#remote_url}
**Description:** The location of the full-size original attachment on the remote website.
**Type:** String \(URL\), or null if the attachment is local
**Description:** The location of the full-size original attachment on the remote website.\
**Type:** String \(URL\), or null if the attachment is local\
**Version history:** Added in 0.6.0.
### `text_url`
### `text_url` {#text_url}
**Description:** A shorter URL for the attachment.
**Type:** String \(URL\)
**Description:** A shorter URL for the attachment.\
**Type:** String \(URL\)\
**Version history:** Added in 0.6.0.
### `meta`
### `meta` {#meta}
**Description:** Metadata returned by Paperclip.
**Type:** Hash
**Description:** Metadata returned by Paperclip.\
**Type:** Hash\
**Version history:** Added in 1.5.0. meta\[focus\] added in 2.3.0.
May contain subtrees `small` and `original`, as well as various other top-level properties.
More importantly, there may be another top-level `focus` Hash object as of 2.3.0, with coordinates can be used for smart thumbnail cropping -- see [Focal points](../methods/statuses/media.md#focal-points) for more.
### `description`
### `description` {#description}
**Description:** Alternate text that describes what is in the media attachment, to be used for the visually impaired or when media attachments do not load.
**Type:** String
**Description:** Alternate text that describes what is in the media attachment, to be used for the visually impaired or when media attachments do not load.\
**Type:** String\
**Version history:** Added in 2.0.0
### `blurhash`
### `blurhash` {#blurhash}
**Description:** A hash computed by [the BlurHash algorithm](https://github.com/woltapp/blurhash), for generating colorful preview thumbnails when media has not been downloaded yet.
**Type:** String
**Description:** A hash computed by [the BlurHash algorithm](https://github.com/woltapp/blurhash), for generating colorful preview thumbnails when media has not been downloaded yet.\
**Type:** String\
**Version history:** Added in 2.8.1
## See also

94
content/en/entities/card.md
View File

@ -1,8 +1,6 @@
---
title: Card
description: >-
Represents a rich preview card that is generated using OpenGraph tags from a
URL.
description: Represents a rich preview card that is generated using OpenGraph tags from a URL.
menu:
docs:
parent: entities
@ -72,88 +70,88 @@ menu:
## Required attributes
### `url`
### `url` {#url}
**Description:** Location of linked resource.
**Type:** String \(URL\)
**Description:** Location of linked resource.\
**Type:** String \(URL\)\
**Version history:** Added in 1.0.0
### `title`
### `title` {#title}
**Description:** Title of linked resource.
**Type:** String
**Description:** Title of linked resource.\
**Type:** String\
**Version history:** Added in 1.0.0
### `description`
### `description` {#description}
**Description:** Description of preview.
**Type:** String
**Description:** Description of preview.\
**Type:** String\
**Version history:** Added in 1.0.0
### `type`
### `type` {#type}
**Description:** The type of the preview card.
**Type:** String \(Enumerable, oneOf\)
- `link` = Link OEmbed
- `photo` = Photo OEmbed
- `video` = Video OEmbed
- `rich` = iframe OEmbed. Not currently accepted, so won't show up in practice.
**Description:** The type of the preview card.\
**Type:** String \(Enumerable, oneOf\)\
`link` = Link OEmbed\
`photo` = Photo OEmbed\
`video` = Video OEmbed\
`rich` = iframe OEmbed. Not currently accepted, so won't show up in practice.\
**Version history:** Added in 1.3.0
## Optional attributes
### `author_name`
### `author_name` {#author_name}
**Description:** The author of the original resource.
**Type:** String
**Description:** The author of the original resource.\
**Type:** String\
**Version history:** Added in 1.3.0
### `author_url`
### `author_url` {#author_url}
**Description:** A link to the author of the original resource.
**Type:** String \(URL\)
**Description:** A link to the author of the original resource.\
**Type:** String \(URL\)\
**Version history:** Added in 1.3.0
### `provider_name`
### `provider_name` {#provider_name}
**Description:** The provider of the original resource.
**Type:** String
**Description:** The provider of the original resource.\
**Type:** String\
**Version history:** Added in 1.3.0
### `provider_url`
### `provider_url` {#provider_url}
**Description:** A link to the provider of the original resource.
**Type:** String \(URL\)
**Description:** A link to the provider of the original resource.\
**Type:** String \(URL\)\
**Version history:** Added in 1.3.0
### `html`
### `html` {#html}
**Description:** HTML to be used for generating the preview card.
**Type:** String \(HTML\)
**Description:** HTML to be used for generating the preview card.\
**Type:** String \(HTML\)\
**Version history:** Added in 1.3.0
### `width`
### `width` {#width}
**Description:** Width of preview, in pixels.
**Type:** Number
**Description:** Width of preview, in pixels.\
**Type:** Number\
**Version history:** Added in 1.3.0
### `height`
### `height` {#height}
**Description:** Height of preview, in pixels.
**Type:** Number
**Description:** Height of preview, in pixels.\
**Type:** Number\
**Version history:** Added in 1.3.0
### `image`
### `image` {#image}
**Description:** Preview thumbnail.
**Type:** String \(URL\)
**Description:** Preview thumbnail.\
**Type:** String \(URL\)\
**Version history:** Added in 1.0.0
### `embed_url`
### `embed_url` {#embed_url}
**Description:** Used for photo embeds, instead of custom `html`.
**Type:** String \(URL\)
**Description:** Used for photo embeds, instead of custom `html`.\
**Type:** String \(URL\)\
**Version history:** Added in 2.1.0
## See also
@ -162,7 +160,3 @@ menu:
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/preview_card_serializer.rb" caption="app/serializers/rest/preview\_card\_serializer.rb" >}}
### <a id="type-1"></a>

16
content/en/entities/context.md
View File

@ -1,8 +1,6 @@
---
title: Context
description: >-
Represents the tree around a given status. Used for reconstructing threads of
statuses.
description: Represents the tree around a given status. Used for reconstructing threads of statuses.
menu:
docs:
parent: entities
@ -46,16 +44,16 @@ menu:
## Required attributes
### `ancestors`
### `ancestors` {#ancestors}
**Description:** Parents in the thread.
**Type:** Array of [Status](status.md)
**Description:** Parents in the thread.\
**Type:** Array of [Status](status.md)\
**Version history:** Added in 0.6.0
### `descendants`
### `descendants` {#descendants}
**Description:** Children in the thread.
**Type:** Array of [Status](status.md)
**Description:** Children in the thread.\
**Type:** Array of [Status](status.md)\
**Version history:** Added in 0.6.0
## See also

24
content/en/entities/conversation.md
View File

@ -32,30 +32,30 @@ menu:
## Required attributes
### `id`
### `id` {#id}
**Description:** Local database ID of the conversation.
**Type:** String \(cast from an integer, but not guaranteed to be a number\)
**Description:** Local database ID of the conversation.\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Version history:** Added in 2.6.0
### `accounts`
### `accounts` {#accounts}
**Description:** Participants in the conversation.
**Type:** Array of [Account](account.md)
**Description:** Participants in the conversation.\
**Type:** Array of [Account](account.md)\
**Version history:** Added in 2.6.0
### `unread`
### `unread` {#unread}
**Description:** Is the conversation currently marked as unread?
**Type:** Boolean
**Description:** Is the conversation currently marked as unread?\
**Type:** Boolean\
**Version history:** Added in 2.6.0
## Optional attributes
### `last_status`
### `last_status` {#last_status}
**Description:** The last status in the conversation, to be used for optional display.
**Type:** [Status](status.md)
**Description:** The last status in the conversation, to be used for optional display.\
**Type:** [Status](status.md)\
**Version history:** Added in 2.6.0
## See also

30
content/en/entities/emoji.md
View File

@ -20,36 +20,36 @@ menu:
## Required attributes
### `shortcode`
### `shortcode` {#shortcode}
**Description:** The name of the custom emoji.
**Type:** String
**Description:** The name of the custom emoji.\
**Type:** String\
**Version history:** Added in 2.0.0
### `url`
### `url` {#url}
**Description:** A link to the custom emoji.
**Type:** String \(URL\)
**Description:** A link to the custom emoji.\
**Type:** String \(URL\)\
**Version history:** Added in 2.0.0
### `static_url`
### `static_url` {#static_url}
**Description:** A link to a static copy of the custom emoji.
**Type:** String \(URL\)
**Description:** A link to a static copy of the custom emoji.\
**Type:** String \(URL\)\
**Version history:** Added in 2.0.0
### `visible_in_picker`
### `visible_in_picker` {#visible_in_picker}
**Description:** Whether this Emoji should be visible in the picker or unlisted.
**Type:** Boolean
**Description:** Whether this Emoji should be visible in the picker or unlisted.\
**Type:** Boolean\
**Version history:** Added in 2.0.0
## Optional attributes
### `category`
### `category` {#category}
**Description:** Used for sorting custom emoji in the picker.
**Type:** String
**Description:** Used for sorting custom emoji in the picker.\
**Type:** String\
**Version history:** Added in 3.0.0
## See also

38
content/en/entities/error.md
View File

@ -21,59 +21,59 @@ menu:
## Required attributes
### `error`
### `error` {#error}
**Description:** The error message.
**Type:** String
**Description:** The error message.\
**Type:** String\
**Version history:** Added in 0.6.0
## Optional attributes
### `error_description`
### `error_description` {#error_description}
**Description:** A longer description of the error, mainly provided with the OAuth API.
**Type:** String
**Description:** A longer description of the error, mainly provided with the OAuth API.\
**Type:** String\
**Version history:** Added in 0.6.0
## Possible reasons
## Possible reasons {#reasons}
### 401 - Unauthorized
### 401 - Unauthorized {#401}
#### require\_authenticated\_user!
#### require\_authenticated\_user! {#auth}
Error: This API requires an authenticated user. Appears when the instance is in secure mode, which disables all public use of API methods.
### 403 - Forbidden
### 403 - Forbidden {#403}
#### current\_user.disabled?
#### current\_user.disabled? {#disabled}
Error: Your login is currently disabled. Appears when the OAuth token's authorized user has had their account disabled by a moderator.
#### !current\_user.confirmed?
#### !current\_user.confirmed? {#unconfirmed}
Error: Your login is missing a confirmed e-mail address. Appears when the email address associated with the OAuth token's authorized user's account has not yet been confirmed.
#### !current\_user.approved?
#### !current\_user.approved? {#unapproved}
Error: Your login is currently pending approval. Appears when the OAuth token's authorized user has signed up on an instance with approval-required registrations, and the user has not yet had their account approved by a moderator.
### 404 - Not Found
### 404 - Not Found {#404}
#### RecordNotFound
#### RecordNotFound {#not-found}
Error: Record not found. Appears when an entity record does not exist, or the authorized user is not within the audience of a private entity.operates on a user.
### 422 - Unprocessable Entity
### 422 - Unprocessable Entity {#422}
#### RecordInvalid
#### RecordInvalid {#invalid}
Error: {string}. May appear when entity creation failed.
#### RecordNotUnique
#### RecordNotUnique {#not-unique}
Error: Duplicate record. Appears when you are trying to pin an account or status that is already pinned.
#### !current\_user
#### !current\_user {#user-required}
Error: This method requires an authenticated user. Appears when using an OAuth token without an authorized user \(or no token at all\), while trying to call an API method that requires a user to be processed.

25
content/en/entities/featuredtag.md
View File

@ -1,5 +1,6 @@
---
title: FeaturedTag
description: Represents a hashtag that is featured on a profile.
menu:
docs:
parent: entities
@ -18,28 +19,28 @@ menu:
## Attributes
### `id`
### `id` {#id}
**Description:** The internal ID of the featured tag in the database.
**Type:** String \(cast from integer but not guaranteed to be a number\)
**Description:** The internal ID of the featured tag in the database.\
**Type:** String \(cast from integer but not guaranteed to be a number\)\
**Version history:** Added in 3.0.0
### `name`
### `name` {#name}
**Description:** The name of the hashtag being featured.
**Type:** String
**Description:** The name of the hashtag being featured.\
**Type:** String\
**Version history:** Added in 3.0.0
### `statuses_count`
### `statuses_count` {#statuses_count}
**Description:** The number of authored statuses containing this hashtag.
**Type:** Number
**Description:** The number of authored statuses containing this hashtag.\
**Type:** Number\
**Version history:** Added in 3.0.0
### `last_status_at`
### `last_status_at` {#last_status_at}
**Description:** The timestamp of the last authored status containing this hashtag.
**Type:** String \(ISO 8601 Datetime\)
**Description:** The timestamp of the last authored status containing this hashtag.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:** Added in 3.0.0
## See also

18
content/en/entities/field.md
View File

@ -37,24 +37,24 @@ menu:
## Required attributes
### `name`
### `name` {#name}
**Description:** The key of a given field's key-value pair.
**Type:** String
**Description:** The key of a given field's key-value pair.\
**Type:** String\
**Version history:** Added in 2.4.0
### `value`
### `value` {#value}
**Description:** The value associated with the `name` key.
**Type:** String \(HTML\)
**Description:** The value associated with the `name` key.\
**Type:** String \(HTML\)\
**Version history:** Added in 2.4.0
## Optional attributes
### `verified_at`
### `verified_at` {#verified_at}
**Description:** Timestamp of when the server verified a URL value for a rel="me" link.
**Type:** String \(ISO 8601 Datetime\) if `value` is a verified URL. Otherwise, null
**Description:** Timestamp of when the server verified a URL value for a rel="me" link.\
**Type:** String \(ISO 8601 Datetime\) if `value` is a verified URL. Otherwise, null\
**Version history:** Added in 2.6.0
## See also

48
content/en/entities/filter.md
View File

@ -1,8 +1,6 @@
---
title: Filter
description: >-
Represents a user-defined filter for determining which statuses should not be
shown to the user.
description: Represents a user-defined filter for determining which statuses should not be shown to the user.
menu:
docs:
parent: entities
@ -28,44 +26,44 @@ menu:
## Attributes
### `id`
### `id` {#id}
**Description:** The ID of the filter in the database.
**Type:** String \(cast from an integer, but not guaranteed to be a number\)
**Description:** The ID of the filter in the database.\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Version history:** Added in 2.4.3
### `phrase`
### `phrase` {#phrase}
**Description:** The text to be filtered.
**Type:** String
**Description:** The text to be filtered.\
**Type:** String\
**Version history:** Added in 2.4.3
### `context`
### `context` {#context}
**Description:** The contexts in which the filter should be applied.
**Type:** Array of String \(Enumerable anyOf\)
- `home` = home timeline
- `notifications` = notifications timeline
- `public` = public timelines
- `thread` = expanded thread of a detailed status
**Description:** The contexts in which the filter should be applied.\
**Type:** Array of String \(Enumerable anyOf\)\
`home` = home timeline\
`notifications` = notifications timeline\
`public` = public timelines\
`thread` = expanded thread of a detailed status\
**Version history:** Added in 2.4.3
### `expires_at`
### `expires_at` {#expires_at}
**Description:** When the filter should no longer be applied
**Type:** String \(ISO 8601 Datetime\), or null if the filter does not expire
**Description:** When the filter should no longer be applied\
**Type:** String \(ISO 8601 Datetime\), or null if the filter does not expire\
**Version history:** Added in 2.4.3
### `irreversible`
### `irreversible` {#irreversible}
**Description:** Should matching entities in home and notifications be dropped by the server?
**Type:** Boolean
**Description:** Should matching entities in home and notifications be dropped by the server?\
**Type:** Boolean\
**Version history:** Added in 2.4.3
### `whole_word`
### `whole_word` {#whole_word}
**Description:** Should the filter consider word boundaries?
**Type:** Boolean
**Description:** Should the filter consider word boundaries?\
**Type:** Boolean\
**Version history:** Added in 2.4.3
## Implementation notes

18
content/en/entities/history.md
View File

@ -18,22 +18,22 @@ menu:
## Required attributes
### `day`
### `day` {#day}
**Description:** UNIX timestamp on midnight of the given day.
**Type:** String \(UNIX timestamp\)
**Description:** UNIX timestamp on midnight of the given day.\
**Type:** String \(UNIX timestamp\)\
**Version history:** Added in 2.4.1
### `uses`
### `uses` {#uses}
**Description:** the counted usage of the tag within that day.
**Type:** String \(cast from an integer\)
**Description:** the counted usage of the tag within that day.\
**Type:** String \(cast from an integer\)\
**Version history:** Added in 2.4.1
### `accounts`
### `accounts` {#accounts}
**Description:** the total of accounts using the tag within that day.
**Type:** String \(cast from an integer\)
**Description:** the total of accounts using the tag within that day.\
**Type:** String \(cast from an integer\)\
**Version history:** Added in 2.4.1
## See also

31
content/en/entities/identityproof.md
View File

@ -1,5 +1,6 @@
---
title: IdentityProof
description: Represents a proof from an external identity provider.
menu:
docs:
parent: entities
@ -17,34 +18,34 @@ menu:
## Attributes
### `provider`
### `provider` {#provider}
**Description:** The name of the identity provider.
**Type:** String
**Description:** The name of the identity provider.\
**Type:** String\
**Version history:** Added in 2.8.0
### `provider_username`
### `provider_username` {#provider_username}
**Description:** The account owner's username on the identity provider's service.
**Type:** String
**Description:** The account owner's username on the identity provider's service.\
**Type:** String\
**Version history:** Added in 2.8.0
### `profile_url`
### `profile_url` {#profile_url}
**Description:** The account owner's profile URL on the identity provider.
**Type:** String \(URL\)
**Description:** The account owner's profile URL on the identity provider.\
**Type:** String \(URL\)\
**Version history:** Added in 2.8.0
### `proof_url`
### `proof_url` {#proof_url}
**Description:** A link to a statement of identity proof, hosted by the identity provider.
**Type:** String \(URL\)
**Description:** A link to a statement of identity proof, hosted by the identity provider.\
**Type:** String \(URL\)\
**Version history:** Added in 2.8.0
### `updated_at`
### `updated_at` {#updated_at}
**Description:** The name of the identity provider.
**Type:** String \(ISO 8601 Datetime\)
**Description:** The name of the identity provider.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:** Added in 2.8.0
## See also

90
content/en/entities/instance.md
View File

@ -52,12 +52,12 @@ menu:
"fields": [
{
"name": "Patreon",
"value": "<a href=\"https://www.patreon.com/mastodon\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://www.</span><span class=\"\">patreon.com/mastodon</span><span class=\"invisible\"></span></a>",
"value": "<a href=\"https://www.patreon.com/mastodon\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://www.</span><span class=\"\">patreon.com/mastodon</span><span class=\"invisible\"></span}",
"verified_at": null
},
{
"name": "Homepage",
"value": "<a href=\"https://zeonfederated.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">zeonfederated.com</span><span class=\"invisible\"></span></a>",
"value": "<a href=\"https://zeonfederated.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">zeonfederated.com</span><span class=\"invisible\"></span}",
"verified_at": "2019-07-15T18:29:57.191+00:00"
}
]
@ -67,100 +67,100 @@ menu:
## Required attributes
### `uri`
### `uri` {#uri}
**Description:** The domain name of the instance.
**Type:** String
**Description:** The domain name of the instance.\
**Type:** String\
**Version history:** Added in 1.1.0
### `title`
### `title` {#title}
**Description:** The title of the website.
**Type:** String
**Description:** The title of the website.\
**Type:** String\
**Version history:** Added in 1.1.0
### `description`
### `description` {#description}
**Description:** Admin-defined description of the Mastodon site.
**Type:** String
**Description:** Admin-defined description of the Mastodon site.\
**Type:** String\
**Version history:** Added in 1.1.0
### `short_description`
### `short_description` {#short_description}
**Description:** A shorter description defined by the admin.
**Type:** String
**Description:** A shorter description defined by the admin.\
**Type:** String\
**Version history:** Added in 2.9.2
### `email`
### `email` {#email}
**Description:** An email that may be contacted for any inquiries.
**Type:** String
**Description:** An email that may be contacted for any inquiries.\
**Type:** String\
**Version history:** Added in 1.1.0
### `version`
### `version` {#version}
**Description:** The version of Mastodon installed on the instance.
**Type:** String
**Description:** The version of Mastodon installed on the instance.\
**Type:** String\
**Version history:** Added in 1.3.0
### `languages`
### `languages` {#languages}
**Description:** Primary langauges of the website and its staff.
**Type:** Array of String \(ISO 639 Part 1-5 language codes\)
**Description:** Primary langauges of the website and its staff.\
**Type:** Array of String \(ISO 639 Part 1-5 language codes\)\
**Version history:** Added in 2.3.0
### `registrations`
### `registrations` {#registrations}
**Description:** Whether registrations are enabled.
**Type:** Boolean
**Description:** Whether registrations are enabled.\
**Type:** Boolean\
**Version history:** Added in 2.7.2
### `approval_required`
### `approval_required` {#approval_required}
**Description:** Whether registrations require moderator approval.
**Type:** Boolean
**Description:** Whether registrations require moderator approval.\
**Type:** Boolean\
**Version history:** Added in 2.9.2
### `urls`
### `urls` {#urls}
**Description:** URLs of interest for clients apps.
**Type:** Hash \(`streaming_api`\)
**Description:** URLs of interest for clients apps.\
**Type:** Hash \(`streaming_api`\)\
**Version history:** Added in 1.4.2
#### `urls[streaming_api]`
#### `urls[streaming_api]` {#streaming_api}
Websockets address for push streaming. String \(URL\).
### `stats`
### `stats` {#stats}
**Description:** Statistics about how much information the instance contains.
**Type:** Hash \(`user_count`, `status_count`, `domain_count`\)
**Description:** Statistics about how much information the instance contains.\
**Type:** Hash \(`user_count`, `status_count`, `domain_count`\)\
**Version history:** Added in 1.6.0
#### `user_count`
#### `user_count` {#user_count}
Users registered on this instance. Number.
#### `status_count`
#### `status_count` {#status_count}
Statuses authored by users on instance. Number.
#### `domain_count`
#### `domain_count` {#domain_count}
Domains federated with this instance. Number.
## Optional attributes
### `thumbnail`
### `thumbnail` {#thumbnail}
**Description:** Banner image for the website.
**Type:** String \(URL\) or null
**Description:** Banner image for the website.\
**Type:** String \(URL\) or null\
**Version history:** Added in 1.6.1
### `contact_account`
### `contact_account` {#contact_account}
**Description:** A user that can be contacted, as an alternative to `email`.
**Type:** [Account](account.md) or null
**Description:** A user that can be contacted, as an alternative to `email`.\
**Type:** [Account](account.md) or null\
**Version history:** Added in 2.3.0
## See also

12
content/en/entities/list.md
View File

@ -17,16 +17,16 @@ menu:
## Required attributes
### `id`
### `id` {#id}
**Description:** The internal database ID of the list.
**Type:** String \(cast from an integer, but not guaranteed to be a number\)
**Description:** The internal database ID of the list.\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Version history:** Added in 2.1.0
### `title`
### `title` {#title}
**Description:** The user-defined title of the list.
**Type:** String
**Description:** The user-defined title of the list.\
**Type:** String\
**Version history:** Added in 2.1.0
## See also

31
content/en/entities/marker.md
View File

@ -1,5 +1,6 @@
---
title: Marker
description: Represents the last read position within a user's timelines.
menu:
docs:
parent: entities
@ -24,36 +25,36 @@ menu:
## Base attributes
### `home`
### `home` {#home}
**Description:** Information about the user's position in the home timeline.
**Type:** Hash
**Description:** Information about the user's position in the home timeline.\
**Type:** Hash\
**Version history:** Added in 3.0.0
### `notifications`
### `notifications` {#notifications}
**Description:** Information about the user's position in their notifications.
**Type:** Hash
**Description:** Information about the user's position in their notifications.\
**Type:** Hash\
**Version history:** Added in 3.0.0
## Nested attributes
### `last_read_id`
### `last_read_id` {#last_read_id}
**Description:** The ID of the most recently viewed entity.
**Type:** String \(cast from integer but not guaranteed to be a number\)
**Description:** The ID of the most recently viewed entity.\
**Type:** String \(cast from integer but not guaranteed to be a number\)\
**Version history:** Added in 3.0.0
### `updated_at`
### `updated_at` {#updated_at}
**Description:** The timestamp of when the marker was set.
**Type:** String \(ISO 8601 Datetime\)
**Description:** The timestamp of when the marker was set.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:** Added in 3.0.0
### `version`
### `version` {#version}
**Description:** Used for locking to prevent write conflicts.
**Type:** Number
**Description:** Used for locking to prevent write conflicts.\
**Type:** Number\
**Version history:** Added in 3.0.0
## See also

24
content/en/entities/mention.md
View File

@ -31,28 +31,28 @@ menu:
## Required attributes
### `id`
### `id` {#id}
**Description:** The account id of the mentioned user.
**Type:** String \(cast from an integer, but not guaranteed to be a number\)
**Description:** The account id of the mentioned user.\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Version history:** Added in 0.6.0
### `username`
### `username` {#username}
**Description:** The username of the mentioned user.
**Type:** String
**Description:** The username of the mentioned user.\
**Type:** String\
**Version history:** Added in 0.6.0
### `acct`
### `acct` {#acct}
**Description:** The webfinger acct: URI of the mentioned user. Equivalent to `username` for local users, or `username@domain` for remote users.
**Type:** String
**Description:** The webfinger acct: URI of the mentioned user. Equivalent to `username` for local users, or `username@domain` for remote users.\
**Type:** String\
**Version history:** Added in 0.6.0
### `url`
### `url` {#url}
**Description:** The location of the mentioned user's profile.
**Type:** String \(URL\)
**Description:** The location of the mentioned user's profile.\
**Type:** String \(URL\)\
**Version history:** Added in 0.6.0
## See also

40
content/en/entities/notification.md
View File

@ -60,41 +60,41 @@ menu:
## Required attributes
### `id`
### `id` {#id}
**Description:** The id of the notification in the database.
**Type:** String \(cast from an integer, but not guaranteed to be a number\)
**Description:** The id of the notification in the database.\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Version history:** Added in 0.9.9
### `type`
### `type` {#type}
**Description:** The type of event that resulted in the notification.
**Type:** String \(Enumerable oneOf\)
- `follow` = Someone followed you
- `mention` = Someone mentioned you in their status
- `reblog` = Someone boosted one of your statuses
- `favourite` = Someone favourited one of your statuses
- `poll` = A poll you have voted in or created has ended
**Description:** The type of event that resulted in the notification.\
**Type:** String \(Enumerable oneOf\)\
`follow` = Someone followed you\
`mention` = Someone mentioned you in their status\
`reblog` = Someone boosted one of your statuses\
`favourite` = Someone favourited one of your statuses\
`poll` = A poll you have voted in or created has ended\
**Version history:** Added in 0.9.9. `poll` added in 2.8.0.
### `created_at`
### `created_at` {#created_at}
**Description:** The timestamp of the notification.
**Type:** String \(ISO 8601 Datetime\)
**Description:** The timestamp of the notification.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:** Added in 0.9.9
### `account`
### `account` {#account}
**Description:** The account that performed the action that generated the notification.
**Type:** [Account](account.md)
**Description:** The account that performed the action that generated the notification.\
**Type:** [Account](account.md)\
**Version history:** Added in 0.9.9
## Optional attributes
### `status`
### `status` {#status}
**Description:** Status that was the object of the notification, e.g. in mentions, reblogs, favourites, or polls.
**Type:** [Status](status.md)
**Description:** Status that was the object of the notification, e.g. in mentions, reblogs, favourites, or polls.\
**Type:** [Status](status.md)\
**Version history:** Added in 0.9.9
## See also

64
content/en/entities/poll.md
View File

@ -6,6 +6,8 @@ menu:
parent: entities
---
## Example
```javascript
{
"id": "34830",
@ -32,60 +34,60 @@ menu:
}
```
## Poll attributes <a id="poll"></a>
## Attributes
### `id`
### `id` {#id}
**Description:** The ID of the poll in the database.
**Type:** String \(cast from an integer, but not guaranteed to be a number\)
**Description:** The ID of the poll in the database.\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Version history:** Added in 2.8.0
### `expires_at`
### `expires_at` {#expires_at}
**Description:** When the poll ends.
**Type:** String \(ISO 8601 Datetime\), or null if the poll does not end
**Description:** When the poll ends.\
**Type:** String \(ISO 8601 Datetime\), or null if the poll does not end\
**Version history:** Added in 2.8.0
### `expired`
### `expired` {#expired}
**Description:** Is the poll currently expired?
**Type:** Boolean
**Description:** Is the poll currently expired?\
**Type:** Boolean\
**Version history:** Added in 2.8.0
### `multiple`
### `multiple` {#multiple}
**Description:** Does the poll allow multiple-choice answers?
**Type:** Boolean
**Description:** Does the poll allow multiple-choice answers?\
**Type:** Boolean\
**Version history:** Added in 2.8.0
### `votes_count`
### `votes_count` {#votes_count}
**Description:** How many votes have been received.
**Type:** Number
**Description:** How many votes have been received.\
**Type:** Number\
**Version history:** Added in 2.8.0
### `voters_count`
### `voters_count` {#voters_count}
**Description:** How many unique accounts have voted on a multiple-choice poll.
**Type:** Number, or null if `multiple` is false.
**Description:** How many unique accounts have voted on a multiple-choice poll.\
**Type:** Number, or null if `multiple` is false.\
**Version history:** Added in 2.8.0
### `voted`
### `voted` {#voted}
**Description:** When called with a user token, has the authorized user voted?
**Type:** Boolean, or null if no current user
**Description:** When called with a user token, has the authorized user voted?\
**Type:** Boolean, or null if no current user\
**Version history:** Added in 2.8.0
### `own_votes`
### `own_votes` {#own_votes}
**Description:** When called with a user token, which options has the authorized user chosen? Contains an array of index values for `options`.
**Type:** Array of Number, or null if no current user
**Description:** When called with a user token, which options has the authorized user chosen? Contains an array of index values for `options`.\
**Type:** Array of Number, or null if no current user\
**Version history:** Added in 2.8.0
### `options[]`
### `options[]` {#options}
**Description:** Possible answers for the poll.
**Type:** Array of Hash
**Description:** Possible answers for the poll.\
**Type:** Array of Hash\
**Version history:** Added in 2.8.0
#### `options[][title]`
@ -96,10 +98,10 @@ The text value of the poll option. String.
The number of received votes for this option. Number, or null if results are not published yet.
### `emojis`
### `emojis` {#emojis}
**Description:** Custom emoji to be used for rendering poll options.
**Type:** Array of Emoji
**Description:** Custom emoji to be used for rendering poll options.\
**Type:** Array of Emoji\
**Version history:** Added in 2.8.0
## See also

44
content/en/entities/preferences.md
View File

@ -20,41 +20,41 @@ menu:
## Attributes
### `posting:default:visibility`
### `posting:default:visibility` {#visibility}
**Description:** Default visibility for new posts. Equivalent to [Source\#privacy](source.md#privacy).
**Type:** String \(Enumerable, oneOf\)
- `public` = Public post
- `unlisted` = Unlisted post
- `private` = Followers-only post
- `direct` = Direct post
**Description:** Default visibility for new posts. Equivalent to [Source\#privacy](source.md#privacy).\
**Type:** String \(Enumerable, oneOf\)\
`public` = Public post\
`unlisted` = Unlisted post\
`private` = Followers-only post\
`direct` = Direct post\
**Version history:** Added in 2.8.0
### `posting:default:sensitive`
### `posting:default:sensitive` {#sensitive}
**Description:** Default sensitivity flag for new posts. Equivalent to [Source\#sensitive](source.md#sensitive).
**Type:** Boolean
**Description:** Default sensitivity flag for new posts. Equivalent to [Source\#sensitive](source.md#sensitive).\
**Type:** Boolean\
**Version history:** Added in 2.8.0
### `posting:default:language`
### `posting:default:language` {#language}
**Description:** Default language for new posts. Equivalent to [Source\#language](source.md#language)
**Type:** String \(ISO 639-1 language two-letter code\), or null
**Description:** Default language for new posts. Equivalent to [Source\#language](source.md#language)\
**Type:** String \(ISO 639-1 language two-letter code\), or null\
**Version history:** Added in 2.8.0
### `reading:expand:media`
### `reading:expand:media` {#media}
**Description:** Whether media attachments should be automatically displayed or blurred/hidden.
**Type:** String \(Enumerable, oneOf\)
- `default` = Hide media marked as sensitive
- `show_all` = Always show all media by default, regardless of sensitivity
- `hide_all` = Always hide all media by default, regardless of sensitivity
**Description:** Whether media attachments should be automatically displayed or blurred/hidden.\
**Type:** String \(Enumerable, oneOf\)\
`default` = Hide media marked as sensitive\
`show_all` = Always show all media by default, regardless of sensitivity\
`hide_all` = Always hide all media by default, regardless of sensitivity\
**Version history:** Added in 2.8.0
### `reading:expand:spoilers`
### `reading:expand:spoilers` {#cw}
**Description:** Whether CWs should be expanded by default.
**Type:** Boolean
**Description:** Whether CWs should be expanded by default.\
**Type:** Boolean\
**Version history:** Added in 2.8.0
## See also

26
content/en/entities/push-subscription.md
View File

@ -23,30 +23,30 @@ menu:
}
```
## Required attributes <a id="push-subscription"></a>
## Required attributes {#push-subscription}
### `id`
### `id` {#id}
**Description:** The id of the push subscription in the database.
**Type:** String \(cast from an integer, but not guaranteed to be a number\)
**Description:** The id of the push subscription in the database.\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Version history:** Added in 2.4.0
### `endpoint`
### `endpoint` {#endpoint}
**Description:** Where push alerts will be sent to.
**Type:** String \(URL\)
**Description:** Where push alerts will be sent to.\
**Type:** String \(URL\)\
**Version history:** Added in 2.4.0
### `server_key`
### `server_key` {#server_key}
**Description:** The streaming server's VAPID key.
**Type:** String
**Description:** The streaming server's VAPID key.\
**Type:** String\
**Version history:** Added in 2.4.0
### `alerts`
### `alerts` {#alerts}
**Description:** Which alerts should be delivered to the `endpoint`.
**Type:** Hash
**Description:** Which alerts should be delivered to the `endpoint`.\
**Type:** Hash\
**Version history:** Added in 2.4.0. `alerts[poll]` added in 2.8.0.
#### `alerts[follow]`

72
content/en/entities/relationship.md
View File

@ -1,8 +1,6 @@
---
title: Relationship
description: >-
Represents the relationship between accounts, such as following / blocking /
muting / etc.
description: Represents the relationship between accounts, such as following / blocking / muting / etc.
menu:
docs:
parent: entities
@ -26,72 +24,72 @@ menu:
}
```
## Required attributes <a id="relationship"></a>
## Required attributes {#relationship}
### `id`
### `id` {#id}
**Description:** The account id.
**Type:** String \(cast from an integer, but not guaranteed to be a number\)
**Description:** The account id.\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Version history:** Added in 0.6.0
### `following`
### `following` {#following}
**Description:** Are you following this user?
**Type:** Boolean
**Description:** Are you following this user?\
**Type:** Boolean\
**Version history:** Added in 0.6.0
### `requested`
### `requested` {#requested}
**Description:** Do you have a pending follow request for this user?
**Type:** Boolean
**Description:** Do you have a pending follow request for this user?\
**Type:** Boolean\
**Version history:** Added in 0.9.9
### `endorsed`
### `endorsed` {#endorsed}
**Description:** Are you featuring this user on your profile?
**Type:** Boolean
**Description:** Are you featuring this user on your profile?\
**Type:** Boolean\
**Version history:** Added in 2.5.0
### `followed_by`
### `followed_by` {#followed_by}
**Description:** Are you followed by this user?
**Type:** Boolean
**Description:** Are you followed by this user?\
**Type:** Boolean\
**Version history:** Added in 0.6.0
### `muting`
### `muting` {#muting}
**Description:** Are you muting this user?
**Type:** Boolean
**Description:** Are you muting this user?\
**Type:** Boolean\
**Version history:** Added in 1.1.0
### `muting_notifications`
### `muting_notifications` {#muting_notifications}
**Description:** Are you muting notifications from this user?
**Type:** Boolean
**Description:** Are you muting notifications from this user?\
**Type:** Boolean\
**Version history:** Added in 2.1.0
### `showing_reblogs`
### `showing_reblogs` {#showing_reblogs}
**Description:** Are you receiving this user's boosts in your home timeline?
**Type:** Boolean
**Description:** Are you receiving this user's boosts in your home timeline?\
**Type:** Boolean\
**Version history:** Added in 2.1.0
### `blocking`
### `blocking` {#blocking}
**Description:** Are you blocking this user?
**Type:** Boolean
**Description:** Are you blocking this user?\
**Type:** Boolean\
**Version history:** Added in 0.6.0
### `domain_blocking`
### `domain_blocking` {#domain_blocking}
**Description:** Are you blocking this user's domain?
**Type:** Boolean
**Description:** Are you blocking this user's domain?\
**Type:** Boolean\
**Version history:** Added in 1.4.0
### `blocked_by`
### `blocked_by` {#blocked_by}
**Description:** Is this user blocking you?
**Type:** Boolean
**Description:** Is this user blocking you?\
**Type:** Boolean\
**Version history:** Added in 2.8.0
## See also

4
content/en/entities/report.md
View File

@ -1,8 +1,6 @@
---
title: Report
description: >-
Reports filed against users and/or statuses, to be taken action on by
moderators.
description: Reports filed against users and/or statuses, to be taken action on by moderators.
menu:
docs:
parent: entities

20
content/en/entities/results.md
View File

@ -47,7 +47,7 @@ menu:
"spoiler_text": "Cats",
...
"content": "<p>Cats are inherently good at self-care. </p><p><a href=\"https://mspsocial.net/tags/cats\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>cats</span></a></p>",
"content": "<p>Cats are inherently good at self-care. </p><p><a href=\"https://mspsocial.net/tags/cats\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>cats</span}</p>",
...
],
@ -85,22 +85,22 @@ menu:
## Required attributes
### `accounts`
### `accounts` {#accounts}
**Description:** Accounts which match the given query
**Type:** Array of [Account](account.md)
**Description:** Accounts which match the given query\
**Type:** Array of [Account](account.md)\
**Version history:** Added in x.x.x
### `statuses`
### `statuses` {#statuses}
**Description:** Statuses which match the given query
**Type:** Array of [Status](status.md)
**Description:** Statuses which match the given query\
**Type:** Array of [Status](status.md)\
**Version history:** Added in x.x.x
### `hashtags`
### `hashtags` {#hashtags}
**Description:** Hashtags which match the given query
**Type:** Array of [Tag](tag.md) \(v2\). Array of String \(v1\).
**Description:** Hashtags which match the given query\
**Type:** Array of [Tag](tag.md) \(v2\). Array of String \(v1\).\
**Version history:** v1 added in 1.1.0 and deprecated in 3.0.0. v2 added in 2.4.1 and replaced v1 in 3.0.0.
## See also

18
content/en/entities/scheduledstatus.md
View File

@ -6,6 +6,10 @@ menu:
parent: entities
---
{{< hint style="warning" >}}
This page is currently under construction.
{{< /hint >}}
## Example
```javascript
@ -30,16 +34,16 @@ menu:
## Required attributes
### id
### id {#id}
**Description:** ID of the scheduled status in the database.
**Type:** String \(cast from an integer but not guaranteed to be a number\)
**Description:** ID of the scheduled status in the database.\
**Type:** String \(cast from an integer but not guaranteed to be a number\)\
**Version history:** Added in 2.7.0
### scheduled\_at
**Description:** ID of the status in the database.
**Type:** String \(ISO 8601 Datetime\)
**Description:** ID of the status in the database.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:** Added in 2.7.0
### params
@ -66,7 +70,7 @@ menu:
#### scheduled\_at
## ScheduledStatus <a id="scheduledstatus"></a>
## ScheduledStatus {#scheduledstatus}
| Attribute | Type | Nullable | Added in |
| :--- | :--- | :--- | :--- |
@ -75,7 +79,7 @@ menu:
| `params` | [StatusParams]() | No | 2.7.0 |
| `media_attachments` | Array of [Attachment]() | No | 2.7.0 |
### StatusParams <a id="statusparams"></a>
### StatusParams {#statusparams}
| Attribute | Type | Nullable | Added in |
| :--- | :--- | :--- | :--- |

49
content/en/entities/source.md
View File

@ -1,9 +1,6 @@
---
title: Source
description: >-
Represents display or publishing preferences of user's own account. Returned
as an additional entity when verifying and updated credentials, as an
attribute of Account.
description: Represents display or publishing preferences of user's own account. Returned as an additional entity when verifying and updated credentials, as an attribute of Account.
menu:
docs:
parent: entities
@ -47,46 +44,46 @@ menu:
## Base attributes
### `note`
### `note` {#note}
**Description:** Profile bio.
**Type:** String
**Description:** Profile bio.\
**Type:** String\
**Version history:** Added in 1.5.0
### `fields`
### `fields` {#fields}
**Description:** Metadata about the account.
**Type:** Array of [Field]({{< relref "field.md" >}})
**Description:** Metadata about the account.\
**Type:** Array of [Field]({{< relref "field.md" >}})\
**Version history:** Added in 2.4.0
## Nullable attributes
### `privacy`
### `privacy` {#privacy}
**Description:** The default post privacy to be used for new statuses.
**Type:** String \(Enumerable, oneOf\)
- `public` = Public post
- `unlisted` = Unlisted post
- `private` = Followers-only post
- `direct` = Direct post
**Description:** The default post privacy to be used for new statuses.\
**Type:** String \(Enumerable, oneOf\)\
`public` = Public post\
`unlisted` = Unlisted post\
`private` = Followers-only post\
`direct` = Direct post\
**Version history:** Added in 1.5.0
### `sensitive`
### `sensitive` {#sensitive}
**Description:** Whether new statuses should be marked sensitive by default.
**Type:** Boolean
**Description:** Whether new statuses should be marked sensitive by default.\
**Type:** Boolean\
**Version history:** Added in 1.5.0
### `language`
### `language` {#language}
**Description:** The default posting language for new statuses.
**Type:** String \(ISO 639-1 language two-letter code\)
**Description:** The default posting language for new statuses.\
**Type:** String \(ISO 639-1 language two-letter code\)\
**Version history:** Added in 2.4.2
### `follow_requests_count`
### `follow_requests_count` {#follow_requests_count}
**Description:** The number of pending follow requests.
**Type:** Number
**Description:** The number of pending follow requests.\
**Type:** Number\
**Version history:** Added in 3.0.0
## See also

188
content/en/entities/status.md
View File

@ -27,7 +27,7 @@ menu:
"reblogged": false,
"muted": false,
"bookmarked": false,
"content": "<p>&quot;I lost my inheritance with one wrong digit on my sort code&quot;</p><p><a href=\"https://www.theguardian.com/money/2019/dec/07/i-lost-my-193000-inheritance-with-one-wrong-digit-on-my-sort-code\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://www.</span><span class=\"ellipsis\">theguardian.com/money/2019/dec</span><span class=\"invisible\">/07/i-lost-my-193000-inheritance-with-one-wrong-digit-on-my-sort-code</span></a></p>",
"content": "<p>&quot;I lost my inheritance with one wrong digit on my sort code&quot;</p><p><a href=\"https://www.theguardian.com/money/2019/dec/07/i-lost-my-193000-inheritance-with-one-wrong-digit-on-my-sort-code\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://www.</span><span class=\"ellipsis\">theguardian.com/money/2019/dec</span><span class=\"invisible\">/07/i-lost-my-193000-inheritance-with-one-wrong-digit-on-my-sort-code</span}</p>",
"reblog": null,
"application": {
"name": "Web",
@ -57,12 +57,12 @@ menu:
"fields": [
{
"name": "Patreon",
"value": "<a href=\"https://www.patreon.com/mastodon\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://www.</span><span class=\"\">patreon.com/mastodon</span><span class=\"invisible\"></span></a>",
"value": "<a href=\"https://www.patreon.com/mastodon\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://www.</span><span class=\"\">patreon.com/mastodon</span><span class=\"invisible\"></span}",
"verified_at": null
},
{
"name": "Homepage",
"value": "<a href=\"https://zeonfederated.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">zeonfederated.com</span><span class=\"invisible\"></span></a>",
"value": "<a href=\"https://zeonfederated.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">zeonfederated.com</span><span class=\"invisible\"></span}",
"verified_at": "2019-07-15T18:29:57.191+00:00"
}
]
@ -92,190 +92,190 @@ menu:
## Base attributes
### `id`
### `id` {#id}
**Description:** ID of the status in the database.
**Type:** String \(cast from an integer but not guaranteed to be a number\)
**Description:** ID of the status in the database.\
**Type:** String \(cast from an integer but not guaranteed to be a number\)\
**Version history:** Added in 0.1.0
### `uri`
### `uri` {#uri}
**Description:** URI of the status used for federation.
**Type:** String
**Description:** URI of the status used for federation.\
**Type:** String\
**Version history:** Added in 0.1.0
### `created_at`
### `created_at` {#created_at}
**Description:** HTML-encoded status content.
**Type:** String \(ISO 8601 Datetime\)
**Description:** HTML-encoded status content.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:** Added in 0.1.0
### `account`
### `account` {#account}
**Description:** The account that authored this status.
**Type:** [Account](account.md)
**Description:** The account that authored this status.\
**Type:** [Account](account.md)\
**Version history:** Added in 0.1.0
### `content`
### `content` {#content}
**Description:** HTML-encoded status content.
**Type:** String \(HTML\)
**Description:** HTML-encoded status content.\
**Type:** String \(HTML\)\
**Version history:** Added in 0.1.0
### `text`
### `text` {#text}
**Description:** Plain-text source of a status. Returned instead of `content` when status is deleted, so the user may redraft from the source text without the client having to reverse-engineer the original text from the HTML content.
**Type:** String
**Description:** Plain-text source of a status. Returned instead of `content` when status is deleted, so the user may redraft from the source text without the client having to reverse-engineer the original text from the HTML content.\
**Type:** String\
**Version history:** Added in 2.9.0
### `visibility`
### `visibility` {#visibility}
**Description:** HTML-encoded status content.
**Type:** String \(Enumerable oneOf\)
- `public` = Visible to everyone, shown in public timelines.
- `unlisted` = Visible to public, but not included in public timelines.
- `private` = Visible to followers only, and to any mentioned users.
- `direct` = Visible only to mentioned users.
**Description:** HTML-encoded status content.\
**Type:** String \(Enumerable oneOf\)\
`public` = Visible to everyone, shown in public timelines.\
`unlisted` = Visible to public, but not included in public timelines.\
`private` = Visible to followers only, and to any mentioned users.\
`direct` = Visible only to mentioned users.\
**Version history:** Added in 0.9.9
### `sensitive`
### `sensitive` {#sensitive}
**Description:** Is this status marked as sensitive content?
**Type:** Boolean
**Description:** Is this status marked as sensitive content?\
**Type:** Boolean\
**Version history:** Added in 0.9.9
### `spoiler_text`
### `spoiler_text` {#spoiler_text}
**Description:** Subject or summary line, below which status content is collapsed until expanded.
**Type:** String
**Description:** Subject or summary line, below which status content is collapsed until expanded.\
**Type:** String\
**Version history:** Added in 1.0.0
### `media_attachments`
### `media_attachments` {#media_attachments}
**Description:** Media that is attached to this status.
**Type:** Array of [Attachment](attachment.md)
**Description:** Media that is attached to this status.\
**Type:** Array of [Attachment](attachment.md)\
**Version history:** Added in 0.6.0
### `application`
### `application` {#application}
**Description:** The application used to post this status.
**Type:** [Application](application.md)
**Description:** The application used to post this status.\
**Type:** [Application](application.md)\
**Version history:** Added in 0.9.9
## Rendering attributes
### `mentions`
### `mentions` {#mentions}
**Description:** Mentions of users within the status content.
**Type:** Array of [Mention]({{< relref "mention.md" >}})
**Description:** Mentions of users within the status content.\
**Type:** Array of [Mention]({{< relref "mention.md" >}})\
**Version history:** Added in 0.6.0
### `tags`
### `tags` {#tags}
**Description:** Hashtags used within the status content.
**Type:** Array of [Tag](tag.md)
**Description:** Hashtags used within the status content.\
**Type:** Array of [Tag](tag.md)\
**Version history:** Added in 0.9.0
### `emojis`
### `emojis` {#emojis}
**Description:** Custom emoji to be used when rendering status content.
**Type:** Array of [Emoji](emoji.md)
**Description:** Custom emoji to be used when rendering status content.\
**Type:** Array of [Emoji](emoji.md)\
**Version history:** Added in 2.0.0
## Informational attributes
### `reblogs_count`
### `reblogs_count` {#reblogs_count}
**Description:** How many boosts this status has received.
**Type:** Number
**Description:** How many boosts this status has received.\
**Type:** Number\
**Version history:** Added in 0.1.0
### `favourites_count`
### `favourites_count` {#favorites_count}
**Description:** How many favourites this status has received.
**Type:** Number
**Description:** How many favourites this status has received.\
**Type:** Number\
**Version history:** Added in 0.1.0
### `replies_count`
### `replies_count` {#replies_count}
**Description:** How many replies this status has received.
**Type:** Number
**Description:** How many replies this status has received.\
**Type:** Number\
**Version history:** Added in 2.5.0
## Nullable attributes
### `url`
### `url` {#url}
**Description:** A link to the status's HTML representation.
**Type:** String \(URL\)
**Description:** A link to the status's HTML representation.\
**Type:** String \(URL\)\
**Version history:** Added in 0.1.0
### `in_reply_to_id`
### `in_reply_to_id` {#in_reply_to_id}
**Description:** ID of the status being replied.
**Type:** String \(cast from an integer but not guaranteed to be a number\)
**Description:** ID of the status being replied.\
**Type:** String \(cast from an integer but not guaranteed to be a number\)\
**Version history:** Added in 0.1.0
### `in_reply_to_account_id`
### `in_reply_to_account_id` {#in_reply_to_account_id}
**Description:** ID of the account being replied to.
**Type:** String \(cast from an integer but not guaranteed to be a number\)
**Description:** ID of the account being replied to.\
**Type:** String \(cast from an integer but not guaranteed to be a number\)\
**Version history:** Added in 1.0.0
### `reblog`
### `reblog` {#reblog}
**Description:** ID of the status in the database.
**Type:** [Status](status.md)
**Description:** ID of the status in the database.\
**Type:** [Status](status.md)\
**Version history:** Added in 0.1.0
### `poll`
### `poll` {#poll}
**Description:** The poll attached to the status.
**Type:** [Poll]({{< relref "poll.md" >}})
**Description:** The poll attached to the status.\
**Type:** [Poll]({{< relref "poll.md" >}})\
**Version history:** Added in 2.8.0
### `card`
### `card` {#card}
**Description:** Preview card for links included within status content.
**Type:** [Card]({{< relref "card.md" >}})
**Description:** Preview card for links included within status content.\
**Type:** [Card]({{< relref "card.md" >}})\
**Version history:** Added in 2.6.0
### `language`
### `language` {#language}
**Description:** A link to the status's HTML representation.
**Type:** String \(ISO 639 Part 1 two-letter language code\)
**Description:** A link to the status's HTML representation.\
**Type:** String \(ISO 639 Part 1 two-letter language code\)\
**Version history:** Added in 1.4.0
## Authorized user attributes
### `favourited`
### `favourited` {#favourited}
**Description:** Have you favourited this status?
**Type:** Boolean
**Description:** Have you favourited this status?\
**Type:** Boolean\
**Version history:** Added in 0.1.0
### `reblogged`
### `reblogged` {#reblogged}
**Description:** Have you boosted this status?
**Type:** Boolean
**Description:** Have you boosted this status?\
**Type:** Boolean\
**Version history:** Added in 0.1.0
### `muted`
### `muted` {#muted}
**Description:** Have you muted notifications for this status's conversation?
**Type:** Boolean
**Description:** Have you muted notifications for this status's conversation?\
**Type:** Boolean\
**Version history:** Added in 1.4.0
### `bookmarked`
### `bookmarked` {#bookmarked}
**Description:** Have you bookmarked this status?
**Type:** Boolean
**Description:** Have you bookmarked this status?\
**Type:** Boolean\
**Version history:** Added in 3.1.0
### `pinned`
### `pinned` {#pinned}
**Description:** Have you pinned this status? Only appears if the status is pinnable.
**Type:** Boolean
**Description:** Have you pinned this status? Only appears if the status is pinnable.\
**Type:** Boolean\
**Version history:** Added in 1.6.0
## See also

18
content/en/entities/tag.md
View File

@ -54,24 +54,24 @@ menu:
## Base attributes
### `name`
### `name` {#name}
**Description:** The value of the hashtag after the \# sign.
**Type:** String
**Description:** The value of the hashtag after the \# sign.\
**Type:** String\
**Version history:** Added in 0.9.0
### `url`
### `url` {#url}
**Description:** A link to the hashtag on the instance.
**Type:** String \(URL\)
**Description:** A link to the hashtag on the instance.\
**Type:** String \(URL\)\
**Version history:** Added in 0.9.0
## Optional attributes
### `history`
### `history` {#history}
**Description:** Usage statistics for given days.
**Type:** Array of [History]({{< relref "history.md" >}})
**Description:** Usage statistics for given days.\
**Type:** Array of [History]({{< relref "history.md" >}})\
**Version history:** Added in 2.4.1
## See also

28
content/en/entities/token.md
View File

@ -1,8 +1,6 @@
---
title: Token
description: >-
Represents an OAuth token used for authenticating with the API and performing
actions.
description: Represents an OAuth token used for authenticating with the API and performing actions.
menu:
docs:
parent: entities
@ -21,28 +19,28 @@ menu:
## Attributes
### `access_token`
### `access_token` {#access_token}
**Description:** An OAuth token to be used for authorization.
**Type:** String
**Description:** An OAuth token to be used for authorization.\
**Type:** String\
**Version history:** Added in 0.1.0
### `token_type`
### `token_type` {#token_type}
**Description:** The OAuth token type. Mastodon uses `Bearer` tokens.
**Type:** String
**Description:** The OAuth token type. Mastodon uses `Bearer` tokens.\
**Type:** String\
**Version history:** Added in 0.1.0
### `scope`
### `scope` {#scope}
**Description:** The OAuth scopes granted by this token, space-separated.
**Type:** String
**Description:** The OAuth scopes granted by this token, space-separated.\
**Type:** String\
**Version history:** Added in 0.1.0
### `created_at`
### `created_at` {#created_at}
**Description:** When the token was generated.
**Type:** Number \(UNIX Timestamp\)
**Description:** When the token was generated.\
**Type:** Number \(UNIX Timestamp\)\
**Version history:** Added in 0.1.0
## See also

18
content/en/methods/timelines/streaming.md
View File

@ -13,39 +13,39 @@ Your application can use a [server-sent events](https://developer.mozilla.org/en
Alternatively, a WebSocket connection can also be established.
## Server-sent events \(HTTP\) <a id="server-sent-events-http"></a>
## Server-sent events \(HTTP\)
### Endpoints <a id="endpoints"></a>
#### GET /api/v1/streaming/health <a id="get-api-v1-streaming-health"></a>
#### GET /api/v1/streaming/health
Returns `OK` when streaming service is fine. Added in 2.5.0
#### GET /api/v1/streaming/user <a id="get-api-v1-streaming-user"></a>
#### GET /api/v1/streaming/user
Returns events that are relevant to the authorized user, i.e. home timeline and notifications
#### GET /api/v1/streaming/public <a id="get-api-v1-streaming-public"></a>
#### GET /api/v1/streaming/public
Returns all public statuses
#### GET /api/v1/streaming/public/local <a id="get-api-v1-streaming-public-local"></a>
#### GET /api/v1/streaming/public/local
Returns all local statuses
#### GET /api/v1/streaming/hashtag?tag=:hashtag <a id="get-api-v1-streaming-hashtag-tag-hashtag"></a>
#### GET /api/v1/streaming/hashtag?tag=:hashtag
Returns all public statuses for a particular hashtag
#### GET /api/v1/streaming/hashtag/local?tag=:hashtag <a id="get-api-v1-streaming-hashtag-local-tag-hashtag"></a>
#### GET /api/v1/streaming/hashtag/local?tag=:hashtag
Returns all local statuses for a particular hashtag
#### GET /api/v1/streaming/list?list=:list_id <a id="get-api-v1-streaming-list-list-list-id"></a>
#### GET /api/v1/streaming/list?list=:list_id
Returns statuses for a list
#### GET /api/v1/streaming/direct <a id="get-api-v1-streaming-direct"></a>
#### GET /api/v1/streaming/direct
Returns all direct messages

40
content/en/spec/activitypub.md
View File

@ -1,8 +1,6 @@
---
title: ActivityPub
description: >-
A decentralized social networking protocol based upon the ActivityStreams 2.0
data format and JSON-LD.
description: A decentralized social networking protocol based upon the ActivityStreams 2.0 data format and JSON-LD.
menu:
docs:
weight: 10
@ -13,7 +11,7 @@ menu:
Sample payloads will be added at a future date.
{{< /hint >}}
## Status federation <a id="status"></a>
## Status federation {#status}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/lib/activitypub/activity.rb" caption="app/lib/activitypub/activity.rb" >}}
@ -43,7 +41,7 @@ Some other Object types are converted as best as possible. The transformer uses
* Video
* Event
## Profile federation <a id="profile"></a>
## Profile federation {#profile}
### Supported activities for profiles
@ -75,7 +73,7 @@ Some other Object types are converted as best as possible. The transformer uses
| attachment | Used for profile fields. See [Profile metadata](activitypub.md#profile-metadata) and [Identity proofs](activitypub.md#identityproof). |
| alsoKnownAs | Required for Move activity. |
## HTML sanitization <a id="sanitization"></a>
## HTML sanitization {#sanitization}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/lib/sanitize_config.rb" caption="app/lib/sanitize\_config.rb" >}}
@ -91,11 +89,11 @@ Some other Object types are converted as best as possible. The transformer uses
* ellipsis
* invisible
## JSON-LD Namespacing <a id="namespaces"></a>
## JSON-LD Namespacing {#namespaces}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/lib/activitypub/adapter.rb" caption="app/lib/activitypub/adapter.rb" >}}
### Mastodon extensions \(`toot:`\) <a id="toot"></a>
### Mastodon extensions \(`toot:`\) {#toot}
Contains definitions for Mastodon features.
@ -107,7 +105,7 @@ Contains definitions for Mastodon features.
* toot:discoverable
* toot:votersCount
### ActivityStreams extensions \(`as:`\) <a id="as"></a>
### ActivityStreams extensions \(`as:`\) {#as}
Contains ActivityStreams extended properties that have been proposed but not officially adopted yet.
@ -117,7 +115,7 @@ Contains ActivityStreams extended properties that have been proposed but not off
* as:movedTo
* as:sensitive
### W3ID Security Vocabulary \(`sec:`\) <a id="sec"></a>
### W3ID Security Vocabulary \(`sec:`\) {#sec}
Contains properties used for HTTPS Signatures and Linked Data Signatures. Also used for identity proofs. See [Security](security.md) for more information.
@ -136,7 +134,7 @@ Contains a collection of terms from various namespaces, used for Linked Data Sig
* sec:signature
* sec:signatureValue
### schema.org extensions \(`schema:`\) <a id="schema"></a>
### schema.org extensions \(`schema:`\) {#schema}
Contains properties used for profile metadata.
@ -145,7 +143,7 @@ Contains properties used for profile metadata.
## Extensions
### Public key
### Public key {#publicKey}
Public keys are used for HTTPS Signatures and Linked Data Signatures. This is implemented using an extra property `publicKey` on actor objects. See [Security](security.md) for more information. Example:
@ -165,7 +163,7 @@ Public keys are used for HTTPS Signatures and Linked Data Signatures. This is im
}
```
### Featured collection <a id="featured"></a>
### Featured collection {#featured}
What is known in Mastodon as “pinned toots”, or statuses that are always featured at the top of people’s profiles, is implemented using an extra property `featured` on the actor object that points to a `Collection` of objects. Example:
@ -188,7 +186,7 @@ What is known in Mastodon as “pinned toots”, or statuses that are always fea
}
```
### Custom emojis <a id="emoji"></a>
### Custom emojis {#emoji}
Mastodon supports arbitrary emojis, that is, small images uploaded by admins and invokable via shortcodes. For this, an `Emoji` type is used. These emojis are listed in the `tag` property just like `Mention` and `Hashtag` objects, since they are entities that affect how the text is rendered. Example:
@ -220,7 +218,7 @@ Mastodon supports arbitrary emojis, that is, small images uploaded by admins and
}
```
### Focal points <a id="focalpoint"></a>
### Focal points {#focalPoint}
Mastodon supports setting a focal point on uploaded images, so that wherever that image is displayed, the focal point stays in view. This is implemented using an extra property `focalPoint` on `Image` objects. The property is simply an array of two floating points between -1.0 and 1.0, with 0,0 being the center of the image, the first value being x \(-1.0 is the left edge, +1.0 is the right edge\) and the second value being y \(-1.0 is the bottom edge, +1.0 is the top edge\). See [Focal points](../methods/statuses/media.md#focal-points) for more information. Example:
@ -254,7 +252,7 @@ Mastodon supports setting a focal point on uploaded images, so that wherever tha
}
```
### Blurhash
### Blurhash {#blurhash}
Mastodon generates colorful preview thumbnails for attachments. This is implemented using an extra property `blurhash` on `Image` objects. The property is a string generated by the [BlurHash algorithm](https://blurha.sh). Example:
@ -282,7 +280,7 @@ Mastodon generates colorful preview thumbnails for attachments. This is implemen
}
```
### Profile metadata
### Profile metadata {#PropertyValue}
Mastodon supports arbitrary profile fields containing name-value pairs. This is implemented using the `attachment` property on actor objects, with objects in the array having a type of `PropertyValue` and a `value` property, both from the schema.org namespace. Example:
@ -301,18 +299,18 @@ Mastodon supports arbitrary profile fields containing name-value pairs. This is
{
"type": "PropertyValue",
"name": "Patreon",
"value": "<a href=\"https://www.patreon.com/mastodon\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://www.</span><span class=\"\">patreon.com/mastodon</span><span class=\"invisible\"></span></a>"
"value": "<a href=\"https://www.patreon.com/mastodon\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://www.</span><span class=\"\">patreon.com/mastodon</span><span class=\"invisible\"></span}"
},
{
"type": "PropertyValue",
"name": "Homepage",
"value": "<a href=\"https://zeonfederated.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">zeonfederated.com</span><span class=\"invisible\"></span></a>"
"value": "<a href=\"https://zeonfederated.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">zeonfederated.com</span><span class=\"invisible\"></span}"
}
]
}
```
### Identity proofs <a id="identityproof"></a>
### Identity proofs {#IdentityProof}
Mastodon supports integration with identity providers to prove that a profile is linked to a certain identity. This is implemented using the `attachment` property on actor objects, with objects in the array having a type of `IdentityProof` from the Mastodon namespace. The object also includes `signatureAlgorithm` and `signatureValue` from the W3ID Security Vocabulary namespace. Example:
@ -339,7 +337,7 @@ Mastodon supports integration with identity providers to prove that a profile is
}
```
### Discoverability flag <a id="discoverable"></a>
### Discoverability flag {#discoverable}
Mastodon allows users to opt-in or opt-out of discoverability features like the profile directory. This flag may also be used as an indicator of the user's preferences toward being included in external discovery services, such as search engines or other indexing tools. If you are implementing such a tool, it is recommended that you respect this property if it is present. This is implemented using an extra property `discoverable` on objects. Example:

48
content/en/spec/microformats.md
View File

@ -7,92 +7,92 @@ menu:
parent: spec
---
## What are microformats?
## What are microformats? {#intro}
[Microformats 2.0](https://microformats.io/) is a standard used to embed metadata directly within an HTML document. Rather than needing to use an API for read-only purposes, a web page can simply be parsed for certain CSS classes in order to extract information that you have already fetched simply by viewing the page, rather than having to separately request that same information from an API. The use of microformats classes allows for semantic parsing of data within a given web page, and can be used to generate feeds, cards, or representations of that data.
## Microformats classes
## Microformats classes {#classes}
All microformats classes use a prefix. The prefix indicates the type of the element, independent of hierarchy. These are the microformats classes as used in Mastodon's codebase.
### Root elements \(`h-*`\)
### Root elements \(`h-*`\) {#h}
#### `h-feed`
#### `h-feed` {#h-feed}
Represents a stream of entries. Attached to a profile's toots. Also attached to the parent thread within detailed status views.
#### `h-entry`
#### `h-entry` {#h-entry}
Represents episodic or date stamped online content. Attached to a status.
#### `h-cite`
#### `h-cite` {#h-cite}
Represents a reference to another online publication. Attached to a boost. Also attached to other statuses in the thread within detailed status views.
#### `h-card`
#### `h-card` {#h-card}
Represents a person or organization. Attached to the container of display name, username, and avatar. Also attached to mentions.
### Plain-text properties \(`p-*`\)
### Plain-text properties \(`p-*`\) {#p}
#### `p-author`
#### `p-author` {#p-author}
Within `h-entry` or `h-cite`, represents the author of the entry, and is attached to the container of display name, username, and avatar.
#### `p-name`
#### `p-name` {#p-name}
Within `h-feed`, represents the title of the feed. Attached to `data` element with `value` attribute.
Within `h-entry` or `h-cite`, represents the title of the entry. Unused in Mastodon.
Within `h-card`, represents the plain-text name of a person or organization. Attached to display name.
#### `p-in-reply-to`
#### `p-in-reply-to` {#p-in-reply-to}
Within `h-entry` of a detailed status, represents the status that is the direct parent.
#### `p-repost-of`
#### `p-repost-of` {#p-repost-of}
Within h-entry of a detailed status, represents a post that is a reblog and also a direct parent. Currently unused, since reblogs cannot be replied to.
#### `p-comment`
#### `p-comment` {#p-comment}
Within `h-entry` of a detailed status, represents statuses that are direct children.
### URL properties \(`u-*`\)
### URL properties \(`u-*`\) {#u}
#### `u-photo`
#### `u-photo` {#u-photo}
Within `h-card`, represents the profile picture. Attached to the avatar image.
#### `u-uid`
#### `u-uid` {#u-uid}
Within `h-entry` or `h-cite`, represents a universally unique identifier. Attached to timestamp link.
#### `u-url`
#### `u-url` {#u-url}
Within `h-entry` or `h-cite`, represents the status permalink. Attached to timestamp link.
Within `h-card`, represents the profile permalink. Attached to display name link.
### Datetime properties \(`dt-*`\)
### Datetime properties \(`dt-*`\) {#dt}
#### `dt-published`
#### `dt-published` {#dt-published}
Within `h-entry` or `h-cite`, represents the date and time at which the status was published. Attached to `data` element with `value` attribute.
### Element tree \(`e-*`\)
### Element tree \(`e-*`\) {#e}
#### `e-content`
#### `e-content` {#e-content}
Within `h-entry` or `h-cite`, represents the content of the status. Attached to status content.
## Additional classes
## Additional classes {#mastodon}
These elements are attached by Mastodon for parsing metadata, but are not technically part of the Microformats vocabulary.
#### `mention`
#### `mention` {#mention}
Indicates that the link should be opened in-app with the associated mention data from the API.
#### `hashtag`
#### `hashtag` {#hashtag}
Indicates that the link should be opened in-app with the associated hashtag data from the API.

14
content/en/spec/oauth.md
View File

@ -1,15 +1,13 @@
---
title: OAuth
description: >-
An open standard for token-based authentication and authorization on the
Internet
description: An open standard for token-based authentication and authorization on the Internet
menu:
docs:
weight: 50
parent: spec
---
## What is OAuth?
## What is OAuth? {#intro}
The Mastodon API has many methods that require authentication from a client or authorization from a user. This is accomplished with OAuth 2.0, an authorization framework described in [RFC 6749](https://tools.ietf.org/html/rfc6749) that allows third-party applications to obtain limited access to an HTTP service on behalf of a resource owner, through the use of a standardized authorization flow that generates a client access token to be used with HTTP requests.
@ -21,7 +19,7 @@ Mastodon supports the following OAuth 2 flows:
To obtain an OAuth token for a Mastodon website, make sure that you allow your users to specify the domain they want to connect to before login. Use that domain to [acquire a client id/secret](../methods/apps/#create-an-application) and then [proceed with normal OAuth 2]({{< relref "../methods/apps/oauth.md" >}}).
## OAuth 2 endpoints implemented <a id="oauth-2-endpoints"></a>
## OAuth 2 endpoints implemented {#implementation}
The following descriptions are taken from the [Doorkeeper documentation](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples). Mastodon uses Doorkeeper to implement OAuth 2. For more information on how to use these endpoints, see the [API documentation for OAuth.]({{< relref "../methods/apps/oauth.md" >}})
@ -31,15 +29,15 @@ The following descriptions are taken from the [Doorkeeper documentation](https:/
Displays an authorization form to the user. If approved, it will create and return an authorization code, then redirect to the desired `redirect_uri`, or show the authorization code if `urn:ietf:wg:oauth:2.0:oob` was requested.
### [POST /oauth/token](../methods/apps/oauth.md#obtain-a-token) <a id="post-oauth-token"></a>
### [POST /oauth/token](../methods/apps/oauth.md#obtain-a-token) {#post-oauth-token}
Obtain an access token. This corresponds to the token endpoint, section 3.2 of the OAuth 2 RFC.
### [POST /oauth/revoke](../methods/apps/oauth.md#revoke-token) <a id="post-oauth-revoke"></a>
### [POST /oauth/revoke](../methods/apps/oauth.md#revoke-token) {#post-oauth-revoke}
Post here with client credentials to revoke an access token. This corresponds to the token endpoint, using the OAuth 2.0 Token Revocation RFC \(RFC 7009\).
## Common gotchas <a id="common-gotchas"></a>
## Common gotchas {#gotchas}
* When registering an application using Mastodon's REST API, there is a `scopes` parameter. When interfacing with OAuth endpoints, you must use the `scope` parameter instead, and this parameter's value must be a subset of the `scopes` registered with the app. You cannot include anything that wasn't in the original set.
* When registering an application using Mastodon's REST API, there is a `redirect_uris` parameter. When interfacing with OAuth endpoints, you must use the `redirect_uri` parameter instead, and this parameter's value must be one of the `redirect_uris` registered with the app.

12
content/en/spec/security.md
View File

@ -7,7 +7,7 @@ menu:
parent: spec
---
## HTTP Signatures
## HTTP Signatures {#http}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/lib/request.rb" caption="app/lib/request.rb" >}}
@ -40,7 +40,7 @@ The `keyId` should correspond to the actor and the key being used to generate th
See also: [https://blog.joinmastodon.org/2018/07/how-to-make-friends-and-verify-requests/](https://blog.joinmastodon.org/2018/07/how-to-make-friends-and-verify-requests/)
### Creating HTTP signatures
### 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:
@ -73,7 +73,7 @@ Signature: keyId="https://my-example.com/actor#main-key",headers="(request-targe
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`.
### Verifying HTTP signatures
### Verifying HTTP signatures {#http-verify}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/controllers/concerns/signature_verification.rb" caption="app/controllers/concerns/signature\_verification.rb" >}}
@ -95,7 +95,7 @@ Mastodon verifies the signature using the following algorithm:
* 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
## Linked Data Signatures {#ld}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/lib/activitypub/linked_data_signature.rb" caption="app/lib/activitypub/linked\_data\_signature.rb" >}}
@ -104,7 +104,7 @@ Mastodon verifies the signature using the following algorithm:
* When running a [self-destruct](../admin/tootctl.md#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
### 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:
@ -121,7 +121,7 @@ To create a signature, Mastodon uses the keypair attached to an actor at `https:
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
### Verifying LD signatures {#ld-verify}
To verify a signature, Mastodon uses the following algorithm:

4
content/en/spec/webfinger.md
View File

@ -7,7 +7,7 @@ menu:
parent: spec
---
## What is WebFinger, and why is it used?
## What is WebFinger, and why is it used? {#intro}
On Mastodon, user profiles can be hosted either locally on the same website as yours, or remotely on a completely different website. The same username may be used on a different domain. Therefore, a Mastodon user's full mention consists of both the username and the domain, in the form `@username@domain`. In practical terms, `@user@example.com` is not the same as `@user@example.org`. If the domain is not included, Mastodon will try to find a local user named `@username`. However, in order to deliver to someone over ActivityPub, the `@username@domain` mention is not enough -- **mentions must be translated to an HTTPS URI first**, so that the remote actor's inbox and outbox can be found.
@ -17,7 +17,7 @@ Enter WebFinger. WebFinger as described in [RFC 7033](https://tools.ietf.org/htm
**Because Mastodon heavily relies on mentions for addressing other profiles, WebFinger is required for fully interoperating with Mastodon.** Users can generally load profiles by searching for the direct HTTPS URI if they know it, or for the `username@domain` address, but Mastodon's internal logic depends almost completely on `acct`: URIs or `username@domain` representations. Searching for any objects or profiles from an ActivityPub implementation without WebFinger will fail because the author cannot be converted to a user in the local database.
{{< /hint >}}
## Sample WebFinger flow
## Sample WebFinger flow {#example}
Suppose we want to lookup the user `@Gargron` hosted on the `mastodon.social` website.

12
content/en/user/contacts.md
View File

@ -1,19 +1,19 @@
---
title: More settings
description: 'Invite new users, sort through your contacts, and secure your account.'
description: Invite new users, sort through your contacts, and secure your account.
menu:
docs:
weight: 80
parent: user
---
## Generating invites
## Generating invites {#invites}
{{< figure src="/assets/image%20%2862%29.png" caption="Invite people from your account&apos;s settings" >}}
Invite links can be generated and shared with other people, and some servers require invites in order to register for an account. When generating an invite link, you can set the max uses to limit how many times a certain link is used, or how long it has been active. Invite links can be deactivated at any time.
## Follows and followers
## Follows and followers {#relationships}
{{< figure src="/assets/image%20%2849%29.png" caption="Mutuals who have not moved their account, sorted by last activity" >}}
@ -25,15 +25,15 @@ Within settings, you can find a relationship manager that lets you filter and so
You can select certain users to unfollow, or to remove from your followers, by checking the boxes and clicking the corresponding button in the table header.
## Account settings
## 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
## Identity proofs {#proofs}
[Link verification](profile.md#link-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 identity verification {#keybase}
{{< figure src="/assets/image%20%2860%29.png" caption="An identity proof on a profile" >}}

12
content/en/user/discoverability.md
View File

@ -1,33 +1,33 @@
---
title: Promoting yourself and others
description: 'Give visibility to hashtags, profiles, and posts.'
description: Give visibility to hashtags, profiles, and posts.
menu:
docs:
weight: 60
parent: user
---
## Featured links on your profile
## Featured links on your profile {#featured}
### Featured hashtags
### Featured hashtags {#featured-tags}
{{< figure src="/assets/image%20%2858%29.png" caption="A featured hashtag showing last usage date and total usage." >}}
You can choose to feature certain hashtags that you use often. Go to Settings &gt; Profile &gt; Featured hashtags to manage which hashtags you are currently featuring. Once featured, a link to the hashtag will be shown on your profile, with the date of the last time it was used in a status, as well as the total number of statuses in which it was used.
### Featured profiles
### Featured profiles {#featured-profiles}
{{< figure src="/assets/image%20%2833%29.png" caption="Four randomly-selected featured profiles." >}}
You can choose to feature profiles of people that you are following. Go to that person's profile dropdown menu and click "Feature on profile". When you feature a profile, a link to their profile will appear on your profile, under a section titled "your choices". Up to 4 profiles will be shown at a time, and these profiles are selected randomly from your pool of featured profiles every time the page is loaded.
## Pinned posts
## Pinned posts {#pinned}
{{< figure src="/assets/image%20%2837%29.png" caption="A pinned toot by mastodon.social/@gargron" >}}
You can choose to feature up to 5 of your own public posts at the top of your profile. Go to the status dropdown menu and click "Pin on profile". When you pin a toot, it will appear at the top of your "toots" tab, before all other chronological status updates.
## Profile directory
## Profile directory {#directory}
{{< figure src="/assets/image%20%2831%29.png" caption="Profile directory as seen from mastodon.social" >}}

4
content/en/user/external.md
View File

@ -7,7 +7,7 @@ menu:
parent: user
---
## Remote interactions on another Mastodon site
## Remote interactions on another Mastodon site {#interact}
{{< figure src="/assets/image%20%2863%29.png" caption="An example of a post&apos;s public permalink on a Mastodon site." >}}
@ -15,7 +15,7 @@ When you are browsing a remote site powered by Mastodon, clicking on any of the
{{< figure src="/assets/image%20%288%29.png" caption="A remote interaction dialog for replying to a toot." >}}
## Signing into a client app
## Signing into a client app {#apps}
You can use your Mastodon account to sign into any app that implements the Mastodon API. A list of such apps can be found at [https://joinmastodon.org/apps](https://joinmastodon.org/apps).

26
content/en/user/moderating.md
View File

@ -1,13 +1,13 @@
---
title: Dealing with unwanted content
description: 'Control what you see, for a more comfortable social media experience.'
description: Control what you see, for a more comfortable social media experience.
menu:
docs:
weight: 50
parent: user
---
## Filtering posts <a id="blocking-and-muting"></a>
## Filtering posts {#filters}
It is possible to filter statuses for specific keywords and phrases so that they can be hidden automatically.
@ -19,15 +19,15 @@ To create or manage your filters, go to Settings &gt; Filters. The "Add new filt
Filters have the following settings:
### Keyword or phrase
### Keyword or phrase {#filter-phrase}
This is the string that will be matched. The keyword will be searched for in any status's content, including CW, media descriptions, and poll options.
### Expire after
### Expire after {#filter-expire}
Optionally only apply the filter for a limited amount of time. Expired filters are not automatically deleted, but can be reactivated by setting a new expiry date \(or changing it back to "never" expire\).
### Filter contexts
### Filter contexts {#filter-context}
Choose where the filter will be applied:
@ -36,23 +36,23 @@ Choose where the filter will be applied:
* Public timelines = matching statuses will not appear in local/federated timelines
* Conversations = matching statuses will be hidden in threads and detailed views
### Drop instead of hide
### Drop instead of hide {#filter-drop}
Filtering is usually done client-side, so that disabling a filter will cause filtered statuses to be visible again. However, if you enable "drop instead of hide", any matching statuses will be disappear completely and will never be delivered to your home or notifications.
### Whole word
### Whole word {#filter-whole}
Filters normally apply to any status that contains the included characters, regardless of whether they are in the middle of a word. Enabling "whole word" will only apply the filter if the keyword is surrounded by spaces or other non-alphanumeric characters.
## User-level actions <a id="blocking-and-muting"></a>
## User-level actions {#blocking-and-muting}
{{< figure src="/assets/image%20%2824%29.png" caption="The user dropdown menu offers various actions." >}}
### Hiding boosts <a id="hiding-boosts"></a>
### Hiding boosts {#hide-boosts}
If you hide boosts from someone, you won’t see their boosts in your home feed. This option only appears on users who you are currently following.
### Muting <a id="muting"></a>
### Muting {#mute}
{{< figure src="/assets/image%20%2852%29.png" caption="Sample of muted accounts." >}}
@ -67,7 +67,7 @@ If you choose to also mute notifications from them, you will additionally not se
The user has no way of knowing they have been muted.
### Blocking <a id="blocking"></a>
### Blocking {#block}
{{< figure src="/assets/image%20%2836%29.png" caption="Sample of blocked accounts." >}}
@ -88,7 +88,7 @@ Additionally, on the blocked user’s side:
If you and the blocked user are on the same server, the blocked user will not be able to view your posts on your profile while logged in.
### Hiding an entire server <a id="hiding-an-entire-server"></a>
### Hiding an entire server {#hide-domain}
![](/assets/image%20%2861%29.png)
@ -99,7 +99,7 @@ If you hide an entire server:
* You won’t see notifications from that server
* You will lose any followers that you might have had on that server
## Reporting problematic content to moderators
## Reporting problematic content to moderators {#report}
{{< figure src="/assets/image%20%283%29.png" caption="The report modal allows selecting example statuses, adding a note, and forwarding reports." >}}

13
content/en/user/moving.md
View File

@ -1,12 +1,13 @@
---
title: Moving or leaving accounts
description: Take your information and do what you want with it.
menu:
docs:
weight: 100
parent: user
---
## Exporting your information
## Exporting your information {#export}
{{< figure src="/assets/image%20%2835%29.png" caption="The data export page in settings" >}}
@ -14,29 +15,29 @@ At any time you want, you can go to Settings &gt; Export and download a CSV file
Requesting an archive of your toots and media can be done once every 7 days, and can be downloaded in ActivityPub JSON format. Mastodon currently does not support importing toots or media due to technical limitations, but your archive can be viewed by any software that understands how to parse ActivityPub documents.
## Redirecting or moving your profile
## Redirecting or moving your profile {#migration}
From the bottom of Settings &gt; Account, you can find options related to account redirection or migration.
### Profile redirect
### Profile redirect {#redirect}
{{< figure src="/assets/image%20%2853%29.png" caption="Profile redirect form" >}}
Redirecting your account disables posting from that account and displays a "profile moved" notice indicating your new account. Anyone viewing your profile can see this notice and will know to follow you at your new account. Following redirected accounts is not possible. The redirect can be canceled at any time.
### Profile move
### Profile move {#move}
{{< figure src="/assets/image%20%2847%29.png" 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 toots 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!
### Account aliases
### Account aliases {#aliases}
{{< figure src="/assets/image%20%2840%29.png" caption="Alias management screen" >}}
Profile moves can only be initiated when your two accounts have been aliased. Account aliases are currently not used for anything other than profile moves, where you will need to set your old account as an alias of your new account before initiating the move. Setting aliases is harmless and reversible on its own.
## Deleting your account
## Deleting your account {#delete}
{{< figure src="/assets/image%20%2816%29.png" caption="Account deletion form" >}}

14
content/en/user/network.md
View File

@ -7,7 +7,7 @@ menu:
parent: user
---
## Browsing content through public timelines
## Browsing content through public timelines {#timelines}
{{< figure src="/assets/image%20%2830%29.png" caption="Posts within a public timeline" >}}
@ -15,7 +15,7 @@ To allow you to discover potentially interesting content, Mastodon provides a wa
There is a way to filter the federated timeline to view only public posts created on your server: The **local timeline**. Mind that “local” here refers to the server, not to a geographical location.
## Interacting with people's posts
## Interacting with people's posts {#actions}
{{< figure src="/assets/image%20%2821%29.png" caption="An expanded view can be loaded by clicking a status in the timeline." >}}
@ -27,7 +27,7 @@ You can perform quick actions on a post directly from the timeline, or you can c
* **Bookmark** a post by clicking the ribbon icon. The post will be privately added to your bookmarks list without generating a notification.
* Access a **menu** of additional options by clicking the ellipsis icon.
## Notifications
## Notifications {#notifications}
{{< figure src="/assets/image%20%2850%29.png" caption="Notifications column" >}}
@ -39,7 +39,7 @@ When other people interact with you or your posts, you will receive a notificati
* **Polls:** Received when a poll that you have voted in or created has ended.
* **Follows:** Received when someone has followed your profile.
## Following profiles
## Following profiles {#follow}
![](/assets/image%20%2811%29.png)
@ -49,7 +49,7 @@ However if you come across someone’s public profile hosted on a different serv
If you are visiting a public page on another Mastodon site, see [Using Mastodon outside of your site](external.md#remote-interactions-on-another-mastodon-site).
## Search
## Search {#search}
{{< figure src="/assets/image%20%2819%29.png" caption="The search function can be accessed from the sidebar." >}}
@ -69,7 +69,7 @@ The following operators are supported:
* **-exclude** will exclude the term prepended by a minus sign. This allows filtering out certain terms, such as `animals -cats` to find posts about animals without posts about cats.
* **+include** will include the term after the plus sign. This allows searching for multiple terms that must be included, such as `cat +dog` to find posts about both cats and dogs.
## Direct conversations
## Direct conversations {#direct}
{{< figure src="/assets/image%20%2812%29.png" caption="A list of conversations containing direct messages." >}}
@ -77,7 +77,7 @@ In Mastodon, direct messages are simply toots that have the "direct" visibility
{{< figure src="/assets/image%20%2857%29.png" caption="A direct message in a thread." >}}
## List timelines
## List timelines {#lists}
Lists are subsets of your home timeline. You can create a list, give it a name, and add users that you follow to that list.

30
content/en/user/posting.md
View File

@ -9,39 +9,39 @@ menu:
{{< figure src="/assets/image%20%2859%29.png" caption="Compose form with CW enabled" >}}
## Text
## Text {#text}
The main body of each status update can be composed using the text field. The default character limit is 500 characters.
### Links
### Links {#links}
{{< figure src="/assets/image%20%287%29.png" caption="Links must start with http\(s\):// and are counted as 23 characters regardless of length." >}}
If you include links in your post, they must begin with `http://` or `https://`. 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.
### Mentions
### Mentions {#mentions}
{{< figure src="/assets/image%20%2820%29.png" caption="Suggested mentions for both local and remote users." >}}
You can mention users by typing out their full address, e.g. `@alice@example.com`. Note that any usage of`@word` will be interpreted as mentioning the local user with the username `word`, if that user exists. Only the username part will count against your character limit -- the domain is not counted.
### Hashtags
### Hashtags {#hashtags}
{{< figure src="/assets/image%20%2825%29.png" caption="Hashtags are autosuggested by usage frequency." >}}
You can use a `#hashtag` to make your post discoverable to anyone searching for that hashtag. Hashtags can contain alphanumeric characters and underscores, but cannot contain numbers only.
### Custom emoji
### Custom emoji {#emoji}
{{< figure src="/assets/image%20%2838%29.png" caption="An array of custom emoji are available in the selector." >}}
Each server offers a set of custom emoji you can use, like on Discord. You can use an emoji using its shortcode like `:thounking:`, or by clicking the emoji face in the compose box and browsing through the "Custom" category. You can also browse through and search for standard unicode emoji.
## Attachments
## Attachments {#attachments}
You can attach either files or a poll to your status.
### Files
### Files {#media}
{{< figure src="/assets/image%20%2844%29.png" caption="Thumbnail for attached media, with options to delete, edit, or mark as sensitive" >}}
@ -52,13 +52,13 @@ Click the paper clip to attach a file to your post. You can attach the following
* **Videos** \(MP4, M4V, MOV, WebM\) **up to 40MB**. Video will be transcoded to H.264 MP4 with a maximum bitrate of 1300kbps and framerate of 60fps.
* **Audio** \(MP3, OGG, WAV, FLAC, OPUS, AAC, M4A, 3GP\) **up to 40MB**. Audio will be transcoded to MP3 using V2 VBR \(roughly 192kbps\).
#### Editing media
#### Editing media {#edit}
{{< figure src="/assets/image%20%2826%29.png" caption="Edit media to add a media description or choose a focal point for the preview thumbnail." >}}
By clicking the "Edit" link on the attachment thumbnail, you can load a modal which will allow adding a media description or changing the focal point. Although optional, it is a good idea to add media descriptions that briefly describe what is in contained in the media. These descriptions will be shown when the media fails to load for any reason, or when accessed by screen readers and other assistive technology. Setting the focal point is also optional, but can make preview thumbnails looks better when they are not shown in a 16:9 aspect ratio.
### Polls
### Polls {#polls}
{{< figure src="/assets/image%20%2841%29.png" caption="A poll with 2 one-of choices, expiring in 1 day" >}}
@ -68,7 +68,7 @@ Click the bar graph icon to attach a poll to your post.
* Polls default to one-of / single-choice. Click on the radio button to switch your poll to any-of / multiple-choice checkboxes.
* Polls can be set to expire in 5 minutes, 30 minutes, 1 hour, 6 hours, 1 day, 3 days, or 7 days.
## Publishing levels
## Publishing levels {#privacy}
| Level | Public timelines | Permalink | Profile view | Home feeds |
| :--- | :--- | :--- | :--- | :--- |
@ -79,7 +79,7 @@ Click the bar graph icon to attach a poll to your post.
Posts can be published with four different privacy levels:
### Public
### Public {#public}
The default option.
@ -88,13 +88,13 @@ The default option.
* Your followers will receive the post in their home feeds, and anyone mentioned will receive the post in notifications.
* Your post can be boosted into other home feeds.
### Unlisted
### Unlisted {#unlisted}
Exactly the same as public, but with the following difference:
* Your post will not appear in Mastodon's public timelines.
### Followers-only
### Followers-only {#private}
A more limited delivery option.
@ -111,7 +111,7 @@ To effectively publish private \(followers-only\) posts, you must **lock your ac
Please mind that post privacy on Mastodon is per-post, rather than account-wide, and as such **there is no way to make past public posts private.**
{{< /hint >}}
### Direct
### Direct {#direct}
Send your post only to mentioned users.
@ -124,7 +124,7 @@ Send your post only to mentioned users.
**Do not share dangerous and sensitive information over direct messages**. Mastodon is not an encrypted messaging app like Signal or Wire, the database administrators of the sender’s and recipient’s servers have access to the text. Use them with the same caution as you would use forum PMs, Discord PMs and Twitter DMs.
{{< /hint >}}
## Content warnings and sensitive content
## Content warnings and sensitive content {#cw}
{{< figure src="/assets/image.png" caption="A status with a CW that is marked as sensitive content." >}}

22
content/en/user/preferences.md
View File

@ -7,15 +7,15 @@ menu:
parent: user
---
## Customizing the user interface
## Customizing the user interface {#interface}
### Choose a theme
### Choose a theme {#theme}
Mastodon defaults to a dark theme, but a light or high-contrast theme can be selected.
{{< figure src="/assets/image%20%2834%29.png" caption="Mastodon light theme" >}}
### Choose your layout
### Choose your layout {#layout}
Mastodon defaults to a simple, one-column layout with a compose box on the left and a column switcher on the right. You can choose to enable the advanced web interface, which allows you view and pin multiple columns at the same time.
@ -27,7 +27,7 @@ For accessibility reasons, the auto-play of animated GIFs is disabled by default
Trending hashtags can be shown or hidden below the getting started column in the advanced UI, or below the column switcher in the simple UI \(only when there is enough space to display them\).
### Confirmation dialogs
### Confirmation dialogs {#confirm}
You can choose to require confirmation before performing certain actions. Currently, confirmations can be set before performing the following actions:
@ -35,7 +35,7 @@ You can choose to require confirmation before performing certain actions. Curren
* Boost
* Delete
### Sensitive content
### Sensitive content {#sensitive}
By default, any media marked as sensitive is hidden behind a click-through overlay. You can also choose to always show/hide media behind this overlay, regardless of whether it is marked as sensitive.
@ -45,9 +45,9 @@ Hidden and unloaded media uses a colorful gradient provided by the BlurHash algo
Posts with content warnings are collapsed by default, but you can choose to always expand the warnings so that the full post is displayed.
## Controlling your notifications
## Controlling your notifications {#notifications}
### Sending emails
### Sending emails {#email}
You can choose to receive email notifications according to the type of notification you receive within Mastodon. The following notification types are available to enable:
@ -59,13 +59,13 @@ You can choose to receive email notifications according to the type of notificat
You can also enable digest emails, which will provide you with an overview of notifications received during periods of long inactivity.
### Hiding certain notifications
### Hiding certain notifications {#hide-notifications}
You can choose to not receive notifications from people you don't follow, or from people who don't follow you. This will cause replies, favourites, boosts, and other interactions to not be shown to you.
You can also choose to not receive notifications when you receive a direct message from people you don't follow.
## Miscellaneous options
## Miscellaneous options {#misc}
If you opt out of search engine indexing, a `noindex` flag will be added to your public profile and status pages.
@ -75,7 +75,7 @@ You can choose to hide your network, which will make your following and follower
If you want to see posts that are boosted multiple times be reinserted into your feed at the top, you can disable boost grouping in timelines.
### Posting defaults
### Posting defaults {#posting}
Posts default to public privacy. You can choose to default new posts as unlisted or followers-only instead. For an explanation of post privacy levels, see [Posting to your Mastodon profile &gt; Publishing levels](posting.md#publishing-levels).
@ -83,7 +83,7 @@ By default, the language of your posts is automatically detected, but this detec
If you often post sensitive media, you can choose to always mark your media as sensitive.
### Filtering languages on public timelines
### Filtering languages on public timelines {#languages}
You can choose to only show posts in certain detected languages while browsing the public timelines. However, note that language detection can be very imprecise, so you may still see some posts in a disabled language, or miss some posts from enabled languages.

22
content/en/user/profile.md
View File

@ -7,50 +7,50 @@ menu:
parent: user
---
## Your appearance
## Your appearance {#appearance}
{{< figure src="/assets/image%20%2829%29.png" caption="Profile cards showing display name, avatar, and header" >}}
You can change how your profile appears to others by navigating to Settings &gt; Profile &gt; Appearance.
### Display name
### Display name {#name}
Your display name is shown to other users before your address. You can set a display name up to 30 characters by default.
### Bio
### 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.
### Avatar
### Avatar {#avatar}
Your avatar is an icon that is displayed next to your posts and is part of your visual identity. You can upload an avatar as a PNG, GIF, or JPG image up to 2MB in size. This image will be downscaled to 400x400.
### Header
### Header {#header}
Your header is a banner image shown at the top of your profile, as well as in profile cards used in follow lists and account directories. You can upload a header as a PNG, GIF, or JPG image up to 2MB in size. This image will be downscaled to 1500x500.
## Profile flags
## Profile flags {#flags}
You can set certain flags on your profile to let others know how you use Mastodon.
![](/assets/image%20%281%29.png)
### Locked account
### Locked account {#locked}
By locking your account, two things will happen:
* New followers will not be automatically accepted, but will instead require you to manually approve them.
* A lock icon will be shown to others, to let them know that their follow will not be immediately accepted.
### Bot account
### Bot account {#bot}
Enabling the bot flag will add a bot icon to your profile. This icon will let others know that your profile may perform automated actions, or might not be monitored by a human. Other software may choose to treat bot profiles differently, but Mastodon currently treats the bot flag as a visual indication only.
### Profile directory
### Profile directory {#discoverable}
Opting in to be listed on the profile directory will make your profile discoverable through a feature that allows browsing through profiles.
## Profile metadata
## Profile metadata {#fields}
Profile metadata is a way to add extra information to your profile that is easy to skim. You have 4 rows where you can define the label and the value. For example:
@ -63,7 +63,7 @@ Profile metadata is a way to add extra information to your profile that is easy
It’s completely up to you what you put there. The content can contain mentions, hashtags, custom emojis and links.
### Link verification
### Link verification {#verification}
Document-based verification and blue ticks are not possible without a central authority. However, Mastodon can cross-reference the links you put on your profile to prove that you are the real owner of those links. In case one of those links is your personal homepage that is known and trusted, it can serve as the next-best-thing to identity verification.

14
content/en/user/signup.md
View File

@ -7,7 +7,7 @@ menu:
parent: user
---
## Choosing a website
## Choosing a website {#picker}
You have to choose a website to sign up on, like you would choose an e-mail provider, or a World of Warcraft realm for your new character. The website will be your service provider, hosting your account, your profile, and your home feed.
@ -15,27 +15,27 @@ You have to choose a website to sign up on, like you would choose an e-mail prov
You can [browse a list of servers by categories and languages on joinmastodon.org](https://joinmastodon.org/#getting-started).
{{< /hint >}}
### Understanding a website's policies
### Understanding a website's policies {#tos}
Before you sign up for a service, it is important to understand its policies and terms of use. A Mastodon website will usually have its policies listed on the `/about/more` page, which can be found by clicking "learn more" on the landing page while not logged in to that website.
### Signup modes
### Signup modes {#signup}
Mastodon allows website administrators to set one of three different signup modes: open signups, invites, and approval mode.
#### Open signup
#### Open signup {#open}
Some websites may allow you to register immediately -- simply fill out the registration with your username, email address, and password, and you can start using your account.
#### Server invites
#### Server invites {#invite}
Some websites disable the registration form, and instead require invite links to be generated and shared in order to allow people to register.
#### Approval-based registration
#### Approval-based registration {#approval}
Some websites allow you to fill out a registration form, but with an additional form entry for mentioning why you want to join that website. Once you submit the form, your account must be approved by a moderator before you can start using it.
## Your username and your domain
## Your username and your domain {#address}
Mastodon usernames actually consist of two parts: