...
 
Commits (3)
......@@ -17,6 +17,36 @@ enableGitInfo = true
contentDir = "content/pl"
languageName = "Polski"
weight = 1
[languages.fr]
contentDir = "content/fr"
languageName = "Français"
weight = 1
[languages.fr.menu]
[[languages.fr.menu.docs]]
name = "Guide d'utilisation"
weight = 1
identifier = "usage"
url = "/usage/"
[[languages.fr.menu.docs]]
name = "Guide d'administration"
weight = 2
identifier = "administration"
url = "/administration/"
[[languages.fr.menu.docs]]
name = "Guide de développement"
weight = 3
identifier = "development"
url = "/development/"
[[languages.fr.menu.docs]]
name = "Aperçu de l'API"
weight = 4
identifier = "api"
url = "/api/"
[[languages.fr.menu.docs]]
name = "API REST"
weight = 5
identifier = "rest-api"
url = "/api/rest/"
[menu]
[[menu.docs]]
......
---
title: Documentation de Mastodon
---
Bienvenue dans la documentation de Mastodon !
<div style="margin-bottom: 26px">
{{< youtube "IPSbNdBmWKE" >}}
</div>
**Choisissez ce que vous voulez voir aujourd'hui :**
- [Apprendre à se servir de Mastodon]({{< relref "usage/basics.md" >}})
- [Apprendre à installer Mastodon]({{< relref "administration/installation.md" >}})
- [Apprendre à coder une application pour Mastodon]({{< relref "api/guidelines.md" >}})
---
title: Configuration
description: Vue d'ensemble des options de configuration de Mastodon
menu:
docs:
parent: administration
weight: 2
---
Mastodon utilise des variables d'environnement pour sa configuration.
Par commodité, Mastodon lit ces variables depuis un fichier texte nommé `.env.production` dans le dossier contenant Mastodon, mais elles peuvent toujours être outrepassées par un processus. Par exemple, les fichiers de service systemd peuvent lire des variables d'environnement depuis un `EnvironmentFile` ou des variables définies avec `Environment` dans le fichier de service directement, pour que vous puissiez avoir plusieurs configurations pour des services spécifiques. Ces variables peuvent aussi être définies quand Mastodon est exécuté depuis la ligne de commande.
## Basique
### Fédération
- `LOCAL_DOMAIN`
- `WEB_DOMAIN`
- `ALTERNATE_DOMAINS`
### Secrets
- `SECRET_KEY_BASE`
- `OTP_SECRET`
- `VAPID_PRIVATE_KEY`
- `VAPID_PUBLIC_KEY`
### Déploiement
- `RAILS_ENV`
- `RAILS_SERVE_STATIC_FILES`
- `RAILS_LOG_LEVEL`
- `TRUSTED_PROXY_IP`
- `SOCKET`
- `PORT`
- `NODE_ENV`
- `BIND`
### Options pour l'aménagement des ressources
- `WEB_CONCURRENCY`
- `MAX_THREADS`
- `PREPARED_STATEMENTS`
- `STREAMING_API_BASE_URL`
- `STREAMING_CLUSTER_NUM`
## Connexion aux bases de données
### 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`
## Limites
- `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`
## Stockage distant des fichiers
- `CDN_HOST`
- `S3_ALIAS_HOST`
### Stockage local des fichiers
- `PAPERCLIP_ROOT_PATH`
- `PAPERCLIP_ROOT_URL`
### Amazon S3 et compatibles
- `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`
## Authentification externe
- `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`
## Services cachés (Tor)
- `http_proxy`
- `ALLOW_ACCESS_TO_HIDDEN_SERVICE`
## Autres
- `SKIP_POST_DEPLOYMENT_MIGRATIONS`
This diff is collapsed.
---
title: Migration de serveur
description: Comment migrer une instance Mastodon sur un nouveau serveur
menu:
docs:
parent: administration
weight: 6
---
Parfois, pour des raisons diverses, vous avez besoin de migrer votre instance Mastodon d'un serveur à un autre. Heureusement, ce n'est pas une opération trop complexe, même si ça peut résulter en un petit temps où l'instance n'est pas utilisable.
**Note :** ce guide a été écrit avec l'utilisation d'Ubuntu Server en tête ; certaines opérations peuvent différer si vous utilisez un autre système d'exploitation.
Étapes basiques
----
1. Créez une nouvelle instance Mastodon en utilisant le [guide d'installation](/administration/installation/) (mais n'exécutez pas `mastodon:setup`).
2. Arrêtez Mastodon sur l'ancien serveur (par ex. `systemctl stop 'mastodon-*.service'`).
3. Sauvegardez et chargez la base de données PostgreSQL en suivant les instructions plus bas.
4. Copier les fichiers du dossier `system/` en suivant les instructions plus bas. (Note : si vous utilisez S3, vous pouvez passer cette étape.)
5. Copiez le fichier `.env.production`.
6. Exécutez `RAILS_ENV=production ./bin/tootctl feeds build` pour reconstruire les timelines personnelles de chaque utilisateur·ice.
7. Démarrez Mastodon sur le nouveau serveur.
8. Mettez à jour la zone DNS pour qu'elle pointe sur le nouveau serveur.
9. Mettez à jour ou copiez votre configuration Nginx, ré-exécutez LetsEncrypt si nécessaire.
10. Profitez de votre nouveau serveur !
Étapes détaillées
----
### Quelles données doivent être migrées
Prioritairement, vous devez copier ceci :
- Le dossier `~/live/public/system`, qui contient les photos et vidéos téléversées par les utilisateur·ice·s (si vous utilisez S3, vous n'avez pas à le faire)
- La base de données PostgreSQL (en utilisant [pg\_dump](https://www.postgresql.org/docs/9.1/static/backup-dump.html))
- Le fichier `~/live/.env.production`, qui contient la configuration de l'instance et ses variables secrètes
Moins important, vous voudrez probablement copier ces fichiers pour plus de commodité :
- La configuration nginx (sous `/etc/nginx/sites-available/default`)
- Les fichiers de services systemd (`/etc/systemd/system/mastodon-*.service`), qui peuvent contenir des modifications spécifiques à votre instance
- La configuration PgBouncer dans `/etc/pgbouncer` (si vous l'utilisez)
### Sauvegarder et charger PostgreSQL
Au lieu d'exécuter `mastodon:setup`, on va créer une base de données PostgreSQL vide
en utilisant la base de données `template0` (qui est utile quand on restaure une sauvegarde PostgreSQL,
[comme détaillé dans la documentation de pg\_dump](https://www.postgresql.org/docs/9.1/static/backup-dump.html#BACKUP-DUMP-RESTORE)).
Exécutez ceci en tant qu'utilisateur `mastodon` sur l'ancien serveur :
```bash
pg_dump -Fc mastodon_production -f backup.dump
```
Copiez le fichier `backup.dump` sur le nouveau serveur, en utilisant `rsync` ou `scp`. Puis, sur le nouveau serveur,
créez une base de données vide en tant qu'utilisateur `mastodon` :
```bash
createdb -T template0 mastodon_production
```
Et importez-la :
```bash
pg_restore -U mastodon -n public --no-owner --role=mastodon \
-d mastodon_production backup.dump
```
(Notez que si le nom d'utilisateur sur le nouveau serveur n'est pas `mastodon`, vous devriez changer les valeurs de
`-U` AND `--role` dans la commande juste au-dessus. C'est pas grave si le nom d'utilisateur est différent entre les deux serveurs.)
### Copier les fichiers
Cela va sûrement prendre du temps, et vous voudrez sûrement éviter de recopier des fichiers inutilement, utiliser `rsync` est donc recommandé.
Sur l'ancien serveur, en tant qu'utilisateur `mastodon`, faites :
```bash
rsync -avz ~/live/public/system/ mastodon@exemple.fr:~/live/public/system/
```
Vous répèterez l'opération si jamais les fichiers sur l'ancien serveur devaient changer.
Vous devriez copier le fichier `.env.production`, qui contient des secrets nécessaires à l'instance.
Optionnellement, vous pouvez copier les fichiers de configuration nginx, systemd, et pgbouncer, ou les réécrire de zéro.
### Durant la migration
Vous pouvez modifier le fichier `~/live/public/500.html` sur l'ancien serveur si vous voulez afficher un joli message d'erreur et permettre de faire savoir aux utilisateur·ice·s qu'une migration est en cours.
Vous voudrez probablement modifier le TTL DNS pour quelque chose de plus petit (30 à 60 minutes) un jour à l'avance, la propagation DNS se fera ainsi plus rapidement quand vous aurez indiqué la nouvelle adresse IP.
### Après la migration
Vous pouvez aller sur [whatsmydns.net](http://whatsmydns.net/) pour voir la progression de la propagation DNS.
Pour ne pas attendre, vous pouvez toujours modifier votre propre fichier `/etc/hosts` pour pointer vers votre nouveau serveur et donc commencer à vous amuser avec avant les autres.
---
title: Fonctionnalités facultatives
description: Comment activer les fonctionnalités facultatives de Mastodon
menu:
docs:
parent: administration
weight: 5
---
## Recherche plein-texte
Mastodon supporte la recherche plein-texte quand ElasticSearch est disponible. La recherche plein-texte permet aux utilisateur·ice·s connecté·e·s de chercher dans leurs propres pouets, favoris et mentions. Cependant, la recherche plein-texte empêche délibérément de chercher arbitrairement dans toute la base de données.
### Installer ElasticSearch
ElasticSearch requiert un environnement java. Si vous n'avez pas Java d'installé, faites-le maintenant. En supposant que vous êtes connecté en `root` :
apt install openjdk-8-jre-headless
Ajoutez le dépôt logiciel officiel d'ElasticSearch :
wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | apt-key add -
echo "deb https://artifacts.elastic.co/packages/6.x/apt stable main" | tee -a /etc/apt/sources.list.d/elastic-6.x.list
apt update
Vous pouvez désormais installer ElasticSearch:
apt install elasticsearch
> **Avertissement de sécurité :** Par défaut, ElasticSearch est supposé se connecter à localhost uniquement, c-à-d être inaccessible depuis le réseau. Vous pouvez vérifier à quelle adresse ElasticSearch se connecte en regardant `network.host` dans le fichier `/etc/elasticsearch/elasticsearch.yml`. Considérez le fait que quiconque pouvant accéder à ElasticSearch sera en mesure de lire et de modifier n'importe quelle donnée à l'intérieur, puisqu'il n'y a pas de système d'authentification. C'est donc très important d'assurer la sécurité de la connexion. Avoir un pare-feu qui n'autorise que les ports 22, 80, et 443 est conseillé, comme expliqué dans [les instructions d'installation]({{< relref "installation.md" >}}). Si vous avez une instance répartie sur plusieurs serveurs, vous devez savoir comment sécuriser son trafic interne.
Pour démarrer ElasticSearch:
systemctl enable elasticsearch
systemctl start elasticsearch
### Configurer Mastodon
Modifiez `.env.production` pour ajouter les variables suivantes :
```bash
ES_ENABLED=true
ES_HOST=localhost
ES_PORT=9200
```
Si vous avez plusieurs instances Mastodon sur la même machine et que vous prévoyez d'utiliser la même installation d'ElasticSearch pour chacune d'entre elles, assurez-vous que chaque instance a un `REDIS_NAMESPACE` unique dans leur fichier de configuration, afin de différencier les index. Si vous avez besoin de passer outre le préfixe d'un index ElasticSearch, vous pouvez directement définir `ES_PREFIX`.
Après avoir sauvegardé le nouveau fichier de configuration, créez l'index dans ElasticSearch avec :
RAILS_ENV=production bundle exec rake chewy:upgrade
Puis, redémarrez les processus Mastodon pour que la nouvelle configuration soit prise en compte :
systemctl restart mastodon-sidekiq
systemctl reload mastodon-web
Désormais, les nouveaux messages seront inscrits dans l'index ElasticSearch. La dernière étape est d'importer également toutes les anciennes données. Cela peut prendre du temps :
RAILS_ENV=production bundle exec rake chewy:sync
## Services cachés (Tor)
Mastodon peut être accédé via Tor à l'aide d'un service caché. Cela vous donnera une addresse .onion qui ne peut être utilisée qu'en se connectant au réseau Tor.
### Installer Tor
Tout d'abord, le dépôt logiciel de Tor pour Debian doit être ajouté à apt.
```
deb https://deb.torproject.org/torproject.org stretch main
deb-src https://deb.torproject.org/torproject.org stretch main
```
Puis, ajoutez la clé GPG.
```bash
curl https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc | gpg --import
```
Enfin, installez les paquets nécessaires.
```bash
apt install tor deb.torproject.org-keyring
```
### Configurer Tor
Modifiez le fichier `/etc/tor/torrc` et ajoutez la configuration suivante.
```bash
HiddenServiceDir /var/lib/tor/mastodon/
HiddenServiceVersion 3
HiddenServicePort 80 127.0.0.1:80
```
Redémarrez tor.
```bash
sudo service tor restart
```
Vous pouvez désormais récupérer votre adresse .onion dans le fichier `/var/lib/tor/mastodon/hostname`. Cela ne fonctionne _que_ si vous servez Mastodon à travers le port 80 et _que_ s'il s'agit du seul site que vous avez sur votre serveur.
### Configurer un serveur web multi-sites
Si vous avez plusieurs sites sur votre serveur web, vous devrez indiquer à votre serveur web comment servir l'adresse .onion. Dans le fichier de configuration du serveur web pour Mastodon, ajoutez une entrée additionnelle. Par exemple pour Nginx :
```bash
server {
server_name mastodon.myhosting.com qKnFwnNH2oH4QhQ7CoRf7HYj8wCwpDwsa8ohJmcPG9JodMZvVA6psKq7qKnFwnNH2oH4QhQ7CoRf7HYj8wCwpDwsa8ohJmcPG9JodMZvVA6psKq7.onion
}
```
### Servir le service caché Tor via HTTP
Même s'il est tentant de servir votre Mastodon "caché" via HTTPS, ce n'est pas une bonne idée. Lisez [cet article de blog](https://blog.torproject.org/facebook-hidden-services-and-https-certs) du Tor Project pour savoir pourquoi les certificats SSL ne changent rien ici. Puisque vous ne pouvez pas obtenir de certificat SSL pour un .onion, vous seriez submergé d'erreurs de certificat quand vous utiliseriez votre instance Mastodon.
La solution est de servir votre instance Mastodon via HTTP, mais uniquement pour Tor.
Prenez pour exemple cette configuration Nginx.
```
server {
listen 80;
server_name mastodon.myhosting.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl http2;
server_name mastodon.myhomsting.com;
}
```
Ajoutez une nouvelle entrée `server` qui recopie celle ayant SSL (sans pour autant recopier les lignes concernant SSL), mais qui définit l'utilisation du port 80 avec votre adresse .onion.
```
server {
listen 80;
server_name mastodon.myhosting.com;
return 301 https://$host$request_uri;
}
server {
listen 80;
server_name qKnFwnNH2oH4QhQ7CoRf7HYj8wCwpDwsa8ohJmcPG9JodMZvVA6psKq7qKnFwnNH2oH4QhQ7CoRf7HYj8wCwpDwsa8ohJmcPG9JodMZvVA6psKq7.onion;
}
server {
listen 443 ssl http2;
server_name mastodon.myhosting.com;
}
```
Redémarrez le serveur web.
```bash
service nginx restart
```
Vous pouvez également lire cette [réponse sur Server Fault](https://serverfault.com/a/373661) (en anglais) pour une solution plus [DRY](https://fr.wikipedia.org/wiki/Ne_vous_r%C3%A9p%C3%A9tez_pas).
## Connexion via LDAP/PAM/CAS/SAML
Bientôt.
---
title: Opérations post-installation
description: Que faire après que l'installation de Mastodon soit terminée
menu:
docs:
parent: administration
weight: 3
---
## Utiliser l'interface en ligne de commande
L'interface en ligne de commande de Mastodon réside dans un fichier exécutable nommé `tootctl`, dans le répertoire `bin`, à l'intérieur du dossier contenant Mastodon. Vous devez obligatoirement spécifier dans quel mode vous avez l'intention de l'invoquer, en spécifiant la variable d'environnement `RAILS_ENV`. Vous devez utiliser `RAILS_ENV=production`, sauf si vous êtes un·e développeur·euse qui travaillerait sur sa propre machine. Si vous êtes sûr·e que vous n'utiliserez pas d'autre mode que `production` (les autres étant `development`, `test`, ou `staging`), vous pouvez ajouter cette variable dans le fichier `.bashrc` pour plus de commodité :
```bash
echo "export RAILS_ENV=production" >> ~/.bashrc
```
Si vous faites ainsi, vous n'aurez pas à spécifier la variable à chaque fois. Sinon, les invocations de `tootctl` se passent généralement ainsi, en supposant que le code source de Mastodon réside dans `/home/mastodon/live` :
```bash
cd /home/mastodon/live
RAILS_ENV=production bin/tootctl help
```
## Créer un compte administrateur
### Dans le navigateur
Après avoir s'être inscrit·e depuis le navigateur, vous devrez user de la ligne de commande pour donner à votre compte fraîchement créé les privilèges administrateur. En supposant que votre nom d'utilisateur est `alice` :
```bash
RAILS_ENV=production bin/tootctl accounts modify alice --role admin
```
### Depuis la ligne de commande
Vous pouvez créer un nouveau compte à partir de la ligne de commande.
```bash
RAILS_ENV=production bin/tootctl accounts create \
alice \
--email alice@exemple.fr \
--confirmed \
--role admin
```
Un mot de passé généré aléatoirement s'affichera dans le terminal.
## Remplir les infos de l'instance
Après vous être connecté, allez dans les paramètres, sur la page **Paramètres du site**, dans l'onglet Administration. Bien que techniquement il n'y ait pas d'obligation de fournir d'informations, c'est une tâche considérée comme cruciale quand il s'agit d'une instance dédiée à recevoir du monde dessus.
|Paramètre|Signification|
|-------|-------|
|Nom d'utilisateur·ice|Votre nom d'utilisateur·ice pour que les gens sachent à qui appartient l'instance|
|Adresse courriel publique|Une adresse mail pour que les gens ne pouvant se connecter, ou les gens qui voudraient se créer un compte, puissent vous contacter|
|Description de l'instance|Pourquoi avez-vous créé cette instance ? À qui est-elle destinée ? Qu'est-ce qui la rend différente ? |
|Description étendue de l'instance|Vous pouvez mettre toutes sortes d'information dedans, mais mettre un **code de conduite** est recommandé. |
Une fois fini, appuyez sur "Enregistrer les modifications".
## Mettre en place des sauvegardes régulières (facultatif, mais pas vraiment non plus)
Pour toute utilisation en conditions réelles, vous devriez vous assurer de faire des sauvegardes régulières de votre instance Mastodon.
### Vue d'ensemble
Voici les choses qui doivent être sauvegardées par ordre d'importance :
1. La base de données PostgreSQL
2. Les secrets du fichier `.env.production` ou son équivalent
3. Les fichiers téléversés par les utilisateur·ice·s
4. La base de données Redis
### Types de défaillances
Il y a deux types de défaillances que les gens vont essayer d'éviter : la défaillance du matériel, comme la corruption des données sur le disque dur ; et l'erreur humaine et logicielle, comme une suppression involontaire des données. Dans cette documentation, on ne parlera que du premier type.
Une base de données PostgreSQL effacée ou perdue, et c'est le game over. Mastodon stocke toutes les données les plus importantes dans la base de données PostgreSQL. Si la base de données disparaît, tous les comptes, posts et abonné·e·s de votre instance disparaîtront avec.
Si vous perdez les secrets de configuration, certaines fonctionnalités de Mastodon cesseront de fonctionner, vos utilisateur·ice·s seront déconnectés, la double authentification (2FA) sera indisponible, les notifications push ne seront plus délivrées.
Si vous perdez les fichiers téléversés par les utilisateur·ice·s, vous perdrez les photos de profil, bannières et photos rattachés aux posts, mais Mastodon continuera de fonctionner.
Perdre la base de données Redis est presque inoffensif : les seules données irrécupérables seront le contenu des queues Sidekiq et les retentatives planifiées de tâches qui ont échouées. Les timelines personnelles et celles des listes sont stockées dans Redis, mais elles peuvent être refaites avec `tootctl`.
Les meilleures sauvegardes sont celles qui sont "hors-site", c-à-d des sauvegardes qui ne sont pas sur la même machine que celle où se trouve Mastodon. Si le serveur que vous utilisez prend feu et que le disque dur explose, les sauvegardes qui sont dessus ne seront pas d'une grande aide.
### Sauvegarder les secrets
Les secrets sont les plus simples à sauvegarder, puisqu'ils ne changent jamais. Vous n'avez qu'à sauvegarder `.env.production` dans un endroit sûr.
### Sauvegarder PostgreSQL
PostgreSQL encoure le risque d'avoir des données corrompues à cause d'une coupure de courant, un disque dur défectueux, et des schémas de migrations bâclés. Pour cette raison, faire une sauvegarde de temps en temps avec `pg_dump` ou `pg_dumpall` est recommandé.
Pour des configurations nécessitant une haute disponibilité, il est possible de répliquer la base de données afin d'avoir un deuxième serveur PostgreSQL avec des données constamment à jour, prêt à être utilisé si le premier est indisponible.
### Sauvegarder les fichiers téléversés par les utilisateur·ice·s
Si vous utilisez un fournisseur de stockage externe comme Amazon S3, Google Cloud ou Wasabi, vous n'avez pas besoin de vous inquiétez pour les sauvegardes. Ces entreprises sont responsables des défaillances matérielles.
Si vous stockez localement les fichiers, c'est à vous de faire des copies du volumineux dossier `public/system`, où les fichiers téléversés sont stockés par défaut.
### Sauvegarder Redis
Sauvegarder Redis est simple. Redis écrit régulièrement dans `/var/lib/redis/dump.rdb`, qui est le seul fichier que vous avez à récupérer.
This diff is collapsed.
---
title: Résolution de problèmes
description: Comment trouver ce qui ne va pas avec votre instance Mastodon
menu:
docs:
parent: administration
weight: 99
---
**Je vois une page d'erreur qui dit que quelque chose ne s'est pas bien passé. Comment je fais pour savoir ce qui ne va pas ?**
Tous les messages d'erreur avec des stack traces sont inscrits dans le log système. Si vous utilisez systemd, les logs de chaque service systemd peuvent être lus avec `journalctl -u mastodon-web` (remplacez avec le nom du service désiré). Si vous utilisez Docker, c'est à peu près pareil : `docker logs mastodon_web_1` (remplacez avec le nom du conteneur désiré).
Le détail des erreurs côté serveur n'est *jamais* donné au public, puisqu'il peut révéler comment votre instance est configurée et cela peut donner aux attaquants des indices pour s'infiltrer dans le système ou mieux en abuser.
Chaque réponse du serveur web Mastodon est accompagné d'un header avec un identifiant de requête unique, qui apparaît dans les logs. En inspectant les headers de la page d'erreur, vous pourrez facilement retrouver la stack trace correspondante dans les logs.
**Après avoir mis à jour vers une version supérieure, quelques pages s'affichent bizarrement. Pourquoi ?**
Vérifier que vous avez exécuté `RAILS_ENV=production bin/rails assets:precompile` après la mise à jour, et redémarré le processus web de Mastodon, puisqu'il semble que le processus envoie encore des feuilles de style et des scripts périmés. Il se peut aussi que la précompilation ait échouée à cause d'un manque de mémoire RAM, webpack prenant malheureusement beaucoup trop de mémoire. Si c'est le cas, assurez-vous d'avoir un espace swap de disponible. Sinon, il est possible de pré-compiler les ressources web sur une autre machine, et de les copier ensuite dans le dossier `public/packs`.
**Après avoir mis à jour vers une version supérieure, certaines requêtes échouent et les logs montrent des messages d'erreurs à propos de colonnes ou tables manquantes. Pourquoi ?**
Vérifiez que vous avez exécuté `RAILS_ENV=production bin/rails db:migrate` après la mise à jour, puisqu'il semble que votre Mastodon essaye d'accéder à un schéma de base de données plus ancien ou plus récent que prévu. Si vous utilisez PgBouncer, assurez-vous que cette commande le connecte directement à PostgreSQL, puisque PgBouncer ne supporte pas vraiment les verrouillages de tables qui sont utilisés lors des mises à jour.
**J'essaye d'exécuter une commande `tootctl` ou `rake`/`rails`, mais tout ce que j'obtiens est une erreur à propos de constantes non initialisées. Qu'est-ce qui ne va pas ?**
Vérifiez que vous avez mis `RAILS_ENV=production` avant le début de votre commande. Par défaut, Mastodon s'exécute dans un environnement supposé être de développement, donc il essaye de charger des gemmes Ruby liées au développement. Cependant, dans un environnement de production, on évite d'installer ces gems Ruby, et c'est de là que vient l'erreur.
---
title: Mettre à jour son instance
description: Comment mettre à jour Mastodon vers une version plus récente
menu:
docs:
parent: administration
weight: 5
---
Quand une nouvelle version de Mastodon est publiée, elle apparaît sur la [page des versions sur GitHub](https://github.com/tootsuite/mastodon/releases). Notez toutefois qu'exécuter du code de la branche `master` (et donc pas prêt pour le grand public) est dans la plupart des cas non recommandé.
Les versions de Mastodon correspondent aux étiquettes git. Tout d'abord, connectez-vous avec l'utilisateur `mastodon` :
```sh
su - mastodon
```
Allez à la racine du répertoire contenant Mastodon :
```sh
cd /home/mastodon/live
```
Téléchargez le code de la dernière version, en supposant ici que la dernière version se nomme `v2.5.0` :
```sh
git fetch --tags
git checkout v2.5.0
```
La page des versions contient une liste des modifications et nouveautés apportées par une version, et en dessous, les instructions pour réaliser la mise à jour (en anglais). Si la dernière version nécessite par exemple de recompiler les ressources web, vous exécuteriez cette commande :
```sh
RAILS_ENV=production bundle exec rails assets:precompile
```
Après avoir exécuté toutes les instructions spécifiques à la dernière version, il ne reste plus qu'à redémarrer Mastodon. *Habituellement*, l'API de streaming n'est pas mise à jour et ne nécessite pas de redémarrage. La redémarrer pourrait causer une charge inhabituellement haute sur le serveur, il est donc conseillé d'éviter de le faire le plus possible.
Déconnectez-vous pour retourner à l'utilisateur root :
```sh
exit
```
Vous devriez redémarrer Sidekiq :
```sh
systemctl restart mastodon-sidekiq
```
Et vous devriez recharger le processus web pour éviter une période d'indisponibilité de l'instance :
```sh
systemctl reload mastodon-web
```
**C'est tout !** Vous utilisez désormais la dernière version de Mastodon.
---
title: Authentication
description: How to authenticate with OAuth 2 on Mastodon
menu:
docs:
parent: api
weight: 1
---
Mastodon is federated, therefore you can't be expected to manually register your application on all potential servers your users might want to login on. For this reason, there is an open app registration API, so obtaining OAuth 2 credentials for OAuth 2 authorization can be automated.
Make sure that you allow your users to specify the domain they want to connect to before login. Use that domain to acquire a client id/secret for OAuth 2 and then proceed with normal OAuth 2 also using that domain to build the URLs.
Mastodon supports the following OAuth 2 flows:
- **Authorization code flow**: For end-users
- **Password grant flow**: For bots and other single-user applications
- **Client credentials flow**: For applications that do not act on behalf of users
## OAuth 2 endpoints
The following descriptions are taken from the [Doorkeeper documentation](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples). Mastodon uses Doorkeeper to implement OAuth 2.
### GET /oauth/authorize
Redirect here with `response_type=code`, `client_id`, `client_secret`, `redirect_uri`, `scope`. Displays an authorization form to the user. If approved, it will create and return an authorization code, then redirect to the desired `redirect_uri`, or show the authorization code if `urn:ietf:wg:oauth:2.0:oob` was requested.
### POST /oauth/token
Post here with `authorization_code` for authorization code grant type or `username` and `password` for password grant type. Returns an access token. This corresponds to the token endpoint, section 3.2 of the OAuth 2 RFC.
### POST /oauth/revoke
Post here with client credentials (in basic auth or in params `client_id` and `client_secret`) to revoke an access token. This corresponds to the token endpoint, using the OAuth 2.0 Token Revocation RFC (RFC 7009).
## Example authorization code flow
1. Get `client_id` and `client_secret` from your local cache. If you don't have the two, you need to [register the application]({{< relref "api/rest/apps.md#post-api-v1-apps" >}}). Store `client_id` and `client_secret` in your local cache for next time. We actually don't need the `id` returned from this call.
1. Tell the user to visit `/oauth/authorize` with parameters `scope`, `response_type=code`, `redirect_uri`, and your `client_id`. The user clicks on the URL and gets shown a page asking them to authorize your app for the scopes you requested. If the user clicks on the right button, they are redirected back to your `redirect_uri` with a `code` param in the query string. That is the authorization code.
1. Send a POST request to `/oauth/token` with the parameters `client_id`, `client_secret`, `grant_type=authorization_code`, `code`, `redirect_uri`. Save the `access_token` you get back in your local cache. Note that an authorization code can only be used once. If it has been used already, you need to repeat step two to get a new one.
Once you have the access token, add the HTTP header `Authorization: Bearer ...` to any API call.
## Common gotchas
- The OAuth param name is `scope`, but when registering the application using Mastodon's REST API, the param name is `scopes`. The OAuth param can be a subset of the scopes you registered initially, but cannot include anything that wasn't in the original set.
- The OAuth param name is `redirect_uri`, but when registering the application using Mastodon's REST API, the param name is `redirect_uris`. The latter can actually consist of multiple allowed URIs, separated by newlines.
- The `redirect_uri` in all OAuth requests must either be the same as the one registered with the application, or one of them, if you registered multiple URIs separated by newlines with the application.
\ No newline at end of file
This diff is collapsed.
---
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.
---
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)
---
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.
---
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.
---
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" >}}).
---
title: Accounts
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/accounts/:id
Returns [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="No" user="No" scope="read read:accounts" version="0.0.0" >}}
## POST /api/v1/accounts
Returns [Token]({{< relref "entities.md#token" >}})
The method is available to apps with a token obtained via the client credentials grant. It creates a user and account records, as well as an access token for the app that initiated the request. The user is unconfirmed, and an e-mail is sent as usual.
The method returns the access token, which the app should save for later. The REST API is not available to users with unconfirmed accounts, so the app must be smart to wait for the user to click a link in their e-mail inbox.
The method is rate-limited by IP to 5 requests per 30 minutes.
### Resource information
{{< api_method_info auth="Yes" user="No" scope="write write:accounts" version="2.7.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `username` | User name | Required |
| `email` | E-mail address | Required |
| `password` | Password text | Required |
| `agreement` | Agreement to local rules, terms of use, privacy policy (Bool) | Required |
| `locale` | The language of the e-mail to be sent first | Required |
The `agreement` parameter must be set to true after presenting the local rules, terms of use, privacy policy for the user and obtaining consent.
## GET /api/v1/accounts/verify_credentials
User's own account.
Returns [Account]({{< relref "entities.md#account" >}}) with an extra [`source` attribute]({{< relref "entities.md#source" >}}).
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:accounts" version="0.0.0" >}}
## PATCH /api/v1/accounts/update_credentials
Update user's own account.
Returns [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="0.0.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `display_name` | Display name | Optional |
| `note` | Biography | Optional |
| `avatar` | Avatar encoded using `multipart/form-data` | Optional |
| `header` | Header image encoded using `multipart/form-data` | Optional |
| `locked` | Enable follow requests | Optional |
| `source[privacy]` | Default post privacy preference | Optional |
| `source[sensitive]`| Whether to mark statuses as sensitive by default | Optional |
| `source[language]` | Override language on statuses by default (ISO6391) | Optional |
| `fields_attributes` | Profile metadata (max. 4) | Optional |
## GET /api/v1/accounts/:id/followers
Accounts which follow the given account.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="No" scope="read read:accounts" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 40 |
### Pagination
{{< api_pagination >}}
## GET /api/v1/accounts/:id/following
Accounts which the given account is following.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="No" scope="read read:accounts" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 40 |
### Pagination
{{< api_pagination >}}
## GET /api/v1/accounts/:id/statuses
An account's statuses.
Returns array of [Status]({{< relref "entities.md#status" >}})
### Resource information
{{< api_method_info auth="Yes" user="No" scope="read read:statuses" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|Added in|
|----|-----------|:------:|:-----:|:------:|
| `only_media` | Only return statuses that have media attachments | Optional | false | |
| `pinned` | Only return statuses that have been pinned | Optional | false | |
| `exclude_replies` | Skip statuses that reply to other statuses | Optional | false | |
| `max_id` | Return results older than ID | Optional | | |
| `since_id` | Return results newer than ID | Optional | | |
| `min_id` | Return results immediately newer than ID | Optional | | |
| `limit` | Maximum number of results | Optional | 20 | | |
| `exclude_reblogs` | Skip statuses that are reblogs of other statuses | Optional | false | 2.7.0 |
### Pagination
{{< api_dynamic_pagination >}}
## POST /api/v1/accounts/:id/follow
Follow an account.
Returns [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write:follows follow" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `reblogs` | Whether the followed account's reblogs will show up in the home timeline | Optional | true |
## POST /api/v1/accounts/:id/unfollow
Unfollow an account.
Returns [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write:follows follow" version="0.0.0" >}}
## GET /api/v1/accounts/relationships
Relationship of the user to the given accounts in regards to following, blocking, muting, etc.
Returns array of [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:follows" version="0.0.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `id` | Array of account IDs | Required |
## GET /api/v1/accounts/search
Search for matching accounts by username, domain and display name.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:accounts" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `q` | What to search for | Required ||
| `limit` | Maximum number of results | Optional | 40 |
| `resolve` | Attempt WebFinger look-up | Optional | false |
| `following` | Only who the user is following | Optional | false |
---
title: Apps
menu:
docs:
parent: rest-api
weight: 10
---
## POST /api/v1/apps
Create a new application to obtain OAuth2 credentials.
Returns [App]({{< relref "entities.md#app" >}}) with `client_id` and `client_secret`
### Resource information
{{< api_method_info auth="No" user="No" version="0.0.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `client_name` | Name of your application | Required |
| `redirect_uris` | Where the user should be redirected after authorization | Required |
| `scopes` | Space separated list of [scopes]({{< relref "permissions.md" >}}) | Required |
| `website` | URL to the homepage of your app | Optional |
> To display the authorization code to the end-user instead of redirecting to a web page, use `urn:ietf:wg:oauth:2.0:oob` in `redirect_uris`
## GET /api/v1/apps/verify_credentials
Confirm that the app's OAuth2 credentials work.
Returns [App]({{< relref "entities.md#app" >}})
### Resource information
{{< api_method_info auth="Yes" user="No" version="2.0.0" >}}
---
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" >}}
---
title: Custom emoji
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/custom_emojis
Custom emojis that are available on the server.
Returns array of [Emoji]({{< relref "entities.md#emoji" >}})
### Resource information
{{< api_method_info auth="No" user="No" version="2.0.0" >}}
---
title: Domain blocks
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/domain_blocks
Domains the user has blocked.
Returns array of string.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:blocks follow" version="1.4.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 40 |
### Pagination
{{< api_pagination >}}
## POST /api/v1/domain_blocks
Block a domain to hide all public posts from it, all notifications from it, and remove all followers from it.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:blocks follow" version="1.4.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `domain` | Domain to block| Required |
## DELETE /api/v1/domain_blocks
Remove a domain block.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:blocks follow" version="1.4.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `domain` | Domain to unblock| Required |
---
title: Endorsements
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/endorsements
Accounts the user chose to endorse.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:account" version="2.5.0" >}}
### Pagination
{{< api_pagination >}}
## POST /api/v1/accounts/:id/pin
Endorse an account, i.e. choose to feature the account on the user's public profile.
Returns [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="2.5.0" >}}
## POST /api/v1/accounts/:id/unpin
Undo endorse of an account.
Returns [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="2.5.0" >}}
---
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" >}})
---
title: Filters
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/filters
Text filters the user has configured that potentially must be applied client-side.
Returns array of [Filter]({{< relref "entities.md#filter" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:filters" version="2.4.3" >}}
## POST /api/v1/filters
Create a new filter.
Returns [Filter]({{< relref "entities.md#filter" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:filters" version="2.4.3" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `phrase` | Keyword or phrase to filter | Required |
| `context` | Array of strings that means filtering context. Each string is one of `home`, `notifications`, `public`, `thread`. At least one context must be specified. | Required |
| `irreversible` | Irreversible filtering will only work in `home` and `notifications` contexts by fully dropping the records. Otherwise, filtering is up to the client. | Optional |
| `whole_word` | Whether to consider word boundaries when matching | Optional |
| `expires_in` | Number that indicates seconds. Filter will be expire in seconds after API processed. Leave blank for no expiration | Optional |
## GET /api/v1/filters/:id
A text filter.
Returns [Filter]({{< relref "entities.md#filter" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:filters" version="2.4.3" >}}
## PUT /api/v1/filters/:id
Update a text filter.
Returns [Filter]({{< relref "entities.md#filter" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:filters" version="2.4.3" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `phrase` | Keyword or phrase to filter | Required |
| `context` | Array of strings that means filtering context. Each string is one of `home`, `notifications`, `public`, `thread`. At least one context must be specified. | Required |
| `irreversible` | Irreversible filtering will only work in `home` and `notifications` contexts by fully dropping the records. Otherwise, filtering is up to the client. | Optional |
| `whole_word` | Whether to consider word boundaries when matching | Optional |
| `expires_in` | Number that indicates seconds. Filter will be expire in seconds after API processed. Leave blank to not change | Optional |
## DELETE /api/v1/filters/:id
Delete a text filter.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:filters" version="2.4.3" >}}
---
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" >}}
---
title: Follow suggestions
menu:
docs:
parent: rest-api
weight: 10
---