start Polish translation work
Signed-off-by: Marcin Mikołajczak <me@m4sk.in>
This commit is contained in:
Marcin Mikołajczak
parent
4428120873
commit
2efc21ca29
|
|
@ -13,6 +13,10 @@ enableGitInfo = true
|
|||
contentDir = "content/en"
|
||||
languageName = "English"
|
||||
weight = 1
|
||||
[languages.pl]
|
||||
contentDir = "content/pl"
|
||||
languageName = "Polski"
|
||||
weight = 1
|
||||
|
||||
[menu]
|
||||
[[menu.docs]]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,15 @@
|
|||
---
|
||||
title: Dokumentacja Mastodona
|
||||
---
|
||||
|
||||
Witaj w dokumentacji Mastodona!
|
||||
|
||||
<div style="margin-bottom: 26px">
|
||||
{{< youtube "IPSbNdBmWKE" >}}
|
||||
</div>
|
||||
|
||||
**Wybierz swoją drogę:**
|
||||
|
||||
- [Dowiedz się jak korzystać z Mastodona]({{< relref "usage/basics.md" >}})
|
||||
- [Dowiedz się jak zainstalować Mastodona]({{< relref "administration/installation.md" >}})
|
||||
- [Dowiedz się jak napisać aplikację dla Mastodona]({{< relref "api/guidelines.md" >}})
|
||||
|
|
@ -0,0 +1,216 @@
|
|||
---
|
||||
title: Configuration
|
||||
description: Overview of Mastodon's configuration options
|
||||
menu:
|
||||
docs:
|
||||
parent: administration
|
||||
weight: 2
|
||||
---
|
||||
|
||||
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
|
||||
### Federation
|
||||
|
||||
- `LOCAL_DOMAIN`
|
||||
- `WEB_DOMAIN`
|
||||
- `ALTERNATE_DOMAINS`
|
||||
|
||||
### Secrets
|
||||
|
||||
- `SECRET_KEY_BASE`
|
||||
- `OTP_SECRET`
|
||||
- `VAPID_PRIVATE_KEY`
|
||||
- `VAPID_PUBLIC_KEY`
|
||||
|
||||
### Deployment
|
||||
|
||||
- `RAILS_ENV`
|
||||
- `RAILS_SERVE_STATIC_FILES`
|
||||
- `RAILS_LOG_LEVEL`
|
||||
- `TRUSTED_PROXY_IP`
|
||||
- `SOCKET`
|
||||
- `PORT`
|
||||
- `NODE_ENV`
|
||||
- `BIND`
|
||||
|
||||
### Scaling options
|
||||
|
||||
- `WEB_CONCURRENCY`
|
||||
- `MAX_THREADS`
|
||||
- `PREPARED_STATEMENTS`
|
||||
- `STREAMING_API_BASE_URL`
|
||||
- `STREAMING_CLUSTER_NUM`
|
||||
|
||||
## Database connections
|
||||
### PostgreSQL
|
||||
|
||||
- `DB_HOST`
|
||||
- `DB_USER`
|
||||
- `DB_NAME`
|
||||
- `DB_PASS`
|
||||
- `DB_PORT`
|
||||
- `DATABASE_URL`
|
||||
|
||||
### Redis
|
||||
|
||||
- `REDIS_HOST`
|
||||
- `REDIS_PORT`
|
||||
- `REDIS_URL`
|
||||
- `REDIS_NAMESPACE`
|
||||
- `CACHE_REDIS_HOST`
|
||||
- `CACHE_REDIS_PORT`
|
||||
- `CACHE_REDIS_URL`
|
||||
- `CACHE_REDIS_NAMESPACE`
|
||||
|
||||
### ElasticSearch
|
||||
|
||||
- `ES_ENABLED`
|
||||
- `ES_HOST`
|
||||
- `ES_PORT`
|
||||
- `ES_PREFIX`
|
||||
|
||||
### StatsD
|
||||
|
||||
- `STATSD_ADDR`
|
||||
- `STATSD_NAMESPACE`
|
||||
|
||||
## Limits
|
||||
|
||||
- `SINGLE_USER_MODE`
|
||||
- `EMAIL_DOMAIN_WHITELIST`
|
||||
- `DEFAULT_LOCALE`
|
||||
- `MAX_SESSION_ACTIVATIONS`
|
||||
- `USER_ACTIVE_DAYS`
|
||||
|
||||
## E-mail
|
||||
|
||||
- `SMTP_SERVER`
|
||||
- `SMTP_PORT`
|
||||
- `SMTP_LOGIN`
|
||||
- `SMTP_PASSWORD`
|
||||
- `SMTP_FROM_ADDRESS`
|
||||
- `SMTP_DOMAIN`
|
||||
- `SMTP_DELIVERY_METHOD`
|
||||
- `SMTP_AUTH_METHOD`
|
||||
- `SMTP_CA_FILE`
|
||||
- `SMTP_OPENSSL_VERIFY_MODE`
|
||||
- `SMTP_ENABLE_STARTTLS_AUTO`
|
||||
- `SMTP_TLS`
|
||||
|
||||
## File storage
|
||||
|
||||
- `CDN_HOST`
|
||||
- `S3_ALIAS_HOST`
|
||||
|
||||
### Local file storage
|
||||
|
||||
- `PAPERCLIP_ROOT_PATH`
|
||||
- `PAPERCLIP_ROOT_URL`
|
||||
|
||||
### Amazon S3 and compatible
|
||||
|
||||
- `S3_ENABLED`
|
||||
- `S3_BUCKET`
|
||||
- `AWS_ACCESS_KEY_ID`
|
||||
- `AWS_SECRET_ACCESS_KEY`
|
||||
- `S3_REGION`
|
||||
- `S3_PROTOCOL`
|
||||
- `S3_HOSTNAME`
|
||||
- `S3_ENDPOINT`
|
||||
- `S3_SIGNATURE_VERSION`
|
||||
|
||||
### Swift
|
||||
|
||||
- `SWIFT_ENABLED`
|
||||
- `SWIFT_USERNAME`
|
||||
- `SWIFT_TENANT`
|
||||
- `SWIFT_PASSWORD`
|
||||
- `SWIFT_PROJECT_ID`
|
||||
- `SWIFT_AUTH_URL`
|
||||
- `SWIFT_CONTAINER`
|
||||
- `SWIFT_OBJECT_URL`
|
||||
- `SWIFT_REGION`
|
||||
- `SWIFT_DOMAIN_NAME`
|
||||
- `SWIFT_CACHE_TTL`
|
||||
|
||||
## External authentication
|
||||
|
||||
- `OAUTH_REDIRECT_AT_SIGN_IN`
|
||||
|
||||
### LDAP
|
||||
|
||||
- `LDAP_ENABLED`
|
||||
- `LDAP_HOST`
|
||||
- `LDAP_PORT`
|
||||
- `LDAP_METHOD`
|
||||
- `LDAP_BASE`
|
||||
- `LDAP_BIND_DN`
|
||||
- `LDAP_PASSWORD`
|
||||
- `LDAP_UID`
|
||||
- `LDAP_SEARCH_FILTER`
|
||||
|
||||
### PAM
|
||||
|
||||
- `PAM_ENABLED`
|
||||
- `PAM_EMAIL_DOMAIN`
|
||||
- `PAM_DEFAULT_SERVICE`
|
||||
- `PAM_CONTROLLED_SERVICE`
|
||||
|
||||
### CAS
|
||||
|
||||
- `CAS_ENABLED`
|
||||
- `CAS_URL`
|
||||
- `CAS_HOST`
|
||||
- `CAS_PORT`
|
||||
- `CAS_SSL`
|
||||
- `CAS_VALIDATE_URL`
|
||||
- `CAS_CALLBACK_URL`
|
||||
- `CAS_LOGOUT_URL`
|
||||
- `CAS_LOGIN_URL`
|
||||
- `CAS_UID_FIELD`
|
||||
- `CAS_CA_PATH`
|
||||
- `CAS_DISABLE_SSL_VERIFICATION`
|
||||
- `CAS_UID_KEY`
|
||||
- `CAS_NAME_KEY`
|
||||
- `CAS_EMAIL_KEY`
|
||||
- `CAS_NICKNAME_KEY`
|
||||
- `CAS_FIRST_NAME_KEY`
|
||||
- `CAS_LAST_NAME_KEY`
|
||||
- `CAS_LOCATION_KEY`
|
||||
- `CAS_IMAGE_KEY`
|
||||
- `CAS_PHONE_KEY`
|
||||
|
||||
### SAML
|
||||
|
||||
- `SAML_ENABLED`
|
||||
- `SAML_ACS_URL`
|
||||
- `SAML_ISSUER`
|
||||
- `SAML_IDP_SSO_TARGET_URL`
|
||||
- `SAML_IDP_CERT`
|
||||
- `SAML_IDP_CERT_FINGERPRINT`
|
||||
- `SAML_NAME_IDENTIFIER_FORMAT`
|
||||
- `SAML_CERT`
|
||||
- `SAML_PRIVATE_KEY`
|
||||
- `SAML_SECURITY_WANT_ASSERTION_SIGNED`
|
||||
- `SAML_SECURITY_WANT_ASSERTION_ENCRYPTED`
|
||||
- `SAML_SECURITY_ASSUME_EMAIL_IS_VERIFIED`
|
||||
- `SAML_ATTRIBUTES_STATEMENTS_UID`
|
||||
- `SAML_ATTRIBUTES_STATEMENTS_EMAIL`
|
||||
- `SAML_ATTRIBUTES_STATEMENTS_FULL_NAME`
|
||||
- `SAML_ATTRIBUTES_STATEMENTS_FIRST_NAME`
|
||||
- `SAML_ATTRIBUTES_STATEMENTS_LAST_NAME`
|
||||
- `SAML_UID_ATTRIBUTE`
|
||||
- `SAML_ATTRIBUTES_STATEMENTS_VERIFIED`
|
||||
- `SAML_ATTRIBUTES_STATEMENTS_VERIFIED_EMAIL`
|
||||
|
||||
## Hidden services
|
||||
|
||||
- `http_proxy`
|
||||
- `ALLOW_ACCESS_TO_HIDDEN_SERVICE`
|
||||
|
||||
## Other
|
||||
|
||||
- `SKIP_POST_DEPLOYMENT_MIGRATIONS`
|
||||
|
|
@ -0,0 +1,333 @@
|
|||
---
|
||||
title: Installation
|
||||
description: How to install Mastodon on an Ubuntu 18.04 server
|
||||
menu:
|
||||
docs:
|
||||
parent: administration
|
||||
weight: 1
|
||||
---
|
||||
|
||||
<img src="/setup.png" alt="" style="margin: 0; box-shadow: none">
|
||||
|
||||
## Basic server setup (optional)
|
||||
|
||||
If you are setting up a fresh machine, it is recommended that you secure it first. Assuming that you are running **Ubuntu 18.04**:
|
||||
|
||||
### Do not allow password-based SSH login (keys only)
|
||||
|
||||
First make sure you are actually logging in to the server using keys and not via a password, otherwise this will lock you out. Many hosting providers support uploading a public key and automatically set up key-based root login on new machines for you.
|
||||
|
||||
Edit `/etc/ssh/sshd_config` and find `PasswordAuthentication`. Make sure it's uncommented and set to `no`. If you made any changes, restart sshd:
|
||||
|
||||
```sh
|
||||
systemctl restart ssh
|
||||
```
|
||||
|
||||
### Update system packages
|
||||
|
||||
```sh
|
||||
apt update && apt upgrade -y
|
||||
```
|
||||
|
||||
### Install fail2ban so it blocks repeated login attempts
|
||||
|
||||
```sh
|
||||
apt install fail2ban
|
||||
```
|
||||
|
||||
Edit `/etc/fail2ban/jail.local` and put this inside:
|
||||
|
||||
```ini
|
||||
[DEFAULT]
|
||||
destemail = your@email.here
|
||||
sendername = Fail2Ban
|
||||
|
||||
[sshd]
|
||||
enabled = true
|
||||
port = 22
|
||||
|
||||
[sshd-ddos]
|
||||
enabled = true
|
||||
port = 22
|
||||
```
|
||||
|
||||
Finally restart fail2ban:
|
||||
|
||||
```sh
|
||||
systemctl restart fail2ban
|
||||
```
|
||||
|
||||
### Install a firewall and only whitelist SSH, HTTP and HTTPS ports
|
||||
|
||||
First, install iptables-persistent. During installation it will ask you if you want to keep current rules--decline.
|
||||
|
||||
```sh
|
||||
apt install -y iptables-persistent
|
||||
```
|
||||
|
||||
Edit `/etc/iptables/rules.v4` and put this inside:
|
||||
|
||||
```
|
||||
*filter
|
||||
|
||||
# Allow all loopback (lo0) traffic and drop all traffic to 127/8 that doesn't use lo0
|
||||
-A INPUT -i lo -j ACCEPT
|
||||
-A INPUT ! -i lo -d 127.0.0.0/8 -j REJECT
|
||||
|
||||
# Accept all established inbound connections
|
||||
-A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
|
||||
|
||||
# Allow all outbound traffic - you can modify this to only allow certain traffic
|
||||
-A OUTPUT -j ACCEPT
|
||||
|
||||
# Allow HTTP and HTTPS connections from anywhere (the normal ports for websites and SSL).
|
||||
-A INPUT -p tcp --dport 80 -j ACCEPT
|
||||
-A INPUT -p tcp --dport 443 -j ACCEPT
|
||||
|
||||
# Allow SSH connections
|
||||
# The -dport number should be the same port number you set in sshd_config
|
||||
-A INPUT -p tcp -m state --state NEW --dport 22 -j ACCEPT
|
||||
|
||||
# Allow ping
|
||||
-A INPUT -p icmp -m icmp --icmp-type 8 -j ACCEPT
|
||||
|
||||
# Log iptables denied calls
|
||||
-A INPUT -m limit --limit 5/min -j LOG --log-prefix "iptables denied: " --log-level 7
|
||||
|
||||
# Reject all other inbound - default deny unless explicitly allowed policy
|
||||
-A INPUT -j REJECT
|
||||
-A FORWARD -j REJECT
|
||||
|
||||
COMMIT
|
||||
```
|
||||
|
||||
With iptables-persistent, that configuration will be loaded at boot time. But since we are not rebooting right now, we need to load it manually for the first time:
|
||||
|
||||
```sh
|
||||
iptables-restore < /etc/iptables/rules.v4
|
||||
```
|
||||
|
||||
## 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`
|
||||
- An e-mail delivery service or other **SMTP server**
|
||||
|
||||
You will be running the commands as root. If you aren't already root, switch to root:
|
||||
|
||||
```sh
|
||||
sudo -i
|
||||
```
|
||||
|
||||
### System repositories
|
||||
|
||||
Make sure curl is installed first:
|
||||
|
||||
```sh
|
||||
apt install -y curl
|
||||
```
|
||||
|
||||
#### Node.js
|
||||
|
||||
```sh
|
||||
curl -sL https://deb.nodesource.com/setup_8.x | bash -
|
||||
```
|
||||
|
||||
#### Yarn
|
||||
|
||||
```sh
|
||||
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
|
||||
|
||||
```sh
|
||||
apt update
|
||||
apt install -y \
|
||||
imagemagick ffmpeg libpq-dev libxml2-dev libxslt1-dev file git-core \
|
||||
g++ libprotobuf-dev protobuf-compiler pkg-config nodejs gcc autoconf \
|
||||
bison build-essential libssl-dev libyaml-dev libreadline6-dev \
|
||||
zlib1g-dev libncurses5-dev libffi-dev libgdbm5 libgdbm-dev \
|
||||
nginx redis-server redis-tools postgresql postgresql-contrib \
|
||||
certbot yarn libidn11-dev libicu-dev libjemalloc-dev
|
||||
```
|
||||
|
||||
### 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:
|
||||
|
||||
```sh
|
||||
adduser --disabled-login mastodon
|
||||
```
|
||||
|
||||
We can then switch to the user:
|
||||
|
||||
```sh
|
||||
su - mastodon
|
||||
```
|
||||
|
||||
And proceed to install rbenv and rbenv-build:
|
||||
|
||||
```sh
|
||||
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
|
||||
cd ~/.rbenv && src/configure && make -C src
|
||||
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
|
||||
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
|
||||
exec bash
|
||||
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
|
||||
```
|
||||
|
||||
Once this is done, we can install the correct Ruby version:
|
||||
|
||||
```sh
|
||||
RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 2.5.1
|
||||
rbenv global 2.5.1
|
||||
```
|
||||
|
||||
We'll also need to install bundler:
|
||||
|
||||
```sh
|
||||
gem install bundler --no-ri --no-rdoc
|
||||
```
|
||||
|
||||
Return to the root user:
|
||||
|
||||
```sh
|
||||
exit
|
||||
```
|
||||
|
||||
## Setup
|
||||
### Setting up PostgreSQL
|
||||
#### 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
|
||||
|
||||
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.
|
||||
|
||||
Open the prompt:
|
||||
|
||||
```sh
|
||||
sudo -u postgres psql
|
||||
```
|
||||
|
||||
In the prompt, execute:
|
||||
|
||||
```
|
||||
CREATE USER mastodon CREATEDB;
|
||||
\q
|
||||
```
|
||||
|
||||
Done!
|
||||
|
||||
### Setting up Mastodon
|
||||
|
||||
It is time to download the Mastodon code. Switch to the mastodon user:
|
||||
|
||||
```sh
|
||||
su - mastodon
|
||||
```
|
||||
|
||||
#### Checking out the code
|
||||
|
||||
Use git to download the latest stable release of Mastodon:
|
||||
|
||||
```sh
|
||||
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
|
||||
|
||||
Now to install Ruby and JavaScript dependencies:
|
||||
|
||||
```sh
|
||||
bundle install \
|
||||
-j$(getconf _NPROCESSORS_ONLN) \
|
||||
--deployment --without development test
|
||||
yarn install --pure-lockfile
|
||||
```
|
||||
|
||||
#### Generating a configuration
|
||||
|
||||
Run the interactive setup wizard:
|
||||
|
||||
```sh
|
||||
RAILS_ENV=production bundle exec rake mastodon:setup
|
||||
```
|
||||
|
||||
This will:
|
||||
|
||||
- Create a configuration file
|
||||
- Run asset precompilation
|
||||
- Create the database schema
|
||||
|
||||
The configuration file is saved as `.env.production`. You can review and edit it to your liking. Refer to the [documentation on configuration]({{< relref "configuration.md" >}}).
|
||||
|
||||
You're done with the mastodon user for now, so switch back to root:
|
||||
|
||||
```sh
|
||||
exit
|
||||
```
|
||||
|
||||
### Setting up nginx
|
||||
|
||||
Copy the configuration template for nginx from the Mastodon directory:
|
||||
|
||||
```sh
|
||||
cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon
|
||||
ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/mastodon
|
||||
```
|
||||
|
||||
Then edit `/etc/nginx/sites-available/mastodon` to replace `example.com` with your own domain name, and make any other adjustments you might need.
|
||||
|
||||
Reload nginx for the changes to take effect:
|
||||
|
||||
```sh
|
||||
systemctl reload nginx
|
||||
```
|
||||
|
||||
### Acquiring a SSL certificate
|
||||
|
||||
We'll use Let's Encrypt to get a free SSL certificate:
|
||||
|
||||
```sh
|
||||
certbot certonly --webroot -d example.com -w /home/mastodon/live/public/
|
||||
```
|
||||
|
||||
You can now edit `/etc/nginx/sites-available/mastodon` to uncomment and adjust the `ssl_certificate` and `ssl_certificate_key` lines.
|
||||
|
||||
Then, reload nginx for the changes to take effect:
|
||||
|
||||
```sh
|
||||
systemctl reload nginx
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
Copy the systemd service templates from the Mastodon directory:
|
||||
|
||||
```sh
|
||||
cp /home/mastodon/live/dist/mastodon-*.service /etc/systemd/system/
|
||||
```
|
||||
|
||||
Then edit the files to make sure the username and paths are correct:
|
||||
|
||||
- `/etc/systemd/system/mastodon-web.service`
|
||||
- `/etc/systemd/system/mastodon-sidekiq.service`
|
||||
- `/etc/systemd/system/mastodon-streaming.service`
|
||||
|
||||
Finally, start and enable the new systemd services:
|
||||
|
||||
```sh
|
||||
systemctl start mastodon-web mastodon-sidekiq mastodon-streaming
|
||||
systemctl enable mastodon-*
|
||||
```
|
||||
|
||||
They will now automatically start at boot time.
|
||||
|
||||
**Hurray! This is it. You can visit your domain in the browser now!**
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
---
|
||||
title: Optional features
|
||||
description: How to enable Mastodon's optional features
|
||||
menu:
|
||||
docs:
|
||||
parent: administration
|
||||
weight: 5
|
||||
---
|
||||
|
||||
## Full-text search
|
||||
|
||||
TODO
|
||||
|
||||
## Hidden services
|
||||
|
||||
TODO
|
||||
|
||||
## Login via LDAP/PAM/CAS/SAML
|
||||
|
||||
TODO
|
||||
|
||||
|
|
@ -0,0 +1,106 @@
|
|||
---
|
||||
title: Post-installation steps
|
||||
description: What to do after the installation of Mastodon is complete
|
||||
menu:
|
||||
docs:
|
||||
parent: administration
|
||||
weight: 3
|
||||
---
|
||||
|
||||
## Using the command-line interface
|
||||
|
||||
The command-line interface of Mastodon is an executable file called `tootctl` residing in the `bin` directory within the Mastodon root directory. You must specify which environment you intend to use whenever you execute it by specifying the `RAILS_ENV` environment variable. Unless you are a developer working on a local machine, you need to use `RAILS_ENV=production`. If you are sure that you will never need another environment (for development, testing, or staging), you can add it to your `.bashrc` file for convenience, e.g.:
|
||||
|
||||
```bash
|
||||
echo "export RAILS_ENV=production" >> ~/.bashrc
|
||||
```
|
||||
|
||||
If so, you won't need to specify it each time inline. Otherwise, calls to `tootctl` will usually go like this, assuming that the Mastodon code is checked out in `/home/mastodon/live`:
|
||||
|
||||
```bash
|
||||
cd /home/mastodon/live
|
||||
RAILS_ENV=production bin/tootctl help
|
||||
```
|
||||
|
||||
## Creating an admin account
|
||||
### In the browser
|
||||
|
||||
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`:
|
||||
|
||||
```bash
|
||||
RAILS_ENV=production bin/tootctl accounts update alice --role admin
|
||||
```
|
||||
|
||||
### From the command line
|
||||
|
||||
You can create a new account using the command-line interface.
|
||||
|
||||
```bash
|
||||
RAILS_ENV=production bin/tootctl accounts create \
|
||||
alice \
|
||||
--email alice@example.com \
|
||||
--confirmed \
|
||||
--role admin
|
||||
```
|
||||
|
||||
A randomly generated password will be shown in the terminal.
|
||||
|
||||
## Filling in server information
|
||||
|
||||
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.
|
||||
|
||||
|Setting|Meaning|
|
||||
|-------|-------|
|
||||
|Contact username|Your username so people know who owns the server|
|
||||
|Business e-mail|An e-mail address so people locked out of their accounts, or people without accounts, can contact you|
|
||||
|Instance description|Why did you start this server? Who is it for? What makes it different?|
|
||||
|Custom extended information|You can put all sorts of information in here but a **code of conduct** is recommended|
|
||||
|
||||
After you fill these in, simply hit "Save changes".
|
||||
|
||||
## Setting up regular backups (optional, but not really)
|
||||
|
||||
For any real-world use, you should make sure to regularly backup your Mastodon server.
|
||||
|
||||
### Overview
|
||||
|
||||
Things that need to be backed up in order of importance:
|
||||
|
||||
1. PostgreSQL database
|
||||
2. Application secrets from the `.env.production` file or equivalent
|
||||
3. User-uploaded files
|
||||
4. Redis database
|
||||
|
||||
### Failure modes
|
||||
|
||||
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.
|
||||
|
||||
A lost PostgreSQL database is complete game over. Mastodon stores all the most important data in the PostgreSQL database. If the database disappears, all the accounts, posts and followers on your server will disappear with it.
|
||||
|
||||
If you lose application secrets, some functions of Mastodon will stop working for your users, they will be logged out, two-factor authentication will become unavailable, Web Push API subscriptions will stop working.
|
||||
|
||||
If you lose user-uploaded files, you will lose avatars, headers, and media attachments, but Mastodon *will* work moving forward.
|
||||
|
||||
Losing the Redis database is almost harmless: The only irrecoverable data will be the contents of the Sidekiq queues and scheduled retries of previously failed jobs. The home and list feeds are stored in Redis, but can be regenerated with tootctl.
|
||||
|
||||
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
|
||||
|
||||
Application secrets are the easiest to backup, since they never change. You only need to store `.env.production` somewhere safe.
|
||||
|
||||
### Backing up 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
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,265 @@
|
|||
---
|
||||
title: Scaling up
|
||||
description: How to scale Mastodon horizontally to handle more requests
|
||||
menu:
|
||||
docs:
|
||||
parent: administration
|
||||
weight: 4
|
||||
---
|
||||
|
||||
## Managing concurrency
|
||||
|
||||
Mastodon has three types of processes:
|
||||
|
||||
- Web (Puma)
|
||||
- Streaming API
|
||||
- Background processing (Sidekiq)
|
||||
|
||||
### Web (Puma)
|
||||
|
||||
The web process serves short-lived HTTP requests for most of the application. The following environment variables control it:
|
||||
|
||||
- `WEB_CONCURRENCY` controls the number of worker processes
|
||||
- `MAX_THREADS` controls the number of threads per process
|
||||
|
||||
Threads share the memory of their parent process. Different processes allocate their own memory, though they share some memory via copy-on-write. A larger number of threads maxes out your CPU first, a larger number of processes maxes out your RAM first.
|
||||
|
||||
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
|
||||
|
||||
The streaming API handles long-lived HTTP and WebSockets connections, through which clients receive real-time updates. The following environment variables control it:
|
||||
|
||||
- `STREAMING_CLUSTER_NUM` controls the number of worker processes
|
||||
- `STREAMING_API_BASE_URL` controls the base URL of the streaming API
|
||||
|
||||
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)
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
The amount of threads is not controlled by an environment variable in this case, but a command line argument in the invocation of Sidekiq, e.g.:
|
||||
|
||||
```sh
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
|Queue|Significance|
|
||||
|:---:|------------|
|
||||
|`default`|All tasks that affect local users|
|
||||
|`push`|Delivery of payloads to other servers|
|
||||
|`mailers`|Delivery of e-mails|
|
||||
|`pull`|Fetching information from other servers|
|
||||
|
||||
The default queues and their priorities are stored in `config/sidekiq.yml`, but can be overridden by the command-line invocation of Sidekiq, e.g.:
|
||||
|
||||
```sh
|
||||
bundle exec sidekiq -q default
|
||||
```
|
||||
|
||||
To run just the `default` queue.
|
||||
|
||||
The way Sidekiq works with queues, it first checks for tasks from the first queue, and if there are none, checks the next queue. This means, if the first queue is overfilled, the other queues will lag behind.
|
||||
|
||||
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
|
||||
### Why you might need PgBouncer
|
||||
|
||||
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
|
||||
|
||||
On Debian and Ubuntu:
|
||||
|
||||
sudo apt install pgbouncer
|
||||
|
||||
### Configuring PgBouncer
|
||||
#### Setting a password
|
||||
|
||||
First off, if your `mastodon` user in Postgres is set up wthout a password, you will need to set a password.
|
||||
|
||||
Here's how you might reset the password:
|
||||
|
||||
psql -p 5432 -U mastodon mastodon_production -w
|
||||
|
||||
Then (obviously, use a different password than the word "password"):
|
||||
|
||||
ALTER USER mastodon WITH PASSWORD 'password';
|
||||
|
||||
Then `\q` to quit.
|
||||
|
||||
#### Configuring userlist.txt
|
||||
|
||||
Edit `/etc/pgbouncer/userlist.txt`
|
||||
|
||||
As long as you specify a user/password in pgbouncer.ini later, the values in userlist.txt do *not* have to correspond to real PostgreSQL roles. You can arbitrarily define users and passwords, but you can reuse the "real" credentials for simplicity's sake. Add the `mastodon` user to the `userlist.txt`:
|
||||
|
||||
"mastodon" "md5d75bb2be2d7086c6148944261a00f605"
|
||||
|
||||
Here we're using the md5 scheme, where the md5 password is just the md5sum of `password + username` with the string `md5` prepended. For instance, to derive the hash for user `mastodon` with password `password`, you can do:
|
||||
|
||||
```bash
|
||||
# ubuntu, debian, etc.
|
||||
echo -n "passwordmastodon" | md5sum
|
||||
# macOS, openBSD, etc.
|
||||
md5 -s "passwordmastodon"
|
||||
```
|
||||
|
||||
Then just add `md5` to the beginning of that.
|
||||
|
||||
You'll also want to create a `pgbouncer` admin user to log in to the PgBouncer admin database. So here's a sample `userlist.txt`:
|
||||
|
||||
```
|
||||
"mastodon" "md5d75bb2be2d7086c6148944261a00f605"
|
||||
"pgbouncer" "md5a45753afaca0db833a6f7c7b2864b9d9"
|
||||
```
|
||||
|
||||
In both cases the password is just `password`.
|
||||
|
||||
#### Configuring pgbouncer.ini
|
||||
|
||||
Edit `/etc/pgbouncer/pgbouncer.ini`
|
||||
|
||||
Add a line under `[databases]` listing the Postgres databases you want to connect to. Here we'll just have PgBouncer use the same username/password and database name to connect to the underlying Postgres database:
|
||||
|
||||
```ini
|
||||
[databases]
|
||||
mastodon_production = host=127.0.0.1 port=5432 dbname=mastodon_production user=mastodon password=password
|
||||
```
|
||||
|
||||
The `listen_addr` and `listen_port` tells PgBouncer which address/port to accept connections. The defaults are fine:
|
||||
|
||||
```ini
|
||||
listen_addr = 127.0.0.1
|
||||
listen_port = 6432
|
||||
```
|
||||
|
||||
Put `md5` as the `auth_type` (assuming you're using the md5 format in `userlist.txt`):
|
||||
|
||||
```ini
|
||||
auth_type = md5
|
||||
```
|
||||
|
||||
Make sure the `pgbouncer` user is an admin:
|
||||
|
||||
```ini
|
||||
admin_users = pgbouncer
|
||||
```
|
||||
|
||||
**This next part is very important!** The default pooling mode is session-based, but for Mastodon we want transaction-based. In other words, a Postgres connection is created when a transaction is created and dropped when the transaction is done. So you'll want to change the `pool_mode` from `session` to `transaction`:
|
||||
|
||||
```ini
|
||||
pool_mode = transaction
|
||||
```
|
||||
|
||||
Next up, `max_client_conn` defines how many connections PgBouncer itself will accept, and `default_pool_size` puts a limit on how many Postgres connections will be opened under the hood. (In PgHero the number of connections reported will correspond to `default_pool_size` because it has no knowledge of PgBouncer.)
|
||||
|
||||
The defaults are fine to start, and you can always increase them later:
|
||||
|
||||
```ini
|
||||
max_client_conn = 100
|
||||
default_pool_size = 20
|
||||
```
|
||||
|
||||
Don't forget to reload or restart pgbouncer after making your changes:
|
||||
|
||||
sudo systemctl reload pgbouncer
|
||||
|
||||
#### Debugging that it all works
|
||||
|
||||
You should be able to connect to PgBouncer just like you would with Postgres:
|
||||
|
||||
psql -p 6432 -U mastodon mastodon_production
|
||||
|
||||
And then use your password to log in.
|
||||
|
||||
You can also check the PgBouncer logs like so:
|
||||
|
||||
tail -f /var/log/postgresql/pgbouncer.log
|
||||
|
||||
#### Configuring Mastodon to talk to PgBouncer
|
||||
|
||||
In your `.env.production` file, first off make sure that this is set:
|
||||
|
||||
```bash
|
||||
PREPARED_STATEMENTS=false
|
||||
```
|
||||
|
||||
Since we're using transaction-based pooling, we can't use prepared statements.
|
||||
|
||||
Next up, configure Mastodon to use port 6432 (PgBouncer) instead of 5432 (Postgres) and you should be good to go:
|
||||
|
||||
```bash
|
||||
DB_HOST=localhost
|
||||
DB_USER=mastodon
|
||||
DB_NAME=mastodon_production
|
||||
DB_PASS=password
|
||||
DB_PORT=6432
|
||||
```
|
||||
|
||||
> **Gotcha:** 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)
|
||||
|
||||
#### Administering PgBouncer
|
||||
|
||||
The easiest way to reboot is:
|
||||
|
||||
sudo systemctl restart pgbouncer
|
||||
|
||||
But if you've set up a PgBouncer admin user, you can also connect as the admin:
|
||||
|
||||
psql -p 6432 -U pgbouncer pgbouncer
|
||||
|
||||
And then do:
|
||||
|
||||
RELOAD;
|
||||
|
||||
Then use `\q` to quit.
|
||||
|
||||
## Separate Redis for cache
|
||||
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
- The streaming API server does not issue writes at all, so you can connect it straight to the replica. But it's not querying the database very often anyway so the impact of this is little.
|
||||
- Use the Makara driver in the web and sidekiq processes, so that writes go to the master database, while reads go to the replica. Let's talk about that.
|
||||
|
||||
You will have to edit the `config/database.yml` file and replace the `production` section as follows:
|
||||
|
||||
```yml
|
||||
production:
|
||||
<<: *default
|
||||
adapter: postgresql_makara
|
||||
prepared_statements: false
|
||||
makara:
|
||||
id: postgres
|
||||
sticky: true
|
||||
connections:
|
||||
- role: master
|
||||
blacklist_duration: 0
|
||||
url: postgresql://db_user:db_password@db_host:db_port/db_name
|
||||
- role: slave
|
||||
url: postgresql://db_user:db_password@db_host:db_port/db_name
|
||||
```
|
||||
|
||||
Make sure the URLs point to wherever your PostgreSQL servers are. You can add multiple replicas. You could have a locally installed pgBouncer with configuration to connect to two different servers based on database name, e.g. "mastodon" going to master, "mastodon_replica" going to the replica, so in the file above both URLs would point to the local pgBouncer with the same user, password, host and port, but different database name. There are many possibilities how this could be setup! For more information on Makara, [see their documentation](https://github.com/taskrabbit/makara#databaseyml).
|
||||
|
|
@ -0,0 +1,57 @@
|
|||
---
|
||||
title: Upgrading to a new release
|
||||
description: How to upgrade Mastodon to a newer version
|
||||
menu:
|
||||
docs:
|
||||
parent: administration
|
||||
weight: 5
|
||||
---
|
||||
|
||||
When a new version of Mastodon comes out, it appears on the [GitHub releases page](https://github.com/tootsuite/mastodon/releases). Please mind that running unreleased code from the `master` branch, while possible, is not recommended.
|
||||
|
||||
Mastodon releases correspond to git tags. First, switch to the `mastodon` user:
|
||||
|
||||
```sh
|
||||
su - mastodon
|
||||
```
|
||||
|
||||
And navigate to the Mastodon root directory:
|
||||
|
||||
```sh
|
||||
cd /home/mastodon/live
|
||||
```
|
||||
|
||||
Download the releases's code, assuming that the version is called `v2.5.0`:
|
||||
|
||||
```sh
|
||||
git fetch --tags
|
||||
git checkout v2.5.0
|
||||
```
|
||||
|
||||
The release page contains a changelog, and below it, upgrade instructions. This is where you would execute them, for example, if the release mentions that you need to re-compile assets, you would execute:
|
||||
|
||||
```sh
|
||||
RAILS_ENV=production bundle exec rails assets:precompile
|
||||
```
|
||||
|
||||
After you have executed all special release-specific instructions, the last thing remaining is restarting Mastodon. *Usually* the streaming API is not updated, and therefore does not require a restart. Restarting the streaming API can lead to an unusually high load on the server, so it is advised to avoid it if possible.
|
||||
|
||||
Switch back to root:
|
||||
|
||||
```sh
|
||||
exit
|
||||
```
|
||||
|
||||
You would restart Sidekiq:
|
||||
|
||||
```sh
|
||||
systemctl restart mastodon-sidekiq
|
||||
```
|
||||
|
||||
And you would reload the web process to avoid downtime:
|
||||
|
||||
```sh
|
||||
systemctl reload mastodon-web
|
||||
```
|
||||
|
||||
**That's all!** You're running the new version of Mastodon now.
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
---
|
||||
title: Authentication
|
||||
description: How to authenticate with OAuth 2 on Mastodon
|
||||
menu:
|
||||
docs:
|
||||
parent: api
|
||||
weight: 1
|
||||
---
|
||||
|
||||
Mastodon is federated, therefore you can't be expected to manually register your application on all potential servers your users might want to login on. For this reason, there is an open app registration API, so obtaining OAuth 2 credentials for OAuth 2 authorization can be automated.
|
||||
|
||||
Make sure that you allow your users to specify the domain they want to connect to before login. Use that domain to acquire a client id/secret for OAuth 2 and then proceed with normal OAuth 2 also using that domain to build the URLs.
|
||||
|
||||
Mastodon supports the following OAuth 2 flows:
|
||||
|
||||
- **Authorization code flow**: For end-users
|
||||
- **Password grant flow**: For bots and other single-user applications
|
||||
- **Client credentials flow**: For applications that do not act on behalf of users
|
||||
|
|
@ -0,0 +1,317 @@
|
|||
---
|
||||
title: Entities
|
||||
description: Overview of entities returned from Mastodon's REST API
|
||||
menu:
|
||||
docs:
|
||||
parent: api
|
||||
weight: 3
|
||||
---
|
||||
|
||||
- All IDs are encoded as strings
|
||||
- All datetimes are in ISO 8601 format
|
||||
- All HTML strings are sanitized by the server
|
||||
- All language codes are in ISO 6391 format
|
||||
|
||||
## Account
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `id` | String |{{< no >}}|0.1.0|
|
||||
| `username` | String |{{< no >}}|0.1.0|
|
||||
| `acct` | String |{{< no >}}|0.1.0|
|
||||
| `display_name` | String |{{< no >}}|0.1.0|
|
||||
| `locked` | Boolean |{{< no >}}|0.1.0|
|
||||
| `created_at` | String (Datetime) |{{< no >}}|0.1.0|
|
||||
| `followers_count` | Number |{{< no >}}|0.1.0|
|
||||
| `following_count` | Number |{{< no >}}|0.1.0|
|
||||
| `statuses_count` | Number |{{< no >}}|0.1.0|
|
||||
| `note` | String |{{< no >}}|0.1.0|
|
||||
| `url` | String (URL) |{{< no >}}|0.1.0|
|
||||
| `avatar` | String (URL) |{{< no >}}|0.1.0|
|
||||
| `avatar_static` | String (URL) |{{< no >}}|1.1.2|
|
||||
| `header` | String (URL) |{{< no >}}|0.1.0|
|
||||
| `header_static` | String (URL) |{{< no >}}|1.1.2|
|
||||
| `emojis` | Array of [Emoji](#emoji) |{{< no >}}|2.4.0|
|
||||
| `moved` | [Account](#account) |{{< yes >}}|2.1.0|
|
||||
| `fields` | Array of [Hash](#field) |{{< yes >}}|2.4.0|
|
||||
| `bot` | Boolean |{{< yes >}}|2.4.0|
|
||||
|
||||
### Field
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `name` | String |{{< no >}}|2.4.0|
|
||||
| `value` | String (HTML) |{{< no >}}|2.4.0|
|
||||
| `verified_at` | String (Datetime) |{{< yes >}}|2.6.0|
|
||||
|
||||
### Source
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `privacy` | String |{{< yes >}}|1.5.0|
|
||||
| `sensitive` | Boolean |{{< yes >}}|1.5.0|
|
||||
| `language` | String (ISO6391) |{{< yes >}}|2.4.2|
|
||||
| `note` | String |{{< no >}}|1.5.0|
|
||||
| `fields` | Array of Hash |{{< no >}}|2.4.0|
|
||||
|
||||
## Application
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `name` | String |{{< no >}}|0.9.9|
|
||||
| `website` | String (URL) |{{< yes >}}|0.9.9|
|
||||
|
||||
## Attachment
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `id` | String |{{< no >}}|0.6.0|
|
||||
| `type` | [String (Enum)](#type) |{{< no >}}|0.6.0|
|
||||
| `url` | String (URL) |{{< no >}}|0.6.0|
|
||||
| `remote_url` | String (URL) |{{< yes >}}|0.6.0|
|
||||
| `preview_url` | String (URL) |{{< no >}}|0.6.0|
|
||||
| `text_url` | String (URL) |{{< yes >}}|0.6.0|
|
||||
| `meta` | [Hash](#meta) |{{< yes >}}|1.5.0|
|
||||
| `description` | String |{{< yes >}}|2.0.0|
|
||||
|
||||
### Type
|
||||
|
||||
- `unknown`
|
||||
- `image`
|
||||
- `gifv`
|
||||
- `video`
|
||||
|
||||
### Meta
|
||||
|
||||
May contain subtrees `small` and `original`.
|
||||
|
||||
Images may contain `width`, `height`, `size`, `aspect`, while videos (including GIFV) may contain `width`, `height`, `frame_rate`, `duration` and `bitrate`.
|
||||
|
||||
There may be another top-level object, `focus` with the coordinates `x` and `y`. These coordinates can be used for smart thumbnail cropping, [see this for reference](https://github.com/jonom/jquery-focuspoint#1-calculate-your-images-focus-point).
|
||||
|
||||
## Card
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `url` | String (URL) |{{< no >}}|1.0.0|
|
||||
| `title` | String |{{< no >}}|1.0.0|
|
||||
| `description` | String |{{< no >}}|1.0.0|
|
||||
| `image` | String (URL) |{{< yes >}}|1.0.0|
|
||||
| `type` | [String (Enum)](#type-1) |{{< no >}}|1.3.0|
|
||||
| `author_name` | String |{{< yes >}}|1.3.0|
|
||||
| `author_url` | String (URL) |{{< yes >}}|1.3.0|
|
||||
| `provider_name` | String |{{< yes >}}|1.3.0|
|
||||
| `provider_url` | String (URL) |{{< yes >}}|1.3.0|
|
||||
| `html` | String (HTML) |{{< yes >}}|1.3.0|
|
||||
| `width` | Number |{{< yes >}}|1.3.0|
|
||||
| `height` | Number |{{< yes >}}|1.3.0|
|
||||
|
||||
### Type
|
||||
|
||||
- `link`
|
||||
- `photo`
|
||||
- `video`
|
||||
- `rich`
|
||||
|
||||
## Context
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `ancestors` | Array of [Status](#status) |{{< no >}}|0.6.0|
|
||||
| `descendants` | Array of [Status](#status) |{{< no >}}|0.6.0|
|
||||
|
||||
## Emoji
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `shortcode` | String |{{< no >}}|2.0.0|
|
||||
| `static_url` | String (URL) |{{< no >}}|2.0.0|
|
||||
| `url` | String (URL) |{{< no >}}|2.0.0|
|
||||
| `visible_in_picker` | Boolean |{{< no >}}|2.1.0|
|
||||
|
||||
## Error
|
||||
|
||||
The most important part of an error response is the HTTP status code. Standard semantics are followed. The body of an error is a JSON object with this structure:
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `error` | String |{{< no >}}|0.6.0|
|
||||
|
||||
## Filter
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `id` | String |{{< no >}}|2.4.3|
|
||||
| `phrase` | String |{{< no >}}|2.4.3|
|
||||
| `context` | Array of [String (Enum)](#context) |{{< no >}}|2.4.3|
|
||||
| `expires_at` | String (Datetime) |{{< yes >}}|2.4.3|
|
||||
| `irreversible` | Boolean |{{< no >}}|2.4.3|
|
||||
| `whole_word` | Boolean |{{< no >}}|2.4.3|
|
||||
|
||||
### Context
|
||||
|
||||
- `home`
|
||||
- `notifications`
|
||||
- `public`
|
||||
- `thread`
|
||||
|
||||
### Implementation notes
|
||||
|
||||
If `whole_word` is true , client app should do:
|
||||
|
||||
- Define 'word constituent character' for your app. In the official implementation, it's `[A-Za-z0-9_]` in JavaScript, and `[[:word:]]` in Ruby. In Ruby case it's the POSIX character class (Letter | Mark | Decimal_Number | Connector_Punctuation).
|
||||
- If the phrase starts with a word character, and if the previous character before matched range is a word character, its matched range should be treated to not match.
|
||||
- If the phrase ends with a word character, and if the next character after matched range is a word character, its matched range should be treated to not match.
|
||||
|
||||
Please check `app/javascript/mastodon/selectors/index.js` and `app/lib/feed_manager.rb` in the Mastodon source code for more details.
|
||||
|
||||
## Instance
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `uri` | String |{{< no >}}|1.1.0|
|
||||
| `title` | String |{{< no >}}|1.1.0|
|
||||
| `description` | String |{{< no >}}|1.1.0|
|
||||
| `email` | String |{{< no >}}|1.1.0|
|
||||
| `version` | String |{{< no >}}|1.3.0|#
|
||||
| `thumbnail` | String (URL) |{{< yes >}}|1.6.1|
|
||||
| `urls` | [Hash](#urls) |{{< no >}}|1.4.2|
|
||||
| `stats` | [Hash](#stats) |{{< no >}}|1.6.0|
|
||||
| `languages` | Array of String (ISO6391) |{{< no >}}|2.3.0|
|
||||
| `contact_account` | [Account](#account) |{{< yes >}}|2.3.0|
|
||||
|
||||
### URLs
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
|`streaming_api`| String (URL) |{{< no >}}|1.4.2|
|
||||
|
||||
### Stats
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
|`user_count`| Number |{{< no >}}|1.6.0|
|
||||
|`status_count`| Number |{{< no >}}|1.6.0|
|
||||
|`domain_count`| Number |{{< no >}}|1.6.0|
|
||||
|
||||
## List
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `id` | String |{{< no >}}|2.1.0|
|
||||
| `title` | String |{{< no >}}|2.1.0|
|
||||
|
||||
## Mention
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `url` | String (URL) |{{< no >}}|0.6.0|
|
||||
| `username` | String |{{< no >}}|0.6.0|
|
||||
| `acct` | String |{{< no >}}|0.6.0|
|
||||
| `id` | String |{{< no >}}|0.6.0|
|
||||
|
||||
## Notification
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `id` | String |{{< no >}}|0.9.9|
|
||||
| `type` | [String (Enum)](#type-2) |{{< no >}}|0.9.9|
|
||||
| `created_at` | String (Datetime) |{{< no >}}|0.9.9|
|
||||
| `account` | [Account](#account) |{{< no >}}|0.9.9|
|
||||
| `status` | [Status](#status) |{{< yes >}}|0.9.9|
|
||||
|
||||
### Type
|
||||
|
||||
- `follow`
|
||||
- `mention`
|
||||
- `reblog`
|
||||
- `favourite`
|
||||
|
||||
## Push subscription
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `id` | String |{{< no >}}|2.4.0|
|
||||
| `endpoint` | String (URL) |{{< no >}}|2.4.0|
|
||||
| `server_key` | String |{{< no >}}|2.4.0|
|
||||
| `alerts` | [Hash](#alerts) |{{< no >}}|2.4.0|
|
||||
|
||||
### Alerts
|
||||
|
||||
???
|
||||
|
||||
## Relationship
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `id` | String |{{< no >}}|0.6.0|
|
||||
| `following` | Boolean |{{< no >}}|0.6.0|
|
||||
| `followed_by` | Boolean |{{< no >}}|0.6.0|
|
||||
| `blocking` | Boolean |{{< no >}}|0.6.0|
|
||||
| `muting` | Boolean |{{< no >}}|1.1.0|
|
||||
| `muting_notifications` | Boolean |{{< no >}}|2.1.0|
|
||||
| `requested` | Boolean |{{< no >}}|0.9.9|
|
||||
| `domain_blocking` | Boolean |{{< no >}}|1.4.0|
|
||||
| `showing_reblogs` | Boolean |{{< no >}}|2.1.0|
|
||||
| `endorsed` | Boolean |{{< no >}}|2.5.0|
|
||||
|
||||
## Results
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `accounts` | Array of [Account](#account) |{{< no >}}|1.1.0|
|
||||
| `statuses` | Array of [Status](#status) |{{< no >}}|1.1.0|
|
||||
| `hashtags` | Array of [Tag](#tag) |{{< no >}}|1.1.0|
|
||||
|
||||
## Status
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `id` | String |{{< no >}}|0.1.0|
|
||||
| `uri` | String |{{< no >}}|0.1.0|
|
||||
| `url` | String (URL) |{{< yes >}}|0.1.0|
|
||||
| `account` | [Account](#account) |{{< no >}}|0.1.0|
|
||||
| `in_reply_to_id` | String |{{< yes >}}|0.1.0|
|
||||
| `in_reply_to_account_id` | String |{{< yes >}}|1.0.0|
|
||||
| `reblog` | [Status](#status) |{{< yes >}}|0.1.0|
|
||||
| `content` | String (HTML) |{{< no >}}|0.1.0|
|
||||
| `created_at` | String (Datetime) |{{< no >}}|0.1.0|
|
||||
| `emojis` | Array of [Emoji](#emoji) |{{< no >}}|2.0.0|
|
||||
| `replies_count` | Number |{{< no >}}|2.5.0|
|
||||
| `reblogs_count` | Number |{{< no >}}|0.1.0|
|
||||
| `favourites_count` | Number |{{< no >}}|0.1.0|
|
||||
| `reblogged` | Boolean |{{< yes >}}|0.1.0|
|
||||
| `favourited` | Boolean |{{< yes >}}|0.1.0|
|
||||
| `muted` | Boolean |{{< yes >}}|1.4.0|
|
||||
| `sensitive` | Boolean |{{< no >}}|0.9.9|
|
||||
| `spoiler_text` | String |{{< no >}}|1.0.0|
|
||||
| `visibility` | [String (Enum)](#visibility) |{{< no >}}|0.9.9|
|
||||
| `media_attachments` | Array of [Attachment](#attachment) |{{< no >}}|0.6.0|
|
||||
| `mentions` | Array of [Mention](#mention) |{{< no >}}|0.6.0|
|
||||
| `tags` | Array of [Tag](#tag) |{{< no >}}|0.9.0|
|
||||
| `application` | [Application](#application) |{{< no >}}|0.9.9|
|
||||
| `language` | String (ISO6391) |{{< yes >}}|1.4.0|
|
||||
| `pinned` | Boolean |{{< yes >}}|1.6.0|
|
||||
|
||||
### Visibility
|
||||
|
||||
- `public`
|
||||
- `unlisted`
|
||||
- `private`
|
||||
- `direct`
|
||||
|
||||
## Tag
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `name` | String |{{< no >}}|0.9.0|
|
||||
| `url` | String (URL) |{{< no >}}|0.9.0|
|
||||
| `history` | Array of [History](#history) |{{< yes >}}|2.4.1|
|
||||
|
||||
### History
|
||||
|
||||
|Attribute|Type|Nullable|Added in|
|
||||
|---------|-----------|:------:|:------:|
|
||||
| `day` | String (UNIX timestamp) |{{< no >}}|2.4.1|
|
||||
| `uses` | Number |{{< no >}}|2.4.1|
|
||||
| `accounts` | Number |{{< no >}}|2.4.1|
|
||||
|
|
@ -0,0 +1,52 @@
|
|||
---
|
||||
title: Guidelines
|
||||
description: Guidelines that app developers for Mastodon should follow
|
||||
menu:
|
||||
docs:
|
||||
parent: api
|
||||
weight: -1
|
||||
---
|
||||
|
||||
## Login
|
||||
|
||||
**The user must be able to login to any Mastodon server from the app**. This means you must ask for either the full handle, or server domain, and use the app registrations API to dynamically obtain OAuth2 credentials.
|
||||
|
||||
## Usernames
|
||||
|
||||
**Decentralization must be transparent to the user**. It should be possible to see that a given user is from another server, by e.g. displaying their `acct` (username and domain) somewhere.
|
||||
|
||||
## Formatting
|
||||
|
||||
Plain text is not available for content from remote servers, and plain text syntax rules may vary wildly between Mastodon and other fediverse applications. For certain attributes, such as the content of statuses, **Mastodon provides sanitized HTML**.
|
||||
|
||||
### HTML tags
|
||||
|
||||
You may expect these tags to appear in the content: `<p>`, `<br>`, `<span>`, `<a>`
|
||||
|
||||
### Mentions and hashtags
|
||||
|
||||
Mentions and hashtags are `<a>` tags. To give those links their semantic meaning and add special handling, such as opening a mentioned profile within your app instead of as a web page, metadata is included with the status, which can be matched to a particular tag.
|
||||
|
||||
### Custom emoji
|
||||
|
||||
Custom emoji remain in their plain text shortcode form. Metadata about the determined custom emoji is included with the status, and the shortcodes must be matched against the text to display the images.
|
||||
|
||||
### Other links
|
||||
|
||||
Links in Mastodon are not shortened using URL shorteners. However, URLs in text always count for 23 characters, and are intended to be shortened visually. For that purpose, a link is marked up like this:
|
||||
|
||||
```html
|
||||
<a href="https://example.com/page/that/is/very/long">
|
||||
<span class="invisible">https://</span>
|
||||
<span class="ellipsis">example.com/page</span>
|
||||
<span class="invisible">/that/is/very/long</span>
|
||||
</a>
|
||||
```
|
||||
|
||||
The spans with the `invisible` class can be hidden. The middle span is intended to remain visible. It may have no class if the URL is not very long, otherwise it will have an `ellipsis` class. No ellipsis (`…`) character is inserted in the markup, instead, you are expected to insert it yourself if you need it in your app.
|
||||
|
||||
## Filters
|
||||
|
||||
Clients must do their own text filtering based on filters returned from the API. The server will apply `irreversible` filters for home and notifications context, but anything else is still up to the client to filter!
|
||||
|
||||
Expired filters are not deleted by the server. They should no longer be applied but they are still stored by the server. It is up to clients to delete those filters eventually.
|
||||
|
|
@ -0,0 +1,102 @@
|
|||
---
|
||||
title: Libraries
|
||||
description: List of libraries that work with the Mastodon API in various programming languages
|
||||
menu:
|
||||
docs:
|
||||
parent: api
|
||||
weight: -1
|
||||
---
|
||||
|
||||
## Apex (Salesforce)
|
||||
|
||||
- [apex-mastodon](https://github.com/tzmfreedom/apex-mastodon)
|
||||
|
||||
## C# (.NET Standard)
|
||||
|
||||
- [Mastodot](https://github.com/yamachu/Mastodot)
|
||||
- [Mastonet](https://github.com/glacasa/Mastonet)
|
||||
- [TootNet](https://github.com/cucmberium/TootNet)
|
||||
- [mastodon-api-cs](https://github.com/pawotter/mastodon-api-cs)
|
||||
- [Mastodon.Net](https://github.com/Tlaster/Mastodon.Net)
|
||||
|
||||
## C++
|
||||
|
||||
- [mastodon-cpp](https://github.com/tastytea/mastodon-cpp)
|
||||
|
||||
## Crystal
|
||||
|
||||
- [mastodon.cr](https://github.com/decors/mastodon.cr)
|
||||
|
||||
## Common Lisp
|
||||
|
||||
- [tooter](https://github.com/Shinmera/tooter)
|
||||
|
||||
## Elixir
|
||||
|
||||
- [hunter](https://github.com/milmazz/hunter)
|
||||
|
||||
## Go
|
||||
|
||||
- [go-mastodon](https://github.com/mattn/go-mastodon)
|
||||
- [madon](https://github.com/McKael/madon)
|
||||
|
||||
## Haskell
|
||||
|
||||
- [hastodon](https://github.com/syucream/hastodon)
|
||||
|
||||
## Java
|
||||
|
||||
- [mastodon4j](https://github.com/sys1yagi/mastodon4j)
|
||||
|
||||
## JavaScript
|
||||
|
||||
- [libodonjs](https://github.com/Zatnosk/libodonjs)
|
||||
|
||||
## JavaScript (Browser)
|
||||
|
||||
- [mastodon.js](https://github.com/Kirschn/mastodon.js)
|
||||
|
||||
## JavaScript (Node.js)
|
||||
|
||||
- [node-mastodon](https://github.com/jessicahayley/node-mastodon)
|
||||
- [mastodon-api](https://github.com/vanita5/mastodon-api)
|
||||
|
||||
## Perl
|
||||
|
||||
- [Mastodon::Client](https://metacpan.org/pod/Mastodon::Client)
|
||||
|
||||
## PHP
|
||||
|
||||
- [Mastodon API for Laravel](https://github.com/kawax/laravel-mastodon-api)
|
||||
- [Mastodon-api-php](https://github.com/yks118/Mastodon-api-php)
|
||||
- [Composer based php API wrapper](https://github.com/r-daneelolivaw/mastodon-api-php)
|
||||
- [MastodonOAuthPHP](https://github.com/TheCodingCompany/MastodonOAuthPHP)
|
||||
- [Phediverse Mastodon REST Client](https://github.com/phediverse/mastodon-rest)
|
||||
- [TootoPHP](https://framagit.org/MaxKoder/TootoPHP)
|
||||
- [oauth2-mastodon](https://github.com/lrf141/oauth2-mastodon)
|
||||
- [Mastodon Wordpress API](https://github.com/L1am0/mastodon_wordpress_api)
|
||||
|
||||
## Python
|
||||
|
||||
- [Mastodon.py](https://github.com/halcy/Mastodon.py)
|
||||
|
||||
## R
|
||||
|
||||
- [mastodon](https://github.com/ThomasChln/mastodon)
|
||||
|
||||
## Ruby
|
||||
|
||||
- [mastodon-api](https://github.com/tootsuite/mastodon-api)
|
||||
|
||||
## Rust
|
||||
|
||||
- [mammut](https://github.com/Aaronepower/mammut)
|
||||
- [elefren](https://github.com/pwoolcoc/elefren)
|
||||
|
||||
## Scala
|
||||
|
||||
- [scaladon](https://github.com/schwitzerm/scaladon)
|
||||
|
||||
## Swift
|
||||
|
||||
- [MastodonKit](https://github.com/ornithocoder/MastodonKit)
|
||||
|
|
@ -0,0 +1,44 @@
|
|||
---
|
||||
title: Parameters
|
||||
description: Specifics of parameter passing to the Mastodon API
|
||||
menu:
|
||||
docs:
|
||||
parent: api
|
||||
weight: 3
|
||||
---
|
||||
|
||||
## Parameter format
|
||||
|
||||
Query strings, form data, and JSON submitted via POST body is equally understood by the API. It is expected that query strings are used for GET requests, and form data or JSON is used for all other requests.
|
||||
|
||||
## Arrays
|
||||
|
||||
An array parameter must encoded using bracket notation, e.g. `array[0]=foo&array[1]=bar` would be translated into:
|
||||
|
||||
```ruby
|
||||
array = [
|
||||
'foo',
|
||||
'bar',
|
||||
]
|
||||
```
|
||||
|
||||
## Booleans
|
||||
|
||||
A boolean value is considered false for the values `0`, `f`, `F`, `false`, `FALSE`, `off`, `OFF`, considered to not be provided for empty strings, and considered to be true for all other values.
|
||||
|
||||
## Files
|
||||
|
||||
File uploads must be encoded using `multipart/form-data`.
|
||||
|
||||
## Nested parameters
|
||||
|
||||
Some parameters need to be nested. For that, bracket notation must also be used. For example, `source[privacy]=public&source[language]=en` would be translated into:
|
||||
|
||||
```ruby
|
||||
source = {
|
||||
privacy: 'public',
|
||||
language: 'en',
|
||||
}
|
||||
```
|
||||
|
||||
This can be combined with arrays as well.
|
||||
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
title: Permissions
|
||||
description: Overview of OAuth 2 access scopes in Mastodon
|
||||
menu:
|
||||
docs:
|
||||
parent: api
|
||||
weight: 2
|
||||
---
|
||||
|
||||
The API is divided up into access scopes:
|
||||
|
||||
|Scope|Parent(s)|Added in|
|
||||
|:----|---------|:------:|
|
||||
|`write`||0.9.0|
|
||||
|`write:accounts`|`write`|2.4.3|
|
||||
|`write:blocks`|`write`, `follow`|2.4.3|
|
||||
|`write:favourites`|`write`|2.4.3|
|
||||
|`write:filters`|`write`|2.4.3|
|
||||
|`write:follows`|`write`, `follow`|2.4.3|
|
||||
|`write:lists`|`write`|2.4.3|
|
||||
|`write:media`|`write`|2.4.3|
|
||||
|`write:mutes`|`write`, `follow`|2.4.3|
|
||||
|`write:notifications`|`write`|2.4.3|
|
||||
|`write:reports`|`write`|2.4.3|
|
||||
|`write:statuses`|`write`|2.4.3|
|
||||
|`read`||0.9.0|
|
||||
|`read:accounts`|`read`|2.4.3|
|
||||
|`read:blocks`|`read`, `follow`|2.4.3|
|
||||
|`read:favourites`|`read`|2.4.3|
|
||||
|`read:filters`|`read`|2.4.3|
|
||||
|`read:follows`|`read`, `follow`|2.4.3|
|
||||
|`read:lists`|`read`|2.4.3|
|
||||
|`read:mutes`|`read`, `follow`|2.4.3|
|
||||
|`read:notifications`|`read`|2.4.3|
|
||||
|`read:reports`|`read`|2.4.3|
|
||||
|`read:search`|`read`|2.4.3|
|
||||
|`read:statuses`|`read`|2.4.3|
|
||||
|`follow`||0.9.0|
|
||||
|`push`||2.4.0|
|
||||
|
||||
The scopes are hierarchical, i.e. if you have access to `read`, you automatically have access to `read:accounts`. **It is recommended that you request as little as possible for your application.**
|
||||
|
||||
Multiple scopes can be requested at the same time: During app creation with the `scopes` param, and during the authorization phase with the `scope` query param (space-separate the scopes).
|
||||
|
||||
> **Note:** Mind the `scope` vs `scopes` difference. This is because `scope` is a standard OAuth parameter name, so it is used in the OAuth methods. Mastodon's own REST API uses the more appropriate `scopes`.
|
||||
|
||||
If you do not specify a `scope` in your authorization request, or a `scopes` in your app creation request, the resulting access token / app will default to `read` access.
|
||||
|
||||
The set of scopes saved during app creation must include all the scopes that you will request in the authorization request, otherwise authorization will fail.
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
---
|
||||
title: Web Push API
|
||||
overview: How to use the Web Push API in Mastodon to receive push notifications in a native or browser app
|
||||
menu:
|
||||
docs:
|
||||
parent: api
|
||||
weight: 5
|
||||
---
|
||||
|
||||
Mastodon natively supports the [Web Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API). You can utilize the same mechanisms for your native app. It requires running a proxy server that connects to Android's and Apple's proprietary notification gateways. However, the proxy server does not have access to the contents of the notifications. For a reference, see [Mozilla's web push server](https://github.com/mozilla-services/autopush), or more practically, see:
|
||||
|
||||
- [toot-relay](https://github.com/DagAgren/toot-relay)
|
||||
- [PushToFCM](https://github.com/tateisu/PushToFCM)
|
||||
|
||||
Using the Web Push API requires your app to have the `push` scope. To create a new Web Push API subscription, use [POST /api/v1/push/subscription]({{< relref "notifications.md#post-api-v1-push-subscription" >}}).
|
||||
|
|
@ -0,0 +1,176 @@
|
|||
---
|
||||
title: Accounts
|
||||
menu:
|
||||
docs:
|
||||
parent: rest-api
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## GET /api/v1/accounts/:id
|
||||
|
||||
Returns [Account]({{< relref "entities.md#account" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="No" user="No" scope="read read:accounts" version="0.0.0" >}}
|
||||
|
||||
## GET /api/v1/accounts/verify_credentials
|
||||
|
||||
User's own account.
|
||||
|
||||
Returns [Account]({{< relref "entities.md#account" >}}) with an extra [`source` attribute]({{< relref "entities.md#source" >}}).
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read read:accounts" version="0.0.0" >}}
|
||||
|
||||
## PATCH /api/v1/accounts/update_credentials
|
||||
|
||||
Update user's own account.
|
||||
|
||||
Returns [Account]({{< relref "entities.md#account" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|
|
||||
|----|-----------|:------:|
|
||||
| `display_name` | Display name | Optional |
|
||||
| `note` | Biography | Optional |
|
||||
| `avatar` | Avatar encoded using `multipart/form-data` | Optional |
|
||||
| `header` | Header image encoded using `multipart/form-data` | Optional |
|
||||
| `locked` | Enable follow requests | Optional |
|
||||
| `source[privacy]` | Default post privacy preference | Optional |
|
||||
| `source[sensitive]`| Whether to mark statuses as sensitive by default | Optional |
|
||||
| `source[language]` | Override language on statuses by default (ISO6391) | Optional |
|
||||
| `fields_attributes` | Profile metadata (max. 4) | Optional |
|
||||
|
||||
## GET /api/v1/accounts/:id/followers
|
||||
|
||||
Accounts which follow the given account.
|
||||
|
||||
Returns array of [Account]({{< relref "entities.md#account" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="No" scope="read read:accounts" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `limit` | Maximum number of results | Optional | 40 |
|
||||
|
||||
### Pagination
|
||||
|
||||
{{< api_pagination >}}
|
||||
|
||||
## GET /api/v1/accounts/:id/following
|
||||
|
||||
Accounts which the given account is following.
|
||||
|
||||
Returns array of [Account]({{< relref "entities.md#account" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="No" scope="read read:accounts" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `limit` | Maximum number of results | Optional | 40 |
|
||||
|
||||
### Pagination
|
||||
|
||||
{{< api_pagination >}}
|
||||
|
||||
## GET /api/v1/accounts/:id/statuses
|
||||
|
||||
An account's statuses.
|
||||
|
||||
Returns array of [Status]({{< relref "entities.md#status" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="No" scope="read read:statuses" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `only_media` | Only return statuses that have media attachments | Optional |false|
|
||||
| `pinned` | Only return statuses that have been pinned | Optional |false|
|
||||
| `exclude_replies` | Skip statuses that reply to other statuses | Optional |false|
|
||||
| `max_id` | Return results older than ID | Optional ||
|
||||
| `since_id` | Return results newer than ID | Optional ||
|
||||
| `min_id` | Return results immediately newer than ID | Optional ||
|
||||
| `limit` | Maximum number of results | Optional | 20 |
|
||||
|
||||
### Pagination
|
||||
|
||||
{{< api_dynamic_pagination >}}
|
||||
|
||||
## POST /api/v1/accounts/:id/follow
|
||||
|
||||
Follow an account.
|
||||
|
||||
Returns [Relationship]({{< relref "entities.md#relationship" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write:follows follow" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `reblogs` | Whether the followed account's reblogs will show up in the home timeline | Optional | true |
|
||||
|
||||
## POST /api/v1/accounts/:id/unfollow
|
||||
|
||||
Unfollow an account.
|
||||
|
||||
Returns [Relationship]({{< relref "entities.md#relationship" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write:follows follow" version="0.0.0" >}}
|
||||
|
||||
## GET /api/v1/accounts/relationships
|
||||
|
||||
Relationship of the user to the given accounts in regards to following, blocking, muting, etc.
|
||||
|
||||
Returns array of [Relationship]({{< relref "entities.md#relationship" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read read:follows" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|
|
||||
|----|-----------|:------:|
|
||||
| `id` | Array of account IDs | Required |
|
||||
|
||||
## GET /api/v1/accounts/search
|
||||
|
||||
Search for matching accounts by username, domain and display name.
|
||||
|
||||
Returns array of [Account]({{< relref "entities.md#account" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read read:accounts" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `q` | What to search for | Required ||
|
||||
| `limit` | Maximum number of results | Optional | 40 |
|
||||
| `resolve` | Attempt WebFinger look-up | Optional | false |
|
||||
| `following` | Only who the user is following | Optional | false |
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
---
|
||||
title: Apps
|
||||
menu:
|
||||
docs:
|
||||
parent: rest-api
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## POST /api/v1/apps
|
||||
|
||||
Create a new application to obtain OAuth2 credentials.
|
||||
|
||||
Returns [App]({{< relref "entities.md#app" >}}) with `client_id` and `client_secret`
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="No" user="No" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|
|
||||
|----|-----------|:------:|
|
||||
| `client_name` | Name of your application | Required |
|
||||
| `redirect_uris` | Where the user should be redirected after authorization | Required |
|
||||
| `scopes` | Space separated list of [scopes]({{< relref "permissions.md" >}}) | Required |
|
||||
| `website` | URL to the homepage of your app | Optional |
|
||||
|
||||
> To display the authorization code to the end-user instead of redirecting to a web page, use `urn:ietf:wg:oauth:2.0:oob` in `redirect_uris`
|
||||
|
||||
## GET /api/v1/apps/verify_credentials
|
||||
|
||||
Confirm that the app's OAuth2 credentials work.
|
||||
|
||||
Returns [App]({{< relref "entities.md#app" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="No" version="0.0.0" >}}
|
||||
|
|
@ -0,0 +1,47 @@
|
|||
---
|
||||
title: Blocks
|
||||
menu:
|
||||
docs:
|
||||
parent: rest-api
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## GET /api/v1/blocks
|
||||
|
||||
Accounts the user has blocked.
|
||||
|
||||
Returns array of [Account]({{< relref "entities.md#account" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read:blocks follow" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `limit` | Maximum number of results | Optional | 40 |
|
||||
|
||||
### Pagination
|
||||
|
||||
{{< api_pagination >}}
|
||||
|
||||
## POST /api/v1/accounts/:id/block
|
||||
|
||||
Block an account.
|
||||
|
||||
Returns [Relationship]({{< relref "entities.md#relationship" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write:blocks follow" version="0.0.0" >}}
|
||||
|
||||
## POST /api/v1/accounts/:id/unblock
|
||||
|
||||
Unblock an account.
|
||||
|
||||
Returns [Relationship]({{< relref "entities.md#relationship" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write:blocks follow" version="0.0.0" >}}
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
title: Custom emoji
|
||||
menu:
|
||||
docs:
|
||||
parent: rest-api
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## GET /api/v1/custom_emojis
|
||||
|
||||
Custom emojis that are available on the server.
|
||||
|
||||
Returns array of [Emoji]({{< relref "entities.md#emoji" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="No" user="No" version="0.0.0" >}}
|
||||
|
|
@ -0,0 +1,55 @@
|
|||
---
|
||||
title: Domain blocks
|
||||
menu:
|
||||
docs:
|
||||
parent: rest-api
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## GET /api/v1/domain_blocks
|
||||
|
||||
Domains the user has blocked.
|
||||
|
||||
Returns array of string.
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read read:blocks follow" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `limit` | Maximum number of results | Optional | 40 |
|
||||
|
||||
### Pagination
|
||||
|
||||
{{< api_pagination >}}
|
||||
|
||||
## POST /api/v1/domain_blocks
|
||||
|
||||
Block a domain to hide all public posts from it, all notifications from it, and remove all followers from it.
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:blocks follow" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|
|
||||
|----|-----------|:------:|
|
||||
| `domain` | Domain to block| Required |
|
||||
|
||||
## DELETE /api/v1/domain_blocks
|
||||
|
||||
Remove a domain block.
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:blocks follow" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|
|
||||
|----|-----------|:------:|
|
||||
| `domain` | Domain to unblock| Required |
|
||||
|
|
@ -0,0 +1,41 @@
|
|||
---
|
||||
title: Endorsements
|
||||
menu:
|
||||
docs:
|
||||
parent: rest-api
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## GET /api/v1/endorsements
|
||||
|
||||
Accounts the user chose to endorse.
|
||||
|
||||
Returns array of [Account]({{< relref "entities.md#account" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read read:account" version="0.0.0" >}}
|
||||
|
||||
### Pagination
|
||||
|
||||
{{< api_pagination >}}
|
||||
|
||||
## POST /api/v1/accounts/:id/pin
|
||||
|
||||
Endorse an account, i.e. choose to feature the account on the user's public profile.
|
||||
|
||||
Returns [Relationship]({{< relref "entities.md#relationship" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="0.0.0" >}}
|
||||
|
||||
## POST /api/v1/accounts/:id/unpin
|
||||
|
||||
Undo endorse of an account.
|
||||
|
||||
Returns [Relationship]({{< relref "entities.md#relationship" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="0.0.0" >}}
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
---
|
||||
title: Favourites
|
||||
menu:
|
||||
docs:
|
||||
parent: rest-api
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## GET /api/v1/favourites
|
||||
|
||||
Statuses the user has favourited.
|
||||
|
||||
Returns array of [Status]({{< relref "entities.md#status" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read read:favourites" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `limit` | Maximum number of results | Optional | 20 |
|
||||
|
||||
### Pagination
|
||||
|
||||
{{< api_pagination >}}
|
||||
|
||||
## POST /api/v1/statuses/:id/favourite
|
||||
|
||||
Favourite a status.
|
||||
|
||||
Returns [Status]({{< relref "entities.md#status" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:favourites" version="0.0.0" >}}
|
||||
|
||||
## POST /api/v1/statuses/:id/unfavourite
|
||||
|
||||
Undo the favourite of a status.
|
||||
|
||||
Returns [Status]({{< relref "entities.md#status" >}})
|
||||
|
|
@ -0,0 +1,75 @@
|
|||
---
|
||||
title: Filters
|
||||
menu:
|
||||
docs:
|
||||
parent: rest-api
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## GET /api/v1/filters
|
||||
|
||||
Text filters the user has configured that potentially must be applied client-side.
|
||||
|
||||
Returns array of [Filter]({{< relref "entities.md#filter" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read read:filters" version="0.0.0" >}}
|
||||
|
||||
## POST /api/v1/filters
|
||||
|
||||
Create a new filter.
|
||||
|
||||
Returns [Filter]({{< relref "entities.md#filter" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:filters" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|
|
||||
|----|-----------|:------:|
|
||||
| `phrase` | Keyword or phrase to filter | Required |
|
||||
| `context` | Array of strings that means filtering context. Each string is one of `home`, `notifications`, `public`, `thread`. At least one context must be specified. | Required |
|
||||
| `irreversible` | Irreversible filtering will only work in `home` and `notifications` contexts by fully dropping the records. Otherwise, filtering is up to the client. | Optional |
|
||||
| `whole_word` | Whether to consider word boundaries when matching | Optional |
|
||||
| `expires_in` | Number that indicates seconds. Filter will be expire in seconds after API processed. Leave blank for no expiration | Optional |
|
||||
|
||||
## GET /api/v1/filters/:id
|
||||
|
||||
A text filter.
|
||||
|
||||
Returns [Filter]({{< relref "entities.md#filter" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read read:filters" version="0.0.0" >}}
|
||||
|
||||
## PUT /api/v1/filters/:id
|
||||
|
||||
Update a text filter.
|
||||
|
||||
Returns [Filter]({{< relref "entities.md#filter" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:filters" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|
|
||||
|----|-----------|:------:|
|
||||
| `phrase` | Keyword or phrase to filter | Required |
|
||||
| `context` | Array of strings that means filtering context. Each string is one of `home`, `notifications`, `public`, `thread`. At least one context must be specified. | Required |
|
||||
| `irreversible` | Irreversible filtering will only work in `home` and `notifications` contexts by fully dropping the records. Otherwise, filtering is up to the client. | Optional |
|
||||
| `whole_word` | Whether to consider word boundaries when matching | Optional |
|
||||
| `expires_in` | Number that indicates seconds. Filter will be expire in seconds after API processed. Leave blank to not change | Optional |
|
||||
|
||||
## DELETE /api/v1/filters/:id
|
||||
|
||||
Delete a text filter.
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:filters" version="0.0.0" >}}
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
---
|
||||
title: Follow requests
|
||||
menu:
|
||||
docs:
|
||||
parent: rest-api
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## GET /api/v1/follow_requests
|
||||
|
||||
Accounts that have requested to follow the user.
|
||||
|
||||
Returns array of [Account]({{< relref "entities.md#account" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read read:follows follow" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `limit` | Maximum number of results | Optional | 40 |
|
||||
|
||||
### Pagination
|
||||
|
||||
{{< api_pagination >}}
|
||||
|
||||
## POST /api/v1/follow_requests/:id/authorize
|
||||
|
||||
Allow the account to follow the user.
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write:follows follow" version="0.0.0" >}}
|
||||
|
||||
## POST /api/v1/follow_requests/:id/reject
|
||||
|
||||
Do not allow the account to follow the user.
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write:follows follow" version="0.0.0" >}}
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
---
|
||||
title: Follow suggestions
|
||||
menu:
|
||||
docs:
|
||||
parent: rest-api
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## GET /api/v1/suggestions
|
||||
|
||||
Accounts the user had past positive interactions with, but is not following yet.
|
||||
|
||||
Returns array of [Account]({{< relref "entities.md#account" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read" version="0.0.0" >}}
|
||||
|
||||
## DELETE /api/v1/suggestions/:account_id
|
||||
|
||||
Remove account from suggestions.
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read" version="0.0.0" >}}
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
title: Instances
|
||||
menu:
|
||||
docs:
|
||||
parent: rest-api
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## GET /api/v1/instance
|
||||
|
||||
Information about the server.
|
||||
|
||||
Returns [Instance]({{< relref "entities.md#instance" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="No" user="No" version="0.0.0" >}}
|
||||
|
|
@ -0,0 +1,127 @@
|
|||
---
|
||||
title: Lists
|
||||
menu:
|
||||
docs:
|
||||
parent: rest-api
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## GET /api/v1/lists
|
||||
|
||||
User's lists.
|
||||
|
||||
Returns array of [List]({{< relref "entities.md#list" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read read:lists" version="0.0.0" >}}
|
||||
|
||||
## GET /api/v1/accounts/:id/lists
|
||||
|
||||
User's lists that a given account is part of.
|
||||
|
||||
Returns array of [List]({{< relref "entities.md#list" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read read:lists" version="0.0.0" >}}
|
||||
|
||||
## GET /api/v1/lists/:id/accounts
|
||||
|
||||
Accounts that are in a given list.
|
||||
|
||||
Returns array of [Account]({{< relref "entities.md#account" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read read:lists" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `limit` | Maximum number of results | Optional | 40 |
|
||||
|
||||
### Pagination
|
||||
|
||||
>If you specify a `limit` of `0` in the query, all accounts will be returned without pagination. Otherwise, standard account pagination rules apply.
|
||||
|
||||
{{< api_pagination >}}
|
||||
|
||||
## GET /api/v1/lists/:id
|
||||
|
||||
Returns [List]({{< relref "entities.md#list" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read read:lists" version="0.0.0" >}}
|
||||
|
||||
## POST /api/v1/lists
|
||||
|
||||
Create a new list.
|
||||
|
||||
Returns [List]({{< relref "entities.md#list" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|
|
||||
|----|-----------|:------:|
|
||||
| `title` | The title of the list | Required |
|
||||
|
||||
## PUT /api/v1/lists/:id
|
||||
|
||||
Update a list.
|
||||
|
||||
Returns [List]({{< relref "entities.md#list" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|
|
||||
|----|-----------|:------:|
|
||||
| `title` | The title of the list | Required |
|
||||
|
||||
## DELETE /api/v1/lists/:id
|
||||
|
||||
Remove a list.
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="0.0.0" >}}
|
||||
|
||||
## POST /api/v1/lists/:id/accounts
|
||||
|
||||
Add accounts to a list.
|
||||
|
||||
> Only accounts already followed by the user can be added to a list.
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|
|
||||
|----|-----------|:------:|
|
||||
| `account_ids` | Array of account IDs | Required |
|
||||
|
||||
## DELETE /api/v1/lists/:id/accounts
|
||||
|
||||
Remove accounts from a list.
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|
|
||||
|----|-----------|:------:|
|
||||
| `account_ids` | Array of account IDs | Required |
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
---
|
||||
title: Media attachments
|
||||
menu:
|
||||
docs:
|
||||
parent: rest-api
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## POST /api/v1/media
|
||||
|
||||
Upload a media attachment that can be used with a new status.
|
||||
|
||||
Returns [Attachment]({{< relref "entities.md#attachment" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:media" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|
|
||||
|----|-----------|:------:|
|
||||
| `file` | Media file encoded using `multipart/form-data` | Required |
|
||||
| `description` | A plain-text description of the media for accessibility (max 420 chars) | Optional |
|
||||
| `focus` | Two floating points, comma-delimited. See [focal points](#focal-points) | Optional |
|
||||
|
||||
## PUT /api/v1/media/:id
|
||||
|
||||
Update a media attachment. Can only be done before the media is attached to a status.
|
||||
|
||||
Returns [Attachment]({{< relref "entities.md#attachment" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:media" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|
|
||||
|----|-----------|:------:|
|
||||
| `description` | A plain-text description of the media for accessibility (max 420 chars) | Optional |
|
||||
| `focus` | Two floating points, comma-delimited. See [focal points](#focal-points) | Optional |
|
||||
|
||||
## Focal points
|
||||
|
||||
Server-side preview images are never cropped, to support a variety of apps and user interfaces. Therefore, the cropping must be done by those apps. To crop intelligently, focal points can be used to ensure a certain section of the image is always within the cropped viewport. [See this for how to let users select focal point coordinates](https://github.com/jonom/jquery-focuspoint#1-calculate-your-images-focus-point).
|
||||
|
|
@ -0,0 +1,73 @@
|
|||
---
|
||||
title: Mutes
|
||||
menu:
|
||||
docs:
|
||||
parent: rest-api
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## GET /api/v1/mutes
|
||||
|
||||
Accounts the user has muted.
|
||||
|
||||
Returns array of [Account]({{< relref "entities.md#account" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read:mutes follow" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `limit` | Maximum number of results | Optional | 40 |
|
||||
|
||||
### Pagination
|
||||
|
||||
{{< api_pagination >}}
|
||||
|
||||
## POST /api/v1/accounts/:id/mute
|
||||
|
||||
Mute an account.
|
||||
|
||||
Returns [Relationship]({{< relref "entities.md#relationship" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write:mutes follow" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `notifications` | Whether the mute will mute notifications or not | Optional | true |
|
||||
|
||||
## POST /api/v1/accounts/:id/unmute
|
||||
|
||||
Unmute an account.
|
||||
|
||||
Returns [Relationship]({{< relref "entities.md#relationship" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write:mutes follow" version="0.0.0" >}}
|
||||
|
||||
## POST /api/v1/statuses/:id/mute
|
||||
|
||||
Mute the conversation the status is part of, to no longer be notified about it.
|
||||
|
||||
Returns [Status]({{< relref "entities.md#status" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:mutes" version="0.0.0" >}}
|
||||
|
||||
## POST /api/v1/statuses/:id/unmute
|
||||
|
||||
Unmute the conversation the status is part of.
|
||||
|
||||
Returns [Status]({{< relref "entities.md#status" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:mutes" version="0.0.0" >}}
|
||||
|
|
@ -0,0 +1,120 @@
|
|||
---
|
||||
title: Notifications
|
||||
menu:
|
||||
docs:
|
||||
parent: rest-api
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## GET /api/v1/notifications
|
||||
|
||||
Notifications concerning the user.
|
||||
|
||||
Returns array of [Notification]({{< relref "entities.md#notification" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read read:notifications" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `max_id` | Return results older than ID | Optional ||
|
||||
| `since_id` | Return results newer than ID | Optional ||
|
||||
| `min_id` | Return results immediately newer than ID | Optional ||
|
||||
| `limit` | Maximum number of results | Optional | 20 |
|
||||
| `exclude_types` | Array of types to exclude (e.g. `follow`, `favourite`, `reblog`, `mention`) | Optional ||
|
||||
|
||||
### Pagination
|
||||
|
||||
{{< api_dynamic_pagination >}}
|
||||
|
||||
## GET /api/v1/notifications/:id
|
||||
|
||||
Returns [Notification]({{< relref "entities.md#notification" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read read:notifications" version="0.0.0" >}}
|
||||
|
||||
## POST /api/v1/notifications/clear
|
||||
|
||||
Delete all notifications from the server.
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:notifications" version="0.0.0" >}}
|
||||
|
||||
## POST /api/v1/notifications/dismiss
|
||||
|
||||
Delete a single notification from the server.
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:notifications" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|
|
||||
|----|-----------|:------:|
|
||||
| `id` | Notification ID | Required |
|
||||
|
||||
## POST /api/v1/push/subscription
|
||||
|
||||
Add a Web Push API subscription to receive notifications. See also: [Web Push API]({{< relref "push.md" >}})
|
||||
|
||||
> Each access token can have one push subscription. If you create a new subscription, the old subscription is deleted.
|
||||
|
||||
Returns [Push Subscription]({{< relref "entities.md#push-subscription" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="push" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|
|
||||
|----|-----------|:------:|
|
||||
| `subscription[endpoint]` | Endpoint URL that called when notification is happen. | Required |
|
||||
| `subscription[keys][p256dh]` | User agent public key. Base64 encoded string of public key of ECDH key using 'prime256v1' curve. | Required |
|
||||
| `subscription[keys][auth]` | Auth secret. Base64 encoded string of 16 bytes of random data. | Required |
|
||||
| `data[alerts][follow]` | Boolean of whether you want to receive follow notification event. | Optional |
|
||||
| `data[alerts][favourite]` | Boolean of whether you want to receive favourite notification event. | Optional |
|
||||
| `data[alerts][reblog]` | Boolean of whether you want to receive reblog notification event. | Optional |
|
||||
| `data[alerts][mention]` | Boolean of whether you want to receive mention notification event. | Optional |
|
||||
|
||||
## GET /api/v1/push/subscription
|
||||
|
||||
Returns [Push Subscription]({{< relref "entities.md#push-subscription" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="push" version="0.0.0" >}}
|
||||
|
||||
## PUT /api/v1/push/subscription
|
||||
|
||||
Update current Web Push API subscription. Only the `data` part can be updated, e.g. which types of notifications are desired. To change fundamentals, a new subscription must be created instead.
|
||||
|
||||
Returns [Push Subscription]({{< relref "entities.md#push-subscription" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="push" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|
|
||||
|----|-----------|:------:|
|
||||
| `data[alerts][follow]` | Boolean of whether you want to receive follow notification event. | Optional |
|
||||
| `data[alerts][favourite]` | Boolean of whether you want to receive favourite notification event. | Optional |
|
||||
| `data[alerts][reblog]` | Boolean of whether you want to receive reblog notification event. | Optional |
|
||||
| `data[alerts][mention]` | Boolean of whether you want to receive mention notification event. | Optional |
|
||||
|
||||
## DELETE /api/v1/push/subscription
|
||||
|
||||
Remove the current Web Push API subscription.
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="push" version="0.0.0" >}}
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
---
|
||||
title: Reports
|
||||
menu:
|
||||
docs:
|
||||
parent: rest-api
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## POST /api/v1/reports
|
||||
|
||||
Report an account.
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:reports" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|
|
||||
|----|-----------|:------:|
|
||||
| `account_id` | The ID of the account to report | Required |
|
||||
| `status_ids` | The IDs of statuses to report as array | Optional |
|
||||
| `comment` | Reason for the report (up to 1,000 characters) | Optional |
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
---
|
||||
title: Search
|
||||
menu:
|
||||
docs:
|
||||
parent: rest-api
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## GET /api/v2/search
|
||||
|
||||
Search for content in accounts, statuses and hashtags.
|
||||
|
||||
Returns [Results]({{< relref "entities.md#results" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read read:search" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `q` | The search query | Required ||
|
||||
| `resolve` | Attempt WebFinger look-up | Optional |false|
|
||||
|
|
@ -0,0 +1,157 @@
|
|||
---
|
||||
title: Statuses
|
||||
menu:
|
||||
docs:
|
||||
parent: rest-api
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## GET /api/v1/statuses/:id
|
||||
|
||||
Returns [Status]({{< relref "entities.md#status" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}
|
||||
|
||||
## GET /api/v1/statuses/:id/context
|
||||
|
||||
What the status replies to, and replies to it.
|
||||
|
||||
Returns [Context]({{< relref "entities.md#context" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}
|
||||
|
||||
## GET /api/v1/statuses/:id/card
|
||||
|
||||
Link preview card for a status, if available.
|
||||
|
||||
Returns [Card]({{< relref "entities.md#card" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}
|
||||
|
||||
## GET /api/v1/statuses/:id/reblogged_by
|
||||
|
||||
Accounts that reblogged the status.
|
||||
|
||||
Returns array of [Account]({{< relref "entities.md#account" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `limit` | Maximum number of results | Optional | 40 |
|
||||
|
||||
### Pagination
|
||||
|
||||
{{< api_pagination >}}
|
||||
|
||||
## GET /api/v1/statuses/:id/favourited_by
|
||||
|
||||
Accounts that favourited the status.
|
||||
|
||||
Returns array of [Account]({{< relref "entities.md#account" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `limit` | Maximum number of results | Optional | 40 |
|
||||
|
||||
### Pagination
|
||||
|
||||
{{< api_pagination >}}
|
||||
|
||||
## POST /api/v1/statuses
|
||||
|
||||
Publish a new status.
|
||||
|
||||
Returns [Status]({{< relref "entities.md#status" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|
|
||||
|----|-----------|:------:|
|
||||
| `status` | The text of the status | Optional\* |
|
||||
| `in_reply_to_id` | ID of the status you want to reply to | Optional |
|
||||
| `media_ids` | Array of media IDs to attach to the status | Optional\* |
|
||||
| `sensitive` | Mark the media in the status as sensitive | Optional |
|
||||
| `spoiler_text` | Text to be shown as a warning before the actual content | Optional |
|
||||
| `visibility` | One of `direct`, `private`, `unlisted` `public` | Optional |
|
||||
| `language` | Override language code of the toot (ISO 639-2) | Optional |
|
||||
|
||||
> You must provide either `status` or `media_ids`, completely empty statuses are not allowed.
|
||||
|
||||
### Idempotency
|
||||
|
||||
In order to prevent duplicate statuses, this endpoint accepts an `Idempotency-Key` header, which should be set to a unique string for each new status. In the event of a network error, a request can be retried with the same `Idempotency-Key`. Only one status will be created regardless of how many requests with the same `Idempotency-Key` did go through.
|
||||
|
||||
See <https://stripe.com/blog/idempotency> for more on idempotency and idempotency keys.
|
||||
|
||||
## DELETE /api/v1/statuses/:id
|
||||
|
||||
Remove a status. The status may still be available a short while after the call.
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="0.0.0" >}}
|
||||
|
||||
## POST /api/v1/statuses/:id/reblog
|
||||
|
||||
Reblog a status.
|
||||
|
||||
Returns [Status]({{< relref "entities.md#status" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="0.0.0" >}}
|
||||
|
||||
## POST /api/v1/statuses/:id/unreblog
|
||||
|
||||
Undo the reblog of a status.
|
||||
|
||||
Returns [Status]({{< relref "entities.md#status" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="0.0.0" >}}
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:favourites" version="0.0.0" >}}
|
||||
|
||||
## POST /api/v1/statuses/:id/pin
|
||||
|
||||
Pin user's own status to user's profile.
|
||||
|
||||
Returns [Status]({{< relref "entities.md#status" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="0.0.0" >}}
|
||||
|
||||
## POST /api/v1/statuses/:id/unpin
|
||||
|
||||
Remove pinned status from user's profile.
|
||||
|
||||
Returns [Status]({{< relref "entities.md#status" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="0.0.0" >}}
|
||||
|
|
@ -0,0 +1,103 @@
|
|||
---
|
||||
title: Timelines
|
||||
menu:
|
||||
docs:
|
||||
parent: rest-api
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## GET /api/v1/timelines/home
|
||||
|
||||
Statuses from accounts the user follows.
|
||||
|
||||
Returns array of [Status]({{< relref "entities.md#status" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read read:statuses" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `max_id` | Return results older than ID | Optional ||
|
||||
| `since_id` | Return results newer than ID | Optional ||
|
||||
| `min_id` | Return results immediately newer than ID | Optional ||
|
||||
| `limit` | Maximum number of results | Optional | 20 |
|
||||
|
||||
### Pagination
|
||||
|
||||
{{< api_dynamic_pagination >}}
|
||||
|
||||
## GET /api/v1/timelines/public
|
||||
|
||||
Public statuses known to the server.
|
||||
|
||||
Returns array of [Status]({{< relref "entities.md#status" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `local` | Only local statuses | Optional |false|
|
||||
| `only_media` | Only statuses with media attachments | Optional |false|
|
||||
| `max_id` | Return results older than ID | Optional ||
|
||||
| `since_id` | Return results newer than ID | Optional ||
|
||||
| `min_id` | Return results immediately newer than ID | Optional ||
|
||||
| `limit` | Maximum number of results | Optional | 20 |
|
||||
|
||||
### Pagination
|
||||
|
||||
{{< api_dynamic_pagination >}}
|
||||
|
||||
## GET /api/v1/timelines/tag/:hashtag
|
||||
|
||||
Public statuses known to the server marked with a given hashtag.
|
||||
|
||||
Returns array of [Status]({{< relref "entities.md#status" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `local` | Only local statuses | Optional |false|
|
||||
| `only_media` | Only statuses with media attachments | Optional |false|
|
||||
| `max_id` | Return results older than ID | Optional ||
|
||||
| `since_id` | Return results newer than ID | Optional ||
|
||||
| `min_id` | Return results immediately newer than ID | Optional ||
|
||||
| `limit` | Maximum number of results | Optional | 20 |
|
||||
|
||||
### Pagination
|
||||
|
||||
{{< api_dynamic_pagination >}}
|
||||
|
||||
## GET /api/v1/timelines/list/:list_id
|
||||
|
||||
Statuses from accounts on a given list.
|
||||
|
||||
Returns array of [Status]({{< relref "entities.md#status" >}})
|
||||
|
||||
### Resource information
|
||||
|
||||
{{< api_method_info auth="Yes" user="Yes" scope="read read:statuses" version="0.0.0" >}}
|
||||
|
||||
### Parameters
|
||||
|
||||
|Name|Description|Required|Default|
|
||||
|----|-----------|:------:|:-----:|
|
||||
| `max_id` | Return results older than ID | Optional ||
|
||||
| `since_id` | Return results newer than ID | Optional ||
|
||||
| `min_id` | Return results immediately newer than ID | Optional ||
|
||||
| `limit` | Maximum number of results | Optional | 20 |
|
||||
|
||||
### Pagination
|
||||
|
||||
{{< api_dynamic_pagination >}}
|
||||
|
|
@ -0,0 +1,78 @@
|
|||
---
|
||||
title: Streaming API
|
||||
description: How to use Mastodon's streaming API for live, real-time updates
|
||||
menu:
|
||||
docs:
|
||||
parent: api
|
||||
weight: 4
|
||||
---
|
||||
|
||||
Your application can use a [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) endpoint to receive updates in real-time. Server-sent events is an incredibly simple transport method that relies entirely on chunked-encoding transfer, i.e. the HTTP connection is kept open and receives new data periodically.
|
||||
|
||||
Alternatively, a WebSocket connection can also be established.
|
||||
|
||||
## Server-sent events (HTTP)
|
||||
### Endpoints
|
||||
#### GET /api/v1/streaming/user
|
||||
|
||||
Returns events that are relevant to the authorized user, i.e. home timeline and notifications
|
||||
|
||||
#### GET /api/v1/streaming/public
|
||||
|
||||
Returns all public statuses
|
||||
|
||||
#### GET /api/v1/streaming/public/local
|
||||
|
||||
Returns all local statuses
|
||||
|
||||
#### GET /api/v1/streaming/hashtag?tag=:hashtag
|
||||
|
||||
Returns all public statuses for a particular hashtag
|
||||
|
||||
#### GET /api/v1/streaming/hashtag/local?tag=:hashtag
|
||||
|
||||
Returns all local statuses for a particular hashtag
|
||||
|
||||
#### GET /api/v1/streaming/list?list=:list_id
|
||||
|
||||
Returns statuses for a list
|
||||
|
||||
#### GET /api/v1/streaming/direct
|
||||
|
||||
Returns all direct messages
|
||||
|
||||
### Stream contents
|
||||
|
||||
The stream will contain events as well as heartbeat comments. Lines that begin with a colon (`:`) can be ignored by parsers, they are simply there to keep the connection open. Events have this structure:
|
||||
|
||||
```
|
||||
event: name
|
||||
data: payload
|
||||
```
|
||||
|
||||
## WebSocket
|
||||
|
||||
For WebSockets, there is only one URL path (`/api/v1/streaming`). The access token as well as the endpoint you are interested in must be provided with query params, respectively `access_token` and `stream`. Query params `list` and `tag` are likewise supported for relevant endpoints.
|
||||
|
||||
Possible `stream` values:
|
||||
|
||||
- `user`
|
||||
- `public`
|
||||
- `public:local`
|
||||
- `hashtag`
|
||||
- `hashtag:local`
|
||||
- `list`
|
||||
- `direct`
|
||||
|
||||
## Event types
|
||||
|
||||
|Event|Description|What's in the payload|
|
||||
|-----|-----------|---------------------|
|
||||
|`update`|A new status has appeared|[Status]({{< relref "entities.md#status" >}})|
|
||||
|`notification`|A new notification has appeared|[Notification]({{< relref "entities.md#notification" >}})|
|
||||
|`delete`|A status has been deleted|ID of the deleted status|
|
||||
|`filters_changed`|Keyword filters have been changed||
|
||||
|
||||
The payload is JSON-encoded.
|
||||
|
||||
> **Note:** In case of `filters_changed` event, `payload` is not defined.
|
||||
|
|
@ -0,0 +1,68 @@
|
|||
---
|
||||
title: Podstawy
|
||||
description: Omówienie podstawowej funkcjonalności Mastodona
|
||||
menu:
|
||||
docs:
|
||||
parent: usage
|
||||
weight: 1
|
||||
---
|
||||
## Rejestracja
|
||||
|
||||
Musisz wybrać serwer na którym się zarejestrujesz, tak jak wybrał(-a)byś dostawcę e-maila lub realm w World of Warcraft dla nowej postaci. Na tym serwerze będzie znajdować się Twoje konto i strumień.
|
||||
|
||||
Możesz [przejrzeć listę serwerów podzieloną według kategorii i języków na joinmastodon.org](https://joinmastodon.org/#getting-started).
|
||||
|
||||
## Edycja profilu
|
||||
### Zdjęcie, nazwa i opis
|
||||
|
||||
- Możesz zmienić awatar
|
||||
- Możesz ustawić obraz nagłówka
|
||||
- Możesz ustawić nazwę wyświetlaną inną niż nazwa użytkownika
|
||||
- Możesz napisać o sobie w biogramie
|
||||
- Możesz tam wspomnieć o innych kontach i używać hashtagów lub niestandardowych emoji
|
||||
|
||||
### Metadane profilu
|
||||
|
||||
Metadane profilu są sposobem na umieszczenie dodatkowych informacji w przejrzysty sposób. Możesz wykorzystać 4 rzędy, w których określasz nazwę i zawartość. Na przykład:
|
||||
|
||||
|Nazwa|Zawartość|
|
||||
|-----|-------|
|
||||
|Wiek|25|
|
||||
|Kraj|Niemcy|
|
||||
|Zaimek osobowy|he/him|
|
||||
|
||||
To, co tam umieścisz zależy tylko od Ciebie – możesz wspomnieć o innych, użyć hashtagów, niestandardowych emoji i odnośników.
|
||||
|
||||
### Weryfikacja odnośników
|
||||
|
||||
Jeżeli umieścisz odnośnik w metadanych profilu, Mastodon sprawdzi, czy ta strona zawiera odnośnik do Twojego profilu na Mastodonie. Jeżeli tak, obok odnośnika zostanie wyświetlony znak weryfikacji, ponieważ jesteś jego potwierdzonym właścicielem.
|
||||
|
||||
Mastodon sprawdza obecność artybutu `rel="me"` w tym odnośniku. Tak samo, Mastodon umieszcza `rel="me"` na odnośnikach w metadanych.
|
||||
|
||||
## Tworzenie wpisów
|
||||
### Tekst
|
||||
|
||||
- Możesz użyć maksymalnie 500 znaków
|
||||
- Możesz wspomnieć o innych użytkownikach, np. `@alice` lub `@alice@example.com`
|
||||
- Jeżeli wspominasz o innych, część zawierająca domenę jest omijana przez limit znaków
|
||||
- Odnośniki muszą zaczynać się od `http://` lub `https://`
|
||||
- Wszystkie odnośniki liczone są jako 23 znaki, niezależnie od ich długości
|
||||
- Możesz używać hashtagów tj. `#przykład`, aby inni mogli znaleźć Twój wpis używając tego tagu
|
||||
- Możesz dodawać ostrzeżenia o zawartości dla wpisów
|
||||
- Ostrzeżenie o zawartości to czysty tekst. Nie obsluguje wspomnień, hashtagów i odnośników
|
||||
|
||||
### Zawartość multimedialna
|
||||
|
||||
- Możesz wysyłać zdjęcia w JPG i PNG
|
||||
- Wysyłane GIF-y są konwertowane do MP4 bez dźwięku, tak jak na Imgur i Gfycat (GIFV)
|
||||
- Możesz też wysyłać bezpośrednio MP4 i WebM bez dźwięku (GIFV)
|
||||
- Możesz wysyłać filmy w formacie MP4, WebM lub MOV
|
||||
- Ograniczenie rozmiaru zdjęć to 8 MB
|
||||
- Ograniczenie rozmiaru filmów to 40 MB
|
||||
- Zdjęcia o powierzchni większej niż 1280² pikseli są skalowane w dół
|
||||
- Możesz ukryć zawartość multimedialną za spoilerem
|
||||
|
||||
### Niestandardowe emoji
|
||||
|
||||
- Każdy serwer może oferować zestaw niestandardowych emoji, tak jak na Discordzie
|
||||
- Możesz używać shortcode aby umieścić emoji, np. `:thounking:`
|
||||
|
|
@ -0,0 +1,91 @@
|
|||
---
|
||||
title: Decentralizacja
|
||||
description: W jaki sposób Mastodon jest zdecentralizowany i co to w praktyce oznacza
|
||||
menu:
|
||||
docs:
|
||||
parent: usage
|
||||
weight: 2
|
||||
---
|
||||
|
||||
Mastodon jest **sfederowaną** siecią społecznościową.
|
||||
|
||||
## Czym jest federacja?
|
||||
|
||||
**Federacja** to rodzaj decentralizacji. Zamiast jednego, centralnego serwera używanego przez wszystkich, istnieje wiele serwerów, z których każdy może korzystać.
|
||||
|
||||
|Rodzaj decentralizacji|Przykład|
|
||||
|:--------------------:|--------|
|
||||
|Scentralizowane|Twitter, Facebook, Instagram|
|
||||
|Sfederowane|E-mail, XMPP|
|
||||
|Dystrybuowane|BitTorrent, IPFS, Scuttlebutt|
|
||||
|
||||
Serwer Mastodona może działać samodzielnie. Tak jak na tradycyjnej stronie internetowej, można tam zarejestrować się, publikować wiadomości, wysyłać zdjęcia i rozmawiać z innymi. *W przeciwieństwie* do tradycyjnej strony internetowej, serwery Mastodona porozumiewają się ze sobą, pozwalając na wzajemną komunikację swoich użytkowników, tak jak możesz wysłać maila adresem GMaila do kogoś używającego Outlooka.
|
||||
|
||||
<figure>
|
||||
<img src="/decentralization.png" alt="" style="margin: 0; box-shadow: none">
|
||||
<figcaption><p>Od lewej do prawej: scentralizowana, sfederowana i dystrybuowana sieć</p></figcaption>
|
||||
</figure>
|
||||
|
||||
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 would be possible.
|
||||
|
||||
## The fediverse
|
||||
|
||||
Mastodon uses a standartized, 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 servers communicate with one another.
|
||||
|
||||
The **fediverse** ("federated universe") is the name for all servers that can communicate with each other. That includes all Mastodon servers, but also other implementations:
|
||||
|
||||
- Misskey
|
||||
- Pleroma
|
||||
- PeerTube
|
||||
- Plume
|
||||
- and many more
|
||||
|
||||
The fediverse does not have its own brand, so you will more often hear "follow me on Mastodon" than "follow me on the fediverse", but technically the latter is more correct.
|
||||
|
||||
## Practical implications
|
||||
### Addressing people
|
||||
|
||||
Mastodon usernames actually consist of two parts:
|
||||
|
||||
- The local username, e.g. `alice`
|
||||
- And the domain of the server, e.g. `example.com`
|
||||
|
||||
Just like an e-mail address. For convenience sake, Mastodon allows you to skip the second part when addressing people on the same server as you, but you have to keep in mind when sharing your username with other people, you need to include the domain or they won't be able to find you as easily.
|
||||
|
||||
|{{< no >}}|{{< yes >}}|
|
||||
|:--------:|:---------:|
|
||||
|I'm @alice on Mastodon!|I'm @alice@example.com on Mastodon!|
|
||||
|
||||
The search form in Mastodon will find people either with the above address form, or the link to the person's profile, so you can share that instead if you prefer.
|
||||
|
||||
### Following people
|
||||
|
||||
As long as you encounter a person within your app's user interface, e.g. the web interface on your home server, or your mobile app, you can just click "follow" and you won't notice a difference if that person is on your server or not.
|
||||
|
||||
However if you come across someone's public profile hosted on a different server, there's an obstacle: That server sees you as just another anonymous visitor.
|
||||
|
||||
So when you click "follow", a dialog will pop up asking you to enter your own full username (with the domain part, most importantly). This way, the dialog actually sends you back to your home server, where you are logged in and can really do stuff.
|
||||
|
||||
You will also notice that dialog when clicking on "reply", "boost" or "favourite" on public pages of other servers.
|
||||
|
||||
### Browsing content
|
||||
|
||||
To allow you to discover potentially interesting content, Mastodon provides a way to browse all public posts. Well, there is no global shared state between all servers, so there is no way to browse *all* public posts. When you browse the **federated timeline**, you see all public posts that the server you are on knows about. There are various ways your server may discover posts, but the bulk of them will be from people that other users on your server follow.
|
||||
|
||||
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.
|
||||
|
||||
### Funding and monetization
|
||||
|
||||
All Mastodon servers are operated by different people or organizations completely independently. Mastodon does not implement any monetization strategies in the software.
|
||||
|
||||
Some server operators choose to offer paid accounts, some server operators are companies who can utilize their existing infrastructure, and most server operators rely on crowdfunding from their users via Patreon and similar services. So if you want to support the server hosting your account, check if it offers a way to donate.
|
||||
|
||||
Mastodon development is likewise crowdfunded via Patreon. No venture capital is involved.
|
||||
|
||||
### Impersonation and verification
|
||||
|
||||
The same username *can* be registered on different servers, there is no way to claim all of them ahead of time. Just like with e-mail, you should not expect `alice@hotmail.com` to be the same person as `alice@gmail.com`.
|
||||
|
||||
Because Mastodon can be self-hosted, there is no better way to verify your identity than to host Mastodon on your own domain, which people already trust.
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,73 @@
|
|||
---
|
||||
title: Moderation
|
||||
description: Overview of moderation tools on Mastodon
|
||||
menu:
|
||||
docs:
|
||||
parent: usage
|
||||
weight: 4
|
||||
---
|
||||
## 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 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 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.
|
||||
|
||||
At this moment, silence does not affect federation. A locally silenced account is *not* silenced automatically on other servers.
|
||||
|
||||
This limitation is reversible, the account can be unsilenced at any time.
|
||||
|
||||
### Suspend
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
With this option active, no files from the server will be processed locally. That includes avatars, headers, emojis and media attachments.
|
||||
|
||||
### Silence
|
||||
|
||||
Applies a silence to all past and future accounts from the server.
|
||||
|
||||
### Suspend
|
||||
|
||||
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
|
||||
|
||||
There are a few baseline measures for preventing spam in Mastodon:
|
||||
|
||||
- Signing up requires confirming an e-mail address
|
||||
- Signing up is rate-limited by IP
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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`:
|
||||
|
||||
```bash
|
||||
# Install ipset
|
||||
sudo apt install ipset
|
||||
# Create blacklist named "spambots"
|
||||
sudo ipset create spambots nethash
|
||||
# Add 1.2.3.4 to the blacklist
|
||||
sudo ipset add spambots 1.2.3.4
|
||||
# Add firewall rule based on the blacklist
|
||||
sudo iptables -I INPUT 1 -m set --match-set spambots src -j DROP
|
||||
```
|
||||
|
||||
Be careful not to lock yourself out of your machine.
|
||||
|
|
@ -0,0 +1,75 @@
|
|||
---
|
||||
title: Privacy
|
||||
overview: Overview of privacy-related features on Mastodon and their implications
|
||||
menu:
|
||||
docs:
|
||||
parent: usage
|
||||
weight: 3
|
||||
---
|
||||
|
||||
## Publishing levels
|
||||
|
||||
|Level|Public timelines|Permalink|Profile view|Home feeds|
|
||||
|-----|:--------------:|:-------:|:----------:|:--------:|
|
||||
|Public|{{< yes >}}|{{< yes >}}|{{< yes >}}|{{< yes >}}|
|
||||
|Unlisted|{{< no >}}|{{< yes >}}|{{< yes >}}|{{< yes >}}|
|
||||
|Followers-only|{{< no >}}|{{< no >}}|{{< no >}}|{{< yes >}}|
|
||||
|Direct|{{< no >}}|{{< no >}}|{{< no >}}|{{< no >}}|
|
||||
|
||||
No matter which level, every mentioned user can see the message in their notifications.
|
||||
|
||||
**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.
|
||||
|
||||
## Account locking
|
||||
|
||||
To effectively publish private (followers-only) posts, you must lock your account--otherwise, anyone could follow you to view older posts. Locking your account on Mastodon does one thing: Adds an authorization step to the process of following you.
|
||||
|
||||
Once locked, before someone can become your follower, you will receive a follow request, which you can either accept or reject.
|
||||
|
||||
Please mind that post privacy on Mastodon is per-post, rather than account-wide, and as such there is no way to instantly make past public posts private.
|
||||
|
||||
## Blocking and muting
|
||||
### Hiding boosts
|
||||
|
||||
If you hide boosts from someone, you won't see their boosts in your home feed.
|
||||
|
||||
### Muting
|
||||
|
||||
When muting, you have the option to mute notifications from them or not. Muting without muting notifications hides the user from your view:
|
||||
|
||||
- You won't see the user in your home feed
|
||||
- You won't see other people boosting the user
|
||||
- You won't see other people mentioning the user
|
||||
- You won't see the user in public timelines
|
||||
|
||||
If you choose to also mute notifications from them, you will additionally not see notifications from that user.
|
||||
|
||||
The user has no way of knowing they have been muted.
|
||||
|
||||
### Blocking
|
||||
|
||||
Blocking hides a user from your view:
|
||||
|
||||
- You won't see the user in your home feed
|
||||
- You won't see other people boosting the user
|
||||
- You won't see other people mentioning the user
|
||||
- You won't see the user in public timelines
|
||||
- You won't see notifications from that user
|
||||
|
||||
Additionally, on the blocked user's side:
|
||||
|
||||
- The user is forced to unfollow you
|
||||
- The user cannot follow you
|
||||
- The user won't see other people's boosts of you
|
||||
- The user won't see you in public timelines
|
||||
|
||||
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
|
||||
|
||||
If you hide an entire server:
|
||||
|
||||
- You will not see posts from that server on the public timelines
|
||||
- You won't see other people's boosts of that server in your home feed
|
||||
- You won't see notifications from that server
|
||||
- You will lose any followers that you might have had on that server
|
||||
Loading…
Reference in New Issue