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

Merge branch 'master' into email_config_environment_improvement

This commit is contained in:
Andy Piper 2023-11-29 16:59:37 +00:00 committed by GitHub
parent d1bab74814 cb67b8c65e
commit ef982c6af4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
309 changed files with 91149 additions and 12388 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
.github/workflows/deploy.yml vendored Normal file
View File

@ -0,0 +1,64 @@
name: Deploy on Github Pages
on:
push:
branches:
- master
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow one concurrent deployment
concurrency:
group: "pages"
cancel-in-progress: true
# Default to bash
defaults:
run:
shell: bash
jobs:
build:
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v3
with:
submodules: true # Fetch Hugo themes (true OR recursive)
fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
- name: Setup Pages
id: pages
uses: actions/configure-pages@v2
- name: Setup Hugo
uses: peaceiris/actions-hugo@v2
with:
hugo-version: "0.105.0"
extended: true
- name: Build
run: hugo --minify --baseURL "${{ steps.pages.outputs.base_url }}/"
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
path: ./public
# Deployment job
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v1

31
.github/workflows/publish.yml vendored
View File

@ -1,31 +0,0 @@
name: Pages
on:
push:
branches:
- master
jobs:
build-deploy:
runs-on: ubuntu-18.04
steps:
- uses: actions/checkout@v1
- name: Setup Hugo
uses: peaceiris/actions-hugo@v2
with:
hugo-version: '0.62.1'
extended: true
- name: Build
run: hugo --minify
- name: Deploy
uses: easingthemes/ssh-deploy@v2.0.7
env:
SSH_PRIVATE_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
ARGS: "-rltgoDzvO"
SOURCE: ./public/
REMOTE_HOST: ${{ secrets.REMOTE_HOST }}
REMOTE_USER: ${{ secrets.REMOTE_USER }}
TARGET: ${{ secrets.REMOTE_TARGET }}

27
.github/workflows/rebase-needed.yml vendored Normal file
View File

@ -0,0 +1,27 @@
name: PR Needs Rebase
on:
schedule:
- cron: '0 * * * *'
permissions:
pull-requests: write
jobs:
label-rebase-needed:
runs-on: ubuntu-latest
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
steps:
- name: Check for merge conflicts
uses: eps1lon/actions-label-merge-conflict@releases/2.x
with:
dirtyLabel: 'rebase needed :construction:'
repoToken: '${{ secrets.GITHUB_TOKEN }}'
commentOnClean: This pull request has resolved merge conflicts and is ready for review.
commentOnDirty: This pull request has merge conflicts that must be resolved before it can be merged.
retryMax: 30
continueOnMissingPermissions: false

2
.gitignore vendored
View File

@ -1,3 +1,5 @@
public/
static/.sass-cache
resources/
.hugo_build.lock
.vercel

9
README.md
View File

@ -1,4 +1,9 @@
![Mastodon](https://i.imgur.com/NhZc40l.png)
====
<h1><picture>
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/mastodon/mastodon/raw/main/lib/assets/wordmark.dark.png?raw=true">
<source media="(prefers-color-scheme: light)" srcset="https://github.com/mastodon/mastodon/raw/main/lib/assets/wordmark.light.png?raw=true">
<img alt="Mastodon" src="https://github.com/mastodon/mastodon/raw/mainlib/assets/wordmark.light.png?raw=true" height="34">
</picture></h1>
The documentation currently uses Hugo to generate a static site from Markdown.
View the documentation at <https://docs.joinmastodon.org>

31
archetypes/entities.md Normal file
View File

@ -0,0 +1,31 @@
---
title: "{{ replace .Name "-" " " | title }}"
description:
menu:
docs:
parent: entities
aliases: [
"/api/entities/SOMETHING",
"/api/entities/something",
]
---
## Example
```json
```
## Attributes
### `id` {#id}
**Description:** The ID of the SOMETHING in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
x.x.x - added
## See also
{{< page-relref ref="methods/SOMETHING#anchor" caption="POST /api/v1/something/" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/SOMETHING_serializer.rb" caption="app/serializers/rest/SOMETHING_serializer.rb" >}}

127
archetypes/methods.md Normal file
View File

@ -0,0 +1,127 @@
---
title: "{{ replace .Name "-" " " | title }}"
description:
menu:
docs:
parent: methods
aliases: [
"/api/methods/SOMETHING",
"/api/methods/something",
]
---
## What the method does {#anchor}
```http
GET /api/v1/example HTTP/1.1
```
**Returns:** [SOMETHING]({{< relref "entities/SOMETHING" >}})\
**OAuth:** User token + `oauth:scope`\
**Permissions:** Manage ???\
**Version history:**\
x.x.x - added
#### Request
##### Path parameters
:id
: {{<required>}} String. The ID of the SOMETHING in the database.
##### Headers
Authorization
: {{<required>}} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
##### Query parameters
**Internal parameter.** Use HTTP `Link` header for pagination.
max_id
: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
since_id
: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
min_id
: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
limit
: Integer. Maximum number of results to return. Defaults to 20 statuses or 40 accounts. Max twice the default limit.
##### Form data parameters
#### Response
##### 200: OK
```json
```
Because SOMETHING IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link: <https://mastodon.example/api/v1/SOMETHING?max_id=441449>; rel="next", <https://mastodon.example/api/v1/SOMETHING?since_id=444808>; rel="prev"
```
##### 401: Unauthorized
Invalid or missing Authorization header.
```json
{
"error": "The access token is invalid"
}
```
##### 403: Forbidden
Authorized user is missing a permission, or invalid or missing Authorization header
```json
{
"error": "This action is not allowed"
}
```
##### 404: Not found
SOMETHING is not owned by you or does not exist
```json
{
"error": "Record not found"
}
```
##### 410: Gone
##### 422: Unprocessable entity
##### 429: Rate limited
```json
{
"error": "Too many requests"
}
```
##### 503: Service unavailable
```json
{
"error": "There was a temporary problem serving your request, please try again"
}
```
---
## See also
{{< page-relref ref="methods/SOMETHING#anchor" caption="POST /api/v1/something/" >}}
{{< page-ref page="client/authorized" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/SOMETHING_controller.rb" caption="app/controllers/api/v1/SOMETHING_controller.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/SOMETHING" caption="app/controllers/api/v1/SOMETHING/" >}}

4
assets/fontawesome.scss vendored
View File

File diff suppressed because one or more lines are too long

12
assets/roboto-mono.scss Normal file
View File

@ -0,0 +1,12 @@
@font-face {
font-family: 'Roboto Mono';
src:
local('Roboto Mono'),
url('./webfonts/roboto-mono/robotomono-regular-webfont.woff2') format('woff2'),
url('./webfonts/roboto-mono/robotomono-regular-webfont.woff') format('woff'),
url('./webfonts/roboto-mono/robotomono-regular-webfont.ttf') format('truetype'),
url('./webfonts/roboto-mono/robotomono-regular-webfont.svg#roboto_monoregular') format('svg');
font-weight: 400;
font-display: swap;
font-style: normal;
}

51
assets/roboto.scss Normal file
View File

@ -0,0 +1,51 @@
@font-face {
font-family: 'Roboto';
src:
local('Roboto Italic'),
url('./webfonts/roboto/roboto-italic-webfont.woff2') format('woff2'),
url('./webfonts/roboto/roboto-italic-webfont.woff') format('woff'),
url('./webfonts/roboto/roboto-italic-webfont.ttf') format('truetype'),
url('./webfonts/roboto/roboto-italic-webfont.svg#roboto-italic-webfont') format('svg');
font-weight: normal;
font-display: swap;
font-style: italic;
}
@font-face {
font-family: 'Roboto';
src:
local('Roboto Bold'),
url('./webfonts/roboto/roboto-bold-webfont.woff2') format('woff2'),
url('./webfonts/roboto/roboto-bold-webfont.woff') format('woff'),
url('./webfonts/roboto/roboto-bold-webfont.ttf') format('truetype'),
url('./webfonts/roboto/roboto-bold-webfont.svg#roboto-bold-webfont') format('svg');
font-weight: bold;
font-display: swap;
font-style: normal;
}
@font-face {
font-family: 'Roboto';
src:
local('Roboto Medium'),
url('./webfonts/roboto/roboto-medium-webfont.woff2') format('woff2'),
url('./webfonts/roboto/roboto-medium-webfont.woff') format('woff'),
url('./webfonts/roboto/roboto-medium-webfont.ttf') format('truetype'),
url('./webfonts/roboto/roboto-medium-webfont.svg#roboto-medium-webfont') format('svg');
font-weight: 500;
font-display: swap;
font-style: normal;
}
@font-face {
font-family: 'Roboto';
src:
local('Roboto'),
url('./webfonts/roboto/roboto-regular-webfont.woff2') format('woff2'),
url('./webfonts/roboto/roboto-regular-webfont.woff') format('woff'),
url('./webfonts/roboto/roboto-regular-webfont.ttf') format('truetype'),
url('./webfonts/roboto/roboto-regular-webfont.svg#roboto-regular-webfont') format('svg');
font-weight: normal;
font-display: swap;
font-style: normal;
}

34
assets/style.scss
View File

@ -1,5 +1,6 @@
@import url('https://fonts.googleapis.com/css?family=Roboto:400,500,700|Roboto+Mono:400');
@import 'fontawesome.scss';
@import 'roboto.scss';
@import 'roboto-mono.scss';
$white: #fff ; // color5
$lightest: #d9e1e8; // color2
@ -444,6 +445,26 @@ main {
padding: 0;
}
dl {
color: $lightest;
font-size: 16px;
line-height: 28px;
font-weight: normal;
margin-bottom: 26px;
hyphens: auto;
dt {
font-weight: 700;
background: lighten($darkest, 8%);
padding: 2px 16px;
max-width: max-content;
margin-bottom: 4px;
}
dd {
margin-left: 16px;
margin-bottom: 16px;
}
}
.mastodon-embed,
iframe {
width: 100%;
@ -809,3 +830,14 @@ main {
padding: 20px;
}
}
.heading {
display: flex;
align-items: center;
&__anchor-link {
display: inline-flex;
align-content: center;
margin-left: 0.25em;
}
}

7
config.toml
View File

@ -1,4 +1,4 @@
baseURL = "http://docs.joinmastodon.org/"
baseURL = "https://docs.joinmastodon.org/"
languageCode = "en-us"
defaultContentLanguage = "en"
title = "Mastodon documentation"
@ -7,12 +7,15 @@ pygmentsStyle = "dracula"
metaDataFormat = "yaml"
paginate = 100
enableGitInfo = true
disablePathToLower = true
[markup]
[markup.tableOfContents]
endLevel = 2
endLevel = 3
ordered = false
startLevel = 1
[markup.goldmark.renderer]
unsafe = true
[languages.en.menu]
[[languages.en.menu.docs]]

21
content/en/_index.md
View File

@ -6,8 +6,6 @@ menu:
weight: -99
---
{{< youtube id="IPSbNdBmWKE" caption="An introductory video explaining basic Mastodon concepts with visual animations" >}}
## What is a microblog? {#microblogging}
Similar to how blogging is the act of publishing updates to a website, **microblogging** is the act of publishing small updates to a stream of updates on your profile. You can publish text posts and optionally attach media such as pictures, audio, video, or polls. Mastodon lets you follow friends and discover new ones.
@ -24,7 +22,7 @@ Similar to how blogging is the act of publishing updates to a website, **microbl
A Mastodon website can operate alone. Just like a traditional website, people sign up on it, post messages, upload pictures and talk to each other. _Unlike_ a traditional website, Mastodon websites can interoperate, letting their users communicate with each other; just like you can send an email from your Gmail account to someone from Outlook, Fastmail, Protonmail, or any other email provider, as long as you know their email address, **you can mention or message anyone on any website using their address**.
{{< figure src="/assets/network-models.jpg" caption="From left to right: Centralized, Federated, Distributed" >}}
{{< figure src="assets/network-models.jpg" caption="From left to right: Centralized, Federated, Distributed" >}}
@ -32,7 +30,7 @@ A Mastodon website can operate alone. Just like a traditional website, people si
Mastodon uses a standardized, open protocol to implement federation. It is called **ActivityPub**. Any software that likewise implements federation via ActivityPub can seamlessly communicate with Mastodon, just like Mastodon websites communicate with one another.
The **fediverse** \(“federated universe”\) is the name for all websites that can communicate with each other over ActivityPub and the World Wide Web. That includes all Mastodon servers, but also other implementations:
The **fediverse** (“federated universe”) is the name for all websites that can communicate with each other over ActivityPub and the World Wide Web. That includes all Mastodon servers, but also other implementations:
* Pleroma, a modular microblogging engine,
* Pixelfed, federated image sharing platform, which lets you share and consume media posts,
@ -47,13 +45,13 @@ The fediverse does not have its own brand, so you might more often hear “follo
### Choice of service provider and policy {#choice}
Because Mastodon is simply software that can be used to power any website, potential users of Mastodon have the option of choosing a service provider from already-existing Mastodon websites, or to create their own Mastodon website if they wish. The Mastodon project maintains a list of recommended service providers at [joinmastodon.org](https://joinmastodon.org), sortable by category and/or language. Some websites may have moderation policies that go beyond this, such as requiring the use of certain tags on potentially sensitive content, and some websites may have more relaxed moderation policies, but websites listed in the picker all agree to adopt the [Mastodon Server Covenant](https://joinmastodon.org/covenant), meaning that they pledge to actively moderate against hate speech, to take daily backups, to have at least one emergency admin, and to provide at least 3 months advance notice in case of shutdown.
Because Mastodon is just software that can be used to power any website, potential users of Mastodon have the option of choosing a service provider from already-existing Mastodon websites, or to create their own Mastodon website if they wish. The Mastodon project maintains a list of recommended service providers at [joinmastodon.org](https://joinmastodon.org), sortable by category and/or language. Some websites may have moderation policies that go beyond this, such as requiring the use of certain tags on potentially sensitive content, and some websites may have more relaxed moderation policies, but websites listed in the picker all agree to adopt the [Mastodon Server Covenant](https://joinmastodon.org/covenant), meaning that they pledge to actively moderate against hate speech, to take daily backups, to have at least one emergency admin, and to provide at least 3 months advance notice in case of shutdown.
> Maintaining communities that feel safe for all of its members is not easy. Mastodon provides a lot of foundational framework and tools for doing it, and shifts the power to effect change from one commercial entity to the communities themselves.
>
> -- Eugen Rochko, Jul 6 2018, ["Cage the Mastodon"](https://blog.joinmastodon.org/2018/07/cage-the-mastodon/)
> A centralized social media platform has a hierarchical structure where rules and their enforcement, as well as the development and direction of the platform, are decided by the CEO \[...\] A decentralized network deliberately relinquishes control of the platform owner, by essentially not having one.
> A centralized social media platform has a hierarchical structure where rules and their enforcement, as well as the development and direction of the platform, are decided by the CEO [...] A decentralized network deliberately relinquishes control of the platform owner, by essentially not having one.
>
> -- Eugen Rochko, Dec 30 2018, ["Why does decentralization matter?"](https://blog.joinmastodon.org/2018/12/why-does-decentralization-matter/)
@ -93,19 +91,16 @@ Unlike proprietary services, **anyone has the complete freedom to run, examine,
Learn how to use Mastodon:
{{< page-ref page="user/signup.md" >}}
{{< page-ref page="user/signup" >}}
Learn how to install Mastodon:
{{< page-ref page="admin/prerequisites.md" >}}
{{< page-ref page="admin/prerequisites" >}}
Learn how to write an app for Mastodon:
{{< page-ref page="client/intro.md" >}}
{{< page-ref page="client/intro" >}}
Learn about the Mastodon backend and how to contribute:
{{< page-ref page="dev/overview.md" >}}
{{< page-ref page="dev/overview" >}}

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

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

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

File diff suppressed because it is too large Load Diff

229
content/en/admin/elasticsearch.md Normal file
View File

@ -0,0 +1,229 @@
---
title: Configuring full-text search
description: Setting up Elasticsearch to search for statuses (authored, favourited, or mentioned), public indexable status, and accounts
aliases:
- /admin/optional/elasticsearch
menu:
docs:
weight: 40
parent: admin
---
Mastodon supports full-text search when Elasticsearch is available. It is strongly recommended to configure this feature.
Mastodon’s full-text search allows logged in users to find results from:
- public statuses from account that opted into appearing in search results
- their own statuses
- their mentions
- their favourites
- their bookmarks
- accounts (display name, usernames and bios)
It deliberately does not allow searching for arbitrary strings in the entire database.
## Installing Elasticsearch {#install}
{{< hint style="info" >}}
Mastodon is tested with Elasticsearch version 7. It should support OpenSearch, as well as Elasticsearch versions 6 and 8, but those setups are not officially supported.
{{< /hint >}}
Elasticsearch requires a Java runtime. If you don’t have Java already installed, do it now. Assuming you are logged in as `root`:
```bash
apt install openjdk-17-jre-headless
```
Add the official Elasticsearch repository to apt:
```bash
wget -O /usr/share/keyrings/elasticsearch.asc https://artifacts.elastic.co/GPG-KEY-elasticsearch
echo "deb [signed-by=/usr/share/keyrings/elasticsearch.asc] https://artifacts.elastic.co/packages/7.x/apt stable main" > /etc/apt/sources.list.d/elastic-7.x.list
```
Now you can install Elasticsearch:
```bash
apt update
apt install elasticsearch
```
{{< hint style="warning" >}}
**Security warning:** By default, Elasticsearch is supposed to bind to localhost only, i.e. be inaccessible from the outside network. You can check which address Elasticsearch binds to by looking at `network.host` within `/etc/elasticsearch/elasticsearch.yml`. Consider that anyone who can access Elasticsearch can access and modify any data within it, as there is no authentication layer. So it’s really important that the access is secured. Having a firewall that only exposes the 22, 80 and 443 ports is advisable, as outlined in the [main installation instructions](../../prerequisites/#install-a-firewall-and-only-whitelist-ssh-http-and-https-ports). If you have a multi-host setup, you must know how to secure internal traffic.
{{< /hint >}}
To start Elasticsearch:
```bash
systemctl daemon-reload
systemctl enable --now elasticsearch
```
## Configuring Mastodon {#config}
Edit `.env.production` to add the following variables:
```bash
ES_ENABLED=true
ES_HOST=localhost
ES_PORT=9200
ES_PRESET= # single_node_cluster, small_cluster or large_cluster
# ES_USER=
# ES_PASS=
```
### Choosing the correct preset
The value for `ES_PRESET` depends on the size of your Elasticsearch and will be used to set the number of shards and replica for your indices to the best value for your setup:
- `single_node_cluster` if you only have one node in your Elasticsearch cluster. Indices will be configured without any replica
- `small_cluster` if you have less than 6 nodes in your cluster. Indices will be configured with 1 replica
- `large_cluster` if you have 6 or more nodes in your cluster. Indices will be configured with more shards than with the `small_cluster` setting, to allow them to be distributed over more nodes
If you have multiple Mastodon servers on the same machine, and you are planning to use the same Elasticsearch installation for all of them, make sure that all of them have unique `REDIS_NAMESPACE` in their configurations, to differentiate the indices. If you need to override the prefix of the Elasticsearch indices, you can set `ES_PREFIX` directly.
### Security
By default, Elasticsearch does not handle any authentication and every request is made with full admin permission. We strongly advise you to configure Elasticsearch security features on your cluster.
To configure it, please refer [to the official documentation](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/security-minimal-setup.html). It will guide you through:
- Enabling the security features (`xpack.security.enabled: true`)
- Creating password for built-in users
Once done, you can create a custom role for Mastodon to connect.
For example (please adapt this snippet to use your Elastic admin password):
```sh
curl -X POST -u elastic:admin_password "localhost:9200/_security/role/mastodon_full_access?pretty" -H 'Content-Type: application/json' -d'
{
"cluster": ["monitor"],
"indices": [{
"names": ["*"],
"privileges": ["read", "monitor", "write", "manage"]
}]
}
'
```
[Elasticsearch documentation for role creation](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/security-api-put-role.html)
Once the role is created, you can create a user for the Mastodon server to use, and assign it the role.
For example (please adapt this snippet to use your Elastic admin password, and customize your new user `mastodon` user password):
```sh
curl -X POST -u elastic:admin_password "localhost:9200/_security/user/mastodon?pretty" -H 'Content-Type: application/json' -d'
{
"password" : "l0ng-r4nd0m-p@ssw0rd",
"roles" : ["mastodon_full_access"]
}
'
```
[Elasticsearch documentation for user creation](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/security-api-put-user.html)
Once this is done, you need to configure Mastodon to use the credentials for your newly created user.
In `.env.production`, adjust your configuration:
```bash
ES_USER=mastodon
ES_PASS=l0ng-r4nd0m-p@ssw0rd
```
You are all set, and your Elasticsearch server should be much more secure!
### Populate the indices
After saving the new configuration, restart Mastodon processes for it to take effect:
```bash
systemctl restart mastodon-sidekiq
systemctl reload mastodon-web
```
Now it's time to create the Elasticsearch indices and fill them with data:
```bash
su - mastodon
cd live
RAILS_ENV=production bin/tootctl search deploy
```
## Search optimization for other languages
### Chinese search optimization {#chinese-search-optimization}
The default analyzer of the Elasticsearch is the standard analyzer, which may not be the best especially for Chinese. To improve search experience, you can install a language specific analyzer. Before creating the indices in Elasticsearch, install the following Elasticsearch extensions:
- [elasticsearch-analysis-ik](https://github.com/medcl/elasticsearch-analysis-ik)
- [elasticsearch-analysis-stconvert](https://github.com/medcl/elasticsearch-analysis-stconvert)
And then modify Mastodon's index definition as follows:
```diff
diff --git a/app/chewy/accounts_index.rb b/app/chewy/accounts_index.rb
--- a/app/chewy/accounts_index.rb
+++ b/app/chewy/accounts_index.rb
@@ -4,7 +4,7 @@ class AccountsIndex < Chewy::Index
settings index: { refresh_interval: '5m' }, analysis: {
analyzer: {
content: {
- tokenizer: 'whitespace',
+ tokenizer: 'ik_max_word',
filter: %w(lowercase asciifolding cjk_width),
},
diff --git a/app/chewy/statuses_index.rb b/app/chewy/statuses_index.rb
--- a/app/chewy/statuses_index.rb
+++ b/app/chewy/statuses_index.rb
@@ -16,9 +16,17 @@ class StatusesIndex < Chewy::Index
language: 'possessive_english',
},
},
+ char_filter: {
+ tsconvert: {
+ type: 'stconvert',
+ keep_both: false,
+ delimiter: '#',
+ convert_type: 't2s',
+ },
+ },
analyzer: {
content: {
- tokenizer: 'uax_url_email',
+ tokenizer: 'ik_max_word',
filter: %w(
english_possessive_stemmer
lowercase
@@ -27,6 +35,7 @@ class StatusesIndex < Chewy::Index
english_stop
english_stemmer
),
+ char_filter: %w(tsconvert),
},
},
}
diff --git a/app/chewy/tags_index.rb b/app/chewy/tags_index.rb
--- a/app/chewy/tags_index.rb
+++ b/app/chewy/tags_index.rb
@@ -2,10 +2,19 @@
class TagsIndex < Chewy::Index
settings index: { refresh_interval: '15m' }, analysis: {
+ char_filter: {
+ tsconvert: {
+ type: 'stconvert',
+ keep_both: false,
+ delimiter: '#',
+ convert_type: 't2s',
+ },
+ },
analyzer: {
content: {
- tokenizer: 'keyword',
+ tokenizer: 'ik_max_word',
filter: %w(lowercase asciifolding cjk_width),
+ char_filter: %w(tsconvert),
},
edge_ngram: {
```

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

@ -9,27 +9,31 @@ menu:
## Pre-requisites {#pre-requisites}
* A machine running **Ubuntu 18.04** that you have root access to
* A **domain name** \(or a subdomain\) for the Mastodon server, e.g. `example.com`
* A machine running **Ubuntu 20.04** or **Debian 11** 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:
You will be running the commands as root. If you aren’t already root, switch to root: `sudo su -`
### System repositories {#system-repositories}
Make sure curl is installed first:
Make sure curl, wget, gnupg, apt-transport-https, lsb-release and ca-certificates is installed first:
```bash
apt install -y curl wget gnupg apt-transport-https lsb-release ca-certificates
```
#### Node.js {#node-js}
```bash
curl -sL https://deb.nodesource.com/setup_12.x | bash -
curl -sL https://deb.nodesource.com/setup_16.x | bash -
```
#### Yarn {#yarn}
#### PostgreSQL {#postgresql}
```bash
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list
wget -O /usr/share/keyrings/postgresql.asc https://www.postgresql.org/media/keys/ACCC4CF8.asc
echo "deb [signed-by=/usr/share/keyrings/postgresql.asc] http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/postgresql.list
```
### System packages {#system-packages}
@ -42,7 +46,14 @@ apt install -y \
bison build-essential libssl-dev libyaml-dev libreadline6-dev \
zlib1g-dev libncurses5-dev libffi-dev libgdbm-dev \
nginx redis-server redis-tools postgresql postgresql-contrib \
certbot python-certbot-nginx yarn libidn11-dev libicu-dev libjemalloc-dev
certbot python3-certbot-nginx libidn11-dev libicu-dev libjemalloc-dev
```
#### Yarn {#yarn}
```bash
corepack enable
yarn set version classic
```
### Installing Ruby {#installing-ruby}
@ -73,8 +84,8 @@ git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
Once this is done, we can install the correct Ruby version:
```bash
RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 2.7.2
rbenv global 2.7.2
RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 3.2.2
rbenv global 3.2.2
```
We’ll also need to install bundler:
@ -93,9 +104,9 @@ exit
### Setting up PostgreSQL {#setting-up-postgresql}
#### Performance configuration \(optional\) {#performance-configuration-optional}
#### Performance configuration (optional) {#performance-configuration-optional}
For optimal performance, you may use [pgTune](https://pgtune.leopard.in.ua/#/) to generate an appropriate configuration and edit values in `/etc/postgresql/9.6/main/postgresql.conf` before restarting PostgreSQL with `systemctl restart postgresql`
For optimal performance, you may use [pgTune](https://pgtune.leopard.in.ua/#/) to generate an appropriate configuration and edit values in `/etc/postgresql/16/main/postgresql.conf` before restarting PostgreSQL with `systemctl restart postgresql`
#### Creating a user {#creating-a-user}
@ -129,8 +140,8 @@ su - mastodon
Use git to download the latest stable release of Mastodon:
```bash
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)
git clone https://github.com/mastodon/mastodon.git live && cd live
git checkout $(git tag -l | grep '^v[0-9.]*$' | sort -V | tail -n 1)
```
#### Installing the last dependencies {#installing-the-last-dependencies}
@ -162,7 +173,7 @@ This will:
* 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 "config.md" >}})
The configuration file is saved as `.env.production`. You can review and edit it to your liking. Refer to the [documentation on configuration.]({{< relref "config" >}})
You’re done with the mastodon user for now, so switch back to root:
@ -170,6 +181,16 @@ You’re done with the mastodon user for now, so switch back to root:
exit
```
### Acquiring a SSL certificate {#acquiring-a-ssl-certificate}
We’ll use Let’s Encrypt to get a free SSL certificate:
```bash
certbot certonly --nginx -d example.com
```
This will obtain the certificate, and save it in the directory `/etc/letsencrypt/live/example.com/`.
### Setting up nginx {#setting-up-nginx}
Copy the configuration template for nginx from the Mastodon directory:
@ -181,18 +202,14 @@ 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.
Un-comment the lines starting with `ssl_certificate` and `ssl_certificate_key`, updating the path with the correct domain name.
Reload nginx for the changes to take effect:
### Acquiring a SSL certificate {#acquiring-a-ssl-certificate}
We’ll use Let’s Encrypt to get a free SSL certificate:
```bash
certbot --nginx -d example.com
systemctl reload nginx
```
This will obtain the certificate, automatically update `/etc/nginx/sites-available/mastodon` to use the new certificate, and reload nginx for the changes to take effect.
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 {#setting-up-systemd-services}

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

@ -15,10 +15,10 @@ This guide was written with Ubuntu Server in mind; your mileage may vary for oth
## Basic steps {#basic-steps}
1. Set up a new Mastodon server using the [Production Guide]({{< relref "install.md" >}}) \(however, don’t run `mastodon:setup`\).
2. Stop Mastodon on the old server \(e.g. `systemctl stop 'mastodon-*.service'`\).
1. Set up a new Mastodon server using the [Production Guide]({{< relref "install" >}}) (however, don’t run `mastodon:setup`).
2. Stop Mastodon on the old server (e.g. `systemctl stop 'mastodon-*.service'`).
3. Dump and load the Postgres database using the instructions below.
4. Copy the `system/` files using the instructions below. \(Note: if you’re using S3, you can skip this step.\)
4. Copy the `system/` files using the instructions below. (Note: if you’re using S3, you can skip this step.)
5. Copy the `.env.production` file.
6. Run `RAILS_ENV=production bundle exec rails assets:precompile` to compile Mastodon
7. Run `RAILS_ENV=production ./bin/tootctl feeds build` to rebuild the home timelines for each user.
@ -33,19 +33,19 @@ This guide was written with Ubuntu Server in mind; your mileage may vary for oth
At a high level, you’ll need to copy over the following:
* The `~/live/public/system` directory, which contains user-uploaded images and videos \(if using S3, you don’t need this\)
* The Postgres database \(using [pg\_dump](https://www.postgresql.org/docs/9.1/static/backup-dump.html)\)
* The `~/live/public/system` directory, which contains user-uploaded images and videos (if using S3, you don’t need this)
* The Postgres database (using [pg_dump](https://www.postgresql.org/docs/9.1/static/backup-dump.html))
* The `~/live/.env.production` file, which contains server config and secrets
Less crucially, you’ll probably also want to copy the following for convenience:
* The nginx config \(under `/etc/nginx/sites-available/default`\)
* The systemd config files \(`/etc/systemd/system/mastodon-*.service`\), which may contain your server tweaks and customizations
* The pgbouncer configuration under `/etc/pgbouncer` \(if you’re using it\)
* The nginx config (under `/etc/nginx/sites-available/default`)
* The systemd config files (`/etc/systemd/system/mastodon-*.service`), which may contain your server tweaks and customizations
* The pgbouncer configuration under `/etc/pgbouncer` (if you’re using it)
### Dump and load Postgres {#dump-and-load-postgres}
Instead of running `mastodon:setup`, we’re going to create an empty Postgres database using the `template0` database \(which is useful when restoring a Postgres dump, [as described in the pg\_dump documentation](https://www.postgresql.org/docs/9.1/static/backup-dump.html#BACKUP-DUMP-RESTORE)\).
Instead of running `mastodon:setup`, we’re going to create an empty Postgres database using the `template0` database (which is useful when restoring a Postgres dump, [as described in the pg_dump documentation](https://www.postgresql.org/docs/9.1/static/backup-dump.html#BACKUP-DUMP-RESTORE)).
Run this as the `mastodon` user on your old system:
@ -62,11 +62,11 @@ createdb -T template0 mastodon_production
Then import it:
```bash
pg_restore -U mastodon -n public --no-owner --role=mastodon \
pg_restore -Fc -U mastodon -n public --no-owner --role=mastodon \
-d mastodon_production backup.dump
```
\(Note that if the username is not `mastodon` on the new server, you should change the `-U` AND `--role` values above. It’s okay if the username is different between the two servers.\)
(Note that if the username is not `mastodon` on the new server, you should change the `-U` AND `--role` values above. It’s okay if the username is different between the two servers.)
### Copy files {#copy-files}
@ -86,7 +86,7 @@ Optionally, you may copy over the nginx, systemd, and pgbouncer config files, or
You can edit the `~/live/public/500.html` page on the old machine if you want to show a nice error message to let existing users know that a migration is in progress.
You’ll probably also want to set the DNS TTL to something small \(30-60 minutes\) about a day in advance, so that DNS can propagate quickly once you point it to the new IP address.
You’ll probably also want to set the DNS TTL to something small (30-60 minutes) about a day in advance, so that DNS can propagate quickly once you point it to the new IP address.
### After migrating {#after-migrating}

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

@ -7,29 +7,43 @@ menu:
parent: admin
---
## Individual moderation {#individual-moderation}
## Moderating individual users {#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 {#disable-login}
As of v3.5.0, all default user moderation decisions will notify the affected user by email. The user can access an appeal page, where they can submit one appeal within 20 days of the decision. Moderators can approve or reject the appeal.
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.
### Sensitive {#sensitive-user}
### Silence {#silence-user}
When an account is marked as sensitive, all media that user posts will be automatically [marked as sensitive](https://docs.joinmastodon.org/user/posting/#cw).
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.
### Freeze {#freeze-user}
At this moment, silence does not affect federation. A locally silenced account is _not_ silenced automatically on other servers.
A Mastodon account can be frozen. 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 un-frozen at any time. This limitation is only available for local users on your server.
This limitation is reversible, the account can be unsilenced at any time.
When a user's account is frozen, they are redirected to their **Account Settings** page, where the following message is displayed:
> You can no longer login to your account or use it in any other way, but your profile and other data remains intact.
When the user's account is un-frozen, normal functionality resumes.
### Limit {#limit-user}
Previously known as "silencing". A limited account is hidden to all other users on that instance, except for its followers. All of the content is still there, and it can still be found via search, mentions, and following, but the content is invisible publicly.
At this moment, limit does not affect federation. A locally limited account is *not* limited automatically on other servers. Account limitations are reversible.
### Suspend {#suspend-user}
A Mastodon suspension is synonymous with deletion. The account no longer appears in search, the profile page is gone, all of the posts, uploads, followers, and all other data is removed. This limitation is **irreversible**. While the account can be unsuspended, allowing the user to take control of it again, the old data is gone for good.
A Mastodon suspension means the account is effectively deleted. The account no longer appears in search, the profile page is gone, all of the posts, uploads, followers, and all other data is removed publicly. However, all the data is available in the admin back-end for a period of 30 days from suspension. This is to give the user an opportunity to work with instance admins to resolve any potential issues and have the account re-instated.
As of v3.3.0, suspensions are now reversible for 30 days.
If the account is reinstated within the 30 day period, all data is once again accessible publicly without any adverse effects. If the 30 day period lapses, **all** that user's data is purged from the instance. Admins also have the option to immediately delete the user's account data at any point during the 30 days.
## Server-wide moderation {#server-wide-moderation}
Once the data has been deleted, whether that is after the 30 day period, or if an admin has force deleted it, the account can still be un-suspended. However, the account will have no data (statuses, profile information, avatar or header image) associated with it.
For remote accounts, suspending will make them unfollow any local account. Those relationships are not restored in case the remote account is un-suspended, even within the 30-day time window.
## Moderating entire websites {#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.
@ -37,13 +51,15 @@ Because individually moderating a large volume of users from a misbehaving serve
With this option active, no files from the server will be processed locally. That includes avatars, headers, emojis and media attachments.
### Silence {#silence-server}
### Limit {#limit-server}
Applies a silence to all past and future accounts from the server.
Equivalent to [limiting](#limit-user) all past and future accounts from the server. Previously known as "silencing".
### Suspend {#suspend-server}
Applies a suspension to all past and future accounts from the server. No content from the server will be stored locally except for usernames.
Equivalent to [suspending](#suspend-user) all past and future accounts from the server. No content from the server will be stored locally except for usernames.
Suspending a server will remove all existing follow relationships between local accounts and accounts on the suspended server. They will not be restored in case the remote server is un-suspended later.
## Spam-fighting measures {#spam-fighting-measures}
@ -74,4 +90,3 @@ sudo iptables -I INPUT 1 -m set --match-set spambots src -j DROP
```
Be careful not to lock yourself out of your machine.

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

@ -7,3 +7,8 @@ menu:
identifier: admin-optional
---
Mastodon offers a few optional features that can be used if needed.
- [Object storage](./object-storage/)
- [Hidden services](./tor/)
- [Single Sign On](./sso/)

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

@ -1,148 +0,0 @@
---
title: Full-text search
description: Setting up ElasticSearch to search for statuses authored, favourited, or mentioned in.
menu:
docs:
weight: 10
parent: admin-optional
---
Mastodon supports full-text search when it ElasticSearch is available. Mastodon’s full-text search allows logged in users to find results from their own toots, their favourites, and their mentions. It deliberately does not allow searching for arbitrary strings in the entire database.
## Installing ElasticSearch {#install}
ElasticSearch requires a Java runtime. If you don’t have Java already installed, do it now. Assuming you are logged in as `root`:
```bash
apt install openjdk-8-jre-headless
```
Add the official ElasticSearch repository to apt:
```bash
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
```
Now you can install ElasticSearch:
```bash
apt install elasticsearch
```
{{< hint style="warning" >}}
**Security warning:** By default, ElasticSearch is supposed to bind to localhost only, i.e. be inaccessible from the outside network. You can check which address ElasticSearch binds to by looking at `network.host` within `/etc/elasticsearch/elasticsearch.yml`. Consider that anyone who can access ElasticSearch can access and modify any data within it, as there is no authentication layer. So it’s really important that the access is secured. Having a firewall that only exposes the 22, 80 and 443 ports is advisable, as outlined in the [main installation instructions](../../prerequisites/#install-a-firewall-and-only-whitelist-ssh-http-and-https-ports). If you have a multi-host setup, you must know how to secure internal traffic.
{{< /hint >}}
To start ElasticSearch:
```bash
systemctl enable elasticsearch
systemctl start elasticsearch
```
## Configuring Mastodon {#config}
Edit `.env.production` to add the following variables:
```bash
ES_ENABLED=true
ES_HOST=localhost
ES_PORT=9200
```
If you have multiple Mastodon servers on the same machine, and you are planning to use the same ElasticSearch installation for all of them, make sure that all of them have unique `REDIS_NAMESPACE` in their configurations, to differentiate the indices. If you need to override the prefix of the ElasticSearch indices, you can set `ES_PREFIX` directly.
After saving the new configuration, restart Mastodon processes for it to take effect:
```bash
systemctl restart mastodon-sidekiq
systemctl reload mastodon-web
```
Now it's time to create the ElasticSearch indices and fill them with data:
```bash
RAILS_ENV=production bin/tootctl search deploy
```
## Search optimization for other languages
### Chinese search optimization {#chinese-search-optimization}
The default analyzer of the ElasticSearch is the standard analyzer, which may not be the best especially for Chinese. To improve search experience, you can install a language specific analyzer. Before creating the indices in ElasticSearch, install the following ElasticSearch extensions:
- [elasticsearch-analysis-ik](https://github.com/medcl/elasticsearch-analysis-ik)
- [elasticsearch-analysis-stconvert](https://github.com/medcl/elasticsearch-analysis-stconvert)
And then modify Mastodon's index definition as follows:
```diff
diff --git a/app/chewy/accounts_index.rb b/app/chewy/accounts_index.rb
--- a/app/chewy/accounts_index.rb
+++ b/app/chewy/accounts_index.rb
@@ -4,7 +4,7 @@ class AccountsIndex < Chewy::Index
settings index: { refresh_interval: '5m' }, analysis: {
analyzer: {
content: {
- tokenizer: 'whitespace',
+ tokenizer: 'ik_max_word',
filter: %w(lowercase asciifolding cjk_width),
},
diff --git a/app/chewy/statuses_index.rb b/app/chewy/statuses_index.rb
--- a/app/chewy/statuses_index.rb
+++ b/app/chewy/statuses_index.rb
@@ -16,9 +16,17 @@ class StatusesIndex < Chewy::Index
language: 'possessive_english',
},
},
+ char_filter: {
+ tsconvert: {
+ type: 'stconvert',
+ keep_both: false,
+ delimiter: '#',
+ convert_type: 't2s',
+ },
+ },
analyzer: {
content: {
- tokenizer: 'uax_url_email',
+ tokenizer: 'ik_max_word',
filter: %w(
english_possessive_stemmer
lowercase
@@ -27,6 +35,7 @@ class StatusesIndex < Chewy::Index
english_stop
english_stemmer
),
+ char_filter: %w(tsconvert),
},
},
}
diff --git a/app/chewy/tags_index.rb b/app/chewy/tags_index.rb
--- a/app/chewy/tags_index.rb
+++ b/app/chewy/tags_index.rb
@@ -2,10 +2,19 @@
class TagsIndex < Chewy::Index
settings index: { refresh_interval: '15m' }, analysis: {
+ char_filter: {
+ tsconvert: {
+ type: 'stconvert',
+ keep_both: false,
+ delimiter: '#',
+ convert_type: 't2s',
+ },
+ },
analyzer: {
content: {
- tokenizer: 'keyword',
+ tokenizer: 'ik_max_word',
filter: %w(lowercase asciifolding cjk_width),
+ char_filter: %w(tsconvert),
},
edge_ngram: {
```

4
content/en/admin/optional/object-storage-proxy.md
View File

@ -37,7 +37,7 @@ server {
}
resolver 8.8.8.8;
proxy_set_header Host YOUR_S3_HOSTNAME;
proxy_set_header Host YOUR_BUCKET_NAME.YOUR_S3_HOSTNAME;
proxy_set_header Connection '';
proxy_set_header Authorization '';
proxy_hide_header Set-Cookie;
@ -63,6 +63,8 @@ server {
add_header Cache-Control public;
add_header 'Access-Control-Allow-Origin' '*';
add_header X-Cache-Status $upstream_cache_status;
add_header X-Content-Type-Options nosniff;
add_header Content-Security-Policy "default-src 'none'; form-action 'none'";
}
}
```

232
content/en/admin/optional/object-storage.md Normal file
View File

@ -0,0 +1,232 @@
---
title: Configuring object storage
description: Serving user-uploaded files in Mastodon using external object storage
menu:
docs:
weight: 15
parent: admin-optional
---
User-uploaded files can be stored on the main server's file system, or using an external object storage server, which can be required for scaling.
## Using the filesystem {#FS}
The simplest way to store user uploads is by using the server's file system. This is how it works by default and is suitable for small servers.
By default, Mastodon will store file uploads under `public/system` in its installation directory, but that can be overridden using the `PAPERCLIP_ROOT_PATH` environment variable.
By default, the files are served at `https://your-domain/system`, which can be overridden using `PAPERCLIP_ROOT_URL` and `CDN_HOST`.
{{< hint style="info" >}}
While using the server's file system is perfectly serviceable for small servers, using external object storage is more scalable.
{{</ hint >}}
{{< hint style="danger" >}}
The web server must be configured to serve those files but not allow listing them (that is, `https://your-domain/system/` should not return a file list). This should be the case if you use the configuration files distributed with Mastodon, but it is worth double-checking.
{{</ hint >}}
## S3-compatible object storage backends {#S3}
Mastodon can use S3-compatible object storage backends. ACL support is recommended as it allows Mastodon to quickly make the content of temporarily suspended users unavailable, or marginally improve security of private data.
On Mastodon's end, you need to configure the following environment variables:
- `S3_ENABLED=true`
- `S3_BUCKET=mastodata` (replacing `mastodata` with the name of your bucket)
- `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` need to be set to your credentials
- `S3_ALIAS_HOST` is optional but highly recommended in order to set up a caching proxy and not lock you to a specific provider
- `S3_REGION`
- `S3_HOSTNAME` (optional if you use Amazon AWS)
- `S3_PERMISSION` (optional, if you use a provider that does not support ACLs or want to use custom ACLs)
- `S3_FORCE_SINGLE_REQUEST=true` (optional, if you run in trouble processing large files)
{{< page-ref page="admin/optional/object-storage-proxy.md" >}}
{{< hint style="info" >}}
You must serve the files with CORS headers, otherwise some functions of Mastodon's web UI will not work. For example, `Access-Control-Allow-Origin: *`
{{</ hint >}}
{{< hint style="danger" >}}
In any case, your S3 bucket must be configured so that -- ACL configuration nonwithstanding -- all objects are publicly readable but neither writable or listable, while Mastodon itself can write to it. The configuration should be similar for all S3 providers, but common ones have been highlighted below.
{{</ hint >}}
### MinIO
MinIO is an open source implementation of an S3 object provider. This section does not cover how to install it, but how to configure a bucket for use in Mastodon.
You need to set a policy for anonymous access that allows read-only access to objects contained by the bucket without allowing listing them.
To do this, you need to set a custom policy (replace `mastodata` by the actual name of your S3 bucket):
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::mastodata/*"
}
]
}
```
Mastodon itself needs to be able to write to the bucket, so either use your admin MinIO account (discouraged) or an account specific to Mastodon (recommended) with the following policy attached (replace `mastodata` by the actual name of your S3 bucket):
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": "arn:aws:s3:::mastodata/*"
}
]
}
```
You can set those policies from the MinIO Console (web-based user interface) or the command-line client (`mcli` / `mc`).
#### Using the MinIO Console
Connect to the MinIO Console web interface and create a new bucket (or navigate to your existing bucket):
![](/assets/object-storage/minio-bucket.png)
Then, configure the “Access Policy” to a custom one that allows read access (`s3:GetObject`) without write access or ability to list objects (see above):
![](/assets/object-storage/minio-access-policy.png)
{{< hint style="info" >}}
If the MinIO Console does not allow you to set a “Custom” policy, you will likely need to update MinIO. If you are using MinIO in *standalone* or *filesystem* mode, [`RELEASE.2022-10-24T18-35-07Z`](https://github.com/minio/minio/releases/tag/RELEASE.2022-10-24T18-35-07Z) should be a safe version to update to that does not require [an involved migration procedure](https://min.io/docs/minio/linux/operations/install-deploy-manage/migrate-fs-gateway.html#migrate-from-gateway-or-filesystem-mode).
{{< /hint >}}
Create a new `mastodon-readwrite` policy (see above):
![](/assets/object-storage/minio-mastodon-readwrite.png)
Finally, create a new `mastodon` user with the `mastodon-readwrite` policy:
![](/assets/object-storage/minio-mastodon-user.png)
#### Using the command-line utility
The same can be achieved using the [MinIO Client](https://min.io/docs/minio/linux/reference/minio-mc.html) command-line utility (can be called `mc` or `mcli` depending on where it is installed from).
Create a new bucket:
`mc mb myminio/mastodata`
Save the anonymous access policy from above as `anonymous-readonly-policy.json` and the Mastodon user access policy as `mastodon-readwrite.json` (make sure to replace `mastodata` with the name of your newly-created bucket).
Set the anonymous access policy for your bucket:
`mc anonymous set-json anonymous-readonly-policy.json myminio/mastodata`
Add a `mastodon-readwrite` policy:
`mc admin policy add myminio mastodon-readwrite mastodon-readwrite.json`
Add the `mastodon` user (replace the password):
`mc admin user add myminio mastodon SECRET_PASSWORD`
Apply the `mastodon-readwrite` policy to the `mastodon` user:
`mc admin policy set myminio mastodon-readwrite user=mastodon`
### Wasabi Object Storage
Create a new bucket and define its policy to allow objects to be anonymously readable but not listable:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::mastodata/*"
}
]
}
```
![](/assets/object-storage/wasabi-access-policy.png)
{{< hint style="info" >}}
If you are using an old bucket, ensure you are not giving “Everyone” read access to objects through Wasabi's legacy Access Control settings, as that allows listing objects and take precedence over the IAM policy defined above.
![](/assets/object-storage/wasabi-access-control.png)
{{< /hint >}}
Then, create a `mastodon-readwrite` policy to grant read and write access to your bucket:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": "arn:aws:s3:::mastodata/*"
}
]
}
```
![](/assets/object-storage/wasabi-mastodon-readwrite.png)
Finally, create a new `mastodon` user and don't forget to enable the `mastodon-readwrite` policy:
![](/assets/object-storage/wasabi-mastodon-user.png)
On Mastodon's side, you need to set `S3_FORCE_SINGLE_REQUEST=true` to properly handle large uploads.
### DigitalOcean Spaces
In your DigitalOcean Spaces Bucket, make sure that “File Listing” is “Restricted” to users with access keys.
![](/assets/object-storage/do-spaces.png)
### Scaleway
If you want to use Scaleway Object Storage, we strongly recommend you to create a Scaleway project dedicaced to your Mastodon instance assets and to use a custom IAM policy.
First, create a new Scaleway project, in which you create your object storage bucket. You need to set your bucket visibility to "Private" to not allow objects to be listed.
![](/assets/object-storage/scaleway-bucket.png)
Now that your bucket is created, you need to create API keys to be used in your Mastodon instance configuration.
Head to the IAM settings (in your organisation menu, top right of the screen), and create a new IAM policy (eg `mastodon-media-access`)
![](/assets/object-storage/scaleway-policy.jpg)
This policy needs to have one rule, allowing it to read, write and delete objects in the Scaleway project you created above (the scope).
![](/assets/object-storage/scaleway-policy-rules.jpg)
Then head to the IAM Applications page, and a create a new one (eg `my-mastodon-instance`) and select the policy you created above.
Finally, click on the application you just created, then "API Keys", and create a new API key to use in your instance configuration. You should use the "Yes, set up preferred Project" option and select the project you created above as the default project for this key.
![](/assets/object-storage/scaleway-api-key.png)
Copy the Access Key ID and Secret, and use them for your `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` Mastodon config variables.
### Exoscale
In Exoscale, your bucket should not have any read ACLs (Mastodon will set the ACLs on the object themselves as appropriate).
You need to create an API Key for the Mastodon app, restricted to the Object Storage (`sos`) service, restricted to your bucket, and with unrestricted operations.
![](/assets/object-storage/exoscale.png)
On Mastodon's side, you need to set `S3_FORCE_SINGLE_REQUEST=true` to properly handle large uploads.
### Cloudflare R2
Cloudflare R2 does not support ACLs, so Mastodon needs to be instructed not to try setting them. To do that, set the `S3_PERMISSION` environment variable to an empty string.
{{< hint style="warning" >}}
Without support for ACLs, media files from temporarily-suspended users will remain accessible.
{{< /hint >}}
To get credentials for use in Mastodon, selecte “Manage R2 API Tokens” and create a new API token with “Edit” permissions.
{{< hint style="warning" >}}
This section is currently under construction.
{{< /hint >}}

2
content/en/admin/optional/sso.md
View File

@ -8,5 +8,7 @@ menu:
{{< hint style="danger" >}}
This page is under construction.
For the moment, please refer to [this pull request](https://github.com/mastodon/mastodon/pull/16221)
{{< /hint >}}

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

@ -1,13 +1,13 @@
---
title: Hidden services
description: Serving Mastodon through TOR hidden services.
title: Onion services
description: Serving Mastodon through Tor onion services.
menu:
docs:
weight: 20
parent: admin-optional
---
Mastodon can be served through Tor as an onion service. This will give you a \*.onion address that can only be used while connected to the Tor network.
Mastodon can be served through Tor as an onion service. This will give you a `*.onion` address that can only be used while connected to the Tor network.
## Installing Tor {#install}
@ -36,7 +36,7 @@ apt install tor deb.torproject.org-keyring
Edit the file at `/etc/tor/torrc` and add the following configuration.
```text
HiddenServiceDir /var/lib/tor/hidden_service/
HiddenServiceDir /var/lib/tor/onion_service/
HiddenServiceVersion 3
HiddenServicePort 80 127.0.0.1:80
```
@ -47,7 +47,7 @@ Restart tor.
sudo service tor restart
```
Your tor hostname can now be found at `/var/lib/tor/hidden_service/hostname`.
Your tor hostname can now be found at `/var/lib/tor/onion_service/hostname`.
## Move your Mastodon configuration {#nginx}
@ -101,7 +101,7 @@ server {
## Serve Tor over http {#http}
While it may be tempting to serve your Tor version of Mastodon over https it is not a good idea for most people. See [this](https://blog.torproject.org/facebook-hidden-services-and-https-certs) blog post from the Tor Project about why https certificates do not add value. Since you cannot get an SSL cert for an onion domain, you will also be plagued with certificate errors when trying to use your Mastodon instance. A Tor developer has more recently spelled out the reasons why serving a Tor service over https is not beneficial for most use cases [here](https://matt.traudt.xyz/p/o44SnkW2.html).
While it may be tempting to serve your Tor version of Mastodon over https it is not a good idea for most people. See [this](https://blog.torproject.org/facebook-hidden-services-and-https-certs) blog post from the Tor Project about why https certificates do not add value. Since you cannot get an SSL cert for an onion domain, you will also be plagued with certificate errors when trying to use your Mastodon instance. A Tor developer has more recently spelled out the reasons why serving a Tor service over https is not beneficial for most use cases [here](https://matt.traudt.xyz/posts/2017-12-02-dont-https-your-onions/).
The solution is to serve your Mastodon instance over http, but only for Tor. This can be added by prepending an additional configuration to your Nginx configuration.
@ -134,7 +134,7 @@ server {
}
```
Replace the long hash provided here with your Tor domain located in the file at `/var/lib/tor/hidden_service/hostname`.
Replace the long hash provided here with your Tor domain located in the file at `/var/lib/tor/onion_service/hostname`.
Note that the onion hostname has been prefixed with “mastodon.”. Your Tor address acts a wildcard domain. All subdomains will be routed through, and you can configure Nginx to respond to any subdomain you wish. If you do not wish to host any other services on your tor address you can omit the subdomain, or choose a different subdomain.

57
content/en/admin/prerequisites.md
View File

@ -6,14 +6,18 @@ menu:
parent: admin
---
If you are setting up a fresh machine, it is recommended that you secure it first. Assuming that you are running **Ubuntu 18.04**:
If you are setting up a fresh machine, it is recommended that you secure it first. Assuming that you are running **Ubuntu 20.04**:
## Do not allow password-based SSH login \(keys only\)
## 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:
```bash
systemctl restart ssh.service
```
## Update system packages
```bash
@ -22,6 +26,12 @@ apt update && apt upgrade -y
## Install fail2ban so it blocks repeated login attempts
First, install fail2ban:
```bash
apt install fail2ban
```
Edit `/etc/fail2ban/jail.local` and put this inside:
```text
@ -44,7 +54,7 @@ Finally restart fail2ban:
systemctl restart fail2ban
```
## Install a firewall and only whitelist SSH, HTTP and HTTPS ports
## Install a firewall and only allow SSH, HTTP and HTTPS ports
First, install iptables-persistent. During installation it will ask you if you want to keep current rules–decline.
@ -78,6 +88,9 @@ Edit `/etc/iptables/rules.v4` and put this inside:
# Allow ping
-A INPUT -p icmp -m icmp --icmp-type 8 -j ACCEPT
# Allow destination unreachable messages, especially code 4 (fragmentation required) is required or PMTUD breaks
-A INPUT -p icmp -m icmp --icmp-type 3 -j ACCEPT
# Log iptables denied calls
-A INPUT -m limit --limit 5/min -j LOG --log-prefix "iptables denied: " --log-level 7
@ -94,3 +107,41 @@ With iptables-persistent, that configuration will be loaded at boot time. But si
iptables-restore < /etc/iptables/rules.v4
```
If your server is also reachable over IPv6, edit `/etc/iptables/rules.v6` and add this inside:
```text
*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 ::1/128 -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 icmpv6 -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
```
Similar to the IPv4 rules, you can load it manually like this:
```bash
ip6tables-restore < /etc/iptables/rules.v6
```

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

@ -11,16 +11,16 @@ menu:
Mastodon has three types of processes:
* Web \(Puma\)
* Streaming API
* Background processing \(Sidekiq\)
- Web (Puma)
- Streaming API
- Background processing (Sidekiq)
### Web \(Puma\) {#web}
### Web (Puma) {#web}
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
- `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.
@ -32,12 +32,38 @@ In terms of throughput, more processes are better than more threads.
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
- `STREAMING_API_BASE_URL` controls the base URL of the streaming API
- `PORT` controls the port the streaming server will listen on, by default 4000. The `BIND` and `SOCKET` environment variables are also able to be used.
- Additionally the shared [database](/admin/config#postgresql) and [redis](/admin/config#redis) environment variables are used.
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.
The streaming API can be use a different subdomain if you want to by setting `STREAMING_API_BASE_URL`, this allows you to have one load balancer for streaming and one for web/API requests.
### Background processing \(Sidekiq\) {#sidekiq}
{{< hint style="warning" >}}
Previous versions of Mastodon had a `STREAMING_CLUSTER_NUM` environment variable that made the streaming server use clustering, which started mulitple processes (workers) and used node.js to load balance them.
This interacted with the other settings in ways which made capacity planning difficult, especially when it comes to database connections and CPU resources. By default the streaming server would consume resources on all available CPUs which could cause contention with other software running on that server. Another common issue was that misconfiguring the `STREAMING_CLUSTER_NUM` would exhaust your database connections by opening up a connection pool per cluster worker process, so a `STREAMING_CLUSTER_NUM` of `5` and `DB_POOL` of `10` would potentially consume 50 database connections.
Now a single streaming server process will only use at maximum `DB_POOL` PostgreSQL connections, and scaling is handled by running more instances of the streaming server.
{{< /hint >}}
One process can handle a reasonably high number of connections and throughput, but if you find that a single streaming server process isn't handling your instance's load, you can run multiple processes by varying the `PORT` number of each, and then using nginx to load balance traffic to each of those instances.
{{< hint style="info" >}}
The more streaming server processes that you run, the more database connections will be consumed on PostgreSQL, so you'll likely want to use PgBouncer, as documented below.
{{< /hint >}}
An example nginx configuration to route traffic to three different processes on `PORT` 4000, 4001, and 4002 is as follows:
```
upstream streaming {
least_conn;
server 127.0.0.1:4000 fail_timeout=0;
server 127.0.0.1:4001 fail_timeout=0;
server 127.0.0.1:4002 fail_timeout=0;
}
```
### Background processing (Sidekiq) {#sidekiq}
Many tasks in Mastodon are delegated to background processing to ensure the HTTP requests are fast, and to prevent HTTP request aborts from affecting the execution of those tasks. Sidekiq is a single process, with a configurable number of threads.
@ -57,14 +83,16 @@ Would start the sidekiq process with 15 threads. Please mind that each threads n
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 |
| Queue | Significance |
| :---------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| `default` | All tasks that affect local users |
| `push` | Delivery of payloads to other servers |
| `mailers` | Delivery of e-mails |
| `pull` | Lower priority tasks such as handling imports, backups, resolving threads, deleting users, forwarding replies |
| `scheduler` | Doing cron jobs like refreshing trending hashtags and cleaning up logs |
| `ingress` | Incoming remote activities. Lower priority than the default queue so local users still see their posts when the server is under load |
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.:
The default queues and their priorities are stored in [config/sidekiq.yml](https://github.com/mastodon/mastodon/blob/main/config/sidekiq.yml), but can be overridden by the command-line invocation of Sidekiq, e.g.:
```bash
bundle exec sidekiq -q default
@ -76,11 +104,13 @@ The way Sidekiq works with queues, it first checks for tasks from the first queu
As a solution, it is possible to start different Sidekiq processes for the queues to ensure truly parallel execution, by e.g. creating multiple systemd services for Sidekiq with different arguments.
**Make sure you only have one `scheduler` queue running!!**
## Transaction pooling with pgBouncer {#pgbouncer}
### Why you might need PgBouncer {#pgbouncer-why}
If you start running out of available Postgres connections \(the default is 100\) then you may find PgBouncer to be a good solution. This document describes some common gotchas as well as good configuration defaults for Mastodon.
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.
@ -96,7 +126,7 @@ sudo apt install pgbouncer
#### Setting a password {#pgbouncer-password}
First off, if your `mastodon` user in Postgres is set up wthout a password, you will need to set a password.
First off, if your `mastodon` user in Postgres is set up without a password, you will need to set a password.
Here’s how you might reset the password:
@ -104,7 +134,7 @@ 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”\):
Then (obviously, use a different password than the word “password”):
```sql
ALTER USER mastodon WITH PASSWORD 'password';
@ -160,13 +190,25 @@ 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`\):
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`:
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.\)
```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:
@ -207,7 +249,7 @@ 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:
Next up, configure Mastodon to use port 6432 (PgBouncer) instead of 5432 (Postgres) and you should be good to go:
```bash
DB_HOST=localhost
@ -218,7 +260,7 @@ DB_PORT=6432
```
{{< hint style="warning" >}}
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\)
You cannot use pgBouncer to perform `db:migrate` tasks. But this is easy to work around. If your postgres and pgbouncer are on the same host, it can be as simple as defining `DB_PORT=5432` together with `RAILS_ENV=production` when calling the task, for example: `RAILS_ENV=production DB_PORT=5432 bundle exec rails db:migrate` (you can specify `DB_HOST` too if it’s different, etc)
{{< /hint >}}
#### Administering PgBouncer {#pgbouncer-admin}
@ -245,18 +287,22 @@ Then use `\q` to quit.
## Separate Redis for cache {#redis}
Redis is used widely throughout the application, but some uses are more important than others. Home feeds, list feeds, and Sidekiq queues as well as the streaming API are backed by Redis and that’s important data you wouldn’t want to lose \(even though the loss can be survived, unlike the loss of the PostgreSQL database - never lose that!\). However, Redis is also used for volatile cache. If you are at a stage of scaling up where you are worried if your Redis can handle everything, you can use a different Redis database for the cache. In the environment, you can specify `CACHE_REDIS_URL` or individual parts like `CACHE_REDIS_HOST`, `CACHE_REDIS_PORT` etc. Unspecified parts fallback to the same values as without the cache prefix.
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 {#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:
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.
- 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 processes, so that writes go to the primary 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:
{{< hint style="warning" >}}
Read replicas are currently not supported for the Sidekiq processes, and using them will lead to failing jobs and data loss.
{{< /hint >}}
You will have to use a separate `config/database.yml` file for the web processes and edit it to replace the `production` section as follows:
```yaml
production:
@ -274,9 +320,8 @@ production:
url: postgresql://db_user:db_password@db_host:db_port/db_name
```
Make sure the URLs point to wherever your PostgreSQL servers are. You can add multiple replicas. You could have a locally installed pgBouncer with configuration to connect to two different servers based on database name, e.g. “mastodon” going to master, “mastodon\_replica” going to the replica, so in the file above both URLs would point to the local pgBouncer with the same user, password, host and port, but different database name. There are many possibilities how this could be setup! For more information on Makara, [see their documentation](https://github.com/taskrabbit/makara#databaseyml).
Make sure the URLs point to wherever your PostgreSQL servers are. You can add multiple replicas. You could have a locally installed pgBouncer with configuration to connect to two different servers based on database name, e.g. “mastodon” going to the primary, “mastodon_replica” going to the replica, so in the file above both URLs would point to the local pgBouncer with the same user, password, host and port, but different database name. There are many possibilities how this could be setup! For more information on Makara, [see their documentation](https://github.com/taskrabbit/makara#databaseyml).
{{< hint style="warning" >}}
Sidekiq cannot reliably use read-replicas because even the tiniest replication lag leads to failing jobs due to queued up records not being found.
Make sure the sidekiq processes run with the stock `config/database.yml` to avoid failing jobs and data loss!
{{< /hint >}}

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

@ -14,9 +14,13 @@ menu:
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 modify alice --role admin
RAILS_ENV=production bin/tootctl accounts modify alice --role Owner
```
{{<hint style="warning">}}
Prior to Mastodon 4.0, roles were hardcoded to be one of `user`, `moderator`, or `admin`. Since Mastodon 4.0, there is a customizable role system, with default roles created for `Moderator`, `Admin`, and `Owner`. Names of custom roles are case-sensitive.
{{</hint>}}
### From the command line {#admin-cli}
You can create a new account using the command-line interface.
@ -26,14 +30,14 @@ RAILS_ENV=production bin/tootctl accounts create \
alice \
--email alice@example.com \
--confirmed \
--role admin
--role Owner
```
A randomly generated password will be shown in the terminal.
## Filling in server information {#info}
After logging in, navigate to the **Site settings** page. While there are no technical requirements for filling in this information, it is considered crucial for operating a server for humans.
After logging in, navigate to the **Site settings** page (under **Preferences** -> **Administration**). While there are no technical requirements for filling in this information, it is considered crucial for operating a server for humans.
| Setting | Meaning |
| :--- | :--- |
@ -42,7 +46,7 @@ After logging in, navigate to the **Site settings** page. While there are no tec
| 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”.
After you fill these in, click “Save changes”.
## Running periodic cleanup tasks {#cleanup}

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

File diff suppressed because it is too large Load Diff

10
content/en/admin/troubleshooting.md
View File

@ -9,7 +9,7 @@ menu:
## **I see an error page that says something went wrong. How do I find out what’s wrong?**
All error messages with stack traces are written to the system log. When using systemd, the logs of each systemd service can be browsed with `journalctl -u mastodon-web` \(substitute with the correct service name\). When using Docker, it’s similar: `docker logs mastodon_web_1` \(substitute with the correct container name\).
All error messages with stack traces are written to the system log. When using systemd, the logs of each systemd service can be browsed with `journalctl -u mastodon-web` (substitute with the correct service name). When using Docker, it’s similar: `docker logs mastodon_web_1` (substitute with the correct container name).
Specific details of server-side errors are _never_ displayed to the public, as they can reveal what your setup looks like internally and give attackers clues how to get in, or how to abuse the system more efficiently.
@ -30,3 +30,11 @@ Check that you are specifying the correct environment with `RAILS_ENV=production
## **I encountered a compilation error while executing `RAILS_ENV=production bundle exec rails assets:precompile`, but no more information is given. How to fix it?**
Usually it's because your server ran out of memory while compiling assets. Use a swapfile or increase the swap space to increase the memory capacity. Run `RAILS_ENV=production bundle exec rake tmp:cache:clear` to clear cache, then execute `RAILS_ENV=production bundle exec rails assets:precompile` to compile again. Make sure you clear the cache after a compilation error, or it will show "Everything's OK" but leave the assets unchanged.
## **I am getting this error: `Read-only file system @ dir_s_mkdir`. Why?**
By default, Mastodon makes use of [systemd's sandboxing capabilities](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Sandboxing) in a way that disallows writing outside of `/home/mastodon`. If Mastodon is installed elsewhere, you may need to allow `mastodon-sidekiq` and `mastodon-web` to write to a custom directory:
1. Add parameter `ReadWritePaths` to files `/etc/systemd/system/mastodon-sidekiq.service` and `/etc/systemd/system/mastodon-web.service`. Example - `ReadWritePaths=/example/mastodon/live`.
2. run `systemctl stop mastodon-sidekiq mastodon-web`
3. run `systemctl daemon-reload`
4. run `systemctl start mastodon-sidekiq mastodon-web`

24
content/en/admin/troubleshooting/index-corruption.md
View File

@ -11,7 +11,7 @@ A somewhat common configuration issue can lead to index corruption throughout th
## Locale data and collation {#explanation}
Textual values in the database, such as usernames, or toot identifiers, are compared using so-called collation rules defining how characters are ordered and how to change their case.
Textual values in the database, such as usernames, or status identifiers, are compared using so-called collation rules defining how characters are ordered and how to change their case.
When setting up a database, Mastodon will use the database server's default locale settings, including the default collation rules, which often is defined by the operating system's settings.
Unfortunately, in late 2018, a `glibc` update changed the collation rules for many locales, which means databases using an affected locale would now order textual values differently.
@ -24,6 +24,10 @@ More information: https://wiki.postgresql.org/wiki/Locale_data_changes https://p
If your database is not using `C` or `POSIX` for its collation setting (which you can check with `SELECT datcollate FROM pg_database WHERE datname = current_database();`),
your indexes might be inconsistent, if you ever ran with a version of glibc prior to 2.28 and did not immediately reindex your databases after updating to glibc 2.28 or newer.
{{< hint style="info" >}}
You may have found this page because of **PgHero** warnings about "Duplicate Indexes". While such warnings can sometimes be indicative of an issue in deploying or updating Mastodon, **they are not related to database index corruption and not indicative of any functional issue with your database**.
{{< /hint >}}
You can check whether your indexes are consistent using [PostgreSQL's `amcheck` module](https://www.postgresql.org/docs/10/amcheck.html): as the database server's super user, connect to your Mastodon database and issue the following (this may take a while):
```SQL
@ -79,14 +83,28 @@ Unless you take action, if you are affected, your database could get more and mo
Mastodon 3.2.2 and later come with a semi-interactive script to fix those corruptions as best as possible. If you're on an earlier version, update to 3.2.2 first. It is possible that running the database migrations to 3.2.2 will fail because of those very corruptions, but the database should then be brought to a state that the maintenance tool bundled with Mastodon 3.2.2 can then recover from.
Before attempting to fix your database, stop Mastodon and make a backup of your database. Then, with Mastodon still stopped, run the maintenance script:
Before attempting to fix your database, **stop Mastodon and make a backup of your database**. Then, with **Mastodon still stopped**, run the maintenance script:
```
RAILS_ENV=production tootctl maintenance fix-duplicates
```
The tool will walk through the database to find duplicate and fix them. In some cases, those operations are destructive. In the most destructive cases, you will be asked to chose which record to keep. In all cases, walking through the whole database in search of duplicates is an extremely long operation. Mastodon **has** to be stopped during the whole process to prevent additional duplicates from occuring.
The script will walk through the database to automatically find duplicates and fix them. In some cases, those operations are destructive. In the most destructive cases, you will be asked to choose which record to keep and which records to discard. In all cases, walking through the whole database in search of duplicates is an extremely long operation.
{{< hint style="warning" >}}
In some cases, duplicate records may have unreconcilable conflicts (such as two different local users sharing the same username). In these cases, the deduplication operation may be **partially destructive** and you will be asked which records to keep unchanged and which records will be changed.
This script is therefore semi-interactive. In all cases, walking through the whole database in search of duplicates is an extremely long operation.
{{< /hint >}}
{{< hint style="danger" >}}
**Because the maintenance script will temporarily remove indexes, Mastodon has to be completely stopped during the whole process to prevent additional duplicates from occurring.**
{{< /hint >}}
## Avoiding the issue
To avoid the issue, reindex your database immediately after any libc update.
The
[SQL command `REINDEX`](https://www.postgresql.org/docs/current/sql-reindex.html)
or the
[`reindexdb` command-line tool](https://www.postgresql.org/docs/current/app-reindexdb.html)
may be useful for this.

18
content/en/admin/upgrading.md
View File

@ -7,10 +7,20 @@ menu:
---
{{< hint style="info" >}}
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.
When a new version of Mastodon comes out, it appears on the [GitHub releases page](https://github.com/mastodon/mastodon/releases). Please mind that running unreleased code from the `main` branch, while possible, is not recommended.
{{< /hint >}}
Mastodon releases correspond to git tags. Before attempting an upgrade, look up the desired release on the [GitHub releases page](https://github.com/tootsuite/mastodon/releases). The page will contain a **changelog** describing everything you need to know about what's different, as well as **specific upgrade instructions**.
### Automatic update verification {#automated_checks}
Since v4.2.0, Mastodon will automatically check for available updates and notify the users of your server that have the `DevOps` permission.
This happens by fetching `https://api.joinmastodon.org/update-check?version=<current_version>` in the background every 30 minutes. `current_version` omits the build metadata (everything after the first `+`, if there is one, in the version string). For instance, if your version is `4.3.0-beta2+my-fork`, Mastodon will query `https://api.joinmastodon.org/update-check?version=4.3.0-beta2`.
You can change which URL Mastodon queries by setting the `UPDATE_CHECK_URL` environment variable. You can also completely disable this behavior by setting this environment variable to an empty string, although we strongly recommend against doing that unless you are keeping up with Mastodon updates in another way, as Mastodon occasionally releases critical security updates that must be applied in a timely fashion.
### Upgrade steps
Mastodon releases correspond to git tags. Before attempting an upgrade, look up the desired release on the [GitHub releases page](https://github.com/mastodon/mastodon/releases). The page will contain a **changelog** describing everything you need to know about what's different, as well as **specific upgrade instructions**.
To begin, switch to the `mastodon` user:
@ -59,14 +69,14 @@ systemctl reload mastodon-web
The `reload` operation is a zero-downtime restart, also called "phased restart". As such, Mastodon upgrades usually do not require any advance notice to users about planned downtime. In rare cases, you can use the `restart` operation instead, but there will be a (short) felt interruption of service for your users.
{{< /hint >}}
Rarely, the **streaming API** server is also updated and requires a restart:
The **streaming API** server is also updated and requires a restart, doing so will result in all connected clients being disconnected, which can increase load on your server:
```bash
systemctl restart mastodon-streaming
```
{{< hint style="danger" >}}
The streaming API server is updated very rarely, and in most releases, does *not* require a restart. Restarting the streaming API leads to an increased load on your server as disconnected clients attempt to reconnect or poll the REST API instead, so avoid it whenever you can.
Restarting the streaming API leads to an increased load on your server as disconnected clients attempt to reconnect or poll the REST API instead, so avoid it whenever you can.
{{< /hint >}}
{{< hint style="success" >}}

154
content/en/api/guidelines.md Normal file
View File

@ -0,0 +1,154 @@
---
title: Guidelines and best practices
description: Things to keep in mind when implementing a Mastodon app.
menu:
docs:
weight: 10
parent: api
---
## Login {#login}
**The user must be able to login to any Mastodon server from the app**. This means you must ask for the server's domain and use the app registrations API to dynamically obtain OAuth2 credentials.
{{< page-ref page="client/authorized" >}}
{{< page-relref ref="methods/oauth" caption="oauth methods" >}}
{{< page-relref ref="api/oauth-scopes" caption="OAuth scopes" >}}
## Usernames {#username}
**Decentralization must be transparent to the user**. It should be possible to see that a given user is from another server, for example, by displaying their `acct` somewhere. Note that `acct` is equal to `username` for local users, and equal to `username@domain` for remote users.
## Handling and sorting IDs {#id}
Vanilla Mastodon entity IDs are generated as integers and cast to string. However, this does not mean that IDs _are_ integers, nor should they be cast to integer! Doing so can lead to broken client apps due to integer overflow, so **always treat IDs as strings.**
With that said, because IDs are string representations of numbers, they can still be sorted chronologically very easily by doing the following:
1. Sort by size. Newer statuses will have longer IDs.
2. Sort lexically. Newer statuses will have at least one digit that is higher when compared positionally.
## Paginating through API responses {#pagination}
Many API methods allow you to paginate for more information, using parameters such as `limit`, `max_id`, `min_id`, and `since_id`.
limit
: The maximum number of results to return. Usually, there is a default limit and a maximum limit; these will vary according to the API method.
max_id
: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
since_id
: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
min_id
: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward. (Available since v2.6.0.)
For example, we might fetch `https://mastodon.example/api/v1/accounts/1/statuses` with certain parameters, and we will get the following results in the following cases:
- Setting `?max_id=1` will return no statuses, since there are no statuses with an ID earlier than `1`.
- Setting `?since_id=1` will return the latest statuses, since there have been many statuses since `1`.
- Setting `?min_id=1` will return the oldest statuses, as `min_id` sets the cursor.
Some API methods operate on entity IDs that are not publicly exposed in the API response, and are only known to the backend and the database. (This is usually the case for entities that reference other entities, such as Follow entities which reference Accounts, or Favourite entities which reference Statuses, etc.)
To get around this, Mastodon may return links to a "prev" and "next" page. These links are made available via the HTTP `Link` header on the response. Consider the following fictitious API call:
```http
GET https://mastodon.example/api/v1/endpoint HTTP/1.1
Authorization: Bearer token
Link: <https://mastodon.example/api/v1/endpoint?max_id=7163058>; rel="next", <https://mastodon.example/api/v1/endpoint?min_id=7275607>; rel="prev"
[
{
// some Entity
},
// more Entities in an Array
]
```
In this case, you may retrieve the `Link` header and parse it for links to the older or newer page. Keep in mind the following rules:
- The links will be returned all via one `Link` header, separated by a comma and a space (`, `)
- Each link consists of a URL and a link relation, separated by a semicolon and a space (`; `)
- The URL will be surrounded by angle brackets (`<>`), and the link relation will be surrounded by double quotes (`""`) and prefixed with `rel=`.
- The value of the link relation will be either `prev` or `next`.
Following the `next` link should show you older results. Following the `prev` link should show you newer results.
## Formatting {#formatting}
Plain text is not available for content from remote servers, and plain text syntax rules may vary wildly between Mastodon and other fediverse applications. For certain attributes, such as the content of statuses, **Mastodon provides sanitized HTML**. See [HTML Sanitization]({{< relref "spec/activitypub#sanitization" >}}) for more details. You may expect these tags to appear in the content:
* `<p>`
* `<br>`
* `<span>`
* `<a>`
{{< page-relref ref="spec/activitypub#sanitization" caption="ActivityPub > HTML Sanitization" >}}
### Mentions, hashtags, and custom emoji {#tags}
Mentions and hashtags are `<a>` tags. Custom emoji remain in their plain text shortcode form. To give those entities their semantic meaning and add special handling, such as opening a mentioned profile within your app instead of as a web page, metadata is included with the [Status]({{< relref "entities/Status" >}}), which can be matched to a particular tag.
{{< page-relref ref="entities/Status" caption="Status entity" >}}
{{< page-relref ref="entities/Status#mentions" caption="Status#mentions" >}}
{{< page-relref ref="entities/Status#tags" caption="Status#tags" >}}
{{< page-relref ref="entities/Status#emojis" caption="Status#emojis" >}}
### Link shortening {#links}
Links in Mastodon are not shortened using URL shorteners, and the usage of URL shorteners is heavily discouraged. URLs in text always count for 23 characters, and are intended to be shortened visually. For that purpose, a link is marked up like this:
```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 {#filters}
### Server-side filtering (v2, Mastodon 4.0 and above) {#server-filtered}
If a filter applies to a Status, a corresponding FilterResult will be included in the `filtered` attribute. Clients should check this attribute for any matches and use them to apply the intended filter action.
However, client implementations may still want to perform their own rule matching client-side, as this would allow retroactively apply filter changes without re-fetching posts from the server. When doing so, they should take care to not ignore `filtered` entries for which there are other attributes than `keyword_matches`, so as to handle extensions of the filtering system (e.g. `status_matches`).
Matched filters need to be filtered based on context (`home`, `notifications`, `public`, `thread` or `profile`) and expiration date.
When at least one active matched filter has `hide` for `filter_action`, the post should not be shown at all. Otherwise, if at least one active matched filter has `warn` for `filter_action`, the post should be hidden with a warning, and the user should be able to reveal the post after being informed of which filters matched (identified by `title` rather than the exact matched keywords).
For extension purposes, unknown values for `filter_action` should be treated as `warn`.
### Client-side filtering (v1, prior to Mastodon 4.0) {#client-filtered}
Clients must do their own text filtering based on filters returned from the API. The server will apply `irreversible` filters for `home` and `notifications` contexts, but **anything else is still up to the client to filter**! If a status is somehow not removed by an `irreversible` filter, the client should still filter it.
Expired filters are not deleted by the server. They should no longer be applied, but they are still stored by the server, as users may update the expiry time to re-enable the filter. It is up to users to delete those filters eventually, if they wish to do so.
If `whole_word` is true, the client app should do the following:
* Define ‘word constituent characters’ for your app. In the official implementation, it’s `[A-Za-z0-9_]` in JavaScript, and `[[:word:]]` in Ruby. Ruby uses 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.
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/javascript/mastodon/selectors/index.js" caption="app/javascript/mastodon/selectors/index.js" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/feed_manager.rb" caption="app/lib/feed_manager.rb" >}}
## Focal points for cropping media thumbnails {#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 [guide on how focal points are defined](https://github.com/jonom/jquery-focuspoint#1-calculate-your-images-focus-point). In summary, floating points range from -1.0 to 1.0, left-to-right or bottom-to-top. (0,0) is the center of the image. (0.5, 0.5) would be in the center of the upper-right quadrant. (-0.5, -0.5) would be in the center of the lower-left quadrant. For reference, thumbnails in the Mastodon frontend are most commonly 16:9.
{{< figure src="assets/focal-points.jpg" caption="A demonstration of various focal points and their coordinates." >}}

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

@ -3,7 +3,7 @@ title: OAuth Scopes
description: Defining what you have permission to do with the API
menu:
docs:
weight: 10
weight: 20
parent: api
---
@ -11,7 +11,7 @@ menu:
The API is divided up into access scopes. 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\).
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).
{{< hint style="info" >}}
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`.
@ -25,11 +25,12 @@ The set of scopes saved during app creation must include all the scopes that you
- 0.9.0 - read, write, follow
- 2.4.0 - push
- 2.4.3 - granular scopes [https://github.com/tootsuite/mastodon/pull/7929](https://github.com/tootsuite/mastodon/pull/7929)
- 2.6.0 - read:reports deprecated \(unused stub\) [https://github.com/tootsuite/mastodon/pull/8736/commits/adcf23f1d00c8ff6877ca2ee2af258f326ae4e1f](https://github.com/tootsuite/mastodon/pull/8736/commits/adcf23f1d00c8ff6877ca2ee2af258f326ae4e1f)
- 2.6.0 - write:conversations added [https://github.com/tootsuite/mastodon/pull/9009](https://github.com/tootsuite/mastodon/pull/9009)
- 2.9.1 - Admin scopes added [https://github.com/tootsuite/mastodon/pull/9387](https://github.com/tootsuite/mastodon/pull/9387)
- 3.1.0 - Bookmark scopes added
- 2.4.3 - granular scopes [#7929](https://github.com/mastodon/mastodon/pull/7929)
- 2.6.0 - read:reports deprecated (unused stub) [#8736/adcf23f](https://github.com/mastodon/mastodon/pull/8736/commits/adcf23f1d00c8ff6877ca2ee2af258f326ae4e1f)
- 2.6.0 - write:conversations added [#9009](https://github.com/mastodon/mastodon/pull/9009)
- 2.9.1 - Admin scopes added [#9387](https://github.com/mastodon/mastodon/pull/9387)
- 3.1.0 - Bookmark scopes added [#7107](https://github.com/mastodon/mastodon/pull/7107)
- 4.1.0 - Added admin scopes for blocks and allows [#20918](https://github.com/mastodon/mastodon/pull/20918)
## List of scopes
@ -37,12 +38,45 @@ The set of scopes saved during app creation must include all the scopes that you
Grants access to read data. Requesting `read` will also grant child scopes shown in the left column of the table below.
* `read`
* `read:accounts`
* `read:blocks`
* `read:bookmarks`
* `read:favourites`
* `read:filters`
* `read:follows`
* `read:lists`
* `read:mutes`
* `read:notifications`
* `read:search`
* `read:statuses`
### `write` {#write}
Grants access to write data. Requesting `write` will also grant child scopes shown in the right column of the table below.
* `write`
* `write:accounts`
* `write:blocks`
* `write:bookmarks`
* `write:conversations`
* `write:favourites`
* `write:filters`
* `write:follows`
* `write:lists`
* `write:media`
* `write:mutes`
* `write:notifications`
* `write:reports`
* `write:statuses`
### `follow` {#follow}
{{< hint style="danger" >}}
**Deprecated**\
This scope has been deprecated in 3.5.0 and newer. You should instead request the child scopes individually, or request read/write permission as needed.
{{< /hint >}}
Grants access to manage relationships. Requesting `follow` will also grant the following child scopes, shown in bold in the table:
* `read:blocks`, `write:blocks`
@ -51,18 +85,28 @@ Grants access to manage relationships. Requesting `follow` will also grant the f
### `push` {#push}
Grants access to [Web Push API subscriptions.]({{< relref "../methods/notifications/push.md" >}}) Added in Mastodon 2.4.0.
Grants access to [Web Push API subscriptions.]({{< relref "methods/push" >}}) Added in Mastodon 2.4.0.
### Admin scopes {#admin}
Used for moderation API. Added in Mastodon 2.9.1. The following granular scopes are available \(note that there is no singular `admin` scope\):
Used for moderation API. Added in Mastodon 2.9.1. The following granular scopes are available (note that there is no singular `admin` scope):
* `admin:read`
* `admin:read:accounts`
* `admin:read:reports`
* `admin:read:domain_allows`
* `admin:read:domain_blocks`
* `admin:read:ip_blocks`
* `admin:read:email_domain_blocks`
* `admin:read:canonical_email_blocks`
* `admin:write`
* `admin:write:accounts`
* `admin:write:reports`
* `admin:write:domain_allows`
* `admin:write:domain_blocks`
* `admin:write:ip_blocks`
* `admin:write:email_domain_blocks`
* `admin:write:canonical_email_blocks`
## Granular scopes {#granular}
@ -87,4 +131,8 @@ Used for moderation API. Added in Mastodon 2.9.1. The following granular scopes
| :--- | :--- |
| admin:read:accounts | admin:write:accounts |
| admin:read:reports | admin:write:reports |
| admin:read:domain_allows | admin:write:domain_allows |
| admin:read:domain_blocks | admin:write:domain_blocks |
| admin:read:ip_blocks | admin:write:ip_blocks |
| admin:read:email_domain_blocks | admin:write:email_domain_blocks |
| admin:read:canonical_email_blocks | admin:write:canonical_email_blocks |

52
content/en/api/rate-limits.md
View File

@ -1,31 +1,49 @@
---
title: Rate limits
description: Defining how often you can hit the REST API
description: Defining how often you can call the REST API
menu:
docs:
weight: 20
weight: 30
parent: api
---
## Headers
Rate limit information is returned in the response headers:
|Header|Description|
| :--- | :--- |
|`X-RateLimit-Limit`|Number of requests permitted per time period|
|`X-RateLimit-Remaining`|Number of requests you can still make|
|`X-RateLimit-Reset`|Timestamp when your rate limit will reset|
`X-RateLimit-Limit`
: Number of requests permitted per time period
`X-RateLimit-Remaining`
: Number of requests you can still make
`X-RateLimit-Reset`
: Timestamp when your rate limit will reset
{{< hint style="info" >}}
Mind that an API method can be subject to multiple overlapping rate limits. The headers return information about the one you are closest to exceeding.
An API method can be subject to multiple overlapping rate limits. The headers return information about the one you are closest to exceeding.
{{</ hint >}}
Here is a list of various rate limits:
## Limits
|Endpoint|Bucket|Time period|Limit|Limit type|
| :--- | :--- | :--- | :--- | :--- |
|`* /api/*`|Account access|5 minutes|300|Account|
|`* /api/*`|IP access|5 minutes|300|IP|
|`POST /api/v1/accounts`|App sign-up|30 minutes|5|IP|
|`POST /api/v1/media`|Uploading|30 minutes|30|Account|
|`DELETE /api/v1/statuses/:id`|Deletion|30 minutes|30|Account|
|`POST /api/v1/statuses/:id/unreblog`|Deletion|30 minutes|30|Account|
By default, the following limits are hardcoded:
### Per account
All endpoints and methods can be called 300 times within 5 minutes.
#### Uploading media
`POST /api/v1/media` can be called 30 times within 30 minutes.
#### Deleting statuses
Either `DELETE /api/v1/statuses/:id` or `POST /api/v1/statuses/:id/unreblog` can be called 30 times within 30 minutes.
### Per IP
All endpoints and methods can be called 300 times within 5 minutes.
#### Creating accounts
`POST /api/v1/accounts` can be called 5 times within 30 minutes.

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

@ -11,7 +11,7 @@ menu:
When we registered our app and when we will authorize our user, we need to define what exactly our generated token will have permission to do. This is done through the use of OAuth scopes. Each API method has an associated scope, and can only be called if the token being used for authorization has been generated with the corresponding scope.
Scopes must be a subset. When we created our app, we specified `read write follow push` -- we could simply request all available scopes by specifying `read write follow push`, but it is a better idea to only request what your app will actually need through granular scopes. See [OAuth Scopes]({{< relref "../api/oauth-scopes.md" >}}) for a full list of scopes. Each API method's documentation will also specify the OAuth access level and scope required to call it.
Scopes must be a subset. When we created our app, we specified `read write push` -- we could request all available scopes by specifying `read write push`, but it is a better idea to only request what your app will actually need through granular scopes. See [OAuth Scopes]({{< relref "api/oauth-scopes" >}}) for a full list of scopes. Each API method's documentation will also specify the OAuth access level and scope required to call it.
## **Example authorization code flow** {#flow}
@ -19,29 +19,29 @@ This is similar to the authentication flow from before, but this time, we need t
### Client ID and secret {#client}
First, if you have not already registered a client application, then see [Creating our application]({{< relref "token.md#creating-our-application" >}}) on the previous page or go directly to [POST /api/v1/apps]({{< relref "../methods/apps.md#create-an-application" >}}) for the full documentation of that method. We will need the `client_id` and `client_secret` for our application.
First, if you have not already registered a client application, then see [Creating our application]({{< relref "client/token#creating-our-application" >}}) on the previous page or go directly to [POST /api/v1/apps]({{< relref "methods/apps#create" >}}) for the full documentation of that method. We will need the `client_id` and `client_secret` for our application.
### Authorize the user {#login}
To authorize a user, request [GET /oauth/authorize]({{< relref "../methods/apps/oauth.md#authorize-a-user" >}}) in a browser with the following query parameters:
To authorize a user, request [GET /oauth/authorize]({{< relref "methods/oauth#authorize" >}}) in a browser with the following query parameters:
```bash
https://mastodon.example/oauth/authorize
?client_id=CLIENT_ID
&scope=read+write+follow+push
&scope=read+write+push
&redirect_uri=urn:ietf:wg:oauth:2.0:oob
&response_type=code
```
Note the following:
* `client_id` and `client_secret` were obtained when registering our application.
* `scope` must be a subset of our registered app's registered scopes. It is a good idea to only request what you need. See [OAuth Scopes]({{< relref "../api/oauth-scopes.md" >}}) for more information.
* `client_id` was obtained when registering our application.
* `scope` must be a subset of our registered app's registered scopes. It is a good idea to only request what you need. See [OAuth Scopes]({{< relref "api/oauth-scopes" >}}) for more information.
* `redirect_uri` is one of the URIs we registered with our app. We are still using "out of band" for this example, which means we will have to manually copy and paste the resulting code, but if you registered your application with a URI that you control, then the code will be returned as a query parameter `code` and can be logged by your request handler. See the response section of the API method documentation for more information on this.
### Obtain the token {#token}
Now that we have an authorization `code`, let's obtain an access token that will authenticate our requests as the authorized user. To do so, use [POST /oauth/token]({{< relref "../methods/apps/oauth.md#obtain-a-token" >}}) like before, but pass the authorization code we just obtained:
Now that we have an authorization `code`, let's obtain an access token that will authenticate our requests as the authorized user. To do so, use [POST /oauth/token]({{< relref "methods/oauth#token" >}}) like before, but pass the authorization code we just obtained:
```bash
curl -X POST \
@ -50,7 +50,7 @@ curl -X POST \
-F 'redirect_uri=urn:ietf:wg:oauth:2.0:oob' \
-F 'grant_type=authorization_code' \
-F 'code=user_authzcode_here' \
-F 'scope=read write follow push' \
-F 'scope=read write push' \
https://mastodon.example/oauth/token
```
@ -59,9 +59,9 @@ Note the following:
* `client_id` and `client_secret` were provided in the response text when you registered your application.
* `redirect_uri` must be one of the URIs defined when registering the application.
* We are requesting a `grant_type` of `authorization_code`, which still defaults to giving us the `read` scope. However, while authorizing our user, we requested a certain `scope` -- pass the exact same value here.
* The `code` can only be used once. If you need to obtain a new token, you will need to have the user authorize again by repeating the above [Authorize the user]({{< relref "authorized.md#authorize-the-user" >}}) step.
* The `code` can only be used once. If you need to obtain a new token, you will need to have the user authorize again by repeating the above [Authorize the user]({{< relref "client/authorized#authorize-the-user" >}}) step.
The response of this method is a [Token]({{< relref "../entities/token.md" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. To use it in requests, add the HTTP header `Authorization: Bearer ...` to any API call that requires OAuth \(i.e., one that is not publicly accessible\). Let's verify that our obtained credentials are working by calling [GET /api/v1/accounts/verify\_credentials]({{< relref "../methods/accounts/#verify-account-credentials" >}}):
The response of this method is a [Token]({{< relref "entities/token" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. To use it in requests, add the HTTP header `Authorization: Bearer ...` to any API call that requires OAuth (i.e., one that is not publicly accessible). Let's verify that our obtained credentials are working by calling [GET /api/v1/accounts/verify_credentials]({{< relref "methods/accounts#verify_credentials" >}}):
```bash
curl \
@ -69,7 +69,7 @@ curl \
https://mastodon.example/api/v1/accounts/verify_credentials
```
If we've obtained our token and formatted our request correctly, we should see our details returned to us as an [Account]({{< relref "../entities/account.md" >}}) entity, with the `source` parameter included.
If we've obtained our token and formatted our request correctly, we should see our details returned to us as an [Account]({{< relref "entities/account" >}}) entity, with the `source` parameter included.
## Performing actions as the authorized user {#actions}
@ -77,48 +77,48 @@ With our OAuth token for the authorized user, we can now perform any action as t
### Publish and delete statuses {#statuses}
* See [POST /api/v1/statuses]({{< relref "../methods/statuses/#publish-new-status" >}}) for how to create statuses.
* See [/api/v1/media]({{< relref "../methods/statuses/media.md" >}}) for creating media attachments.
* See [/api/v1/scheduled\_statuses]({{< relref "../methods/statuses/scheduled_statuses.md" >}}) for managing scheduled statuses.
* See [POST /api/v1/statuses]({{< relref "methods/statuses#create" >}}) for how to create statuses.
* See [/api/v1/media]({{< relref "methods/media" >}}) for creating media attachments.
* See [/api/v1/scheduled_statuses]({{< relref "methods/scheduled_statuses" >}}) for managing scheduled statuses.
### Interact with timelines {#timelines}
* See [/api/v1/timelines]({{< relref "../methods/timelines/" >}}) for accessing timelines.
* See [/api/v1/markers]({{< relref "../methods/timelines/markers.md" >}}) for saving and loading positions in timelines.
* See [/api/v1/statuses]({{< relref "../methods/statuses/" >}}) for performing actions on statuses.
* See [/api/v1/polls]({{< relref "../methods/statuses/polls.md" >}}) for viewing and voting on polls.
* See [/api/v1/lists]({{< relref "../methods/timelines/lists.md" >}}) for obtaining list IDs to use with [GET /api/v1/timelines/list/:list\_id]({{< relref "../methods/timelines/#list-timeline" >}}).
* See [/api/v1/conversations]({{< relref "../methods/timelines/conversations.md" >}}) for obtaining direct conversations.
* See [/api/v1/favourites]({{< relref "../methods/accounts/favourites.md" >}}) for listing favourites.
* See [/api/v1/bookmarks]({{< relref "../methods/accounts/bookmarks.md" >}}) for listing bookmarks.
* See [/api/v1/timelines]({{< relref "methods/timelines" >}}) for accessing timelines.
* See [/api/v1/markers]({{< relref "methods/markers" >}}) for saving and loading positions in timelines.
* See [/api/v1/statuses]({{< relref "methods/statuses" >}}) for performing actions on statuses.
* See [/api/v1/polls]({{< relref "methods/polls" >}}) for viewing and voting on polls.
* See [/api/v1/lists]({{< relref "methods/lists" >}}) for obtaining list IDs to use with [GET /api/v1/timelines/list/:list_id]({{< relref "methods/timelines#list" >}}).
* See [/api/v1/conversations]({{< relref "methods/conversations" >}}) for obtaining direct conversations.
* See [/api/v1/favourites]({{< relref "methods/favourites" >}}) for listing favourites.
* See [/api/v1/bookmarks]({{< relref "methods/bookmarks" >}}) for listing bookmarks.
### Interact with other users {#accounts}
* See [/api/v1/accounts]({{< relref "../methods/accounts/" >}}) for performing actions on other users.
* See [/api/v1/follow\_requests]({{< relref "../methods/accounts/follow_requests.md" >}}) for handling follow requests.
* See [/api/v1/mutes]({{< relref "../methods/accounts/mutes.md" >}}) for listing mutes.
* See [/api/v1/blocks]({{< relref "../methods/accounts/blocks.md" >}}) for listing blocks.
* See [/api/v1/accounts]({{< relref "methods/accounts" >}}) for performing actions on other users.
* See [/api/v1/follow_requests]({{< relref "methods/follow_requests" >}}) for handling follow requests.
* See [/api/v1/mutes]({{< relref "methods/mutes" >}}) for listing mutes.
* See [/api/v1/blocks]({{< relref "methods/blocks" >}}) for listing blocks.
### Receive notifications {#notifications}
* See [/api/v1/notifications]({{< relref "../methods/notifications/" >}}) for managing a user's notifications.
* See [/api/v1/push]({{< relref "../methods/notifications/push.md" >}}) for subscribing to push notifications.
* See [/api/v1/notifications]({{< relref "methods/notifications" >}}) for managing a user's notifications.
* See [/api/v1/push]({{< relref "methods/push" >}}) for subscribing to push notifications.
### Discovery features {#discovery}
* See [/api/v2/search]({{< relref "../methods/search.md" >}}) for querying resources.
* See [/api/v1/suggestions]({{< relref "../methods/accounts/suggestions.md" >}}) for suggested accounts to follow.
* See [/api/v2/search]({{< relref "methods/search#v2" >}}) for querying resources.
* See [/api/v1/suggestions]({{< relref "methods/suggestions" >}}) for suggested accounts to follow.
### Use safety features {#safety}
### User safety features {#safety}
* See [/api/v1/filters]({{< relref "../methods/accounts/filters.md" >}}) for managing filtered keywords.
* See [/api/v1/domain\_blocks]({{< relref "../methods/accounts/domain_blocks.md" >}}) for managing blocked domains.
* See [/api/v1/reports]({{< relref "../methods/accounts/reports.md" >}}) for creating reports.
* See [/api/v1/admin]({{< relref "../methods/admin.md" >}}) for moderator actions.
* See [/api/v1/filters]({{< relref "methods/filters" >}}) for managing filtered keywords.
* See [/api/v1/domain_blocks]({{< relref "methods/domain_blocks" >}}) for managing blocked domains.
* See [/api/v1/reports]({{< relref "methods/reports" >}}) for creating reports.
* See [/api/v1/admin]({{< relref "methods/admin" >}}) for moderator actions.
### Manage account info {#manage}
* See [/api/v1/endorsements]({{< relref "../methods/accounts/endorsements.md" >}}) for managing a user profile's featured accounts.
* See [/api/v1/featured\_tags]({{< relref "../methods/accounts/featured_tags.md" >}}) for managing a user profile's featured hashtags.
* See [/api/v1/preferences]({{< relref "../methods/accounts/preferences.md" >}}) for reading user preferences.
* See [/api/v1/endorsements]({{< relref "methods/endorsements" >}}) for managing a user profile's featured accounts.
* See [/api/v1/featured_tags]({{< relref "methods/featured_tags" >}}) for managing a user profile's featured hashtags.
* See [/api/v1/preferences]({{< relref "methods/preferences" >}}) for reading user preferences.

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

@ -1,54 +0,0 @@
---
title: Guidelines and best practices
description: Things to keep in mind when implementing a Mastodon app.
menu:
docs:
weight: 50
parent: client
---
## Login {#login}
**The user must be able to login to any Mastodon server from the app**. This means you must ask for the server's domain and use the app registrations API to dynamically obtain OAuth2 credentials.
## Usernames {#username}
**Decentralization must be transparent to the user**. It should be possible to see that a given user is from another server, by e.g. displaying their `acct` somewhere. Note that `acct` is equal to username for local users, and equal to username@domain for remote users.
## Handling and sorting IDs {#id}
Vanilla Mastodon entity IDs are generated as integers and cast to string. However, this does not mean that IDs _are_ integers, nor should they be cast to integer! Doing so can lead to broken client apps due to integer overflow, so **always treat IDs as strings.**
With that said, because IDs are string representations of numbers, they can still be sorted chronologically very easily by doing the following:
1. Sort by size. Newer statuses will have longer IDs.
2. Sort lexically. Newer statuses will have at least one digit that is higher when compared positionally.
## Formatting {#formatting}
Plain text is not available for content from remote servers, and plain text syntax rules may vary wildly between Mastodon and other fediverse applications. For certain attributes, such as the content of statuses, **Mastodon provides sanitized HTML**. You may expect these tags to appear in the content: `<p>`, `<br>`, `<span>`, `<a>`. See [HTML Sanitization]({{< relref "../spec/activitypub.md#html-sanitization" >}}) for more details.
### Mentions, hashtags, and custom emoji {#tags}
Mentions and hashtags are `<a>` tags. Custom emoji remain in their plain text shortcode form. To give those entities their semantic meaning and add special handling, such as opening a mentioned profile within your app instead of as a web page, metadata is included with the [Status]({{< relref "../entities/status.md" >}}), which can be matched to a particular tag. See [Status &gt; Rendering attributes]({{< relref "../entities/status.md#rendering-attributes" >}}) for more information.
### Link shortening {#links}
Links in Mastodon are not shortened using URL shorteners, and the usage of URL shorteners is heavily discouraged. URLs in text always count for 23 characters, and are intended to be shortened visually. For that purpose, a link is marked up like this:
```markup
<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 {#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, as users may update the expiry time to re-enable the filter. It is up to users to delete those filters eventually.

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

@ -20,7 +20,7 @@ REST API endpoints can be called with certain HTTP methods, and more than one me
* **PUT** \| **PATCH**: Update a resource.
* **DELETE**: Removes a resource.
Your favorite programming language probably has a utility or library to make HTTP requests. For the purposes of this section, the cURL utility will be used for examples, which is a command-line utility included with many operating systems by default \(as `curl`\).
Your favorite programming language probably has a utility or library to make HTTP requests. For the purposes of this section, the cURL utility will be used for examples, which is a command-line utility included with many operating systems by default (as `curl`).
With cURL, the default HTTP method is GET, but you can specify the type of request to make by using the `--request` or `-X` flag; for example, `curl -X POST` will send a POST request instead of a GET request. You may also want to use the `-i` flag to include additional HTTP headers that may be returned as part of the response where relevant.
@ -34,7 +34,7 @@ Query strings, form data, and JSON submitted via POST body are equally understoo
### Query strings {#query-strings}
Simply request the URL, but append query strings to the end. Query strings can be appended by first typing ? and then appending them in the form of parameter=value. Multiple query strings can be appended by separating them with &. For example:
Request the URL, but append query strings to the end. Query strings can be appended by first typing ? and then appending them in the form of parameter=value. Multiple query strings can be appended by separating them with &. For example:
```bash
curl https://mastodon.example/endpoint?q=test&n=0
@ -64,6 +64,8 @@ curl -X POST \
### JSON {#json}
*JavaScript Object Notation* as defined in ECMA-404. Quick one page overview: https://www.json.org/
Similar to sending form data, but with an additional header to specify that the data is in JSON format. To send a JSON request with cURL, specify the JSON content type with a header, then send the JSON data as form data:
```bash
@ -75,7 +77,7 @@ curl -X POST \
## Data types {#types}
### Multiple values \(Array\) {#array}
### Multiple values (Array) {#array}
An array parameter must encoded using bracket notation, e.g. `array[]=foo&array[]=bar` would be translated into the following:
@ -88,13 +90,13 @@ array = [
As JSON, arrays are formatted like so:
```javascript
```json
{
"array": ["foo", "bar"]
}
```
### Nested parameters \(Hash\) {#hash}
### Nested parameters (Hash) {#hash}
Some parameters need to be nested. For that, bracket notation must also be used. For example, `source[privacy]=public&source[language]=en` would be translated into:
@ -107,7 +109,7 @@ source = {
As JSON, hashes are formatted like so:
```javascript
```json
{
"source": {
"privacy": "public",
@ -116,7 +118,7 @@ As JSON, hashes are formatted like so:
}
```
### True-or-false \(Booleans\) {#boolean}
### True-or-false (Booleans) {#boolean}
A boolean value is considered false for the values `0`, `f`, `F`, `false`, `FALSE`, `off`, `OFF`, considered to not be provided for empty strings, and considered to be true for all other values. When using JSON data, use the literals `true`, `false`, and `null` instead.

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

@ -1,18 +1,22 @@
---
title: Libraries and implementations
description: Interface with the Mastodon API in the programming language of your choice.
description: Code, libraries and SDKs for the Mastodon API in a range of programming languages.
menu:
docs:
weight: 60
parent: client
---
## Apex \(Salesforce\) {#apex-salesforce}
Thank you to our awesome developer community, for supporting the project with a wide range of implementations of the API. If you have built a library or SDK for the Mastodon API, [let us know](https://github.com/mastodon/mastodon/discussions) about it, and it may be included below in a future update.
* [apex-mastodon](https://github.com/tzmfreedom/apex-mastodon)
Remember to check how recently the library was updated, and whether it includes the API features you may want to use.
## C\# \(.NET Standard\) {#c-net-standard}
## Arduino / ESP32 / IoT {#arduino-iot}
* [lyuba](https://github.com/ringtailsoftware/lyuba)
## C# (.NET Standard) {#c-net-standard}
* [MastodonAPI](https://github.com/golf1052/MastodonAPI)
* [Mastodot](https://github.com/yamachu/Mastodot)
* [Mastonet](https://github.com/glacasa/Mastonet)
* [TootNet](https://github.com/cucmberium/TootNet)
@ -23,26 +27,35 @@ menu:
* [mastodonpp](https://schlomp.space/tastytea/mastodonpp)
## Crystal {#crystal}
* [mastodon.cr](https://github.com/decors/mastodon.cr)
## Common Lisp {#common-lisp}
* [mastodon-cl](https://github.com/compufox/mastodon-cl)
* [tooter](https://github.com/Shinmera/tooter)
## Crystal {#crystal}
* [mastodon-api-crystal](https://github.com/renatolond/mastodon-api-crystal)
## Dart
* [mastodon_dart](https://pub.dev/packages/mastodon_dart)
* [mastodon-api](https://github.com/mastodon-dart/mastodon-api)
* [mastodon-oauth](https://github.com/mastodon-dart/mastodon-oauth2)
* [mastodon](https://github.com/mykdavies/Mastodon)
* [dartodon](https://github.com/darkcl/dartodon)
## Elixir {#elixir}
* [hunter](https://github.com/milmazz/hunter)
## Erlang {#erlang}
* [masterldon](https://github.com/igb/masterldon)
## Go {#go}
* [go-mastodon](https://github.com/mattn/go-mastodon)
* [madon](https://github.com/McKael/madon)
* [go-mastodon-api](https://github.com/aaronland/go-mastodon-api)
## Haskell {#haskell}
@ -50,59 +63,96 @@ menu:
## Java {#java}
* [mastodon4j](https://github.com/sys1yagi/mastodon4j)
* [BigBone](https://github.com/andregasser/bigbone)
* [Mastodon4J](https://github.com/Mastodon4J/Mastodon4J)
* [mastodon-jfx](https://github.com/wakingrufus/mastodon-jfx)
## JavaScript {#javascript}
* [megalodon](https://github.com/h3poteto/megalodon)
* [masto.js](https://github.com/neet/masto.js)
* [libodonjs](https://github.com/Zatnosk/libodonjs)
## JavaScript \(Browser\) {#javascript-browser}
## JavaScript (Browser) {#javascript-browser}
* [mastodon.js](https://github.com/Kirschn/mastodon.js)
## JavaScript \(Node.js\) {#javascript-node-js}
## JavaScript (Node.js) {#javascript-node-js}
* [node-mastodon](https://github.com/jessicahayley/node-mastodon)
* [mastodon-api](https://github.com/vanita5/mastodon-api)
## Kotlin {#kotlin}
* [BigBone](https://github.com/andregasser/bigbone)
* [mastodonk](https://github.com/outadoc/mastodonk)
## Nim {#nim}
* [Mastonim](https://github.com/matrix07012/Mastonim)
## Objective-C {#objective-c}
* [Cocotodon](https://github.com/shibafu528/Cocotodon)
## Perl {#perl}
* [Mastodon::Client](https://metacpan.org/pod/Mastodon::Client)
## PHP {#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)
* [mastodon-api-client](https://github.com/vazaha-nl/mastodon-api-client)
* [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)
* [MastodonBotPHP](https://github.com/Eleirbag89/MastodonBotPHP)
* [mastodon-api-php-oauth](https://github.com/yks118/Mastodon-api-php-oauth)
* [mastodon-api-php](https://github.com/colorfield/mastodon-api-php)
* [Mastodon API for Laravel](https://github.com/kawax/laravel-mastodon-api)
* [Mastodon for Drupal](https://www.drupal.org/project/mastodon)
* [Mastodon for Socialite](https://github.com/kawax/socialite-mastodon)
## PowerShell {#powershell}
* [Mastodon](https://github.com/JB405/Mastodon)
## Python {#python}
* [Mastodon.py](https://github.com/halcy/Mastodon.py)
* [mastopy](https://gitlab.com/spla/mastopy)
## R {#r}
* [mastodon](https://github.com/ThomasChln/mastodon)
* [rtoot](https://github.com/schochastics/rtoot)
## Ruby {#ruby}
* [mastodon-api](https://github.com/tootsuite/mastodon-api)
* [mastodon-api](https://github.com/mastodon/mastodon-api)
## Rust {#rust}
* [mammut](https://github.com/Aaronepower/mammut)
* [elefren](https://github.com/pwoolcoc/elefren)
* [megalodon-rs](https://github.com/h3poteto/megalodon-rs)
* [mastodon-async](https://github.com/dscottboggs/mastodon-async)
## Scala {#scala}
* [scaladon](https://github.com/schwitzerm/scaladon)
## Scheme {#scheme}
### Guile {#guile}
* [Guile-Mastodon](https://codeberg.org/WammKD/Guile-Mastodon)
## Swift {#swift}
* [MastodonKit](https://github.com/ornithocoder/MastodonKit)
* [Mastodon.swift](https://github.com/Swiftodon/Mastodon.swift)
* [MastodonKit](https://github.com/MastodonKit/MastodonKit)
* [tootsdk](https://github.com/tootsdk/tootsdk)
* [MastodonAPI](https://github.com/li-bei/MastodonAPI)
## TypeScript {#typescript}
* [tsl-mastodon](https://github.com/typescriptlibs/tsl-mastodon-api)

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

@ -19,7 +19,7 @@ Examples will be written using the fictional Mastodon website, mastodon.example,
Let's take a look at one of the most basic use cases for public data from Mastodon -- the public timelines.
We can try to request [GET /api/v1/timelines/public]({{< relref "../../methods/timelines.md" >}}) like so:
We can try to request [GET /api/v1/timelines/public]({{< relref "methods/timelines" >}}) like so:
```bash
curl https://mastodon.example/api/v1/timelines/public
@ -33,32 +33,32 @@ curl https://mastodon.example/api/v1/timelines/public?limit=2
Our response should be more manageable this time. We can parse or beautify this JSON with our chosen utility, and we should see that the response looks something like this:
```javascript
```json
[
{
"id": "103206804533200177",
"created_at": "2019-11-26T23:27:31.000Z",
...
// ...
"visibility": "public",
...
// ...
},
{
"id": "103206804086086361",
"created_at": "2019-11-26T23:27:32.000Z",
...
// ...
"visibility": "public",
...
// ...
}
]
```
We can do similarly for hashtags by calling [GET /api/v1/timelines/tag/:hashtag]({{< relref "../../methods/timelines.md#hashtag-timeline" >}}) -- here, the colon means that this part of the endpoint is a path parameter. In the case of :hashtag, this means we use the hashtag's name \(and once again, a limit of 2\):
We can do similarly for hashtags by calling [GET /api/v1/timelines/tag/:hashtag]({{< relref "methods/timelines#tag" >}}) -- here, the colon means that this part of the endpoint is a path parameter. In the case of :hashtag, this means we use the hashtag's name (and once again, a limit of 2):
```bash
curl https://mastodon.example/api/v1/timelines/tag/cats?limit=2
```
We should once again see 2 statuses have been returned in a JSON array of [Status]({{< relref "../entities/status.md" >}}) entities. We can parse the JSON by array, then by object. If we were using Python, our code might look something like this:
We should once again see 2 statuses have been returned in a JSON array of [Status]({{< relref "entities/status" >}}) entities. We can parse the JSON by array, then by object. If we were using Python, our code might look something like this:
```python
import requests
@ -78,17 +78,17 @@ Parsing JSON and using it in your program is outside of the scope of this tutori
[MastoVue](https://mastovue.glitch.me) is an example of an application that lets you browse public timelines.
{{< /hint >}}
## Fetching public accounts and statuses {#toots}
## Fetching public accounts and statuses {#posts}
Now that we are familiar with how to make requests and how to handle responses, you can experiment with more public data. The following methods may be of interest:
* Once you know an account's id, you can use [GET /api/v1/accounts/:id]({{< relref "../../methods/accounts.md" >}}) to view the [Account]({{< relref "../entities/account.md" >}}) entity.
* To view public statuses posted by that account, you can use [GET /api/v1/accounts/:id/statuses]({{< relref "../../methods/statuses.md" >}}) and parse the resulting array of [Status]({{< relref "../entities/status.md" >}}) entities.
* Once you know a status's id, you can use [GET /api/v1/statuses/:id]({{< relref "../../methods/statuses.md#view-specific-status" >}}) to view the Status entity.
* You can also use [GET /api/v1/statuses/:id/reblogged\_by]({{< relref "../../methods/statuses.md#boosted-by" >}}) to view who boosted that status,
* or [GET /api/v1/statuses/:id/favourited\_by]({{< relref "../../methods/statuses.md#favourited-by" >}}) to view who favourited that status.
* Requesting [GET /api/v1/statuses/:id/context]({{< relref "../../methods/statuses.md#parent-and-child-statuses" >}}) will show you the ancestors and descendants of that status in the tree that is the conversational thread.
* If the status has a poll attached, you can use [GET /api/v1/polls/:id]({{< relref "../../methods/statuses/polls.md" >}}) to view the poll separately.
* Once you know an account's id, you can use [GET /api/v1/accounts/:id]({{< relref "methods/accounts" >}}) to view the [Account]({{< relref "entities/account" >}}) entity.
* To view public statuses posted by that account, you can use [GET /api/v1/accounts/:id/statuses]({{< relref "methods/statuses" >}}) and parse the resulting array of [Status]({{< relref "entities/status" >}}) entities.
* Once you know a status's id, you can use [GET /api/v1/statuses/:id]({{< relref "methods/statuses#get-one" >}}) to view the Status entity.
* You can also use [GET /api/v1/statuses/:id/reblogged_by]({{< relref "methods/statuses#boosted_by" >}}) to view who boosted that status,
* or [GET /api/v1/statuses/:id/favourited_by]({{< relref "methods/statuses#favourited_by" >}}) to view who favourited that status.
* Requesting [GET /api/v1/statuses/:id/context]({{< relref "methods/statuses#context" >}}) will show you the ancestors and descendants of that status in the tree that is the conversational thread.
* If the status has a poll attached, you can use [GET /api/v1/polls/:id]({{< relref "methods/polls" >}}) to view the poll separately.
IDs of accounts and statuses are local to the Mastodon website's database and will differ for each Mastodon website.
@ -96,12 +96,12 @@ IDs of accounts and statuses are local to the Mastodon website's database and wi
One last thing you can do with anonymous requests is to view information about the Mastodon website.
* View general information with [GET /api/v1/instance]({{< relref "../../methods/instance.md#fetch-instance" >}}),
* view its peers with [GET /api/v1/instance/peers]({{< relref "../../methods/instance.md#list-of-connected-domains" >}}) or
* its weekly activity with [GET /api/v1/instance/activity]({{< relref "../../methods/instance.md#weekly-activity" >}}), or to
* list all custom emoji available with [GET /api/v1/custom\_emojis]({{< relref "../../methods/instance/custom_emojis.md#custom-emoji" >}}).
* See [GET /api/v1/directory]({{< relref "../../methods/instance/directory.md#view-profile-directory" >}}) for a directory of all available profiles.
* See [GET /api/v1/trends]({{< relref "../../methods/instance/trends.md#trending-tags" >}}) for currently trending hashtags.
* View general information with [GET /api/v1/instance]({{< relref "methods/instance#fetch-instance" >}}),
* view its peers with [GET /api/v1/instance/peers]({{< relref "methods/instance#peers" >}}) or
* its weekly activity with [GET /api/v1/instance/activity]({{< relref "methods/instance#activity" >}}), or to
* list all custom emoji available with [GET /api/v1/custom_emojis]({{< relref "methods/custom_emojis" >}}).
* See [GET /api/v1/directory]({{< relref "methods/directory" >}}) for a directory of all available profiles.
* See [GET /api/v1/trends]({{< relref "methods/trends" >}}) for currently trending hashtags.
{{< hint style="info" >}}
For a practical example of what you can do with just instance data, see [emojos.in](https://emojos.in/), which lets you preview all custom emoji at a given instance.

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

@ -9,9 +9,9 @@ menu:
## Authentication and authorization {#auth}
Up until this point, we've been working with publicly available information, but not all information is public. Some information requires permission before viewing it, in order to audit who is requesting that information \(and to potentially revoke or deny access\).
Up until this point, we've been working with publicly available information, but not all information is public. Some information requires permission before viewing it, in order to audit who is requesting that information (and to potentially revoke or deny access).
This is where [OAuth]({{< relref "../spec/oauth.md" >}}) comes in. OAuth is a mechanism for generating access tokens which can be used to _authenticate \(verify\)_ that a request is coming from a specific client, and ensure that the requested action is _authorized \(allowed\)_ by the server's access control policies.
This is where [OAuth]({{< relref "spec/oauth" >}}) comes in. OAuth is a mechanism for generating access tokens which can be used to _authenticate (verify)_ that a request is coming from a specific client, and ensure that the requested action is _authorized (allowed)_ by the server's access control policies.
## Creating our application {#app}
@ -21,7 +21,7 @@ The first thing we will need to do is to register an application, in order to be
curl -X POST \
-F 'client_name=Test Application' \
-F 'redirect_uris=urn:ietf:wg:oauth:2.0:oob' \
-F 'scopes=read write follow push' \
-F 'scopes=read write push' \
-F 'website=https://myapp.example' \
https://mastodon.example/api/v1/apps
```
@ -29,13 +29,13 @@ curl -X POST \
In the above example, we specify the client name and website, which will be shown on statuses if applicable. But more importantly, note the following two parameters:
* `redirect_uris` has been set to the "out of band" token generation, which means that any generated tokens will have to be copied and pasted manually. The parameter is called `redirect_uris` because it is possible to define more than one redirect URI, but when generating the token, we will need to provide a URI that is included within this list.
* `scopes` allow us to define what permissions we can request later. However, the requested scope later can be a subset of these registered scopes. See [OAuth Scopes]({{< relref "../api/oauth-scopes.md" >}}) for more information.
* `scopes` allow us to define what permissions we can request later. However, the requested scope later can be a subset of these registered scopes. See [OAuth Scopes]({{< relref "api/oauth-scopes" >}}) for more information.
We should see an Application entity returned, but for now we only care about client\_id and client\_secret. These values will be used to generate access tokens, so they should be cached for later use. See [POST /api/v1/apps]({{< relref "../../methods/apps.md#create-an-application" >}}) for more details on registering applications.
We should see an Application entity returned, but for now we only care about client_id and client_secret. These values will be used to generate access tokens, so they should be cached for later use. See [POST /api/v1/apps]({{< relref "methods/apps#create" >}}) for more details on registering applications.
## Example authentication code flow {#flow}
Now that we have an application, let's obtain an access token that will authenticate our requests as that client application. To do so, use [POST /oauth/token]({{< relref "../../methods/apps/oauth.md#obtain-a-token" >}}) like so:
Now that we have an application, let's obtain an access token that will authenticate our requests as that client application. To do so, use [POST /oauth/token]({{< relref "methods/oauth#token" >}}) like so:
```bash
curl -X POST \
@ -52,7 +52,7 @@ Note the following:
* `redirect_uri` must be one of the URIs defined when registering the application.
* We are requesting a `grant_type` of `client_credentials`, which defaults to giving us the `read` scope.
The response of this method is a [Token]({{< relref "../entities/token.md" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. To use it in requests, add the HTTP header `Authorization: Bearer ...` to any API call that requires OAuth \(i.e., one that is not publicly accessible\). Let's verify that our obtained credentials are working by calling [GET /api/v1/apps/verify\_credentials]({{< relref "../methods/apps.md#verify-your-app-works" >}}):
The response of this method is a [Token]({{< relref "entities/token" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. To use it in requests, add the HTTP header `Authorization: Bearer ...` to any API call that requires OAuth (i.e., one that is not publicly accessible). Let's verify that our obtained credentials are working by calling [GET /api/v1/apps/verify_credentials]({{< relref "methods/apps#verify_credentials" >}}):
```bash
curl \
@ -60,9 +60,9 @@ curl \
https://mastodon.example/api/v1/apps/verify_credentials
```
If we've obtained our token and formatted our request correctly, we should see our details returned to us as an [Application]({{< relref "../entities/application.md" >}}) entity.
If we've obtained our token and formatted our request correctly, we should see our details returned to us as an [Application]({{< relref "entities/application" >}}) entity.
## What we can do with authentication {#methods}
With our authenticated client application, we can view relations of an account with [GET /api/v1/accounts/:id/following]({{< relref "../methods/accounts.md#following" >}}) and [GET /api/v1/accounts/:id/followers]({{< relref "../methods/accounts.md#followers" >}}). Also, some instances may require authentication for methods that would otherwise be public, so if you encountered any authentication errors while playing around with public methods, then those methods should now work.
With our authenticated client application, we can view relations of an account with [GET /api/v1/accounts/:id/following]({{< relref "methods/accounts#following" >}}) and [GET /api/v1/accounts/:id/followers]({{< relref "methods/accounts#followers" >}}). Also, some instances may require authentication for methods that would otherwise be public, so if you encountered any authentication errors while playing around with public methods, then those methods should now work.

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

@ -7,55 +7,67 @@ menu:
parent: dev
---
{{< hint style="danger" >}}
This page is under construction.
{{< /hint >}}
### Code structure {#structure}
The following overview should not be seen as complete or authoritative, but as a rough guidance to help you find your way in the application.
#### Ruby {#ruby}
| Path | Description |
| :--- | :--- |
| `app/controllers` | Code that binds business logic to templates |
| `app/helpers` | Code that can be used from views, i.e. common operations |
| `app/lib` | Code that doesn’t fit in the other categories |
| `app/models` | Code that represents data entities |
| `app/serializers` | Code that generates JSON from models |
| `app/services` | Complex logical operations involving multiple models |
| `app/views` | Templates for generating HTML or other output |
| `app/workers` | Code that executes outside the request-response cycle |
| `spec` | Automated test suite |
`app/controllers`
: Code that binds business logic to templates
`app/helpers`
: Code that can be used from views, i.e. common operations
`app/lib`
: Code that doesn’t fit in the other categories
`app/models`
: Representation of data entities and their associated methods
`app/policies`
: Permission checks and other validations, before calling related methods
`app/serializers`
: Code that generates JSON from models
`app/services`
: Complex logical operations involving multiple models
`app/views`
: Templates for generating HTML or other output
`app/workers`
: Code that executes outside the request-response cycle
`spec`
: Automated test suite
#### JavaScript {#javascript}
| Path | Description |
| :--- | :--- |
| `app/javascript/mastodon` | Code for the multi-column React.js application |
| `app/javascript/packs` | Code for non-React.js pages |
`app/javascript/mastodon`
: Code for the frontend React.js application
`app/javascript/packs`
: Code for non-React.js pages
#### CSS and other assets {#assets}
| Path | Description |
| :--- | :--- |
| `app/javascript/images` | Images |
| `app/javascript/styles` | Code that turns into CSS via Sass |
`app/javascript/images`
: Images
`app/javascript/styles`
: Code that turns into CSS via Sass
#### Localizations {#localizations}
| Path | Description |
| :--- | :--- |
| `config/locales` | Server-side localizations in the YML format |
| `app/javascript/mastodon/locales` | Client-side localizations in the JSON format |
`config/locales`
: Server-side localizations in the YML format
### Localization maintenance {#localization-maintenance}
`app/javascript/mastodon/locales`
: Client-side localizations in the JSON format
All locale files are normalized to ensure consistent formatting and key order, which minimizes changesets in version control.
| Command | Description |
| :--- | :--- |
| `i18n-tasks normalize` | Normalize server-side translations |
| `yarn run manage:translations` | Normalize client-side translations |
- Run `bundle exec i18n-tasks normalize` to normalize server-side translations
- Run `yarn run i18n:extract` to extract and normalize client-side translations into `en.json`

2
content/en/dev/disclosure.md
View File

@ -7,7 +7,7 @@ menu:
parent: dev
---
If you believe you've identified a security vulnerability in Mastodon (a bug that allows something to happen that shouldn't be possible), you should send the report to **hello@joinmastodon.org**. We will gladly reward such reports in proportion to the severity of the issue through our OpenCollective fund.
If you believe you've identified a security vulnerability in Mastodon (a bug that allows something to happen that shouldn't be possible), you should send the report to **security@joinmastodon.org**. We will gladly reward such reports in proportion to the severity of the issue through our OpenCollective fund.
You should *not* report such issues on GitHub or in other public spaces to give us time to publish a fix for the issue without exposing Mastodon's users to increased risk.

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

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

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

@ -7,7 +7,7 @@ menu:
parent: dev
---
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/config/routes.rb" caption="config/routes.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/config/routes.rb" caption="config/routes.rb" >}}
## Explanation of routes {#routes}
@ -37,7 +37,7 @@ end
The first available resource is :statuses, which is nested under the :api and :v1 namespaces. Thus, the resulting HTTP route will be /api/v1/statuses. The `only` defines certain allowed methods, which are to be defined in the controller at `app/controllers/api/v1/statuses_controller.rb`.
Within /api/v1/statuses, there is a scope for a module :statuses, where additional resources are defined. The controllers for these resources live in `app/controllers/api/v1/statuses/`. For example, :favourite will be handled by the \#create action within `app/controllers/api/v1/statuses/favourites_controller.rb` and :unfavourite will be handled within the same controller, but by the \#destroy action.
Within /api/v1/statuses, there is a scope for a module :statuses, where additional resources are defined. The controllers for these resources live in `app/controllers/api/v1/statuses/`. For example, :favourite will be handled by the #create action within `app/controllers/api/v1/statuses/favourites_controller.rb` and :unfavourite will be handled within the same controller, but by the #destroy action.
There is also a custom method defined for any `member` within this scope, or in other words, for any status to be controlled by `app/controllers/api/v1/statuses_controller.rb`, which is mapped to GET /api/v1/statuses/:id/context and handled by the :context action defined within that controller.
@ -45,37 +45,37 @@ There is also a custom method defined for any `member` within this scope, or in
#### :index
Maps to HTTP GET, for a list. Handled by the \#index action in a controller.
Maps to HTTP GET, for a list. Handled by the #index action in a controller.
#### :show
Maps to HTTP GET, for a single view. Handled by the \#show action in a controller.
Maps to HTTP GET, for a single view. Handled by the #show action in a controller.
#### :create
Maps to HTTP POST. Handled by the \#create action in a controller.
Maps to HTTP POST. Handled by the #create action in a controller.
#### :update
Maps to HTTP PUT. Handled by the \#update action in a controller.
Maps to HTTP PUT. Handled by the #update action in a controller.
#### :destroy
Maps to HTTP DELETE. Handled by the \#destroy action in a controller.
Maps to HTTP DELETE. Handled by the #destroy action in a controller.
## .well-known {#well-known}
### /.well-known/host-meta {#host-meta}
Extensible Resource Descriptor \(XRD\). Advertises existence of Webfinger.
Extensible Resource Descriptor (XRD). Advertises existence of Webfinger.
### /.well-known/nodeinfo {#nodeinfo}
Maps to NodeInfo 2.0 endpoint at `/nodeinfo/2.0`, used for advertising software name and version, protocols, usage statistics, and whether registrations are open.
### /.well-know/webfinger {#webfinger}
### /.well-known/webfinger {#webfinger}
Used for discovering ActivityPub actor id. See [Spec compliance &gt; WebFinger]({{< relref "../spec/webfinger.md" >}}) for more information.
Used for discovering ActivityPub actor id. See [Spec compliance &gt; WebFinger]({{< relref "spec/webfinger" >}}) for more information.
### /.well-known/change-password {#change-password}
@ -94,8 +94,8 @@ The sections below this point are under construction.
* `/users/username` = user URI
* `/users/username/remote_follow` = remote follow dialog
* `/users/username/statuses/id` = status URI
* `/@username` = "toots" tab
* `/@username/with_replies` = "toots and replies" tab
* `/@username` = "posts" tab
* `/@username/with_replies` = "posts and replies" tab
* `/@username/media` = "media" tab
* `/@username/tagged/:hashtag` = tagged statuses by user
* `/@username/:status_id` = status permalink
@ -113,95 +113,95 @@ The sections below this point are under construction.
* /api/oembed
* /api/proofs
* /api/v1
* [statuses]({{< relref "../methods/statuses/" >}}) \[create, show, destroy\]
* reblogged\_by \[index\]
* favourited\_by \[index\]
* reblog \[create\]
* unreblog \[POST reblog\#destroy\]
* favourite \[create\]
* unfavourite \[POST favourites\#destroy\]
* bookmark \[create\]
* unbookmark \[POST bookmarks\#destroy\]
* mute \[create\]
* unmute \[POST mutes\#destroy\]
* pin \[create\]
* unpin \[POST pins\#destroy\]
* context \[GET\]
* [timelines]({{< relref "../methods/timelines/" >}})
* home \[show\]
* public \[show\]
* tag \[show\]
* list \[show\]
* [streaming]({{< relref "../methods/timelines/streaming.md" >}}) \[index\]
* [custom\_emojis]({{< relref "../methods/instance/custom_emojis.md" >}}) \[index\]
* [suggestions]({{< relref "../methods/accounts/suggestions.md" >}}) \[index, destroy\]
* [scheduled\_statuses]({{< relref "../methods/statuses/scheduled_statuses.md" >}}) \[index, show, update, destroy\]
* [preferences]({{< relref "../methods/accounts/preferences.md" >}}) \[index\]
* [conversations]({{< relref "../methods/timelines/conversations.md" >}}) \[index, destroy\]
* read \[POST\]
* [media]({{< relref "../methods/statuses/media.md" >}}) \[create, update\]
* [blocks]({{< relref "../methods/accounts/blocks.md" >}}) \[index\]
* [mutes]({{< relref "../methods/accounts/mutes.md" >}}) \[index\]
* [favourites]({{< relref "../methods/accounts/favourites.md" >}}) \[index\]
* [bookmarks]({{< relref "../methods/accounts/bookmarks.md" >}}) \[index\]
* [reports]({{< relref "../methods/accounts/reports.md" >}}) \[create\]
* [trends]({{< relref "../methods/instance/trends.md" >}}) \[index\]
* [filters]({{< relref "../methods/accounts/filters.md" >}}) \[index, create, show, update, destroy\]
* [endorsements]({{< relref "../methods/accounts/endorsements.md" >}}) \[index\]
* [markers]({{< relref "../methods/timelines/markers.md" >}}) \[index, create\]
* [apps]({{< relref "../methods/apps/" >}}) \[create\]
* verify\_credentials \[credentials\#show\]
* [instance]({{< relref "../methods/instance/" >}}) \[show\]
* peers \[index\]
* activity \[show\]
* [domain\_blocks]({{< relref "../methods/accounts/domain_blocks.md" >}}) \[show, create, destroy\]
* [directory]({{< relref "../methods/instance/directory.md" >}}) \[show\]
* [follow\_requests]({{< relref "../methods/accounts/follow_requests.md" >}}) \[index\]
* authorize \[POST\]
* reject \[POST\]
* [notifications]({{< relref "../methods/notifications/" >}}) \[index, show\]
* clear \[POST\]
* dismiss \[POST\]
* [accounts]({{< relref "../methods/accounts/" >}})
* verify\_credentials \[GET credentials\#show\]
* update\_credentials \[PATCH credentials\#update\]
* search \[show \(search\#index\)\]
* relationships \[index\]
* [accounts]({{< relref "../methods/accounts/" >}}) \[create, show\]
* statuses \[index accounts/statuses\]
* followers \[index accounts/follower\_accounts\]
* following \[index accounts/following\_accounts\]
* lists \[index accounts/lists\]
* identity\_proofs \[index accounts/identity\_proofs\]
* follow \[POST\]
* unfollow \[POST\]
* block \[POST\]
* unblock \[POST\]
* mute \[POST\]
* unmute \[POST\]
* pin \[POST\]
* unpin \[POST\]
* [lists]({{< relref "../methods/timelines/lists.md" >}}) \[index, create, show, update, destroy\]
* accounts \[POST accounts/pins\#destroy\]
* [featured\_tags]({{< relref "../methods/accounts/featured_tags.md" >}}) \[index, create, destroy\]
* suggestions \[GET suggestions\#index\]
* [polls]({{< relref "../methods/statuses/polls.md" >}}) \[create, show\]
* votes \[create polls/votes\]
* [push]({{< relref "../methods/notifications/push.md" >}})
* subscription \[create, show, update, destroy\]
* [admin]({{< relref "../methods/admin.md" >}})
* accounts \[index, show\]
* enable \[POST\]
* unsilence \[POST\]
* unsuspend \[POST\]
* approve \[POST\]
* reject \[POST\]
* action \[create account\_actions\]
* reports \[index, show\]
* assign\_to\_self \[POST\]
* unassign \[POST\]
* reopen \[POST\]
* resolve \[POST\]
* [statuses]({{< relref "methods/statuses" >}}) [create, show, destroy]
* reblogged_by [index]
* favourited_by [index]
* reblog [create]
* unreblog [POST reblog#destroy]
* favourite [create]
* unfavourite [POST favourites#destroy]
* bookmark [create]
* unbookmark [POST bookmarks#destroy]
* mute [create]
* unmute [POST mutes#destroy]
* pin [create]
* unpin [POST pins#destroy]
* context [GET]
* [timelines]({{< relref "methods/timelines" >}})
* home [show]
* public [show]
* tag [show]
* list [show]
* [streaming]({{< relref "methods/streaming" >}}) [index]
* [custom_emojis]({{< relref "methods/custom_emojis" >}}) [index]
* [suggestions]({{< relref "methods/suggestions" >}}) [index, destroy]
* [scheduled_statuses]({{< relref "methods/scheduled_statuses" >}}) [index, show, update, destroy]
* [preferences]({{< relref "methods/preferences" >}}) [index]
* [conversations]({{< relref "methods/conversations" >}}) [index, destroy]
* read [POST]
* [media]({{< relref "methods/media" >}}) [create, update]
* [blocks]({{< relref "methods/blocks" >}}) [index]
* [mutes]({{< relref "methods/mutes" >}}) [index]
* [favourites]({{< relref "methods/favourites" >}}) [index]
* [bookmarks]({{< relref "methods/bookmarks" >}}) [index]
* [reports]({{< relref "methods/reports" >}}) [create]
* [trends]({{< relref "methods/trends" >}}) [index]
* [filters]({{< relref "methods/filters" >}}) [index, create, show, update, destroy]
* [endorsements]({{< relref "methods/endorsements" >}}) [index]
* [markers]({{< relref "methods/markers" >}}) [index, create]
* [apps]({{< relref "methods/apps" >}}) [create]
* verify_credentials [credentials#show]
* [instance]({{< relref "methods/instance" >}}) [show]
* peers [index]
* activity [show]
* [domain_blocks]({{< relref "methods/domain_blocks" >}}) [show, create, destroy]
* [directory]({{< relref "methods/directory" >}}) [show]
* [follow_requests]({{< relref "methods/follow_requests" >}}) [index]
* authorize [POST]
* reject [POST]
* [notifications]({{< relref "methods/notifications" >}}) [index, show]
* clear [POST]
* dismiss [POST]
* [accounts]({{< relref "methods/accounts" >}})
* verify_credentials [GET credentials#show]
* update_credentials [PATCH credentials#update]
* search [show (search#index)]
* relationships [index]
* [accounts]({{< relref "methods/accounts" >}}) [create, show]
* statuses [index accounts/statuses]
* followers [index accounts/follower_accounts]
* following [index accounts/following_accounts]
* lists [index accounts/lists]
* identity_proofs [index accounts/identity_proofs]
* follow [POST]
* unfollow [POST]
* block [POST]
* unblock [POST]
* mute [POST]
* unmute [POST]
* pin [POST]
* unpin [POST]
* [lists]({{< relref "methods/lists" >}}) [index, create, show, update, destroy]
* accounts [POST accounts/pins#destroy]
* [featured_tags]({{< relref "methods/featured_tags" >}}) [index, create, destroy]
* suggestions [GET suggestions#index]
* [polls]({{< relref "methods/polls" >}}) [create, show]
* votes [create polls/votes]
* [push]({{< relref "methods/push" >}})
* subscription [create, show, update, destroy]
* [admin]({{< relref "methods/admin" >}})
* accounts [index, show]
* enable [POST]
* unsilence [POST]
* unsuspend [POST]
* approve [POST]
* reject [POST]
* action [create account_actions]
* reports [index, show]
* assign_to_self [POST]
* unassign [POST]
* reopen [POST]
* resolve [POST]
* /api/v2
* [search]({{< relref "../methods/search.md" >}}) \[GET search\#index\]
* [search]({{< relref "methods/search" >}}) [GET search#index]

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

@ -7,47 +7,107 @@ menu:
parent: dev
---
{{< hint style="danger" >}}
This page is under construction.
{{< /hint >}}
## Quick start with Vagrant {#vagrant}
### Pre-requisites {#prerequisites}
For convenience, the Mastodon repository includes a Vagrantfile for quickly setting up a development environment without manual configuration. To use this development environment, install [Vagrant](https://vagrantup.com) using a binary executable or through your package manager.
You can follow the [pre-requisites instructions from the production guide](https://docs.joinmastodon.org/admin/install/), but do not create a `mastodon` user. You also don't have to install `nginx`, `certbot` and `python-certbot-nginx` as the development environment brings its own webserver. Setting up and running a development environment has been proven successful over WSL2 as well if you are on Windows.
Once you have Vagrant installed, for convenience, it is recommended to install a plugin to automatically update your machine's hosts file. This will allow you to access the dev environment at `http://mastodon.local` without manually editing the hosts file yourself. To do so:
```sh
vagrant plugin install vagrant-hostsupdater
```
The virtual machine can then be started:
```sh
vagrant up
```
Once the virtual machine has been started, you may launch the Foreman task executor to launch the various Mastodon processes:
```sh
vagrant ssh -c "cd /vagrant && foreman start"
```
Once the Mastodon processes have fully started up, you can load `http://mastodon.local` in your browser to access the Mastodon instance within the VM. You can log in as the default admin user with the username `admin@mastodon.local` and the password `mastodonadmin`.
Any changes to the source code will be reflected after saving your files.
To reset the VM to a fresh state, you can destroy it and bring it up again:
```sh
vagrant destroy
vagrant up
```
## Manual install from source {#manual}
You can follow the [pre-requisites instructions from the production guide]({{<relref "admin/install">}}), but do not create a `mastodon` user. You also don't have to install `nginx`, `certbot` and `python-certbot-nginx` as the development environment brings its own webserver. Setting up and running a development environment has been proven successful over WSL2 as well if you are on Windows.
### Setup {#setup}
Run following commands in the project directory `bundle install`, `yarn install`.
Run the following commands in the project directory:
In the development environment, Mastodon will use PostgreSQL as the currently signed-in Linux user using the `ident` method, which usually works out of the box. The one command you need to run is `rails db:setup` which will create the databases `mastodon_development` and `mastodon_test`, load the schema into them, and then create seed data defined in `db/seed.rb` in `mastodon_development`. The only seed data is an admin account with the credentials `admin@localhost:3000` / `mastodonadmin`.
```sh
bundle install
yarn install
```
> Please keep in mind, by default Mastodon will run on port 3000. If you configure a different port for it, the generated admin account will use that number.
In the development environment, Mastodon will use PostgreSQL as the currently signed-in Linux user using the `ident` method. Ensure that you have created a Postgres user and database for your current signed-in user:
If `rails db:setup` gives you the Postgres error:
```sh
sudo -u postgres createuser $YOUR_USERNAME_HERE --createdb
```
ActiveRecord::NoDatabaseError: FATAL: role "your_user_name" does not exist
You can now create the databases `mastodon_development` and `mastodon_test`, load the schema into them, and create seed data defined in `db/seeds/` into `mastodon_development`.
(where `your_user_name` is your username), then run:
```sh
rails db:setup
```
sudo -u postgres createuser your_user_name --createdb
You can now launch `http://localhost:3000` in your browser and log in with the default admin user (`admin@localhost` / `mastodonadmin`).
This will create the necessary Postgres user with the permission to create a database.
{{<hint style="warning">}}
By default, Mastodon will run on port 3000. If you configure a different port for it, the generated admin account will use that number as well.
{{</hint>}}
### Running {#running}
There are multiple processes that need to be run for the full set of Mastodon’s functionality, although they can be selectively omitted. To run all of them with just one command, you can install Foreman with `gem install foreman --no-document` and then use:
There are multiple processes that need to be run for the full set of Mastodon’s functionality, although they can be selectively omitted. To run all of them with just one command, you can install and use Foreman:
```text
```sh
gem install foreman --no-document
foreman start
```
In the Mastodon directory. This will start processes defined in `Procfile.dev`, which will give you: A Rails server, a Webpack server, a streaming API server, and Sidekiq. Of course, you can run any of those things stand-alone depending on your needs.
This will start processes defined in `Procfile.dev`, which will give you: A Rails server, a Webpack server, a streaming API server, and Sidekiq. Of course, you can run any of those things stand-alone depending on your needs.
### Testing {#testing}
## Working with emails in development
| Command | Description |
| :--- | :--- |
| `rspec` | Run the Ruby test suite |
| `yarn run test` | Run the JavaScript test suite |
| `rubocop` | Check the Ruby code for conformance with our code style |
In development mode, Mastodon will use a gem called [Letter Opener](https://github.com/ryanb/letter_opener) for "sending" emails, which allows you to debug emails in your browser, without actually having to send emails via an SMTP server.
In order to work with emails, you'll need Sidekiq, Redis and PostgreSQL running, and then emails can be viewed by visiting: `http://localhost:3000/letter_opener/`
If you're developing in docker, you'll need to set the `REMOTE_DEV=true` environment variable.
## Useful commands for testing {#testing}
`rspec`
: Run the Ruby test suite
`yarn run test`
: Run the JavaScript test suite
`rubocop`
: Check the Ruby code for conformance with our code style
## Updating your development instance {#update}
`bundle install`
: Update Ruby gems and install any new dependencies
`yarn install`
: Update Javascript packages and install any new dependencies
`RAILS_ENV=development rails db:migrate`
: Run new database migrations for your development instance's database

449
content/en/entities/Account.md Normal file
View File

@ -0,0 +1,449 @@
---
title: Account
description: Represents a user of Mastodon and their associated profile.
menu:
docs:
parent: entities
aliases: [
"/entities/source/",
"/entities/Source/",
"/entities/field/",
"/entities/Field/",
"/entities/account",
"/entities/Account",
"/entities/credentialaccount",
"/entities/CredentialAccount",
"/entities/mutedaccount",
"/entities/MutedAccount",
"/api/entities/source/",
"/api/entities/Source/",
"/api/entities/field/",
"/api/entities/Field/",
"/api/entities/account",
"/api/entities/Account",
"/api/entities/credentialaccount",
"/api/entities/CredentialAccount",
"/api/entities/mutedaccount",
"/api/entities/MutedAccount",
]
---
## Example
```json
{
"id": "23634",
"username": "noiob",
"acct": "noiob@awoo.space",
"display_name": "ikea shark fan account",
"locked": false,
"bot": false,
"created_at": "2017-02-08T02:00:53.274Z",
"note": "<p>:ms_rainbow_flag:​ :ms_bisexual_flagweb:​ :ms_nonbinary_flag:​ <a href=\"https://awoo.space/tags/awoo\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>awoo</span}.space <a href=\"https://awoo.space/tags/admin\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>admin</span} ~ <a href=\"https://awoo.space/tags/bi\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>bi</span} ~ <a href=\"https://awoo.space/tags/nonbinary\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>nonbinary</span} ~ compsci student ~ likes video <a href=\"https://awoo.space/tags/games\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>games</span} and weird/ old electronics and will post obsessively about both ~ avatar by <span class=\"h-card\"><a href=\"https://weirder.earth/@dzuk\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>dzuk</span}</span></p>",
"url": "https://awoo.space/@noiob",
"avatar": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png",
"avatar_static": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png",
"header": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png",
"header_static": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png",
"followers_count": 547,
"following_count": 404,
"statuses_count": 28468,
"last_status_at": "2019-11-17",
"emojis": [
{
"shortcode": "ms_rainbow_flag",
"url": "https://files.mastodon.social/custom_emojis/images/000/028/691/original/6de008d6281f4f59.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/028/691/static/6de008d6281f4f59.png",
"visible_in_picker": true
},
{
"shortcode": "ms_bisexual_flag",
"url": "https://files.mastodon.social/custom_emojis/images/000/050/744/original/02f94a5fca7eaf78.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/050/744/static/02f94a5fca7eaf78.png",
"visible_in_picker": true
},
{
"shortcode": "ms_nonbinary_flag",
"url": "https://files.mastodon.social/custom_emojis/images/000/105/099/original/8106088bd4782072.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/105/099/static/8106088bd4782072.png",
"visible_in_picker": true
}
],
"fields": [
{
"name": "Pronouns",
"value": "they/them",
"verified_at": null
},
{
"name": "Alt",
"value": "<span class=\"h-card\"><a href=\"https://cybre.space/@noiob\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>noiob</span}</span>",
"verified_at": null
},
{
"name": "Bots",
"value": "<span class=\"h-card\"><a href=\"https://botsin.space/@darksouls\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>darksouls</span}</span>, <span class=\"h-card\"><a href=\"https://botsin.space/@nierautomata\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>nierautomata</span}</span>, <span class=\"h-card\"><a href=\"https://mastodon.social/@fedi\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>fedi</span}</span>, code for <span class=\"h-card\"><a href=\"https://botsin.space/@awoobot\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>awoobot</span}</span>",
"verified_at": null
},
{
"name": "Website",
"value": "<a href=\"http://shork.xyz\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">http://</span><span class=\"\">shork.xyz</span><span class=\"invisible\"></span}",
"verified_at": "2019-11-10T10:31:10.744+00:00"
}
]
}
```
## Attributes
### `id` {#id}
**Description:** The account id.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
0.1.0 - added
### `username` {#username}
**Description:** The username of the account, not including domain.\
**Type:** String\
**Version history:**\
0.1.0 - added
### `acct` {#acct}
**Description:** The Webfinger account URI. Equal to `username` for local users, or `username@domain` for remote users.\
**Type:** String\
**Version history:**\
0.1.0 - added
### `url` {#url}
**Description:** The location of the user's profile page.\
**Type:** String (URL)\
**Version history:**\
0.1.0 - added
### `display_name` {#display_name}
**Description:** The profile's display name.\
**Type:** String\
**Version history:**\
0.1.0 - added
### `note` {#note}
**Description:** The profile's bio or description.\
**Type:** String (HTML)\
**Version history:**\
0.1.0 - added
### `avatar` {#avatar}
**Description:** An image icon that is shown next to statuses and in the profile.\
**Type:** String (URL)\
**Version history:**\
0.1.0 - added
### `avatar_static` {#avatar_static}
**Description:** A static version of the avatar. Equal to `avatar` if its value is a static image; different if `avatar` is an animated GIF.\
**Type:** String (URL)\
**Version history:**\
1.1.2 - added
### `header` {#header}
**Description:** An image banner that is shown above the profile and in profile cards.\
**Type:** String (URL)\
**Version history:**\
0.1.0 - added
### `header_static` {#header_static}
**Description:** A static version of the header. Equal to `header` if its value is a static image; different if `header` is an animated GIF.\
**Type:** String (URL)\
**Version history:**\
1.1.2 - added
### `locked` {#locked}
**Description:** Whether the account manually approves follow requests.\
**Type:** Boolean\
**Version history:**\
0.1.0 - added
### `fields` {#fields}
**Description:** Additional metadata attached to a profile as name-value pairs.\
**Type:** Array of [Field](#Field)\
**Version history:**\
2.4.0 - added
### `emojis` {#emojis}
**Description:** Custom emoji entities to be used when rendering the profile.\
**Type:** Array of [CustomEmoji]({{< relref "entities/CustomEmoji" >}})\
**Version history:**\
2.4.0 - added
### `bot` {#bot}
**Description:** Indicates that the account may perform automated actions, may not be monitored, or identifies as a robot.\
**Type:** Boolean\
**Version history:**\
2.4.0 - added
### `group` {#group}
**Description:** Indicates that the account represents a Group actor.\
**Type:** Boolean\
**Version history:**\
3.1.0 - added
### `discoverable` {#discoverable}
**Description:** Whether the account has opted into discovery features such as the profile directory.\
**Type:** {{<nullable>}} Boolean\
**Version history:**\
3.1.0 - added
### `noindex` {{%optional%}} {#noindex}
**Description:** Whether the local user has opted out of being indexed by search engines.\
**Type:** {{<nullable>}} Boolean\
**Version history:**\
4.0.0 - added
### `moved` {{%optional%}} {#moved}
**Description:** Indicates that the profile is currently inactive and that its user has moved to a new account.\
**Type:** {{<nullable>}} [Account]({{< relref "entities/Account" >}}), or null if the profile is suspended.\
**Version history:**\
2.1.0 - added
### `suspended` {{%optional%}} {#suspended}
**Description:** An extra attribute returned only when an account is suspended.\
**Type:** Boolean\
**Version history:**\
3.3.0 - added
### `limited` {{%optional%}} {#limited}
**Description:** An extra attribute returned only when an account is silenced. If true, indicates that the account should be hidden behind a warning screen.\
**Type:** Boolean\
**Version history:**\
3.5.3 - added
### `created_at` {#created_at}
**Description:** When the account was created.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
0.1.0 - added\
3.4.0 - now resolves to midnight instead of an exact time
### `last_status_at` {#last_status_at}
**Description:** When the most recent status was posted.\
**Type:** {{<nullable>}} String (ISO 8601 Date), or null if no statuses\
**Version history:**\
3.0.0 - added\
3.1.0 - now returns date only, no time
### `statuses_count` {#statuses_count}
**Description:** How many statuses are attached to this account.\
**Type:** Integer\
**Version history:**\
0.1.0 - added
### `followers_count` {#followers_count}
**Description:** The reported followers of this profile.\
**Type:** Integer\
**Version history:**\
0.1.0 - added
### `following_count` {#following_count}
**Description:** The reported follows of this profile.\
**Type:** Integer\
**Version history:**\
0.1.0 - added
## CredentialAccount entity attributes {#CredentialAccount}
```json
{
"id": "14715",
"username": "trwnh",
"acct": "trwnh",
"display_name": "infinite love ⴳ",
// ...
"note": "<p>i have approximate knowledge of many things. perpetual student. (nb/ace/they)</p><p>xmpp/email: a@trwnh.com<br /><a href=\"https://trwnh.com\" target=\"_blank\" rel=\"nofollow noopener noreferrer\"><span class=\"invisible\">https://</span><span class=\"\">trwnh.com</span><span class=\"invisible\"></span></a><br />help me live: <a href=\"https://liberapay.com/trwnh\" target=\"_blank\" rel=\"nofollow noopener noreferrer\"><span class=\"invisible\">https://</span><span class=\"\">liberapay.com/trwnh</span><span class=\"invisible\"></span></a> or paypal</p><p>- my triggers are moths and glitter<br />- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise<br />- dm me if i did something wrong, so i can improve<br />- purest person on fedi, do not lewd in my presence</p>",
// ...
"source": {
"privacy": "public",
"sensitive": false,
"language": "",
"note": "i have approximate knowledge of many things. perpetual student. (nb/ace/they)\r\n\r\nxmpp/email: a@trwnh.com\r\nhttps://trwnh.com\r\nhelp me live: https://liberapay.com/trwnh or paypal\r\n\r\n- my triggers are moths and glitter\r\n- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise\r\n- dm me if i did something wrong, so i can improve\r\n- purest person on fedi, do not lewd in my presence",
"fields": [
{
"name": "Website",
"value": "https://trwnh.com",
"verified_at": "2019-08-29T04:14:55.571+00:00"
},
{
"name": "Portfolio",
"value": "https://abdullahtarawneh.com",
"verified_at": "2021-02-11T20:34:13.574+00:00"
},
{
"name": "Fan of:",
"value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo's Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)",
"verified_at": null
},
{
"name": "What to expect:",
"value": "talking about various things i find interesting, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people! and to spill my thoughts.",
"verified_at": null
}
],
"follow_requests_count": 5
},
// ...
"fields": [
{
"name": "Website",
"value": "<a href=\"https://trwnh.com\" target=\"_blank\" rel=\"nofollow noopener noreferrer me\"><span class=\"invisible\">https://</span><span class=\"\">trwnh.com</span><span class=\"invisible\"></span></a>",
"verified_at": "2019-08-29T04:14:55.571+00:00"
},
{
"name": "Portfolio",
"value": "<a href=\"https://abdullahtarawneh.com\" target=\"_blank\" rel=\"nofollow noopener noreferrer me\"><span class=\"invisible\">https://</span><span class=\"\">abdullahtarawneh.com</span><span class=\"invisible\"></span></a>",
"verified_at": "2021-02-11T20:34:13.574+00:00"
},
{
"name": "Fan of:",
"value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo&#39;s Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)",
"verified_at": null
},
{
"name": "What to expect:",
"value": "talking about various things i find interesting, and otherwise being a genuine and decent wholesome poster. i&#39;m just here to hang out and talk to cool people! and to spill my thoughts.",
"verified_at": null
}
],
"role": {
"id": "-99",
"name": "",
"permissions": "65536",
"color": "",
"highlighted": false
}
}
```
### `source` {#source}
**Description:** An extra attribute that contains source values to be used with API methods that [verify credentials]({{< relref "methods/accounts#verify_credentials" >}}) and [update credentials]({{< relref "methods/accounts#update_credentials" >}}).\
**Type:** Hash\
**Version history:**\
2.4.0 - added
#### `source[note]` {#source-note}
**Description:** Profile bio, in plain-text instead of in HTML.\
**Type:** String\
**Version history:**\
1.5.0 - added
#### `source[fields]` {#source-fields}
**Description:** Metadata about the account.\
**Type:** Array of [Field](#Field)\
**Version history:**\
2.4.0 - added
#### `source[privacy]` {#source-privacy}
**Description:** The default post privacy to be used for new statuses.\
**Type:** String (Enumerable, oneOf)\
`public` = Public post\
`unlisted` = Unlisted post\
`private` = Followers-only post\
`direct` = Direct post\
**Version history:**\
1.5.0 - added
#### `source[sensitive]` {#source-sensitive}
**Description:** Whether new statuses should be marked sensitive by default.\
**Type:** Boolean\
**Version history:**\
1.5.0 - added
#### `source[language]` {#source-language}
**Description:** The default posting language for new statuses.\
**Type:** String (ISO 639-1 language two-letter code) or empty string\
**Version history:**\
2.4.2 - added
#### `source[follow_requests_count]` {#follow_requests_count}
**Description:** The number of pending follow requests.\
**Type:** Integer\
**Version history:**\
3.0.0 - added
### `role` {#role}
**Description:** The role assigned to the currently authorized user.\
**Type:** [Role]({{< relref "entities/Role" >}})\
**Version history:**\
4.0.0 - added
## MutedAccount entity attributes {#MutedAccount}
### `mute_expires_at` {#mute_expires_at}
**Description:** When a timed mute will expire, if applicable.\
**Type:** {{<nullable>}} String (ISO 8601 Datetime), or null if the mute is indefinite\
**Version history:**\
3.3.0 - added
## Field entity attributes {#Field}
### `name` {#name}
**Description:** The key of a given field's key-value pair.\
**Type:** String\
**Version history:**\
2.4.0 - added
### `value` {#value}
**Description:** The value associated with the `name` key.\
**Type:** String (HTML)\
**Version history:**\
2.4.0 - added
### `verified_at` {#verified_at}
**Description:** Timestamp of when the server verified a URL value for a rel="me" link.\
**Type:** {{<nullable>}} String (ISO 8601 Datetime) if `value` is a verified URL. Otherwise, null.\
**Version history:**\
2.6.0 - added
## See also
{{< page-relref ref="methods/accounts" caption="accounts API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/account_serializer.rb" caption="app/serializers/rest/account_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/credential_account_serializer.rb" caption="app/serializers/rest/credential_account_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/muted_account_serializer.rb" caption="app/serializers/rest/muted_account_serializer.rb" >}}

213
content/en/entities/Admin_Account.md Normal file
View File

@ -0,0 +1,213 @@
---
title: Admin::Account
description: Admin-level information about a given account.
menu:
docs:
parent: entities
aliases: [
"/entities/admin-account",
"/entities/Admin-Account",
"/entities/admin_account",
"/entities/Admin_Account",
"/api/entities/admin-account",
"/api/entities/Admin-Account",
"/api/entities/admin_account",
"/api/entities/Admin_Account",
]
---
## Example
```json
{
"id": "108965278956942133",
"username": "admin",
"domain": null,
"created_at": "2022-09-08T23:03:26.762Z",
"email": "admin@mastodon.local",
"ip": "192.168.42.1",
"role": {
"id": 3,
"name": "Owner",
"color": "",
"position": 1000,
"permissions": 1,
"highlighted": true,
"created_at": "2022-09-08T22:48:07.983Z",
"updated_at": "2022-09-08T22:48:07.983Z"
},
"confirmed": true,
"suspended": false,
"silenced": false,
"disabled": false,
"approved": true,
"locale": null,
"invite_request": null,
"ips": [
{
"ip": "192.168.42.1",
"used_at": "2022-09-15T01:38:58.851Z"
}
],
"account": {
"id": "108965278956942133",
"username": "admin",
"acct": "admin",
"display_name": "",
"locked": false,
"bot": false,
"discoverable": null,
"group": false,
"created_at": "2022-09-08T00:00:00.000Z",
"note": "",
"url": "http://mastodon.local/@admin",
"avatar": "http://mastodon.local/avatars/original/missing.png",
"avatar_static": "http://mastodon.local/avatars/original/missing.png",
"header": "http://mastodon.local/headers/original/missing.png",
"header_static": "http://mastodon.local/headers/original/missing.png",
"followers_count": 0,
"following_count": 0,
"statuses_count": 0,
"last_status_at": null,
"emojis": [],
"fields": []
}
}
```
## Attributes
### `id` {#id}
**Description:** The ID of the account in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
2.9.1 - added
### `username` {#username}
**Description:** The username of the account.\
**Type:** String\
**Version history:**\
2.9.1 - added
### `domain` {#domain}
**Description:** The domain of the account, if it is remote.\
**Type:** {{<nullable>}} String, or null for local accounts\
**Version history:**\
2.9.1 - added
### `created_at` {#created_at}
**Description:** When the account was first discovered.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
2.9.1 - added
### `email` {#email}
**Description:** The email address associated with the account.\
**Type:** String\
**Version history:**\
2.9.1 - added
### `ip` {#ip}
**Description:** The IP address last used to login to this account.\
**Type:** {{<nullable>}} String\
**Version history:**\
2.9.1 - added\
3.5.0 - return type changed from String to [Admin::Ip]({{< relref "entities/Admin_Ip" >}}) due to a bug\
4.0.0 - bug fixed, return type is now a String again
### `ips` {#ip}
**Description:** All known IP addresses associated with this account.\
**Type:** Array of [Admin::Ip]({{< relref "entities/Admin_Ip" >}})\
**Version history:**\
3.5.0 - added
### `locale` {#locale}
**Description:** The locale of the account.\
**Type:** String (ISO 639 Part 1 two-letter language code)\
**Version history:**\
2.9.1 - added
### `invite_request` {#invite_request}
**Description:** The reason given when requesting an invite (for instances that require manual approval of registrations)\
**Type:** {{<nullable>}} String\
**Version history:**\
2.9.1 - added
### `role` {#role}
**Description:** The current role of the account.\
**Type:** [Role]({{<relref "entities/role">}})\
**Version history:**\
2.9.1 - added, returns a String (enumerable, oneOf `user` `moderator` `admin`)\
4.0.0 - now uses Role entity
### `confirmed` {#confirmed}
**Description:** Whether the account has confirmed their email address.\
**Type:** Boolean\
**Version history:**\
2.9.1 - added
### `approved` {#approved}
**Description:** Whether the account is currently approved.\
**Type:** Boolean\
**Version history:**\
2.9.1 - added
### `disabled` {#disabled}
**Description:** Whether the account is currently disabled.\
**Type:** Boolean\
**Version history:**\
2.9.1 - added
### `silenced` {#silenced}
**Description:** Whether the account is currently silenced.
**Type:** Boolean\
**Version history:**\
2.9.1 - added
### `suspended` {#suspended}
**Description:** Whether the account is currently suspended.\
**Type:** Boolean\
**Version history:**\
2.9.1 - added
### `account` {#account}
**Description:** User-level information about the account.\
**Type:** [Account]({{< relref "entities/account" >}})\
**Version history:**\
2.9.1 - added
### `created_by_application_id` {{%optional%}} {#created_by_application_id}
**Description:** The ID of the [Application]({{< relref "entities/application" >}}) that created this account, if applicable.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
2.9.1 - added
### `invited_by_account_id` {{%optional%}} {#invited_by_account_id}
**Description:** The ID of the [Account]({{< relref "entities/account" >}}) that invited this user, if applicable.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
2.9.1 - added
## See also
{{< page-relref ref="methods/admin/accounts" caption="admin/accounts API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/account_serializer.rb" caption="app/serializers/rest/admin/account_serializer.rb" >}}

48
content/en/entities/Admin_CanonicalEmailBlock.md Normal file
View File

@ -0,0 +1,48 @@
---
title: Admin::CanonicalEmailBlock
description: Represents a canonical email block (hashed).
menu:
docs:
parent: entities
aliases: [
"/entities/admin-canonicalemailblock",
"/entities/Admin-CanonicalEmailBlock",
"/entities/admin_canonicalemailblock",
"/entities/Admin_CanonicalEmailBlock",
"/api/entities/admin-canonicalemailblock",
"/api/entities/Admin-CanonicalEmailBlock",
"/api/entities/admin_canonicalemailblock",
"/api/entities/Admin_CanonicalEmailBlock",
]
---
## Example
```json
{
"id": "2",
"canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c"
}
```
## Attributes
### `id` {#id}
**Description:** The ID of the email block in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
4.0.0 - added
### `canonical_email_hash` {#canonical_email_hash}
**Description:** The SHA256 hash of the canonical email address.\
**Type:** String (SHA256)\
**Version history:**\
4.0.0 - added
## See also
{{< page-relref ref="methods/admin/canonical_email_blocks" caption="admin/canonical_email_blocks API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/canonical_email_block_serializer.rb" caption="app/serializers/rest/admin/canonical_email_block_serializer.rb" >}}

135
content/en/entities/Admin_Cohort.md Normal file
View File

@ -0,0 +1,135 @@
---
title: Admin::Cohort
description: Represents a retention metric.
menu:
docs:
parent: entities
aliases: [
"/entities/admin-cohort",
"/entities/Admin-Cohort",
"/entities/admin_cohort",
"/entities/Admin_Cohort",
"/api/entities/admin-cohort",
"/api/entities/Admin-Cohort",
"/api/entities/admin_cohort",
"/api/entities/Admin_Cohort",
]
---
## Example
Monthly retention data for the month of 2022-09, given that 2 users registered during 2022-09 and were active at least once during that month.
```json
{
"period": "2022-09-01T00:00:00+00:00",
"frequency": "month",
"data": [
{
"date": "2022-09-01T00:00:00+00:00",
"rate": 1.0,
"value": "2"
}
]
}
```
Daily retention data for the week between 2022-09-08 and 2022-09-14, given that 2 users registered on 2022-09-08 and 1 of those users stopped being active after 2022-09-09.
```json
{
"period": "2022-09-08T00:00:00+00:00",
"frequency": "day",
"data": [
{
"date": "2022-09-08T00:00:00+00:00",
"rate": 1.0,
"value": "2"
},
{
"date": "2022-09-09T00:00:00+00:00",
"rate": 1.0,
"value": "2"
},
{
"date": "2022-09-10T00:00:00+00:00",
"rate": 0.5,
"value": "1"
},
{
"date": "2022-09-11T00:00:00+00:00",
"rate": 0.5,
"value": "1"
},
{
"date": "2022-09-12T00:00:00+00:00",
"rate": 0.5,
"value": "1"
},
{
"date": "2022-09-13T00:00:00+00:00",
"rate": 0.5,
"value": "1"
},
{
"date": "2022-09-14T00:00:00+00:00",
"rate": 0.5,
"value": "1"
}
]
}
```
## Attributes
### `period` {#period}
**Description:** The timestamp for the start of the period, at midnight.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
3.5.0 - added
### `frequency` {#frequency}
**Description:** The size of the bucket for the returned data.\
**Type:** String (Enumerable oneOf)\
`day` = Daily buckets\
`month` = Monthly buckets\
**Version history:**\
3.5.0 - added
### `data` {#data}
**Description:** Retention data for users who registered during the given period.\
**Type:** Array of [CohortData](#CohortData)\
**Version history:**\
3.5.0 - added
## CohortData entity attributes {#CohortData}
### `date` {date}
**Description:** The timestamp for the start of the bucket, at midnight.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
3.5.0 - added
### `rate` {#rate}
**Description:** The percentage rate of users who registered in the specified `period` and were active for the given `date` bucket.\
**Type:** Number\
**Version history:**\
3.5.0 - added
### `value` {#value}
**Description:** How many users registered in the specified `period` and were active for the given `date` bucket.\
**Type:** Integer\
**Version history:**\
3.5.0 - added
## See also
{{< page-relref ref="methods/admin/retention" caption="admin/retention API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/cohort_serializer.rb" caption="app/serializers/rest/admin/cohort_serializer.rb" >}}

306
content/en/entities/Admin_Dimension.md Normal file
View File

@ -0,0 +1,306 @@
---
title: Admin::Dimension
description: Represents qualitative data about the server.
menu:
docs:
parent: entities
aliases: [
"/entities/admin-dimension",
"/entities/Admin-Dimension",
"/entities/admin_dimension",
"/entities/Admin_Dimension",
"/api/entities/admin-dimension",
"/api/entities/Admin-Dimension",
"/api/entities/admin_dimension",
"/api/entities/Admin_Dimension",
]
---
## Attributes
### `key` {#key}
**Description:** The unique keystring for the requested dimension.\
**Type:** String\
**Version history:**\
3.5.0 - added
### `data` {#data}
**Description:** The data available for the requested dimension.\
**Type:** Array of Hash\
**Version history:**\
3.5.0 - added
## Data attributes
### `key` {#data-key}
**Description:** The unique keystring for this data item.\
**Type:** String\
**Version history:**\
3.5.0 - added
### `human_key` {#data-human_key}
**Description:** A human-readable key for this data item.\
**Type:** String\
**Version history:**\
3.5.0 - added
### `value` {#data-value}
**Description:** The value for this data item.\
**Type:** String\
**Version history:**\
3.5.0 - added
### `unit` {{%optional%}} {#data-unit}
**Description:** The units associated with this data item's value, if applicable.\
**Type:** String\
**Version history:**\
3.5.0 - added
### `human_value` {{%optional%}} {#data-human_value}
**Description:** A human-readable formatted value for this data item.\
**Type:** String\
**Version history:**\
3.5.0 - added
## Examples
### `languages` {#languages}
Count how many local statuses are posted in each language, then show dimensional data about how popular each language is.
```json
{
"key": "languages",
"data": [
{
"key": "en",
"human_key": "English",
"value": "10"
},
{
"key": "es",
"human_key": "Spanish",
"value": "1"
},
// ...
]
}
```
### `sources` {#sources}
Count how many local statuses were authored by a given client, then show dimensional data about how popular each client is.
```json
{
"key": "sources",
"data": [
{
"key": "web",
"human_key": "Website",
"value": "2"
},
// ...
]
}
```
### `servers` {#servers}
Count how many statuses were posted from a given domain, then show dimensional data about the most popular remote servers.
```json
{
"key": "servers",
"data": [
{
"key": "botsin.space",
"human_key": "botsin.space",
"value": "13738"
},
{
"key": "mastodon.social",
"human_key": "mastodon.social",
"value": "8928"
},
// ...
]
}
```
### `space_usage` {#space_usage}
Show dimensional data about how much space is used by each software in your server stack.
```json
{
"key": "space_usage",
"data": [
{
"key": "postgresql",
"human_key": "PostgreSQL",
"value": "14924935",
"unit": "bytes",
"human_value": "14.2 MB"
},
{
"key": "redis",
"human_key": "Redis",
"value": "1972544",
"unit": "bytes",
"human_value": "1.88 MB"
},
{
"key": "media",
"human_key": "Media storage",
"value": "0",
"unit": "bytes",
"human_value": "0 Bytes"
}
]
}
```
### `software_versions` {#software_versions}
Show dimensional data about which versions of software in your server stack you are using.
```json
{
"key": "software_versions",
"data": [
{
"key": "mastodon",
"human_key": "Mastodon",
"value": "3.5.3",
"human_value": "3.5.3"
},
{
"key": "ruby",
"human_key": "Ruby",
"value": "3.0.4p208",
"human_value": "3.0.4p208"
},
{
"key": "postgresql",
"human_key": "PostgreSQL",
"value": "10.22",
"human_value": "10.22"
},
{
"key": "redis",
"human_key": "Redis",
"value": "4.0.9",
"human_value": "4.0.9"
}
]
}
```
### `tag_servers` {#tag_servers}
Count how many statuses contain the trending tag with the given `id`, then show dimensional data about the most popular servers using that trending tag.
```json
{
"key": "tag_servers",
"data": [
{
"key": "live.hatnix.net",
"human_key": "live.hatnix.net",
"value": "6"
},
{
"key": "linuxrocks.online",
"human_key": "linuxrocks.online",
"value": "4"
}
]
}
```
### `tag_languages` {#tag_languages}
Count how many statuses contain the trending tag with the given `id`, then show dimensional data about the most popular languages for those statuses.
```json
{
"key": "tag_languages",
"data": [
{
"key": "und",
"human_key": "und",
"value": "8"
},
{
"key": "en",
"human_key": "English",
"value": "7"
},
// ...
]
}
```
### `instance_accounts` {#instance_accounts}
Count how many followers each account from the given `domain` has, then show dimensional data about the most popular accounts from that remote server.
```json
{
"key": "instance_accounts",
"data": [
{
"key": "fribbledom",
"human_key": "fribbledom",
"value": "33"
},
{
"key": "ShugoWah",
"human_key": "ShugoWah",
"value": "26"
},
// ...
]
}
```
### `instance_languages` {#instance_languages}
Count how many statuses from the given `domain` are posted in each language, then show dimensional data about how popular each language is on that remote server.
```json
{
"key": "instance_languages",
"data": [
{
"key": "en",
"human_key": "English",
"value": "5848"
},
{
"key": "de",
"human_key": "German",
"value": "155"
},
// ...
]
}
```
## See also
{{< page-relref ref="methods/admin/dimensions" caption="admin/dimensions API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/dimension_serializer.rb" caption="app/serializers/rest/admin/dimension_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/dimension.rb" caption="app/lib/admin/metrics/dimension.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/dimension/" caption="app/lib/admin/metrics/dimension/" >}}

56
content/en/entities/Admin_DomainAllow.md Normal file
View File

@ -0,0 +1,56 @@
---
title: Admin::DomainAllow
description: Represents a domain allowed to federate.
menu:
docs:
parent: entities
aliases: [
"/entities/admin-domainallow",
"/entities/Admin-DomainAllow",
"/entities/admin_domainallow",
"/entities/Admin_DomainAllow",
"/api/entities/admin-domainallow",
"/api/entities/Admin-DomainAllow",
"/api/entities/admin_domainallow",
"/api/entities/Admin_DomainAllow",
]
---
## Example
```json
{
"id": "1",
"domain": "mastodon.social",
"created_at": "2022-09-14T21:23:02.755Z"
}
```
## Attributes
### `id` {#id}
**Description:** The ID of the DomainAllow in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
4.0.0 - added
### `domain` {#domain}
**Description:** The domain that is allowed to federate.\
**Type:** String\
**Version history:**\
4.0.0 - added
### `created_at` {#created_at}
**Description:** When the domain was allowed to federate.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
4.0.0 - added
## See also
{{< page-relref page="methods/admin/domain_allows" caption="admin/domain_allows API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/domain_allows_serializer.rb" caption="app/serializers/rest/admin/domain_allows_serializer.rb" >}}

107
content/en/entities/Admin_DomainBlock.md Normal file
View File

@ -0,0 +1,107 @@
---
title: Admin::DomainBlock
description: Represents a domain limited from federating.
menu:
docs:
parent: entities
aliases: [
"/entities/admin-domainblock",
"/entities/Admin-DomainBlock",
"/entities/admin_domainblock",
"/entities/Admin_DomainBlock",
"/api/entities/admin-domainblock",
"/api/entities/Admin-DomainBlock",
"/api/entities/admin_domainblock",
"/api/entities/Admin_DomainBlock",
]
---
## Example
```json
{
"id": "1",
"domain": "example.com",
"created_at": "2022-11-16T08:15:34.238Z",
"severity": "noop",
"reject_media": false,
"reject_reports": false,
"private_comment": null,
"public_comment": null,
"obfuscate": false
}
```
## Attributes
### `id` {#id}
**Description:** The ID of the DomainBlock in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
4.0.0 - added
### `domain` {#domain}
**Description:** The domain that is not allowed to federate.\
**Type:** String\
**Version history:**\
4.0.0 - added
### `created_at` {#created_at}
**Description:** When the domain was blocked from federating.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
4.0.0 - added
### `severity` {#severity}
**Description:** The policy to be applied by this domain block.\
**Type:** String (Enumerable oneOf)\
`silence` = Account statuses from this domain will be hidden by default\
`suspend` = All incoming data from this domain will be rejected\
`noop` = Do nothing. Allows for rejecting media or reports\
**Version history:**\
4.0.0 - added
### `reject_media` {#reject_media}
**Description:** Whether to reject media attachments from this domain\
**Type:** Boolean\
**Version history:**\
4.0.0 - added
### `reject_reports` {#reject_reports}
**Description:** Whether to reject reports from this domain\
**Type:** Boolean\
**Version history:**\
4.0.0 - added
### `private_comment` {#private_comment}
**Description:** \
**Type:** {{<nullable>}} String\
**Version history:**\
4.0.0 - added
### `public_comment` {#public_comment}
**Description:** \
**Type:** {{<nullable>}} String\
**Version history:**\
4.0.0 - added
### `obfuscate` {#obfuscate}
**Description:** Whether to obfuscate public displays of this domain block\
**Type:** Boolean\
**Version history:**\
4.0.0 - added
## See also
{{< page-relref page="methods/admin/domain_blocks" caption="admin/domain_blocks API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/domain_blocks_serializer.rb" caption="app/serializers/rest/admin/domain_blocks_serializer.rb" >}}

121
content/en/entities/Admin_EmailDomainBlock.md Normal file
View File

@ -0,0 +1,121 @@
---
title: Admin::EmailDomainBlock
description: Represents an email domain that cannot be used to sign up.
menu:
docs:
parent: entities
aliases: [
"/entities/admin-emaildomainblock",
"/entities/Admin-EmailDomainBlock",
"/entities/admin_emaildomainblock",
"/entities/Admin_EmailDomainBlock",
"/api/entities/admin-emaildomainblock",
"/api/entities/Admin-EmailDomainBlock",
"/api/entities/admin_emaildomainblock",
"/api/entities/Admin_EmailDomainBlock",
]
---
## Example
```json
{
"id": "1",
"domain": "foo",
"created_at": "2022-11-16T06:09:36.176Z",
"history": [
{
"day": "1668556800",
"accounts": "0",
"uses": "0"
},
{
"day": "1668470400",
"accounts": "0",
"uses": "0"
},
{
"day": "1668384000",
"accounts": "0",
"uses": "0"
},
{
"day": "1668297600",
"accounts": "0",
"uses": "0"
},
{
"day": "1668211200",
"accounts": "0",
"uses": "0"
},
{
"day": "1668124800",
"accounts": "0",
"uses": "0"
},
{
"day": "1668038400",
"accounts": "0",
"uses": "0"
}
]
}
```
## Attributes
### `id` {#id}
**Description:** The ID of the EmailDomainBlock in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
4.0.0 - added
### `domain` {#domain}
**Description:** The email domain that is not allowed to be used for signups.\
**Type:** String\
**Version history:**\
4.0.0 - added
### `created_at` {#created_at}
**Description:** When the email domain was disallowed from signups.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
4.0.0 - added
### `history` {#history}
**Description:** Usage statistics for given days (typically the past week).\
**Type:** Array of Hash\
**Version history:**\
4.0.0 - added
#### `history[][day]` {#history-day}
**Description:** UNIX timestamp on midnight of the given day.\
**Type:** String (UNIX timestamp)\
**Version history:**\
4.0.0 - added
#### `history[][accounts]` {#history-accounts}
**Description:** The counted accounts signup attempts using that email domain within that day.\
**Type:** String (cast from an integer)\
**Version history:**\
4.0.0 - added
#### `history[][uses]` {#history-uses}
**Description:** The counted IP signup attempts of that email domain within that day.\
**Type:** String (cast from an integer)\
**Version history:**\
4.0.0 - added
## See also
{{< page-relref page="methods/admin/email_domain_blocks" caption="admin/email_domain_blocks API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/email_domain_blocks_serializer.rb" caption="app/serializers/rest/admin/email_domain_blocks_serializer.rb" >}}

48
content/en/entities/Admin_Ip.md Normal file
View File

@ -0,0 +1,48 @@
---
title: Admin::Ip
description: Represents an IP address associated with a user.
menu:
docs:
parent: entities
aliases: [
"/entities/admin-ip",
"/entities/Admin-Ip",
"/entities/admin_ip",
"/entities/Admin_Ip",
"/api/entities/admin-ip",
"/api/entities/Admin-Ip",
"/api/entities/admin_ip",
"/api/entities/Admin_Ip",
]
---
## Example
```json
{
"ip": "192.168.42.1",
"used_at": "2022-09-15T01:38:58.851Z"
}
```
## Attributes
### `ip` {#id}
**Description:** The IP address.\
**Type:** String (IP address)\
**Version history:**\
3.5.0 - added
### `used_at` {#used_at}
**Description:** The timestamp of when the IP address was last used for this account.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
3.5.0 - added
## See also
{{< page-relref ref="entities/Admin_Account#ips" caption="Admin::Account (`ips` attribute)" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/ip_serializer.rb" caption="app/serializers/rest/admin/ip_serializer.rb" >}}

83
content/en/entities/Admin_IpBlock.md Normal file
View File

@ -0,0 +1,83 @@
---
title: Admin::IpBlock
description: Represents an IP address range that cannot be used to sign up.
menu:
docs:
parent: entities
aliases: [
"/entities/admin-ipblock",
"/entities/Admin-IpBlock",
"/entities/admin_ipblock",
"/entities/Admin_IpBlock",
"/api/entities/admin-ipblock",
"/api/entities/Admin-IpBlock",
"/api/entities/admin_ipblock",
"/api/entities/Admin_IpBlock",
]
---
## Example
```json
{
"id": "1",
"ip": "8.8.8.8/32",
"severity": "no_access",
"comment": "",
"created_at": "2022-11-16T07:22:00.501Z",
"expires_at": null
}
```
## Attributes
### `id` {#id}
**Description:** The ID of the DomainBlock in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
4.0.0 - added
### `ip` {#ip}
**Description:** The IP address range that is not allowed to federate.\
**Type:** String (IP address and prefix)\
**Version history:**\
4.0.0 - added
### `severity` {#severity}
**Description:** The associated policy with this IP block.\
**Type:** String (Enumerable, oneOf)\
`sign_up_requires_approval` = Any signup from this IP range will create a pending account\
`sign_up_block` = Any signup from this IP range will be rejected\
`no_access` = Any activity from this IP range will be rejected entirely\
**Version history:**\
4.0.0 - added
### `comment` {#comment}
**Description:** The recorded reason for this IP block.\
**Type:** String\
**Version history:**\
4.0.0 - added
### `created_at` {#created_at}
**Description:** When the IP block was created.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
4.0.0 - added
### `expires_at` {#expires_at}
**Description:** When the IP block will expire.\
**Type:** {{<nullable>}} String (ISO 8601 Datetime)\
**Version history:**\
4.0.0 - added
## See also
{{< page-relref page="methods/admin/ip_blocks" caption="admin/ip_blocks API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/ip_blocks_serializer.rb" caption="app/serializers/rest/admin/ip_blocks_serializer.rb" >}}

787
content/en/entities/Admin_Measure.md Normal file
View File

@ -0,0 +1,787 @@
---
title: Admin::Measure
description: Represents quantitative data about the server.
menu:
docs:
parent: entities
aliases: [
"/entities/admin-measure",
"/entities/Admin-Measure",
"/entities/admin_measure",
"/entities/Admin_Measure",
"/api/entities/admin-measure",
"/api/entities/Admin-Measure",
"/api/entities/admin_measure",
"/api/entities/Admin_Measure",
]
---
## Attributes
### `key` {#key}
**Description:** The unique keystring for the requested measure.\
**Type:** String\
**Version history:**\
3.5.0 - added
### `unit` {#unit}
**Description:** The units associated with this data item's value, if applicable.\
**Type:** {{<nullable>}} String or null\
**Version history:**\
3.5.0 - added
### `total` {#total}
**Description:** The numeric total associated with the requested measure.\
**Type:** String (cast from integer)\
**Version history:**\
3.5.0 - added
### `human_value` {{%optional%}} {#data-human_value}
**Description:** A human-readable formatted value for this data item.\
**Type:** String\
**Version history:**\
3.5.0 - added
### `previous_total` {{%optional%}} {#previous_total}
**Description:** The numeric total associated with the requested measure, in the previous period. Previous period is calculated by subtracting the start_at and end_at dates, then offsetting both start and end dates backwards by the length of the time period.\
**Type:** String (cast from integer)\
**Version history:**\
3.5.0 - added
### `data` {#data}
**Description:** The data available for the requested measure, split into daily buckets.\
**Type:** Array of Hash\
**Version history:**\
3.5.0 - added
#### `data[][date]` {#data-date}
**Description:** Midnight on the requested day in the time period.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
3.5.0 - added
#### `data[][value]` {#data-value}
**Description:** The numeric value for the requested measure.\
**Type:** String (cast from integer)\
**Version history:**\
3.5.0 - added
## Examples
### `active_users`
Total active users on your instance within the time period starting at 2022-09-14 and ending at 2022-09-22
```json
{
"key": "active_users",
"unit": null,
"total": "2",
"previous_total": "0",
"data": [
{
"date": "2022-09-14T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-15T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-16T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-17T00:00:00Z",
"value": "1"
},
{
"date": "2022-09-18T00:00:00Z",
"value": "1"
},
{
"date": "2022-09-19T00:00:00Z",
"value": "1"
},
{
"date": "2022-09-20T00:00:00Z",
"value": "2"
},
{
"date": "2022-09-21T00:00:00Z",
"value": "1"
}
]
}
```
### `new_users`
Users who joined your instance within the time period starting at 2022-09-14 and ending at 2022-09-22
```json
{
"key": "new_users",
"unit": null,
"total": "2",
"previous_total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "1"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "1"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
### `interactions`
Total interactions (favourites, boosts, replies) on local statuses within the time period starting at 2022-09-14 and ending at 2022-09-22
```json
{
"key": "interactions",
"unit": null,
"total": "0",
"previous_total": "0",
"data": [
{
"date": "2022-09-14T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-15T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-16T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-17T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-18T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-19T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-20T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-21T00:00:00Z",
"value": "0"
}
]
}
```
### `opened_reports`
Total reports filed within the time period starting at 2022-09-14 and ending at 2022-09-22
```json
{
"key": "opened_reports",
"unit": null,
"total": "0",
"previous_total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
### `resolved_reports`
Total reports resolved within the time period starting at 2022-09-14 and ending at 2022-09-22
```json
{
"key": "resolved_reports",
"unit": null,
"total": "0",
"previous_total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
### `tag_accounts`
Total accounts who used a tag in at least one status within the time period starting at 2022-09-14 and ending at 2022-09-22
```json
{
"key": "tag_accounts",
"unit": null,
"total": "1",
"previous_total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "1"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
### `tag_uses`
Total statuses which used a tag within the time period starting at 2022-09-14 and ending at 2022-09-22
```json
{
"key": "tag_uses",
"unit": null,
"total": "2",
"previous_total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "1"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "1"
}
]
}
```
### `tag_servers`
Total remote origin servers for statuses which used a tag within the time period starting at 2022-09-14 and ending at 2022-09-22
```json
{
"key": "tag_servers",
"unit": null,
"total": "0",
"previous_total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
### `instance_accounts`
Total accounts originating from a remote domain within the time period starting at 2022-09-14 and ending at 2022-09-22
```json
{
"key": "instance_accounts",
"unit": null,
"total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
### `instance_media_attachments`
Total space used by media attachments from a remote domain within the time period starting at 2022-09-14 and ending at 2022-09-22
```json
{
"key": "instance_media_attachments",
"unit": "bytes",
"total": "0",
"human_value": "0 Bytes",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": ""
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": ""
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": ""
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": ""
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": ""
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": ""
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": ""
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": ""
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": ""
}
]
}
```
### `instance_reports`
Total reports filed against accounts from a remote domain within the time period starting at 2022-09-14 and ending at 2022-09-22
```json
{
"key": "instance_reports",
"unit": null,
"total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
### `instance_statuses`
Total statuses originating from a remote domain within the time period starting at 2022-09-14 and ending at 2022-09-22
```json
{
"key": "instance_statuses",
"unit": null,
"total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
### `instance_follows`
Total accounts from a remote domain followed by a local user within the time period starting at 2022-09-14 and ending at 2022-09-22
```json
{
"key": "instance_follows",
"unit": null,
"total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
### `instance_followers`
Total local accounts followed by accounts from a remote domain within the time period starting at 2022-09-14 and ending at 2022-09-22
```json
{
"key": "instance_followers",
"unit": null,
"total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
## See also
{{< page-relref ref="methods/admin/dimensions" caption="admin/dimensions API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/measure_serializer.rb" caption="app/serializers/rest/admin/measure_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/measure.rb" caption="app/lib/admin/metrics/measure.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/measure/" caption="app/lib/admin/metrics/measure/" >}}

176
content/en/entities/Admin_Report.md Normal file
View File

@ -0,0 +1,176 @@
---
title: Admin::Report
description: Admin-level information about a filed report.
menu:
docs:
parent: entities
aliases: [
"/entities/admin-report",
"/entities/Admin-Report",
"/entities/admin_report",
"/entities/Admin_Report",
"/api/entities/admin-report",
"/api/entities/Admin-Report",
"/api/entities/admin_report",
"/api/entities/Admin_Report",
]
---
## Example
```json
{
"id": "1",
"action_taken": false,
"action_taken_at": null,
"category": "spam",
"comment": "",
"forwarded": false,
"created_at": "2022-09-09T21:19:23.085Z",
"updated_at": "2022-09-09T21:19:23.085Z",
"account": {
"id": "108965218747268792",
"username": "admin",
"domain": null,
"created_at": "2022-09-08T22:48:07.985Z",
"email": "admin@mastodon.local",
// ...
"account": {
"id": "108965218747268792",
"username": "admin",
"acct": "admin",
// ...
}
},
"target_account": {
"id": "108965430868193066",
"username": "goody",
"domain": null,
"created_at": "2022-09-08T23:42:04.731Z",
"email": "goody@mastodon.local",
// ...
"account": {
"id": "108965430868193066",
"username": "goody",
"acct": "goody",
// ...
}
},
"assigned_account": null,
"action_taken_by_account": null,
"statuses": [],
"rules": []
}
```
## Attributes
### `id` {#id}
**Description:** The ID of the report in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
2.9.1 - added
### `action_taken` {#action_taken}
**Description:** Whether an action was taken to resolve this report.\
**Type:** Boolean\
**Version history:**\
2.9.1 - added
### `action_taken_at` {#action_taken_at}
**Description:** When an action was taken, if this report is currently resolved.\
**Type:** {{<nullable>}} String (ISO 8601 Datetime) or null\
**Version history:**\
2.9.1 - added
### `category` {#category}
**Description:** The category under which the report is classified.\
**Type:** String (Enumerable oneOf)\
`spam` = Malicious, fake, or repetitive content\
`violation` = Violates one or more specific [`rules`](#rules)\
`other` = The default (catch-all) category\
**Version history:**\
3.5.0 - added
### `comment` {#comment}
**Description:** An optional reason for reporting.\
**Type:** String\
**Version history:**\
2.9.1 - added
### `forwarded` {#forwarded}
**Description:** Whether a report was forwarded to a remote instance.\
**Type:** Boolean\
**Version history:**\
4.0.0 - added
### `created_at` {#created_at}
**Description:** The time the report was filed.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
2.9.1 - added
### `updated_at` {#updated_at}
**Description:** The time of last action on this report.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
2.9.1 - added
### `account` {#account}
**Description:** The account which filed the report.\
**Type:** [Admin::Account]({{< relref "entities/Admin_Account" >}})\
**Version history:**\
2.9.1 - added
### `target_account` {#target_account}
**Description:** The account being reported.\
**Type:** [Admin::Account]({{< relref "entities/Admin_Account" >}})\
**Version history:**\
2.9.1 - added
### `assigned_account` {#assigned_account}
**Description:** The account of the moderator assigned to this report.\
**Type:** {{<nullable>}} [Admin::Account]({{< relref "entities/Admin_Account" >}}) or null\
**Version history:**\
2.9.1 - added
### `action_taken_by_account` {#action_taken_by_account}
**Description:** The account of the moderator who handled the report.\
**Type:** {{<nullable>}} [Admin::Account]({{< relref "entities/Admin_Account" >}}) or null\
**Version history:**\
2.9.1 - added
### `statuses` {#statuses}
**Description:** Statuses attached to the report, for context.\
**Type:** Array of [Status]({{< relref "entities/Status" >}})\
**Version history:**\
2.9.1 - added
### `rules` {#rules}
**Description:** Rules attached to the report, for context.\
**Type:** Array of [Rule]({{< relref "entities/Rule" >}})\
**Version history:**\
3.5.0 - added
## See also
{{< page-relref page="methods/admin/reports" caption="admin/reports API methods">}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/report_serializer.rb" caption="app/serializers/rest/admin/report_serializer.rb" >}}

211
content/en/entities/Announcement.md Normal file
View File

@ -0,0 +1,211 @@
---
title: Announcement
description: Represents an announcement set by an administrator.
menu:
docs:
parent: entities
aliases: [
"/entities/announcement",
"/entities/Announcement",
"/api/entities/announcement",
"/api/entities/Announcement",
]
---
## Example
```json
{
"id": "8",
"content": "<p>Looks like there was an issue processing audio attachments without embedded art since yesterday due to an experimental new feature. That issue has now been fixed, so you may see older posts with audio from other servers pop up in your feeds now as they are being finally properly processed. Sorry!</p>",
"starts_at": null,
"ends_at": null,
"all_day": false,
"published_at": "2020-07-03T01:27:38.726Z",
"updated_at": "2020-07-03T01:27:38.752Z",
"read": true,
"mentions": [],
"statuses": [],
"tags": [],
"emojis": [],
"reactions": [
{
"name": "bongoCat",
"count": 9,
"me": false,
"url": "https://files.mastodon.social/custom_emojis/images/000/067/715/original/fdba57dff7576d53.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/067/715/static/fdba57dff7576d53.png"
},
{
"name": "thonking",
"count": 1,
"me": false,
"url": "https://files.mastodon.social/custom_emojis/images/000/098/690/original/a8d36edc4a7032e8.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/098/690/static/a8d36edc4a7032e8.png"
},
{
"name": "AAAAAA",
"count": 1,
"me": false,
"url": "https://files.mastodon.social/custom_emojis/images/000/071/387/original/AAAAAA.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/071/387/static/AAAAAA.png"
},
{
"name": "🤔",
"count": 1,
"me": true
}
]
}
```
## Attributes
### `id` {#id}
**Description:** The ID of the announcement in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
3.1.0 - added
### `content` {#content}
**Description:** The text of the announcement.\
**Type:** String (HTML)\
**Version history:**\
3.1.0 - added
### `starts_at` {#starts_at}
**Description:** When the announcement will start.\
**Type:** {{<nullable>}} String (ISO 8601 Datetime) or null\
**Version history:**\
3.1.0 - added
### `ends_at` {#ends_at}
**Description:** When the announcement will end.\
**Type:** {{<nullable>}} String (ISO 8601 Datetime) or null\
**Version history:**\
3.1.0 - added
### `published` {#published}
**Description:** Whether the announcement is currently active.\
**Type:** Boolean\
**Version history:**\
3.1.0 - added
### `all_day` {#all_day}
**Description:** Whether the announcement should start and end on dates only instead of datetimes. Will be false if there is no `starts_at` or `ends_at` time.\
**Type:** Boolean\
**Version history:**\
3.1.0 - added
### `published_at` {#created_at}
**Description:** When the announcement was published.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
3.1.0 - added
### `updated_at` {#updated_at}
**Description:** When the announcement was last updated.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
3.1.0 - added
### `read` {{%optional%}} {#read}
**Description:** Whether the announcement has been read by the current user.\
**Type:** Boolean\
**Version history:**\
3.1.0 - added
### `mentions` {#mentions}
**Description:** Accounts mentioned in the announcement text.\
**Type:** Array of [Announcement::Account](#Account)\
**Version history:**\
3.1.0 - added
### `statuses` {#statuses}
**Description:** Statuses linked in the announcement text.\
**Type:** Array of [Announcement::Status](#Status)\
**Version history:**\
3.1.0 - added
### `tags` {#tags}
**Description:** Tags linked in the announcement text.\
**Type:** Array of [Status::Tag]({{< relref "entities/Status#Tag" >}})\
**Version history:**\
3.1.0 - added
### `emojis` {#emojis}
**Description:** Custom emoji used in the announcement text.\
**Type:** Array of [CustomEmoji]({{< relref "entities/CustomEmoji" >}})\
**Version history:**\
3.1.0 - added
### `reactions` {#reactions}
**Description:** Emoji reactions attached to the announcement.\
**Type:** Array of [Reaction]({{< relref "entities/Reaction" >}})\
**Version history:**\
3.1.0 - added
## Announcement::Account attributes {#Account}
### `id` {#Account-id}
**Description:** The account ID of the mentioned user.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
3.1.0 - added
### `username` {#Account-username}
**Description:** The username of the mentioned user.\
**Type:** String\
**Version history:**\
3.1.0 - added
### `url` {#Account-url}
**Description:** The location of the mentioned user's profile.\
**Type:** String (URL)\
**Version history:**\
3.1.0 - added
### `acct` {#Account-acct}
**Description:** The webfinger acct: URI of the mentioned user. Equivalent to `username` for local users, or `username@domain` for remote users.\
**Type:** String\
**Version history:**\
3.1.0 - added
## Announcement::Status attributes {#Status}
### `id` {#Status-id}
**Description:** The ID of an attached Status in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
3.1.0 - added
### `url` {#Status-url}
**Description:** The URL of an attached Status.\
**Type:** String (URL)\
**Version history:**\
3.1.0 - added
## See also
{{< page-relref ref="methods/announcements" caption="announcements API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/announcement_serializer.rb" caption="app/serializers/rest/announcement_serializer.rb" >}}

72
content/en/entities/Application.md Normal file
View File

@ -0,0 +1,72 @@
---
title: Application
description: Represents an application that interfaces with the REST API to access accounts or post statuses.
menu:
docs:
parent: entities
aliases: [
"/entities/application",
"/entities/Application",
"/api/entities/application",
"/api/entities/Application",
]
---
## Example
```json
{
"name": "test app",
"website": null,
"vapid_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M="
}
```
## Attributes
### `name` {#name}
**Description:** The name of your application.\
**Type:** String\
**Version history:**\
0.9.9 - added
### `website` {{%optional%}} {#website}
**Description:** The website associated with your application.\
**Type:** {{<nullable>}} String (URL)\
**Version history:**\
0.9.9 - added\
3.5.1 - this property is now nullable
### `client_id` {{%optional%}} {#client_id}
**Description:** Client ID key, to be used for obtaining OAuth tokens\
**Type:** String\
**Version history:**\
0.9.9 - added
### `client_secret` {{%optional%}} {#client_secret}
**Description:** Client secret key, to be used for obtaining OAuth tokens\
**Type:** String\
**Version history:**\
0.9.9 - added
## Deprecated attributes
### `vapid_key` {#vapid_key}
**Description:** Used for Push Streaming API. Returned with [POST /api/v1/apps]({{< relref "methods/apps#create" >}}). Equivalent to [WebPushSubscription#server_key]({{< relref "entities/WebPushSubscription#server_key" >}}) and [Instance#vapid_public_key]({{< relref "entities/Instance#vapid_public_key" >}})\
**Type:** String\
**Version history:**\
2.8.0 - added
4.3.0 - deprecated pending removal
## See also
{{< page-relref ref="methods/apps" caption="apps API methods" >}}
{{< page-relref ref="entities/Status#application" caption="Status (`application` attribute)" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/application_serializer.rb" caption="app/serializers/rest/application_serializer.rb" >}}

40
content/en/entities/context.md → content/en/entities/Context.md
View File

@ -4,65 +4,67 @@ description: Represents the tree around a given status. Used for reconstructing
menu:
docs:
parent: entities
aliases: [
"/entities/context",
"/entities/Context",
"/api/entities/context",
"/api/entities/Context",
]
---
## Example
{{< code title="Truncated response from GET statuses/:id/context" >}}
```javascript
```json
{
"ancestors": [
{
"id": "103188938570975982",
"created_at": "2019-11-23T19:44:00.124Z",
"in_reply_to_id": null,
...
// ...
},
{
"id": "103188971072973252",
"created_at": "2019-11-23T19:52:23.398Z",
"in_reply_to_id": "103188938570975982",
...
// ...
},
{
"id": "103188982235527758",
"created_at": "2019-11-23T19:55:08.208Z",
"in_reply_to_id": "103188971072973252",
...
// ...
}
],
"descendants": [
{
"id": "103189026958574542",
"created_at": "2019-11-23T20:06:36.011Z",
"in_reply_to_id": "103189005915505698",
...
// ...
}
]
}
```
{{< /code >}}
## Required attributes
## Attributes
### `ancestors` {#ancestors}
**Description:** Parents in the thread.\
**Type:** Array of [Status]({{< relref "status.md" >}})\
**Version history:** Added in 0.6.0
**Type:** Array of [Status]({{< relref "entities/Status" >}})\
**Version history:**\
0.6.0 - added
### `descendants` {#descendants}
**Description:** Children in the thread.\
**Type:** Array of [Status]({{< relref "status.md" >}})\
**Version history:** Added in 0.6.0
**Type:** Array of [Status]({{< relref "entities/Status" >}})\
**Version history:**\
0.6.0 - added
## See also
* [GET /api/v1/statuses/:id/context]({{< relref "../methods/statuses/#parent-and-child-statuses" >}})
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/context_serializer.rb" caption="app/serializers/rest/context\_serializer.rb" >}}
{{< page-relref ref="methods/statuses#context" caption="GET /api/v1/statuses/:id/context" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/context_serializer.rb" caption="app/serializers/rest/context_serializer.rb" >}}

78
content/en/entities/Conversation.md Normal file
View File

@ -0,0 +1,78 @@
---
title: Conversation
description: Represents a conversation with "direct message" visibility.
menu:
docs:
parent: entities
aliases: [
"/entities/conversation",
"/entities/Conversation",
"/api/entities/conversation",
"/api/entities/Conversation",
]
---
## Example
```json
{
"id": "418450",
"unread": true,
"accounts": [
{
"id": "482403",
"username": "amic",
"acct": "amic@nulled.red",
// ...
}
],
"last_status": {
"id": "103196583826321184",
"created_at": "2019-11-25T04:08:24.000Z",
"in_reply_to_id": "103196540587943467",
"in_reply_to_account_id": "14715",
// ...
}
}
```
## Attributes
### `id` {#id}
**Description:** The ID of the conversation in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
2.6.0 - added
### `unread` {#unread}
**Description:** Is the conversation currently marked as unread?\
**Type:** Boolean\
**Version history:**\
2.6.0 - added
### `accounts` {#accounts}
**Description:** Participants in the conversation.\
**Type:** Array of [Account]({{< relref "entities/Account" >}})\
**Version history:**\
2.6.0 - added
### `last_status` {#last_status}
**Description:** The last status in the conversation.\
**Type:** {{<nullable>}} [Status]({{< relref "entities/Status" >}})\
**Version history:**\
2.6.0 - added
## See also
{{< page-relref ref="methods/conversations" caption="conversations API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/conversation_serializer.rb" caption="app/serializers/rest/conversation_serializer.rb" >}}

81
content/en/entities/CustomEmoji.md Normal file
View File

@ -0,0 +1,81 @@
---
title: CustomEmoji
description: Represents a custom emoji.
menu:
docs:
parent: entities
aliases: [
"/entities/emoji",
"/entities/Emoji",
"/entities/customemoji",
"/entities/CustomEmoji",
"/api/entities/emoji",
"/api/entities/Emoji",
"/api/entities/customemoji",
"/api/entities/CustomEmoji",
]
---
## Example
```json
{
"shortcode": "blobaww",
"url": "https://files.mastodon.social/custom_emojis/images/000/011/739/original/blobaww.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/011/739/static/blobaww.png",
"visible_in_picker": true,
"category": "Blobs"
}
```
## Attributes
### `shortcode` {#shortcode}
**Description:** The name of the custom emoji.\
**Type:** String\
**Version history:**\
2.0.0 - added
### `url` {#url}
**Description:** A link to the custom emoji.\
**Type:** String (URL)\
**Version history:**\
2.0.0 - added
### `static_url` {#static_url}
**Description:** A link to a static copy of the custom emoji.\
**Type:** String (URL)\
**Version history:**\
2.0.0 - added
### `visible_in_picker` {#visible_in_picker}
**Description:** Whether this Emoji should be visible in the picker or unlisted.\
**Type:** Boolean\
**Version history:**\
2.0.0 - added
### `category` {#category}
**Description:** Used for sorting custom emoji in the picker.\
**Type:** String\
**Version history:**\
3.0.0 - added
## See also
{{< page-relref ref="methods/custom_emojis" caption="GET /api/v1/custom_emojis" >}}
{{< page-relref ref="entities/Status#emojis" caption="Status (`emojis` attribute)" >}}
{{< page-relref ref="entities/Announcement#emojis" caption="Announcement (`emojis` attribute)" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/custom_emoji_serializer.rb" caption="app/serializers/rest/custom_emoji_serializer.rb" >}}

62
content/en/entities/DomainBlock.md Normal file
View File

@ -0,0 +1,62 @@
---
title: DomainBlock
description: Represents a domain that is blocked by the instance.
menu:
docs:
parent: entities
aliases: [
"/entities/domainblock",
"/entities/DomainBlock",
"/api/entities/domainblock",
"/api/entities/DomainBlock",
]
---
## Example
```json
{
"domain":"daji******.com",
"digest":"3752f63a7079d60c2de5dceb8bd7608e86a15544eb78a494a482041c3684b37f",
"severity":"suspend",
"comment":"Inappropriate content"
}
```
## Attributes
### `domain` {#domain}
**Description:** The domain which is blocked. This may be obfuscated or partially censored.\
**Type:** String\
**Version history:**\
4.0.0 - added
### `digest` {#digest}
**Description:** The SHA256 hash digest of the domain string.\
**Type:** String (SHA256)\
**Version history:**\
4.0.0 - added
### `severity` {#severity}
**Description:** The level to which the domain is blocked.\
**Type:** String (Enumerable, oneOf)\
`silence` = Users from this domain will be hidden from timelines, threads, and notifications (unless you follow the user).\
`suspend` = Incoming messages from this domain will be rejected and dropped entirely.\
**Version history:**\
4.0.0 - added
### `comment` {{<optional>}} {#comment}
**Description:** An optional reason for the domain block.\
**Type:** String\
**Version history:**\
4.0.0 - added
## See also
{{< page-relref ref="methods/instance#domain_blocks" caption="GET /api/v1/instance/domain_blocks" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/domain_block_serializer.rb" caption="app/serializers/rest/domain_block_serializer.rb" >}}

90
content/en/entities/EncryptedMessage.md Normal file
View File

@ -0,0 +1,90 @@
---
title: EncryptedMessage
description: Represents an encrypted message.
menu:
docs:
parent: entities
aliases: [
"/entities/encryptedmessage",
"/entities/EncryptedMessage",
"/entities/encryptedmessage",
"/entities/EncryptedMessage",
]
draft: true
---
{{< hint style="info" >}}
This entity is currently unused.
{{</hint>}}
## Example
```json
```
## Attributes
### `id` {#id}
**Description:** The ID of the EncryptedMessage in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
3.2.0 - added
### `account_id` {#account_id}
**Description:** The ID of the Account that sent this message.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
3.2.0 - added
### `device_id` {#device_id}
**Description:** The ID of the Device that sent this message.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
3.2.0 - added
### `type` {#type}
**Description:** Whether the message is a pre-key message (used to establish a new session) or a normally encrypted message (part of an existing session).\
**Type:** String (Enumerable, oneOf)\
`0` = Pre-key message (used to establish a new session)\
`1` = Normal encrypted message (part of an existing session)\
**Version history:**\
3.2.0 - added
### `body` {#body}
**Description:** The encrypted message content.\
**Type:** String\
**Version history:**\
3.2.0 - added
### `digest` {#digest}
**Description:** An HMAC SHA-256 digest hash of the message.\
**Type:** String (SHA256)\
**Version history:**\
3.2.0 - added
### `message_franking` {#message_franking}
**Description:** A signed value to be used when reporting the message body for its content.\
**Type:** String\
**Version history:**\
3.2.0 - added
### `created_at` {#created_at}
**Description:** A timestamp for when the message was created.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
3.2.0 - added
## See also
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/encrypted_message_serializer.rb" caption="app/serializers/rest/encrypted_message_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/pull/13820" caption="Add end-to-end encryption API (#13820)" >}}

125
content/en/entities/Error.md Normal file
View File

@ -0,0 +1,125 @@
---
title: Error
description: Represents an error message.
menu:
docs:
parent: entities
aliases: [
"/entities/error",
"/entities/Error",
"/api/entities/error",
"/api/entities/Error",
]
---
## Example
```json
{
"error": "invalid_grant",
"error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."
}
```
{{< hint style="info" >}}
**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 containing more information, if available.
{{< /hint >}}
## Attributes
### `error` {#error}
**Description:** The error message.\
**Type:** String\
**Version history:**\
0.6.0 - added
### `error_description` {{%optional%}} {#error_description}
**Description:** A longer description of the error, mainly provided with the OAuth API.\
**Type:** String\
**Version history:**\
0.6.0 - added
## Possible reasons {#reasons}
### 400 - Bad request
#### ParameterMissing {#parameter-missing}
Error: {string}. Appears when a required parameter is missing from the API call.
### 401 - Unauthorized {#401}
#### require_authenticated_user! {#auth}
Error: This API requires an authenticated user. Appears when the instance is in secure mode, which disables all public use of API methods.
### 403 - Forbidden {#403}
#### NotPermitted {#not-permitted}
Error: This action is not allowed. Appears when trying to call a method that you do not have permission for (such as admin or staff methods), or performing actions you are not allowed to do (such as following a user that blocks you).
#### current_user.disabled? {#disabled}
Error: Your login is currently disabled. Appears when the OAuth token's authorized user has had their account disabled by a moderator.
#### !current_user.confirmed? {#unconfirmed}
Error: Your login is missing a confirmed e-mail address. Appears when the email address associated with the OAuth token's authorized user's account has not yet been confirmed.
#### !current_user.approved? {#unapproved}
Error: Your login is currently pending approval. Appears when the OAuth token's authorized user has signed up on an instance with approval-required registrations, and the user has not yet had their account approved by a moderator.
### 404 - Not found {#404}
#### RecordNotFound {#not-found}
Error: Record not found. Appears when an entity record does not exist, or the authorized user is not within the audience of a private entity.operates on a user.
### 422 - Unprocessable entity {#422}
#### RecordInvalid {#invalid}
Error: {string}. May appear when entity creation failed.
#### RecordNotUnique {#not-unique}
Error: Duplicate record. Appears when you are trying to pin an account or status that is already pinned.
#### !current_user {#user-required}
Error: This method requires an authenticated user. Appears when using an OAuth token without an authorized user (or no token at all), while trying to call an API method that requires a user to be processed.
### 429 - Too many requests {#429}
Error: {translated string}. Appears when you have exceeded the rate limit. See [Rate limits]({{< relref "api/rate-limits" >}}) for more information.
### 503 - Remote service unavailable {#503}
#### UnexpectedResponseError {#unexpected-response}
Error: Remote data could not be fetched. Appears when Mastodon calls a remote service (such as WebFinger from another instance) which returns an error.
#### SSLError {#ssl}
Error: Remote SSL certificate could not be verified. Appears when a remote service is called, but it has an invalid SSL certificate.
#### NetworkingError {#networking-error}
Error: There was a temporary problem serving your request, please try again. Appears when there was a failed call to an S3 storage server.
#### RaceConditionError {#race-condition}
Error: There was a temporary problem serving your request, please try again. Appears when there was an error due to a race condition in server-side code.
## See also
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/base_controller.rb" caption="app/controllers/api/base_controller.rb" >}}

44
content/en/entities/ExtendedDescription.md Normal file
View File

@ -0,0 +1,44 @@
---
title: ExtendedDescription
description: Represents an extended description for the instance, to be shown on its about page.
menu:
docs:
parent: entities
aliases: [
"/entities/extendeddescription",
"/entities/ExtendedDescription",
"/api/entities/extendeddescription",
"/api/entities/ExtendedDescription",
]
---
## Example
```json
{
"updated_at":"2022-11-03T04:09:07Z",
"content":"<p>For inquiries not related specifically to the operation of this server, such as press inquiries, please contact <a href=\"mailto:press@joinmastodon.org\">press@joinmastodon.org</a>.</p>\n\n<h2>Funding</h2>\n\n<p>This server is crowdfunded by <a href=\"https://patreon.com/mastodon\">Patreon donations</a>. For a list of sponsors, see <a href=\"https://joinmastodon.org/sponsors\">joinmastodon.org</a>.</p>\n\n<h2>Reporting and moderation</h2>\n\n<p>When reporting accounts, please make sure to include at least a few posts that show rule-breaking behaviour, when applicable. If there is any additional context that might help make a decision, please also include it in the comment. This is especially important when the content is in a language nobody on the moderation team speaks.</p>\n\n<p>We usually handle reports within 24 hours. Please mind that you are not notified when a report you have made has led to a punitive action, and that not all punitive actions are externally visible. For first time offenses, we may opt to delete offending content, escalating to harsher measures on repeat offenses.</p>\n\n<h2>Impressum</h2>\n\n<p>Mastodon gGmbH<br>\nMühlenstraße 8a<br>\n14167 Berlin<br>\nGermany</p>\n\n<p>E-Mail-Adresse: hello@joinmastodon.org</p>\n\n<p>Vertretungsberechtigt: Eugen Rochko (Geschäftsführer)</p>\n\n<p>Umsatzsteuer Identifikationsnummer (USt-ID): DE344258260</p>\n\n<p>Handelsregister<br>\nGeführt bei: Amtsgericht Charlottenburg<br>\nNummer: HRB 230086 B</p>\n"
}
```
## Attributes
### `updated_at` {#updated_at}
**Description:** A timestamp of when the extended description was last updated.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
4.0.0 - added
### `content` {#content}
**Description:** The rendered HTML content of the extended description.\
**Type:** String (HTML)\
**Version history:**\
4.0.0 - added
## See also
{{< page-relref ref="methods/instance#extended_description" caption="GET /api/v1/instance/extended_description" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/extended_description_serializer.rb" caption="app/serializers/rest/extended_description_serializer.rb" >}}

64
content/en/entities/FamiliarFollowers.md Normal file
View File

@ -0,0 +1,64 @@
---
title: FamiliarFollowers
description: Represents a subset of your follows who also follow some other user.
menu:
docs:
parent: entities
aliases: [
"/entities/familiarfollowers",
"/entities/FamiliarFollowers",
"/api/entities/familiarfollowers",
"/api/entities/FamiliarFollowers",
]
---
## Example
```json
[
{
"id":"1",
"accounts":[
{
"id":"1087990",
"username":"moss",
"acct":"moss@goblin.camp",
// ...
},
{
"id":"1092723",
"username":"vivianrose",
"acct":"vivianrose",
// ...
},
// ...
]
},
{
"id":"2",
"accounts":[]
}
]
```
## Attributes
### `id` {#id}
**Description:** The ID of the Account in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
3.5.0 - added
### `accounts` {#accounts}
**Description:** Accounts you follow that also follow this account.\
**Type:** Array of [Account]({{< relref "entities/Account" >}})\
**Version history:**\
3.5.0 - added
## See also
{{< page-relref ref="methods/accounts#familiar_followers" caption="GET /api/v1/accounts/:id/familiar_followers" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/familiar_followers_serializer.rb" caption="app/serializers/rest/familiar_followers_serializer.rb" >}}

73
content/en/entities/FeaturedTag.md Normal file
View File

@ -0,0 +1,73 @@
---
title: FeaturedTag
description: Represents a hashtag that is featured on a profile.
menu:
docs:
parent: entities
aliases: [
"/entities/featuredtag",
"/entities/FeaturedTag",
"/api/entities/featuredtag",
"/api/entities/FeaturedTag",
]
---
## Example
```json
{
"id": "627",
"name": "nowplaying",
"url": "https://mastodon.social/@trwnh/tagged/nowplaying",
"statuses_count": 70,
"last_status_at": "2022-08-29T12:03:35.061Z"
}
```
## Attributes
### `id` {#id}
**Description:** The internal ID of the featured tag in the database.\
**Type:** String (cast from integer but not guaranteed to be a number)\
**Version history:**\
3.0.0 - added
### `name` {#name}
**Description:** The name of the hashtag being featured.\
**Type:** String\
**Version history:**\
3.0.0 - added
### `url` {#url}
**Description:** A link to all statuses by a user that contain this hashtag.\
**Type:** String (URL)\
**Version history:**\
3.3.0 - added
### `statuses_count` {#statuses_count}
**Description:** The number of authored statuses containing this hashtag.\
**Type:** Integer\
**Version history:**\
3.0.0 - added
### `last_status_at` {#last_status_at}
**Description:** The timestamp of the last authored status containing this hashtag.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
3.0.0 - added
## See also
{{< page-relref ref="methods/featured_tags" caption="featured_tags API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/featured_tag_serializer.rb" caption="app/serializers/rest/featured_tag_serializer.rb" >}}

108
content/en/entities/Filter.md Normal file
View File

@ -0,0 +1,108 @@
---
title: Filter
description: Represents a user-defined filter for determining which statuses should not be shown to the user.
menu:
docs:
parent: entities
aliases: [
"/entities/filter",
"/entities/Filter",
"/api/entities/filter",
"/api/entities/Filter",
]
---
## Example
```json
{
"id": "19972",
"title": "Test filter",
"context": [
"home"
],
"expires_at": "2022-09-20T17:27:39.296Z",
"filter_action": "warn",
"keywords": [
{
"id": "1197",
"keyword": "bad word",
"whole_word": false
}
],
"statuses": [
{
"id": "1",
"status_id": "109031743575371913"
}
]
}
```
## Attributes
### `id` {#id}
**Description:** The ID of the Filter in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
4.0.0 - added
### `title` {#title}
**Description:** A title given by the user to name the filter.\
**Type:** String\
**Version history:**\
4.0.0 - added
### `context` {#context}
**Description:** The contexts in which the filter should be applied.\
**Type:** Array of String (Enumerable, anyOf)\
`home` = home timeline and lists\
`notifications` = notifications timeline\
`public` = public timelines\
`thread` = expanded thread of a detailed status\
`account` = when viewing a profile\
**Version history:**\
4.0.0 - added
### `expires_at` {#expires_at}
**Description:** When the filter should no longer be applied.\
**Type:** {{<nullable>}} String (ISO 8601 Datetime), or null if the filter does not expire\
**Version history:**\
4.0.0 - added
### `filter_action` {#filter_action}
**Description:** The action to be taken when a status matches this filter.\
**Type:** String (Enumerable, oneOf)\
`warn` = show a warning that identifies the matching filter by `title`, and allow the user to expand the filtered status. This is the default (and unknown values should be treated as equivalent to `warn`).\
`hide` = do not show this status if it is received\
**Version history:**\
4.0.0 - added
### `keywords` {#keywords}
**Description:** The keywords grouped under this filter.\
**Type:** Array of [FilterKeyword]({{< relref "entities/FilterKeyword" >}})\
**Version history:**\
4.0.0 - added
### `statuses` {#statuses}
**Description:** The statuses grouped under this filter.\
**Type:** Array of [FilterStatus]({{< relref "entities/FilterStatus" >}})\
**Version history:**\
4.0.0 - added
## See also
{{< page-relref ref="api/guidelines#filters" caption="Implementation guidelines for filters" >}}
{{< page-relref ref="entities/V1_Filter" caption="V1::Filter (for Mastodon 3.5 and earlier)" >}}
{{< page-relref ref="methods/filters" caption="/api/v2/filters methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/filter_serializer.rb" caption="app/serializers/rest/filter_serializer.rb" >}}

54
content/en/entities/FilterKeyword.md Normal file
View File

@ -0,0 +1,54 @@
---
title: FilterKeyword
description: Represents a keyword that, if matched, should cause the filter action to be taken.
menu:
docs:
parent: entities
aliases: [
"/entities/filterkeyword",
"/entities/FilterKeyword",
"/api/entities/filterkeyword",
"/api/entities/FilterKeyword",
]
---
## Example
```json
{
"id": "1197",
"keyword": "bad word",
"whole_word": false
}
```
## Attributes
### `id` {#id}
**Description:** The ID of the FilterKeyword in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
4.0.0 - added
### `keyword` {#keyword}
**Description:** The phrase to be matched against.\
**Type:** String\
**Version history:**\
4.0.0 - added
### `whole_word` {#whole_word}
**Description:** Should the filter consider word boundaries? See [implementation guidelines for filters]({{< relref "api/guidelines#filters" >}}).\
**Type:** Boolean\
**Version history:**\
4.0.0 - added
## See also
{{< page-relref ref="api/guidelines#filters" caption="Implementation guidelines for filters" >}}
{{< page-relref ref="methods/filters" caption="/api/v2/filters methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/filter_keyword_serializer.rb" caption="app/serializers/rest/filter_keyword_serializer.rb" >}}

66
content/en/entities/FilterResult.md Normal file
View File

@ -0,0 +1,66 @@
---
title: FilterResult
description: Represents a filter whose keywords matched a given status.
menu:
docs:
parent: entities
aliases: [
"/entities/filterresult",
"/entities/FilterResult",
"/api/entities/filterresult",
"/api/entities/FilterResult",
]
---
## Example
```json
{
"filter": {
"id": "3",
"title": "Hide completely",
"context": [
"home"
],
"expires_at": "2022-09-20T17:27:39.296Z",
"filter_action": "hide"
},
"keyword_matches": [
"bad word"
],
"status_matches": [
"109031743575371913"
]
}
```
## Attributes
### `filter` {#filter}
**Description:** The filter that was matched.\
**Type:** [Filter]({{< relref "entities/Filter" >}})\
**Version history:**\
4.0.0 - added
### `keyword_matches` {#keyword_matches}
**Description:** The keyword within the filter that was matched.\
**Type:** {{<nullable>}} Array of String, or null\
**Version history:**\
4.0.0 - added
### `status_matches` {#status_matches}
**Description:** The status ID within the filter that was matched.\
**Type:** {{<nullable>}} Array of String, or null\
**Version history:**\
4.0.0 - added
## See also
{{< page-relref ref="api/guidelines#filters" caption="Implementation guidelines for filters" >}}
{{< page-relref ref="methods/filters" caption="/api/v2/filters methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/filter_result_serializer.rb" caption="app/serializers/rest/filter_result_serializer.rb" >}}

46
content/en/entities/FilterStatus.md Normal file
View File

@ -0,0 +1,46 @@
---
title: FilterStatus
description: Represents a status ID that, if matched, should cause the filter action to be taken.
menu:
docs:
parent: entities
aliases: [
"/entities/filterstatus",
"/entities/FilterStatus",
"/api/entities/filterstatus",
"/api/entities/FilterStatus",
]
---
## Example
```json
{
"id": "1",
"status_id": "109031743575371913"
}
```
## Attributes
### `id` {#id}
**Description:** The ID of the FilterStatus in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
4.0.0 - added
### `status_id` {#keyword}
**Description:** The ID of the Status that will be filtered.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
4.0.0 - added
## See also
{{< page-relref ref="api/guidelines#filters" caption="Implementation guidelines for filters" >}}
{{< page-relref ref="methods/filters" caption="/api/v2/filters methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/filter_status_serializer.rb" caption="app/serializers/rest/filter_status_serializer.rb" >}}

55
content/en/entities/identityproof.md → content/en/entities/IdentityProof.md
View File

@ -4,9 +4,19 @@ description: Represents a proof from an external identity provider.
menu:
docs:
parent: entities
aliases: [
"/entities/identityproof",
"/entities/IdentityProof",
"/api/entities/identityproof",
"/api/entities/IdentityProof",
]
---
```javascript
{{< hint style="danger" >}}
Identity proofs have been deprecated in 3.5.0 and newer. Previously, the only proof provider was Keybase, but development on Keybase has stalled entirely since it was acquired by Zoom.
{{< /hint >}}
```json
{
"provider": "Keybase",
"provider_username": "gargron",
@ -22,39 +32,42 @@ menu:
**Description:** The name of the identity provider.\
**Type:** String\
**Version history:** Added in 2.8.0
**Version history:**\
2.8.0 - added
### `provider_username` {#provider_username}
**Description:** The account owner's username on the identity provider's service.\
**Type:** String\
**Version history:** Added in 2.8.0
### `profile_url` {#profile_url}
**Description:** The account owner's profile URL on the identity provider.\
**Type:** String \(URL\)\
**Version history:** Added in 2.8.0
### `proof_url` {#proof_url}
**Description:** A link to a statement of identity proof, hosted by the identity provider.\
**Type:** String \(URL\)\
**Version history:** Added in 2.8.0
**Version history:**\
2.8.0 - added
### `updated_at` {#updated_at}
**Description:** When the identity proof was last updated.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:** Added in 2.8.0
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
2.8.0 - added
### `proof_url` {#proof_url}
**Description:** A link to a statement of identity proof, hosted by the identity provider.\
**Type:** String (URL)\
**Version history:**\
2.8.0 - added
### `profile_url` {#profile_url}
**Description:** The account owner's profile URL on the identity provider.\
**Type:** String (URL)\
**Version history:**\
2.8.0 - added
## See also
* [GET /api/v1/accounts/:id/identity\_proofs]({{< relref "../methods/accounts/#identity-proofs" >}})
* /api/proofs
* [About identity proofs]({{< relref "../user/contacts.md#identity-proofs" >}})
{{< page-relref ref="methods/accounts#identity_proofs" caption="GET /api/v1/accounts/:id/identity_proofs" >}}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/identity_proof_serializer.rb" caption="app/serializers/rest/identity\_proof\_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/pull/17045" caption="Remove Keybase integration (#17045)" >}}

502
content/en/entities/Instance.md Normal file
View File

@ -0,0 +1,502 @@
---
title: Instance
description: Represents the software instance of Mastodon running on this domain.
menu:
docs:
parent: entities
aliases: [
"/entities/instance",
"/entities/Instance",
"/api/entities/instance",
"/api/entities/Instance",
]
---
## Example
```json
{
"domain": "mastodon.social",
"title": "Mastodon",
"version": "4.0.0rc1",
"source_url": "https://github.com/mastodon/mastodon",
"description": "The original server operated by the Mastodon gGmbH non-profit",
"usage": {
"users": {
"active_month": 123122
}
},
"thumbnail": {
"url": "https://files.mastodon.social/site_uploads/files/000/000/001/@1x/57c12f441d083cde.png",
"blurhash": "UeKUpFxuo~R%0nW;WCnhF6RjaJt757oJodS$",
"versions": {
"@1x": "https://files.mastodon.social/site_uploads/files/000/000/001/@1x/57c12f441d083cde.png",
"@2x": "https://files.mastodon.social/site_uploads/files/000/000/001/@2x/57c12f441d083cde.png"
}
},
"languages": [
"en"
],
"configuration": {
"urls": {
"streaming": "wss://mastodon.social"
},
"vapid": {
"public_key": "BCkMmVdKDnKYwzVCDC99Iuc9GvId-x7-kKtuHnLgfF98ENiZp_aj-UNthbCdI70DqN1zUVis-x0Wrot2sBagkMc="
},
"accounts": {
"max_featured_tags": 10
},
"statuses": {
"max_characters": 500,
"max_media_attachments": 4,
"characters_reserved_per_url": 23
},
"media_attachments": {
"supported_mime_types": [
"image/jpeg",
"image/png",
"image/gif",
"image/heic",
"image/heif",
"image/webp",
"video/webm",
"video/mp4",
"video/quicktime",
"video/ogg",
"audio/wave",
"audio/wav",
"audio/x-wav",
"audio/x-pn-wave",
"audio/vnd.wave",
"audio/ogg",
"audio/vorbis",
"audio/mpeg",
"audio/mp3",
"audio/webm",
"audio/flac",
"audio/aac",
"audio/m4a",
"audio/x-m4a",
"audio/mp4",
"audio/3gpp",
"video/x-ms-asf"
],
"image_size_limit": 10485760,
"image_matrix_limit": 16777216,
"video_size_limit": 41943040,
"video_frame_rate_limit": 60,
"video_matrix_limit": 2304000
},
"polls": {
"max_options": 4,
"max_characters_per_option": 50,
"min_expiration": 300,
"max_expiration": 2629746
},
"translation": {
"enabled": true
}
},
"registrations": {
"enabled": false,
"approval_required": false,
"message": null
},
"contact": {
"email": "staff@mastodon.social",
"account": {
"id": "1",
"username": "Gargron",
"acct": "Gargron",
"display_name": "Eugen 💀",
"locked": false,
"bot": false,
"discoverable": true,
"group": false,
"created_at": "2016-03-16T00:00:00.000Z",
"note": "<p>Founder, CEO and lead developer <span class=\"h-card\"><a href=\"https://mastodon.social/@Mastodon\" class=\"u-url mention\">@<span>Mastodon</span></a></span>, Germany.</p>",
"url": "https://mastodon.social/@Gargron",
"avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg",
"avatar_static": "https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg",
"header": "https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg",
"header_static": "https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg",
"followers_count": 133026,
"following_count": 311,
"statuses_count": 72605,
"last_status_at": "2022-10-31",
"noindex": false,
"emojis": [],
"fields": [
{
"name": "Patreon",
"value": "<a href=\"https://www.patreon.com/mastodon\" target=\"_blank\" rel=\"nofollow noopener noreferrer me\"><span class=\"invisible\">https://www.</span><span class=\"\">patreon.com/mastodon</span><span class=\"invisible\"></span></a>",
"verified_at": null
}
]
}
},
"rules": [
{
"id": "1",
"text": "Sexually explicit or violent media must be marked as sensitive when posting"
},
{
"id": "2",
"text": "No racism, sexism, homophobia, transphobia, xenophobia, or casteism"
},
{
"id": "3",
"text": "No incitement of violence or promotion of violent ideologies"
},
{
"id": "4",
"text": "No harassment, dogpiling or doxxing of other users"
},
{
"id": "5",
"text": "No content illegal in Germany"
},
{
"id": "7",
"text": "Do not share intentionally false or misleading information"
}
]
}
```
## Attributes
### `domain` {#domain}
**Description:** The domain name of the instance.\
**Type:** String\
**Version history:**\
4.0.0 - added
### `title` {#title}
**Description:** The title of the website.\
**Type:** String\
**Version history:**\
4.0.0 - added
### `version` {#version}
**Description:** The version of Mastodon installed on the instance.\
**Type:** String\
**Version history:**\
4.0.0 - added
### `source_url` {#source_url}
**Description:** The URL for the source code of the software running on this instance, in keeping with AGPL license requirements.\
**Type:** String (URL)\
**Version history:**\
4.0.0 - added
### `description` {#description}
**Description:** A short, plain-text description defined by the admin.\
**Type:** String\
**Version history:**\
4.0.0 - added
### `usage` {#usage}
**Description:** Usage data for this instance.\
**Type:** Hash\
**Version history:**\
4.0.0 - added
#### `usage[users]` {#users}
**Description:** Usage data related to users on this instance.\
**Type:** Hash\
**Version history:**\
4.0.0 - added
##### `usage[users][active_month]` {#active_month}
**Description:** The number of active users in the past 4 weeks.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
### `thumbnail` {#thumbnail}
**Description:** An image used to represent this instance.\
**Type:** Hash\
**Version history:**\
4.0.0 - added
#### `thumbnail[url]` {#thumbnail-url}
**Description:** The URL for the thumbnail image.\
**Type:** String (URL)\
**Version history:**\
4.0.0 - added
#### `thumbnail[blurhash]` {{<optional>}} {#blurhash}
**Description:** A hash computed by [the BlurHash algorithm](https://github.com/woltapp/blurhash), for generating colorful preview thumbnails when media has not been downloaded yet.\
**Type:** String (Blurhash)\
**Version history:**\
4.0.0 - added
#### `thumbnail[versions]` {{<optional>}} {#thumbnail-versions}
**Description:** Links to scaled resolution images, for high DPI screens.\
**Type:** Hash\
**Version history:**\
4.0.0 - added
##### `thumbnail[versions][@1x]` {{<optional>}} {#1x}
**Description:** The URL for the thumbnail image at 1x resolution.\
**Type:** String (URL)\
**Version history:**\
4.0.0 - added
##### `thumbnail[versions][@2x]` {{<optional>}} {#2x}
**Description:** The URL for the thumbnail image at 2x resolution.\
**Type:** String (URL)\
**Version history:**\
4.0.0 - added
### `languages` {#languages}
**Description:** Primary languages of the website and its staff.\
**Type:** Array of String (ISO 639-1 two-letter code)\
**Version history:**\
4.0.0 - added
### `configuration` {#configuration}
**Description:** Configured values and limits for this website.\
**Type:** Hash\
**Version history:**\
4.0.0 - added
#### `configuration[urls]` {#urls}
**Description:** URLs of interest for clients apps.\
**Type:** Hash\
**Version history:**\
4.0.0 - added
##### `configuration[urls][streaming_api]` {#streaming_api}
**Description:** The Websockets URL for connecting to the streaming API.\
**Type:** String (URL)\
**Version history:**\
4.0.0 - added
### `configuration[vapid][public_key]` (#vapid_public_key)
**Description:** The instances VAPID public key, used for push notifications, the same as [WebPushSubscription#server_key]({{< relref "entities/WebPushSubscription#server_key" >}}).\
**Type:** String\
**Version history:**\
4.3.0 - added
#### `configuration[accounts]` {#accounts}
**Description:** Limits related to accounts.\
**Type:** Hash\
**Version history:**\
4.0.0 - added
##### `configuration[accounts][max_featured_tags]` {#max_featured_tags}
**Description:** The maximum number of featured tags allowed for each account.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
#### `configuration[statuses]` {#statuses}
**Description:** Limits related to authoring statuses.\
**Type:** Hash\
**Version history:**\
4.0.0 - added
##### `configuration[statuses][max_characters]` {#max_characters}
**Description:** The maximum number of allowed characters per status.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
##### `configuration[statuses][max_media_attachments]` {#max_media_attachments}
**Description:** The maximum number of media attachments that can be added to a status.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
##### `configuration[statuses][characters_reserved_per_url]` {#characters_reserved_per_url}
**Description:** Each URL in a status will be assumed to be exactly this many characters.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
#### `configuration[media_attachments]` {#media_attachments}
**Description:** Hints for which attachments will be accepted.\
**Type:** Hash\
**Version history:**\
4.0.0 - added
##### `configuration[media_attachments][supported_mime_types]` {#supported_mime_types}
**Description:** Contains MIME types that can be uploaded.\
**Type:** Array of String\
**Version history:**\
4.0.0 - added
##### `configuration[media_attachments][image_size_limit]` {#image_size_limit}
**Description:** The maximum size of any uploaded image, in bytes.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
##### `configuration[media_attachments][image_matrix_limit]` {#image_matrix_limit}
**Description:** The maximum number of pixels (width times height) for image uploads.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
##### `configuration[media_attachments][video_size_limit]` {#video_size_limit}
**Description:** The maximum size of any uploaded video, in bytes.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
##### `configuration[media_attachments][video_frame_rate_limit]` {#video_frame_rate_limit}
**Description:** The maximum frame rate for any uploaded video.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
##### `configuration[media_attachments][video_matrix_limit]` {#video_matrix_limit}
**Description:** The maximum number of pixels (width times height) for video uploads.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
#### `configuration[polls]` {#polls}
**Description:** Limits related to polls.\
**Type:** Hash\
**Version history:**\
4.0.0 - added
##### `configuration[polls][max_options]` {#max_options}
**Description:** Each poll is allowed to have up to this many options.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
##### `configuration[polls][max_characters_per_option]` {#max_characters_per_option}
**Description:** Each poll option is allowed to have this many characters.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
##### `configuration[polls][min_expiration]` {#min_expiration}
**Description:** The shortest allowed poll duration, in seconds.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
##### `configuration[polls][max_expiration]` {#max_expiration}
**Description:** The longest allowed poll duration, in seconds.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
#### `configuration[translation]` {#translation}
**Description:** Hints related to translation.\
**Type:** Hash\
**Version history:**\
4.0.0 - added
##### `configuration[translation][enabled]` {#translation-enabled}
**Description:** Whether the Translations API is available on this instance.\
**Type:** Boolean\
**Version history:**\
4.0.0 - added
### `registrations`
**Description:** Information about registering for this website.\
**Type:** Hash\
**Version history:**\
4.0.0 - added
#### `registrations[enabled]` {#registrations-enabled}
**Description:** Whether registrations are enabled.\
**Type:** Boolean\
**Version history:**\
4.0.0 - added
#### `registrations[approval_required]` {#approval_required}
**Description:** Whether registrations require moderator approval.\
**Type:** Boolean\
**Version history:**\
4.0.0 - added
#### `registrations[message]` {#registrations-message}
**Description:** A custom message to be shown when registrations are closed.\
**Type:** {{<nullable>}} String (HTML) or null\
**Version history:**\
4.0.0 - added
### `contact` {#contact}
**Description:** Hints related to contacting a representative of the website.\
**Type:** Hash\
**Version history:**\
4.0.0 - added
#### `contact[email]` {#contact-email}
**Description:** An email address that can be messaged regarding inquiries or issues.\
**Type:** String (Email)\
**Version history:**\
4.0.0 - added
#### `contact[account]` {#contact-account}
**Description:** An account that can be contacted natively over the network regarding inquiries or issues.\
**Type:** [Account]({{< relref "entities/Account" >}})\
**Version history:**\
4.0.0 - added
### `rules` {#rules}
**Description:** An itemized list of rules for this website.\
**Type:** Array of [Rule]({{< relref "entities/Rule" >}})\
**Version history:**\
4.0.0 - added
## See also
{{< page-relref ref="methods/instance#v2" caption="GET /api/v2/instance" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/instance_serializer.rb" caption="app/serializers/rest/instance_serializer.rb" >}}

28
content/en/entities/list.md → content/en/entities/List.md
View File

@ -4,23 +4,29 @@ description: Represents a list of some users that the authenticated user follows
menu:
docs:
parent: entities
aliases: [
"/entities/list",
"/entities/List",
"/api/entities/list",
"/api/entities/List",
]
---
## Example
```javascript
{
"id": "12249",
"title": "Friends"
}
```json
{
"id": "12249",
"title": "Friends"
}
```
## Required attributes
## Attributes
### `id` {#id}
**Description:** The internal database ID of the list.\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
2.1.0 - added
@ -33,7 +39,7 @@ menu:
### `replies_policy` {#replies_policy}
**Description:** The user-defined title of the list.\
**Description:** Which replies should be shown in the list.\
**Type:** String (Enumerable oneOf)\
`followed` = Show replies to any followed user\
`list` = Show replies to members of the list\
@ -43,9 +49,11 @@ menu:
## See also
{{< page-ref page="methods/timelines/lists.md" >}}
{{< page-relref ref="methods/accounts#lists" caption="GET /api/v1/accounts/:id/lists" >}}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/list_serializer.rb" caption="app/serializers/rest/list\_serializer.rb" >}}
{{< page-relref ref="methods/lists" caption="lists API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/list_serializer.rb" caption="app/serializers/rest/list_serializer.rb" >}}

53
content/en/entities/Marker.md Normal file
View File

@ -0,0 +1,53 @@
---
title: Marker
description: Represents the last read position within a user's timelines.
menu:
docs:
parent: entities
aliases: [
"/entities/marker",
"/entities/Marker",
"/api/entities/marker",
"/api/entities/Marker",
]
---
## Example
```json
{
"last_read_id": "103194548672408537",
"version": 462,
"updated_at": "2019-11-24T19:39:39.337Z"
}
```
## Attributes
### `last_read_id` {#last_read_id}
**Description:** The ID of the most recently viewed entity.\
**Type:** String (cast from integer but not guaranteed to be a number)\
3.0.0 - added
### `version` {#version}
**Description:** An incrementing counter, used for locking to prevent write conflicts.\
**Type:** Integer\
**Version history:**\
3.0.0 - added
### `updated_at` {#updated_at}
**Description:** The timestamp of when the marker was set.\
**Type:** String (ISO 8601 Datetime)\
3.0.0 - added
## See also
{{< page-relref ref="methods/markers" caption="markers API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/marker_serializer.rb" caption="app/serializers/rest/marker_serializer.rb" >}}

112
content/en/entities/attachment.md → content/en/entities/MediaAttachment.md
View File

@ -1,16 +1,26 @@
---
title: Attachment
title: MediaAttachment
description: Represents a file or media attachment that can be added to a status.
menu:
docs:
parent: entities
aliases: [
"/entities/attachment",
"/entities/Attachment",
"/entities/mediaattachment",
"/entities/MediaAttachment",
"/api/entities/attachment",
"/api/entities/Attachment",
"/api/entities/mediaattachment",
"/api/entities/MediaAttachment",
]
---
## Example
{{< tabs >}}
{{< tab title="Image" >}}
```javascript
### Image
```json
{
"id": "22345792",
"type": "image",
@ -40,10 +50,10 @@ menu:
"blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}"
}
```
{{< endtab >}}
{{< tab title="Video" >}}
```javascript
### Video
```json
{
"id": "22546306",
"type": "video",
@ -80,10 +90,10 @@ menu:
"blurhash": "U58E0g8_0M.94T?bIr00?bD%NGoM?bD%oLt7"
}
```
{{< endtab >}}
{{< tab title="GIFV" >}}
```javascript
### GIFV
```json
{
"id": "21130559",
"type": "gifv",
@ -117,10 +127,10 @@ menu:
"blurhash": "URHT%Jm,2a1d%MRO%LozkrNH$*n*oMn$Rjt7"
}
```
{{< endtab >}}
{{< tab title="Audio" >}}
```javascript
### Audio
```json
{
"id": "21165404",
"type": "audio",
@ -143,88 +153,90 @@ menu:
"blurhash": null
}
```
{{< endtab >}}
{{< endtabs >}}
## Required attributes
## Attributes
### `id` {#id}
**Description:** The ID of the attachment in the database.\
**Type:** String \(cast from an integer but not guaranteed to be a number\)\
**Version history:** Added in 0.6.0.
**Type:** String (cast from an integer but not guaranteed to be a number)\
**Version history:**\
0.6.0 - added
### `type` {#type}
**Description:** The type of the attachment.\
**Type:** String \(Enumerable, oneOf\)\
**Type:** String (Enumerable, oneOf)\
`unknown` = unsupported or unrecognized file type\
`image` = Static image\
`gifv` = Looping, soundless animation\
`video` = Video clip\
`audio` = Audio track\
**Version history:** Added in 0.6.0. Audio added in 2.9.1.
**Version history:**\
0.6.0 - added\
2.9.1 - added `audio`
### `url` {#url}
**Description:** The location of the original full-size attachment.\
**Type:** String \(URL\)\
**Version history:** Added in 0.6.0.
**Type:** String (URL)\
**Version history:**\
0.6.0 - added
### `preview_url` {#preview_url}
**Description:** The location of a scaled-down preview of the attachment.\
**Type:** String \(URL\)\
**Version history:** Added in 0.6.0.
## Optional attributes
**Type:** String (URL)\
**Version history:**\
0.6.0 - added
### `remote_url` {#remote_url}
**Description:** The location of the full-size original attachment on the remote website.\
**Type:** String \(URL\), or null if the attachment is local\
**Version history:** Added in 0.6.0.
### `text_url` {#text_url}
**Description:** A shorter URL for the attachment.\
**Type:** String \(URL\)\
**Version history:** Added in 0.6.0.
**Type:** {{<nullable>}} String (URL), or null if the attachment is local\
**Version history:**\
0.6.0 - added
### `meta` {#meta}
**Description:** Metadata returned by Paperclip.\
**Type:** Hash\
**Version history:** Added in 1.5.0. meta\[focus\] added in 2.3.0.
**Version history:**\
1.5.0 - added\
2.3.0 - added `meta.focus`
May contain subtrees `small` and `original`, as well as various other top-level properties.
More importantly, there may be another top-level `focus` Hash object as of 2.3.0, with coordinates can be used for smart thumbnail cropping -- see [Focal points]({{< relref "../methods/statuses/media.md#focal-points" >}}) for more.
More importantly, there may be another topl-level `focus` Hash object on images as of 2.3.0, with coordinates can be used for smart thumbnail cropping -- see [Focal points for cropped media thumbnails]({{< relref "api/guidelines#focal-points" >}}) for more.
### `description` {#description}
**Description:** Alternate text that describes what is in the media attachment, to be used for the visually impaired or when media attachments do not load.\
**Type:** String\
**Version history:** Added in 2.0.0
**Version history:**\
2.0.0 - added
### `blurhash` {#blurhash}
**Description:** A hash computed by [the BlurHash algorithm](https://github.com/woltapp/blurhash), for generating colorful preview thumbnails when media has not been downloaded yet.\
**Type:** String\
**Version history:** Added in 2.8.1
**Type:** String (Blurhash)\
**Version history:**\
2.8.1 - added
## Deprecated attributes
### `text_url` {#text_url}
**Description:** A shorter URL for the attachment.\
**Type:** String (URL)\
**Version history:**\
0.6.0 - added\
3.5.0 - removed
## See also
* Status\#media\_attachments
* /api/v1/media
{{< page-ref page="status.md" >}}
{{< page-ref page="methods/statuses/media.md" >}}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/media_attachment_serializer.rb" caption="app/serializers/rest/media\_attachment\_serializer.rb" >}}
{{< page-relref ref="entities/Status#media_attachments" caption="Status (`media_attachments` attribute)" >}}
{{< page-relref ref="methods/media" caption="media API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/media_attachment_serializer.rb" caption="app/serializers/rest/media_attachment_serializer.rb" >}}

156
content/en/entities/notification.md → content/en/entities/Notification.md
View File

@ -4,13 +4,79 @@ description: Represents a notification of an event relevant to the user.
menu:
docs:
parent: entities
aliases: [
"/entities/notification",
"/entities/Notification",
"/entities/notification",
"/entities/Notification",
]
---
## Example
## Attributes
### `id` {#id}
**Description:** The id of the notification in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
0.9.9 - added
### `type` {#type}
**Description:** The type of event that resulted in the notification.\
**Type:** String (Enumerable oneOf)\
`mention` = Someone mentioned you in their status\
`status` = Someone you enabled notifications for has posted a status\
`reblog` = Someone boosted one of your statuses\
`follow` = Someone followed you\
`follow_request` = Someone requested to follow you\
`favourite` = Someone favourited one of your statuses\
`poll` = A poll you have voted in or created has ended\
`update` = A status you interacted with has been edited\
`admin.sign_up` = Someone signed up (optionally sent to admins)\
`admin.report` = A new report has been filed\
**Version history:**\
0.9.9 - added\
2.8.0 - added `poll`\
3.1.0 - added `follow_request`\
3.3.0 - added `status`\
3.5.0 - added `update` and `admin.sign_up`\
4.0.0 - added `admin.report`
### `created_at` {#created_at}
**Description:** The timestamp of the notification.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
0.9.9 - added
### `account` {#account}
**Description:** The account that performed the action that generated the notification.\
**Type:** [Account]({{< relref "entities/Account" >}})\
**Version history:**\
0.9.9 - added
### `status` {{%optional%}} {#status}
**Description:** Status that was the object of the notification. Attached when `type` of the notification is `favourite`, `reblog`, `status`, `mention`, `poll`, or `update`.\
**Type:** [Status]({{< relref "entities/Status" >}})\
**Version history:**\
0.9.9 - added
### `report` {{%optional%}} {#report}
**Description:** Report that was the object of the notification. Attached when `type` of the notification is `admin.report`.\
**Type:** [Report]({{< relref "entities/Report" >}})\
**Version history:**\
4.0.0 - added
## Examples
### Mention
```json
{{< code title="excerpt from GET notifications" >}}
```javascript
[
{
"id": "34975861",
"type": "mention",
@ -19,16 +85,21 @@ menu:
"id": "971724",
"username": "zsc",
"acct": "zsc",
...
// ...
},
"status": {
"id": "103186126728896492",
"created_at": "2019-11-23T07:49:01.940Z",
"in_reply_to_id": "103186038209478945",
"in_reply_to_account_id": "14715",
...
// ...
}
},
}
```
### Favourite
```json
{
"id": "34975535",
"type": "favourite",
@ -37,85 +108,28 @@ menu:
"id": "297420",
"username": "haskal",
"acct": "haskal@cybre.space",
...
// ...
},
"status": {
"id": "103186046267791694",
"created_at": "2019-11-23T07:28:34.210Z",
...
},
// ...
"account": {
"id": "14715",
"username": "trwnh",
"acct": "trwnh",
...
// ...
},
...
// ...
}
},
...
]
}
```
{{< /code >}}
## Required attributes
### `id` {#id}
**Description:** The id of the notification in the database.\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Version history:**\
0.9.9 - added
### `type` {#type}
**Description:** The type of event that resulted in the notification.\
**Type:** String \(Enumerable oneOf\)\
`follow` = Someone followed you\
`follow_request` = Someone requested to follow you\
`mention` = Someone mentioned you in their status\
`reblog` = Someone boosted one of your statuses\
`favourite` = Someone favourited one of your statuses\
`poll` = A poll you have voted in or created has ended\
`status` = Someone you enabled notifications for has posted a status\
**Version history:**\
0.9.9 - added\
2.8.0 - added `poll`\
3.1.0 - added `follow_request`\
3.3.0 - added `status`
### `created_at` {#created_at}
**Description:** The timestamp of the notification.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:**\
0.9.9 - added
### `account` {#account}
**Description:** The account that performed the action that generated the notification.\
**Type:** [Account]({{< relref "account.md" >}})\
**Version history:**\
0.9.9 - added
## Optional attributes
### `status` {#status}
**Description:** Status that was the object of the notification, e.g. in mentions, reblogs, favourites, or polls.\
**Type:** [Status]({{< relref "status.md" >}})\
**Version history:**\
0.9.9 - added
## See also
{{< page-ref page="account.md" >}}
{{< page-relref ref="methods/notifications" caption="notifications API methods" >}}
{{< page-ref page="status.md" >}}
{{< page-ref page="methods/notifications.md" >}}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/notification_serializer.rb" caption="app/serializers/rest/notification\_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/notification_serializer.rb" caption="app/serializers/rest/notification_serializer.rb" >}}

142
content/en/entities/Poll.md Normal file
View File

@ -0,0 +1,142 @@
---
title: Poll
description: Represents a poll attached to a status.
menu:
docs:
parent: entities
aliases: [
"/entities/poll",
"/entities/Poll",
"/api/entities/poll",
"/api/entities/Poll",
]
---
## Example
```json
{
"id": "34830",
"expires_at": "2019-12-05T04:05:08.302Z",
"expired": true,
"multiple": false,
"votes_count": 10,
"voters_count": null,
"voted": true,
"own_votes": [
1
],
"options": [
{
"title": "accept",
"votes_count": 6
},
{
"title": "deny",
"votes_count": 4
}
],
"emojis": []
}
```
## Attributes
### `id` {#id}
**Description:** The ID of the poll in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
2.8.0 - added
### `expires_at` {#expires_at}
**Description:** When the poll ends.\
**Type:** {{<nullable>}} String (ISO 8601 Datetime), or null if the poll does not end\
**Version history:**\
2.8.0 - added
### `expired` {#expired}
**Description:** Is the poll currently expired?\
**Type:** Boolean\
**Version history:**\
2.8.0 - added
### `multiple` {#multiple}
**Description:** Does the poll allow multiple-choice answers?\
**Type:** Boolean\
**Version history:**\
2.8.0 - added
### `votes_count` {#votes_count}
**Description:** How many votes have been received.\
**Type:** Integer\
**Version history:**\
2.8.0 - added
### `voters_count` {#voters_count}
**Description:** How many unique accounts have voted on a multiple-choice poll.\
**Type:** {{<nullable>}} Integer, or null if `multiple` is false.\
**Version history:**\
2.8.0 - added
### `options` {#options}
**Description:** Possible answers for the poll.\
**Type:** Array of [Poll::Option](#Option)\
**Version history:**\
2.8.0 - added
### `emojis` {#emojis}
**Description:** Custom emoji to be used for rendering poll options.\
**Type:** Array of [CustomEmoji]({{< relref "entities/CustomEmoji" >}})\
**Version history:**\
2.8.0 - added
### `voted` {{%optional%}} {#voted}
**Description:** When called with a user token, has the authorized user voted?\
**Type:** Boolean\
**Version history:**\
2.8.0 - added
### `own_votes` {{%optional%}} {#own_votes}
**Description:** When called with a user token, which options has the authorized user chosen? Contains an array of index values for `options`.\
**Type:** Array of Integer\
**Version history:**\
2.8.0 - added
## Poll::Option attributes {#Option}
### `title` {#option-title}
**Description:** The text value of the poll option.\
**Type:** String\
**Version history:**\
2.8.0 - added
#### `votes_count` {#option-votes_count}
**Description:** The total number of received votes for this option.\
**Type:** {{<nullable>}} Integer, or null if results are not published yet.\
**Version history:**\
2.8.0 - added
## See also
{{< page-relref ref="entities/Status#poll" caption="Status (`poll` attribute)" >}}
{{< page-relref ref="methods/polls" caption="polls API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/poll_serializer.rb" caption="app/serializers/rest/poll_serializer.rb" >}}

78
content/en/entities/Preferences.md Normal file
View File

@ -0,0 +1,78 @@
---
title: Preferences
description: Represents a user's preferences.
menu:
docs:
parent: entities
aliases: [
"/entities/preferences",
"/entities/Preferences",
"/api/entities/preferences",
"/api/entities/Preferences",
]
---
## Example
```json
{
"posting:default:visibility": "public",
"posting:default:sensitive": false,
"posting:default:language": null,
"reading:expand:media": "default",
"reading:expand:spoilers": false
}
```
## Attributes
### `posting:default:visibility` {#posting-default-visibility}
**Description:** Default visibility for new posts. Equivalent to [CredentialAccount#source\[privacy\]]({{< relref "entities/Account#source-privacy" >}}).\
**Type:** String (Enumerable, oneOf)\
`public` = Public post\
`unlisted` = Unlisted post\
`private` = Followers-only post\
`direct` = Direct post\
**Version history:**\
2.8.0 - added
### `posting:default:sensitive` {#posting-default-sensitive}
**Description:** Default sensitivity flag for new posts. Equivalent to [CredentialAccount#source\[sensitive\]]({{< relref "entities/Account#source-sensitive" >}}).\
**Type:** Boolean\
**Version history:**\
2.8.0 - added
### `posting:default:language` {#posting-default-language}
**Description:** Default language for new posts. Equivalent to [CredentialAccount#source\[language\]]({{< relref "entities/Account#source-language" >}})\
**Type:** {{<nullable>}} String (ISO 639-1 language two-letter code), or null\
**Version history:**\
2.8.0 - added
### `reading:expand:media` {#reading-expand-media}
**Description:** Whether media attachments should be automatically displayed or blurred/hidden.\
**Type:** String (Enumerable, oneOf)\
`default` = Hide media marked as sensitive\
`show_all` = Always show all media by default, regardless of sensitivity\
`hide_all` = Always hide all media by default, regardless of sensitivity\
**Version history:**\
2.8.0 - added
### `reading:expand:spoilers` {#reading-expand-spoilers}
**Description:** Whether CWs should be expanded by default.\
**Type:** Boolean\
**Version history:**\
2.8.0 - added
## See also
{{< page-relref ref="methods/preferences" caption="preferences API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/preferences_serializer.rb" caption="app/serializers/rest/preferences_serializer.rb" >}}

169
content/en/entities/card.md → content/en/entities/PreviewCard.md
View File

@ -1,14 +1,26 @@
---
title: Card
title: PreviewCard
description: Represents a rich preview card that is generated using OpenGraph tags from a URL.
menu:
docs:
parent: entities
aliases: [
"/entities/card",
"/entities/Card",
"/entities/previewcard",
"/entities/PreviewCard",
"/api/entities/card",
"/api/entities/Card",
"/api/entities/previewcard",
"/api/entities/PreviewCard",
]
---
{{< tabs >}}
{{< tab title="video" >}}
```javascript
## Examples
### Video
```json
{
"url": "https://www.youtube.com/watch?v=OMv_EPMED8Y",
"title": "♪ Brand New Friend (Christmas Song!)",
@ -26,10 +38,10 @@ menu:
"blurhash": "UvK0HNkV,:s9xBR%njog0fo2W=WBS5ozofV@"
}
```
{{< endtab >}}
{{< tab title="photo" >}}
```javascript
### Photo
```json
{
"url": "https://www.flickr.com/photos/tomfenskephotography/49088768431/",
"title": "Oregon",
@ -47,10 +59,10 @@ menu:
"blurhash": "UnE{@jt6M_oIAhjYs+ayT2WBf9ayRkkDXAj["
}
```
{{< endtab >}}
{{< tab title="link" >}}
```javascript
### Link
```json
{
"url": "https://www.theguardian.com/money/2019/dec/07/i-lost-my-193000-inheritance-with-one-wrong-digit-on-my-sort-code",
"title": "‘I lost my £193,000 inheritance – with one wrong digit on my sort code’",
@ -68,36 +80,34 @@ menu:
"blurhash": null
}
```
{{< endtab >}}
{{< endtabs >}}
## Base attributes
## Attributes
### `url`
### `url` {#url}
**Description:** Location of linked resource.\
**Type:** String \(URL\)\
**Type:** String (URL)\
**Version history:**\
1.0.0 - added
### `title`
### `title` {#title}
**Description:** Title of linked resource.\
**Type:** String\
**Version history:**\
1.0.0 - added
### `description`
### `description` {#description}
**Description:** Description of preview.\
**Type:** String\
**Version history:**\
1.0.0 - added
### `type`
### `type` {#type}
**Description:** The type of the preview card.\
**Type:** String \(Enumerable, oneOf\)\
**Type:** String (Enumerable, oneOf)\
`link` = Link OEmbed\
`photo` = Photo OEmbed\
`video` = Video OEmbed\
@ -105,8 +115,6 @@ menu:
**Version history:**\
1.3.0 - added
## Optional attributes
### `author_name` {#author_name}
**Description:** The author of the original resource.\
@ -117,7 +125,7 @@ menu:
### `author_url` {#author_url}
**Description:** A link to the author of the original resource.\
**Type:** String \(URL\)\
**Type:** String (URL)\
**Version history:**\
1.3.0 - added
@ -131,55 +139,144 @@ menu:
### `provider_url` {#provider_url}
**Description:** A link to the provider of the original resource.\
**Type:** String \(URL\)\
**Type:** String (URL)\
**Version history:**\
1.3.0 - added
### `html`
### `html` {#html}
**Description:** HTML to be used for generating the preview card.\
**Type:** String \(HTML\)\
**Type:** String (HTML)\
**Version history:**\
1.3.0 - added
### `width`
### `width` {#height}
**Description:** Width of preview, in pixels.\
**Type:** Number\
**Type:** Integer\
**Version history:**\
1.3.0 - added
### `height`
### `height` {#height}
**Description:** Height of preview, in pixels.\
**Type:** Number\
**Type:** Integer\
**Version history:**\
1.3.0 - added
### `image`
### `image` {#image}
**Description:** Preview thumbnail.\
**Type:** String \(URL\)\
**Type:** {{<nullable>}} String (URL)\
**Version history:**\
1.0.0 - added
### `embed_url` {#embed_url}
**Description:** Used for photo embeds, instead of custom `html`.\
**Type:** String \(URL\)\
**Type:** String (URL)\
**Version history:**\
2.1.0 - added
### `blurhash`
### `blurhash` {#blurhash}
**Description:** A hash computed by [the BlurHash algorithm](https://github.com/woltapp/blurhash), for generating colorful preview thumbnails when media has not been downloaded yet.\
**Type:** String\
**Type:** {{<nullable>}} String\
**Version history:**\
3.2.0 - added
## Trends::Link entity attributes {#trends-link}
```json
{
"url": "https://www.nbcnews.com/specials/plan-your-vote-2022-elections/index.html",
"title": "Plan Your Vote: 2022 Elections",
"description": "Everything you need to know about the voting rules where you live, including registration, mail-in voting, changes since 2020, and more.",
"type": "link",
"author_name": "NBC News",
"author_url": "",
"provider_name": "NBC News",
"provider_url": "",
"html": "",
"width": 400,
"height": 225,
"image": "https://files.mastodon.social/cache/preview_cards/images/045/027/478/original/0783d5e91a14fd49.jpeg",
"embed_url": "",
"blurhash": "UcQmF#ay~qofj[WBj[j[~qof9Fayofofayay",
"history": [
{
"day": "1661817600",
"accounts": "7",
"uses": "7"
},
{
"day": "1661731200",
"accounts": "23",
"uses": "23"
},
{
"day": "1661644800",
"accounts": "0",
"uses": "0"
},
{
"day": "1661558400",
"accounts": "0",
"uses": "0"
},
{
"day": "1661472000",
"accounts": "0",
"uses": "0"
},
{
"day": "1661385600",
"accounts": "0",
"uses": "0"
},
{
"day": "1661299200",
"accounts": "0",
"uses": "0"
}
]
}
```
### `history` {#history}
**Description:** Usage statistics for given days (typically the past week).\
**Type:** Array of Hash\
**Version history:**\
3.5.0 - added
#### `history[][day]` {#history-day}
**Description:** UNIX timestamp on midnight of the given day.\
**Type:** String (UNIX timestamp)\
**Version history:**\
3.5.0 - added
#### `history[][accounts]` {#history-accounts}
**Description:** The counted accounts using the link within that day.\
**Type:** String (cast from an integer)\
**Version history:**\
3.5.0 - added
#### `history[][uses]` {#history-uses}
**Description:** The counted statuses using the link within that day.\
**Type:** String (cast from an integer)\
**Version history:**\
3.5.0 - added
## See also
{{< page-ref page="status.md" >}}
{{< page-relref ref="entities/Status#card" caption="Status (`card` attribute)" >}}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/preview_card_serializer.rb" caption="app/serializers/rest/preview\_card\_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/preview_card_serializer.rb" caption="app/serializers/rest/preview_card_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/trends/link_serializer.rb" caption="app/serializers/rest/trends/link_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/trends/links.rb" caption="app/models/trends/links.rb" >}}

81
content/en/entities/Reaction.md Normal file
View File

@ -0,0 +1,81 @@
---
title: Reaction
description: Represents an emoji reaction to an Announcement.
menu:
docs:
parent: entities
aliases: [
"/entities/announcementreaction",
"/entities/AnnouncementReaction",
"/entities/reaction",
"/entities/Reaction",
"/api/entities/announcementreaction",
"/api/entities/AnnouncementReaction",
"/api/entities/reaction",
"/api/entities/Reaction",
]
---
## Example
```json
[
{
"name": "bongoCat",
"count": 9,
"me": false,
"url": "https://files.mastodon.social/custom_emojis/images/000/067/715/original/fdba57dff7576d53.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/067/715/static/fdba57dff7576d53.png"
},
{
"name": "🤔",
"count": 1,
"me": true
}
]
```
## Attributes
### `name` {#name}
**Description:** The emoji used for the reaction. Either a unicode emoji, or a custom emoji's shortcode.\
**Type:** String\
**Version history:**\
3.1.0 - added
### `count` {#count}
**Description:** The total number of users who have added this reaction.\
**Type:** Integer\
**Version history:**\
3.1.0 - added
### `me` {{%optional%}} {#me}
**Description:** If there is a currently authorized user: Have you added this reaction?\
**Type:** Boolean\
**Version history:**\
3.1.0 - added
### `url` {{%optional%}} {#url}
**Description:** If the reaction is a custom emoji: A link to the custom emoji.\
**Type:** String (URL)\
**Version history:**\
3.1.0 - added
### `static_url` {{%optional%}} {#static_url}
**Description:** If the reaction is a custom emoji: A link to a non-animated version of the custom emoji.\
**Type:** String (URL)\
**Version history:**\
3.1.0 - added
## See also
{{< page-relref ref="methods/announcements#put-reactions" caption="Add a reaction to an announcement" >}}
{{< page-relref ref="methods/announcements#delete-reactions" caption="Delete a reaction from an announcement" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/reaction_serializer.rb" caption="app/serializers/rest/reaction_serializer.rb" >}}

121
content/en/entities/relationship.md → content/en/entities/Relationship.md
View File

@ -4,11 +4,17 @@ description: Represents the relationship between accounts, such as following / b
menu:
docs:
parent: entities
aliases: [
"/entities/relationship",
"/entities/Relationship",
"/api/entities/relationship",
"/api/entities/Relationship",
]
---
## Example
```javascript
```json
{
"id": "1",
"following": true,
@ -26,56 +32,22 @@ menu:
}
```
## Required attributes
## Attributes
### `id`
### `id` {#id}
**Description:** The account id.\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Description:** The account ID.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
0.6.0 - added
### `following`
### `following` {#following}
**Description:** Are you following this user?\
**Type:** Boolean\
**Version history:**\
0.6.0 - added
### `requested`
**Description:** Do you have a pending follow request for this user?\
**Type:** Boolean\
**Version history:**\
0.9.9 - added
### `endorsed`
**Description:** Are you featuring this user on your profile?\
**Type:** Boolean\
**Version history:**\
2.5.0 - added
### `followed_by` {#followed_by}
**Description:** Are you followed by this user?\
**Type:** Boolean\
**Version history:**\
0.6.0 - added
### `muting`
**Description:** Are you muting this user?\
**Type:** Boolean\
**Version history:** Added in 1.1.0
### `muting_notifications` {#muting_notifications}
**Description:** Are you muting notifications from this user?\
**Type:** Boolean\
**Version history:**\
2.1.0 - added
### `showing_reblogs` {#showing_reblogs}
**Description:** Are you receiving this user's boosts in your home timeline?\
@ -90,20 +62,27 @@ menu:
**Version history:**\
3.3.0 - added
### `blocking`
### `languages` {#languages}
**Description:** Which languages are you following from this user?\
**Type:** Array of String (ISO 639-1 language two-letter code)\
**Version history:**\
4.0.0 - added
### `followed_by` {#followed_by}
**Description:** Are you followed by this user?\
**Type:** Boolean\
**Version history:**\
0.6.0 - added
### `blocking` {#blocking}
**Description:** Are you blocking this user?\
**Type:** Boolean\
**Version history:**\
0.6.0 - added
### `domain_blocking` {#domain_blocking}
**Description:** Are you blocking this user's domain?\
**Type:** Boolean\
**Version history:**\
1.4.0 - added
### `blocked_by` {#blocked_by}
**Description:** Is this user blocking you?\
@ -111,18 +90,50 @@ menu:
**Version history:**\
2.8.0 - added
### `note`
### `muting` {#muting}
**Description:** Is this user blocking you?\
**Description:** Are you muting this user?\
**Type:** Boolean\
**Version history:**\
1.1.0 - added
### `muting_notifications` {#muting_notifications}
**Description:** Are you muting notifications from this user?\
**Type:** Boolean\
**Version history:**\
2.1.0 - added
### `requested` {#requested}
**Description:** Do you have a pending follow request for this user?\
**Type:** Boolean\
**Version history:**\
0.9.9 - added
### `domain_blocking` {#domain_blocking}
**Description:** Are you blocking this user's domain?\
**Type:** Boolean\
**Version history:**\
1.4.0 - added
### `endorsed` {#endorsed}
**Description:** Are you featuring this user on your profile?\
**Type:** Boolean\
**Version history:**\
2.5.0 - added
### `note` {#note}
**Description:** This user's profile bio\
**Type:** String\
**Version history:**\
3.2.0 - added
## See also
* [GET /api/v1/accounts/relationships]({{< relref "../methods/accounts.md#check-relationships-to-other-accounts" >}})
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/relationship_serializer.rb" caption="app/serializers/rest/relationship\_serializer.rb" >}}
{{< page-relref ref="methods/accounts#relationships" caption="GET /api/v1/accounts/relationships" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/relationship_serializer.rb" caption="app/serializers/rest/relationship_serializer.rb" >}}

140
content/en/entities/Report.md Normal file
View File

@ -0,0 +1,140 @@
---
title: Report
description: Reports filed against users and/or statuses, to be taken action on by moderators.
menu:
docs:
parent: entities
aliases: [
"/entities/report",
"/entities/Report",
"/api/entities/report",
"/api/entities/Report",
]
---
## Example
```json
{
"id": "48914",
"action_taken": false,
"action_taken_at": null,
"category": "spam",
"comment": "Spam account",
"forwarded": false,
"created_at": "2022-08-25T09:56:16.763Z",
"status_ids": [
"108882889550545820"
],
"rule_ids": null,
"target_account": {
"id": "108366849347798387",
"username": "Baluke",
"acct": "Baluke",
"display_name": "Baluke Dental Studios",
"locked": false,
"bot": false,
"discoverable": false,
"group": false,
"created_at": "2022-05-26T00:00:00.000Z",
"note": "<p>Baluke Dental Studios is a full service dental lab offering fabrication, staining, and digital services. Advanced technologies and a meticulous process ensure reduced chair time, lower costs, and better patient outcomes with beautiful smiles. Talk to a representative today.</p><p><a href=\"https://baluke.com/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\"><span class=\"invisible\">https://</span><span class=\"\">baluke.com/</span><span class=\"invisible\"></span></a></p>",
"url": "https://mastodon.social/@Baluke",
"avatar": "https://files.mastodon.social/accounts/avatars/108/366/849/347/798/387/original/dbcfe99ed5def0f4.png",
"avatar_static": "https://files.mastodon.social/accounts/avatars/108/366/849/347/798/387/original/dbcfe99ed5def0f4.png",
"header": "https://static-cdn.mastodon.social/headers/original/missing.png",
"header_static": "https://static-cdn.mastodon.social/headers/original/missing.png",
"followers_count": 0,
"following_count": 0,
"statuses_count": 38,
"last_status_at": "2022-08-25",
"emojis": [],
"fields": []
}
}
```
## Attributes
### `id` {#id}
**Description:** The ID of the report in the database.\
**Type:** String (cast from integer)\
**Version history:**\
1.1.0 - added
### `action_taken` {#action_taken}
**Description:** Whether an action was taken yet.\
**Type:** Boolean\
**Version history:**\
1.1.0 - added
### `action_taken_at` {#action_taken_at}
**Description:** When an action was taken against the report.\
**Type:** {{<nullable>}} String (ISO 8601 Datetime) or null\
**Version history:**\
4.0.0 - added
### `category` {#category}
**Description:** The generic reason for the report.\
**Type:** String (Enumerable oneOf)\
`spam` = Unwanted or repetitive content\
`violation` = A specific rule was violated\
`other` = Some other reason\
**Version history:**\
4.0.0 - added
### `comment` {#comment}
**Description:** The reason for the report.\
**Type:** String\
**Version history:**\
4.0.0 - added
### `forwarded` {#forwarded}
**Description:** Whether the report was forwarded to a remote domain.\
**Type:** Boolean\
**Version history:**\
4.0.0 - added
### `created_at` {#created_at}
**Description:** When the report was created.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
4.0.0 - added
### `status_ids` {#status_ids}
**Description:** IDs of statuses that have been attached to this report for additional context.\
**Type:** {{<nullable>}} Array of String (cast from integer), or null\
**Version history:**\
4.0.0 - added
### `rule_ids` {#rule_ids}
**Description:** IDs of the rules that have been cited as a violation by this report.\
**Type:** {{<nullable>}} Array of String (cast from integer), or null\
**Version history:**\
4.0.0 - added
### `target_account` {#target_account}
**Description:** The account that was reported.\
**Type:** [Account]({{< relref "entities/account" >}})\
**Version history:**\
4.0.0 - added
## See also
{{< page-relref ref="methods/reports" caption="reports API methods" >}}
{{< page-relref ref="entities/Notification#report" caption="Notification (`report` attribute)" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/report_serializer.rb" caption="app/serializers/rest/report_serializer.rb" >}}

130
content/en/entities/Role.md Normal file
View File

@ -0,0 +1,130 @@
---
title: Role
description: Represents a custom user role that grants permissions.
menu:
docs:
parent: entities
aliases: [
"/entities/role",
"/entities/Role",
"/api/entities/role",
"/api/entities/Role",
]
---
## Example
```json
{
"id": 3,
"name": "Owner",
"color": "#ff3838",
"permissions": 1048575,
"highlighted": true
}
```
## Attributes
### `id` {#id}
**Description:** The ID of the Role in the database.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
### `name` {#name}
**Description:** The name of the role.\
**Type:** String\
**Version history:**\
4.0.0 - added
### `color` {#color}
**Description:** The hex code assigned to this role. If no hex code is assigned, the string will be empty.\
**Type:** String\
**Version history:**\
4.0.0 - added
### `permissions` {#permissions}
**Description:** A bitmask that represents the sum of all permissions granted to the role.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
### `highlighted` {#highlighted}
**Description:** Whether the role is publicly visible as a badge on user profiles.\
**Type:** Boolean\
**Version history:**\
4.0.0 - added
## Permission flags
To determine the permissions available to a certain role, convert the `permissions` attribute to binary and compare from the least significant bit upwards. For convenience (and to prevent the terms from growing too long), permissions will be presented below using hexadecimal values.
0x1
: **Administrator**. Users with this permission bypass all permissions.
0x2
: **Devops**. Allows users to access Sidekiq and pgHero dashboards.
0x4
: **View Audit Log**. Allows users to see history of admin actions.
0x8
: **View Dashboard**. Allows users to access the dashboard and various metrics.
0x10
: **Manage Reports**. Allows users to review reports and perform moderation actions against them.
0x20
: **Manage Federation**. Allows users to block or allow federation with other domains, and control deliverability.
0x40
: **Manage Settings**. Allows users to change site settings.
0x80
: **Manage Blocks**. Allows users to block e-mail providers and IP addresses.
0x100
: **Manage Taxonomies**. Allows users to review trending content and update hashtag settings.
0x200
: **Manage Appeals**. Allows users to review appeals against moderation actions.
0x400
: **Manage Users**. Allows users to view other users' details and perform moderation actions against them.
0x800
: **Manage Invites**. Allows users to browse and deactivate invite links.
0x1000
: **Manage Rules**. Allows users to change server rules.
0x2000
: **Manage Announcements**. Allows users to manage announcements on the server.
0x4000
: **Manage Custom Emojis**. Allows users to manage custom emojis on the server.
0x8000
: **Manage Webhooks**. Allows users to set up webhooks for administrative events.
0x10000
: **Invite Users**. Allows users to invite new people to the server.
0x20000
: **Manage Roles**. Allows users to manage and assign roles below theirs.
0x40000
: **Manage User Access**. Allows users to disable other users' two-factor authentication, change their e-mail address, and reset their password.
0x80000
: **Delete User Data**. Allows users to delete other users' data without delay.
## See also
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/role_serializer.rb" caption="app/serializers/rest/role_serializer.rb" >}}

50
content/en/entities/Rule.md Normal file
View File

@ -0,0 +1,50 @@
---
title: Rule
description: Represents a rule that server users should follow.
menu:
docs:
parent: entities
aliases: [
"/entities/rule",
"/entities/Rule",
"/api/entities/rule",
"/api/entities/Rule",
]
---
## Example
```json
{
"id": "2",
"text": "No racism, sexism, homophobia, transphobia, xenophobia, or casteism"
}
```
## Attributes
### `id` {#name}
**Description:** An identifier for the rule.\
**Type:** String (cast from integer, but not guaranteed to be a number)\
**Version history:**\
3.4.0 - added
### `text` {#url}
**Description:** The rule to be followed.\
**Type:** String \
**Version history:**\
3.4.0 - added
## See also
{{< page-relref ref="methods/instance#rules" caption="GET /api/v1/instance/rules" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/rule.rb" caption="app/models/rule.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/rule_serializer.rb" caption="app/serializers/rest/rule_serializer.rb" >}}

220
content/en/entities/ScheduledStatus.md Normal file
View File

@ -0,0 +1,220 @@
---
title: ScheduledStatus
description: Represents a status that will be published at a future scheduled date.
menu:
docs:
parent: entities
aliases: [
"/entities/scheduledstatus",
"/entities/ScheduledStatus",
"/api/entities/scheduledstatus",
"/api/entities/ScheduledStatus",
]
---
## Example
Returned from `POST /api/v1/statuses?status=test post&scheduled_at=2022-09-29`
```json
{
"id": "1",
"scheduled_at": "2022-09-29T00:00:00.000Z",
"params": {
"text": "test post",
"media_ids": null,
"sensitive": null,
"spoiler_text": null,
"visibility": null,
"language": null,
"scheduled_at": null,
"poll": null,
"idempotency": null,
"with_rate_limit": false,
"in_reply_to_id": null,
"application_id": 3
},
"media_attachments": []
}
```
Returned from `GET /api/v1/scheduled_statuses`:
```json
{
"id": "1",
"scheduled_at": "2022-09-29T00:00:00.000Z",
"params": {
"poll": null,
"text": "test post",
"language": null,
"media_ids": null,
"sensitive": null,
"visibility": null,
"idempotency": null,
"scheduled_at": null,
"spoiler_text": null,
"application_id": 3,
"in_reply_to_id": null,
"with_rate_limit": false
},
"media_attachments": []
}
```
## Attributes
### `id` {#id}
**Description:** ID of the scheduled status in the database.\
**Type:** String (cast from an integer but not guaranteed to be a number)\
**Version history:**\
2.7.0 - added
### `scheduled_at` {#scheduled_at}
**Description:** The timestamp for when the status will be posted.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
2.7.0 - added
### `params` {#params}
**Description:** The parameters that were used when scheduling the status, to be used when the status is posted.\
**Type:** Hash\
**Version history:**\
2.7.0 - added
#### `params[text]` {#params-text}
**Description:** Text to be used as status content.\
**Type:** String\
**Version history:**\
2.7.0 - added
#### `params[poll]` {#params-poll}
**Description:** Poll to be attached to the status.\
**Type:** {{<nullable>}} Hash\
**Version history:**\
2.8.0 - added
##### `params[poll][options[]]` {#params-poll-options}
**Description:** The poll options to be used.\
**Type:** Array of String\
**Version history:**\
2.8.0 - added
##### `params[poll][expires_in]` {#params-poll-expires_in}
**Description:** How many seconds the poll should last before closing.\
**Type:** String (cast from integer)\
**Version history:**\
2.8.0 - added
##### `params[poll][multiple]` {#params-poll-multiple}
**Description:** Whether the poll allows multiple choices.\
**Type:** {{<optional>}} Boolean\
**Version history:**\
2.8.0 - added
##### `params[poll][hide_totals]` {#params-poll-hide_totals}
**Description:** Whether the poll should hide total votes until after voting has ended.\
**Type:** {{<optional>}} Boolean\
**Version history:**\
2.8.0 - added
#### `params[media_ids]` {#params-media_ids}
**Description:** IDs of the MediaAttachments that will be attached to the status.\
**Type:** {{<nullable>}} Array of String\
**Version history:**\
2.7.0 - added
#### `params[sensitive]` {#params-sensitive}
**Description:** Whether the status will be marked as sensitive.\
**Type:** {{<nullable>}} Boolean\
**Version history:**\
2.7.0 - added
#### `params[spoiler_text]` {#params-spoiler_text}
**Description:** The text of the content warning or summary for the status.\
**Type:** {{<nullable>}} String\
**Version history:**\
2.7.0 - added
#### `params[visibility]` {#params-visibility}
**Description:** The visibility that the status will have once it is posted.\
**Type:** String (Enumerable oneOf)\
`public` = Visible to everyone, shown in public timelines.\
`unlisted` = Visible to public, but not included in public timelines.\
`private` = Visible to followers only, and to any mentioned users.\
`direct` = Visible only to mentioned users.\
**Version history:**\
2.7.0 - added
#### `params[in_reply_to_id]` {#params-in_reply_to_id}
**Description:** ID of the Status that will be replied to.\
**Type:** {{<nullable>}} Integer\
**Version history:**\
2.7.0 - added
#### `params[language]` {#params-language}
**Description:** The language that will be used for the status.\
**Type:** {{<nullable>}} String (ISO 639-1 two-letter language code)\
**Version history:**\
2.7.0 - added
#### `params[application_id]` {#params-application_id}
**Description:** ID of the Application that posted the status.\
**Type:** Integer\
**Version history:**\
2.7.0 - added
#### `params[scheduled_at]` {#params-scheduled_at}
**Description:** When the status will be scheduled. This will be null because the status is only scheduled once.\
**Type:** {{<nullable>}} Null\
**Version history:**\
2.7.0 - added
#### `params[idempotency]` {#params-idempotency}
**Description:** Idempotency key to prevent duplicate statuses.\
**Type:** {{<nullable>}} String\
**Version history:**\
2.7.0 - added
#### `params[with_rate_limit]` {#params-with_rate_limit}
**Description:** Whether the status should be rate limited <!-- TODO: What does this mean -->.\
**Type:** Boolean\
**Version history:**\
2.7.0 - added
### `media_attachments` {#media_attachments}
**Description:** Media that will be attached when the status is posted.\
**Type:** Array of [MediaAttachment]({{< relref "entities/MediaAttachment" >}})\
**Version history:**\
2.7.0 - added
## See also
{{< page-relref ref="methods/statuses#create" caption="POST /api/v1/statuses (with `scheduled_at` parameter)" >}}
{{< page-relref ref="methods/scheduled_statuses" caption="scheduled_statuses API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/scheduled_status_serializer.rb" caption="app/serializers/rest/scheduled_status_serializer.rb" >}}

70
content/en/entities/results.md → content/en/entities/Search.md
View File

@ -1,15 +1,26 @@
---
title: Results
title: Search
description: Represents the results of a search.
menu:
docs:
parent: entities
aliases: [
"/entities/results",
"/entities/Results",
"/entities/search",
"/entities/Search",
"/api/entities/results",
"/api/entities/Results",
"/api/entities/search",
"/api/entities/Search",
]
---
## Example
{{< code title="Truncated sample search for q=cats limit=2" >}}
```javascript
Truncated sample search for q=cats limit=2
```json
{
"accounts": [
{
@ -17,39 +28,34 @@ menu:
"username": "catstar",
"acct": "catstar@catgram.jp",
"display_name": "catstar",
...
// ...
},
{
"id": "214293",
"username": "catsareweird",
"acct": "catsareweird",
"display_name": "Cats Are Weird",
...
// ...
}
],
"statuses": [
{
"id": "103085519055545958",
"created_at": "2019-11-05T13:23:09.000Z",
...
// ...
"content": "<p>cats<br>cats never change</p>",
...
// ...
},
{
"id": "101068121469614510",
"created_at": "2018-11-14T06:31:48.000Z",
...
// ...
"spoiler_text": "Cats",
...
// ...
"content": "<p>Cats are inherently good at self-care. </p><p><a href=\"https://mspsocial.net/tags/cats\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>cats</span}</p>",
...
// ...
},
// ...
],
"hashtags": [
{
@ -61,8 +67,7 @@ menu:
"uses": "10",
"accounts": "9"
},
...
// ...
]
},
{
@ -74,40 +79,43 @@ menu:
"uses": "6",
"accounts": "5"
},
...
// ...
]
}
]
}
```
{{< /code >}}
## Required attributes
## Attributes
### `accounts` {#accounts}
**Description:** Accounts which match the given query\
**Type:** Array of [Account]({{< relref "account.md" >}})\
**Version history:** Added in x.x.x
**Type:** Array of [Account]({{< relref "entities/Account" >}})\
**Version history:**\
1.1.0 - added
### `statuses` {#statuses}
**Description:** Statuses which match the given query\
**Type:** Array of [Status]({{< relref "status.md" >}})\
**Version history:** Added in x.x.x
**Type:** Array of [Status]({{< relref "entities/Status" >}})\
**Version history:**\
1.1.0 - added
### `hashtags` {#hashtags}
**Description:** Hashtags which match the given query\
**Type:** Array of [Tag]({{< relref "tag.md" >}}) \(v2\). Array of String \(v1\).\
**Version history:** v1 added in 1.1.0 and deprecated in 3.0.0. v2 added in 2.4.1 and replaced v1 in 3.0.0.
**Type:** Array of [Tag]({{< relref "entities/Tag" >}})\
**Version history:**\
1.1.0 - added\
2.4.1 - v1/search deprecated because it returns Array of String. v2/search added which returns Array of Tag.\
3.0.0 - v1 removed
## See also
{{< page-ref page="methods/search.md" >}}
{{< page-relref ref="methods/search" caption="search API methods" >}}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/search_serializer.rb" caption="app/serializers/rest/search\_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/search_serializer.rb" caption="app/serializers/rest/search_serializer.rb" >}}

270
content/en/entities/status.md → content/en/entities/Status.md
View File

@ -4,11 +4,21 @@ description: Represents a status posted by an account.
menu:
docs:
parent: entities
aliases: [
"/entities/mention",
"/entities/Mention",
"/entities/status",
"/entities/Status",
"/api/entities/mention",
"/api/entities/Mention",
"/api/entities/status",
"/api/entities/Status",
]
---
## Example
```javascript
```json
{
"id": "103270115826048975",
"created_at": "2019-12-08T03:48:33.901Z",
@ -90,202 +100,296 @@ menu:
}
```
## Base attributes
## Attributes
### `id` {#id}
**Description:** ID of the status in the database.\
**Type:** String \(cast from an integer but not guaranteed to be a number\)\
**Version history:** Added in 0.1.0
**Type:** String (cast from an integer but not guaranteed to be a number)\
**Version history:**\
0.1.0 - added
### `uri` {#uri}
**Description:** URI of the status used for federation.\
**Type:** String\
**Version history:** Added in 0.1.0
**Version history:**\
0.1.0 - added
### `created_at` {#created_at}
**Description:** The date when this status was created.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:** Added in 0.1.0
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
0.1.0 - added
### `account` {#account}
**Description:** The account that authored this status.\
**Type:** [Account]({{< relref "account.md" >}})\
**Version history:** Added in 0.1.0
**Type:** [Account]({{< relref "entities/Account" >}})\
**Version history:**\
0.1.0 - added
### `content` {#content}
**Description:** HTML-encoded status content.\
**Type:** String \(HTML\)\
**Version history:** Added in 0.1.0
**Type:** String (HTML)\
**Version history:**\
0.1.0 - added
### `visibility` {#visibility}
**Description:** Visibility of this status.\
**Type:** String \(Enumerable oneOf\)\
**Type:** String (Enumerable oneOf)\
`public` = Visible to everyone, shown in public timelines.\
`unlisted` = Visible to public, but not included in public timelines.\
`private` = Visible to followers only, and to any mentioned users.\
`direct` = Visible only to mentioned users.\
**Version history:** Added in 0.9.9
**Version history:**\
0.9.9 - added
### `sensitive` {#sensitive}
**Description:** Is this status marked as sensitive content?\
**Type:** Boolean\
**Version history:** Added in 0.9.9
**Version history:**\
0.9.9 - added
### `spoiler_text` {#spoiler_text}
**Description:** Subject or summary line, below which status content is collapsed until expanded.\
**Type:** String\
**Version history:** Added in 1.0.0
**Version history:**\
1.0.0 - added
### `media_attachments` {#media_attachments}
**Description:** Media that is attached to this status.\
**Type:** Array of [Attachment]({{< relref "attachment.md" >}})\
**Version history:** Added in 0.6.0
**Type:** Array of [MediaAttachment]({{< relref "entities/MediaAttachment" >}})\
**Version history:**\
0.6.0 - added
### `application` {#application}
### `application` {{%optional%}} {#application}
**Description:** The application used to post this status.\
**Type:** [Application]({{< relref "application.md" >}})\
**Version history:** Added in 0.9.9
**Type:** Hash\
**Version history:**\
0.9.9 - added
## Rendering attributes
#### `application[name]` {#application-name}
**Description:** The name of the application that posted this status.\
**Type:** String\
**Version history:**\
0.9.9 - added
#### `application[website]` {#application-website}
**Description:** The website associated with the application that posted this status.\
**Type:** {{<nullable>}} String (URL) or null\
**Version history:**\
0.9.9 - added\
3.5.1 - this property is now nullable
### `mentions` {#mentions}
**Description:** Mentions of users within the status content.\
**Type:** Array of [Mention]({{< relref "mention.md" >}})\
**Version history:** Added in 0.6.0
**Type:** Array of [Status::Mention](#Mention)\
**Version history:**\
0.6.0 - added
### `tags` {#tags}
**Description:** Hashtags used within the status content.\
**Type:** Array of [Tag]({{< relref "tag.md" >}})\
**Version history:** Added in 0.9.0
**Type:** Array of [Status::Tag](#Tag)\
**Version history:**\
0.6.0 - added
### `emojis` {#emojis}
**Description:** Custom emoji to be used when rendering status content.\
**Type:** Array of [Emoji]({{< relref "emoji.md" >}})\
**Version history:** Added in 2.0.0
## Informational attributes
**Type:** Array of [CustomEmoji]({{< relref "entities/CustomEmoji" >}})\
**Version history:**\
2.0.0 - added
### `reblogs_count` {#reblogs_count}
**Description:** How many boosts this status has received.\
**Type:** Number\
**Version history:** Added in 0.1.0
**Type:** Integer\
**Version history:**\
0.1.0 - added
### `favourites_count` {#favorites_count}
**Description:** How many favourites this status has received.\
**Type:** Number\
**Version history:** Added in 0.1.0
**Type:** Integer\
**Version history:**\
0.1.0 - added
### `replies_count` {#replies_count}
**Description:** How many replies this status has received.\
**Type:** Number\
**Version history:** Added in 2.5.0
## Nullable attributes
**Type:** Integer\
**Version history:**\
2.5.0 - added
### `url` {#url}
**Description:** A link to the status's HTML representation.\
**Type:** String \(URL\)\
**Version history:** Added in 0.1.0
**Type:** {{<nullable>}} String (URL) or null\
**Version history:**\
0.1.0 - added
### `in_reply_to_id` {#in_reply_to_id}
**Description:** ID of the status being replied.\
**Type:** String \(cast from an integer but not guaranteed to be a number\)\
**Version history:** Added in 0.1.0
**Description:** ID of the status being replied to.\
**Type:** {{<nullable>}} String (cast from an integer but not guaranteed to be a number) or null\
**Version history:**\
0.1.0 - added
### `in_reply_to_account_id` {#in_reply_to_account_id}
**Description:** ID of the account being replied to.\
**Type:** String \(cast from an integer but not guaranteed to be a number\)\
**Version history:** Added in 1.0.0
**Description:** ID of the account that authored the status being replied to.\
**Type:** {{<nullable>}} String (cast from an integer but not guaranteed to be a number) or null\
**Version history:**\
0.1.0 - added
### `reblog` {#reblog}
**Description:** The status being reblogged.\
**Type:** [Status]({{< relref "status.md" >}})\
**Version history:** Added in 0.1.0
**Type:** {{<nullable>}} [Status](#) or null\
**Version history:**\
0.1.0 - added
### `poll` {#poll}
**Description:** The poll attached to the status.\
**Type:** [Poll]({{< relref "poll.md" >}})\
**Version history:** Added in 2.8.0
**Type:** {{<nullable>}} [Poll]({{< relref "entities/Poll" >}}) or null\
**Version history:**\
2.8.0 - added
### `card` {#card}
**Description:** Preview card for links included within status content.\
**Type:** [Card]({{< relref "card.md" >}})\
**Version history:** Added in 2.6.0
**Type:** {{<nullable>}} [PreviewCard]({{< relref "entities/PreviewCard" >}}) or null\
**Version history:**\
2.6.0 - added
### `language` {#language}
**Description:** Primary language of this status.\
**Type:** String \(ISO 639 Part 1 two-letter language code\)\
**Version history:** Added in 1.4.0
**Type:** {{<nullable>}} String (ISO 639 Part 1 two-letter language code) or null\
**Version history:**\
1.4.0 - added
### `text` {#text}
**Description:** Plain-text source of a status. Returned instead of `content` when status is deleted, so the user may redraft from the source text without the client having to reverse-engineer the original text from the HTML content.\
**Type:** {{<nullable>}} String or null\
**Version history:**\
2.9.0 - added
### `edited_at` {#edited_at}
**Description:** Timestamp of when the status was last edited.\
**Type:** {{<nullable>}} String (ISO 8601 Datetime)\
**Version history:**\
3.5.0 - added
### `favourited` {{%optional%}} {#favourited}
**Description:** If the current token has an authorized user: Have you favourited this status?\
**Type:** Boolean\
**Version history:**\
0.1.0 - added
### `reblogged` {{%optional%}} {#reblogged}
**Description:** If the current token has an authorized user: Have you boosted this status?\
**Type:** Boolean\
**Version history:**\
0.1.0 - added
### `muted` {{%optional%}} {#muted}
**Description:** If the current token has an authorized user: Have you muted notifications for this status's conversation?\
**Type:** Boolean\
**Version history:**\
1.4.0 - added
### `bookmarked` {{%optional%}} {#bookmarked}
**Description:** If the current token has an authorized user: Have you bookmarked this status?\
**Type:** Boolean\
**Version history:**\
3.1.0 - added
### `pinned` {{%optional%}} {#pinned}
**Description:** If the current token has an authorized user: Have you pinned this status? Only appears if the status is pinnable.\
**Type:** Boolean\
**Version history:**\
1.6.0 - added
### `filtered` {{%optional%}} {#filtered}
**Description:** If the current token has an authorized user: The filter and keywords that matched this status.\
**Type:** Array of [FilterResult]({{< relref "entities/FilterResult" >}})\
**Version history:**\
4.0.0 - added
## Status::Mention attributes {#Mention}
### `id` {#Mention-id}
**Description:** The account ID of the mentioned user.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
0.6.0 - added
### `username` {#Mention-username}
**Description:** The username of the mentioned user.\
**Type:** String\
**Version history:** Added in 2.9.0
**Version history:**\
0.6.0 - added
## Authorized user attributes
### `url` {#Mention-url}
### `favourited` {#favourited}
**Description:** The location of the mentioned user's profile.\
**Type:** String (URL)\
**Version history:**\
0.6.0 - added
**Description:** Have you favourited this status?\
**Type:** Boolean\
**Version history:** Added in 0.1.0
### `acct` {#Mention-acct}
### `reblogged` {#reblogged}
**Description:** The webfinger acct: URI of the mentioned user. Equivalent to `username` for local users, or `username@domain` for remote users.\
**Type:** String\
**Version history:**\
0.6.0 - added
**Description:** Have you boosted this status?\
**Type:** Boolean\
**Version history:** Added in 0.1.0
## Status::Tag attributes {#Tag}
### `muted` {#muted}
### `name` {#Tag-name}
**Description:** Have you muted notifications for this status's conversation?\
**Type:** Boolean\
**Version history:** Added in 1.4.0
**Description:** The value of the hashtag after the # sign.\
**Type:** String\
**Version history:**\
0.9.0 - added
### `bookmarked` {#bookmarked}
### `url` {#Tag-url}
**Description:** Have you bookmarked this status?\
**Type:** Boolean\
**Version history:** Added in 3.1.0
### `pinned` {#pinned}
**Description:** Have you pinned this status? Only appears if the status is pinnable.\
**Type:** Boolean\
**Version history:** Added in 1.6.0
**Description:** A link to the hashtag on the instance.\
**Type:** String (URL)\
**Version history:**\
0.9.0 - added
## See also
* GET accounts/:id/statuses
* GET /api/v2/search
{{< page-ref page="methods/statuses.md" >}}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/status_serializer.rb" caption="app/serializers/rest/status\_serializer.rb" >}}
{{< page-relref ref="methods/accounts#statuses" caption="GET /api/v1/accounts/:id/statuses" >}}
{{< page-relref ref="methods/search#v2" caption="POST /api/v2/search/" >}}
{{< page-relref ref="methods/statuses" caption="statuses methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/status_serializer.rb" caption="app/serializers/rest/status_serializer.rb" >}}

125
content/en/entities/StatusEdit.md Normal file
View File

@ -0,0 +1,125 @@
---
title: StatusEdit
description: Represents a revision of a status that has been edited.
menu:
docs:
parent: entities
aliases: [
"/entities/statusedit",
"/entities/StatusEdit",
"/api/entities/statusedit",
"/api/entities/StatusEdit",
]
---
## Example
```json
{
"content": "<p>this is a status that has been edited three times. this time a poll has been added.</p>",
"spoiler_text": "",
"sensitive": false,
"created_at": "2022-09-05T00:03:32.480Z",
"poll": {
"options": [
{
"title": "cool"
},
{
"title": "uncool"
},
{
"title": "spiderman (this option has been changed)"
}
]
},
"account": {
"id": "14715",
"username": "trwnh",
"acct": "trwnh",
"display_name": "infinite love ⴳ",
// ...
},
"media_attachments": [],
"emojis": []
}
```
## Attributes
### `content` {#content}
**Description:** The content of the status at this revision.\
**Type:** String (HTML)\
**Version history:**\
3.5.0 - added
### `spoiler_text` {#spoiler_text}
**Description:** The content of the subject or content warning at this revision.\
**Type:** String (HTML)\
**Version history:**\
3.5.0 - added
### `sensitive` {#sensitive}
**Description:** Whether the status was marked sensitive at this revision.\
**Type:** Boolean\
**Version history:**\
3.5.0 - added
### `created_at` {#created_at}
**Description:** The timestamp of when the revision was published.\
**Type:** String (ISO 8601 Datetime)\
**Version history:**\
3.5.0 - added
### `account` {#account}
**Description:** The account that published this revision.\
**Type:** [Account]({{<relref "entities/Account">}})\
**Version history:**\
3.5.0 - added
### `poll` {{%optional%}} {#poll}
**Description:** The current state of the poll options at this revision. Note that edits changing the poll options will be collapsed together into one edit, since this action resets the poll.\
**Type:** Hash\
**Version history:**\
3.5.0 - added
#### `poll.options[]` {#poll-options}
**Description:** The poll options at this revision.\
**Type:** Array of Hash\
**Version history:**\
3.5.0 - added
#### `poll.options[].title` {#poll-options-title}
**Description:** The text for a poll option.\
**Type:** String\
**Version history:**\
3.5.0 - added
### `media_attachments` {#media_attachments}
**Description:** The current state of the poll options at this revision. Note that edits changing the poll options will be collapsed together into one edit, since this action resets the poll.\
**Type:** Array of [MediaAttachment]({{<relref "entities/MediaAttachment">}})\
**Version history:**\
3.5.0 - added
### `emojis` {#emojis}
**Description:** Any custom emoji that are used in the current revision.\
**Type:** Array of [CustomEmoji]({{<relref "entities/CustomEmoji">}})\
**Version history:**\
3.5.0 - added
## See also
{{< page-relref ref="methods/statuses#history" caption="GET /api/v1/statuses/:id/history" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/status_edit_serializer.rb" caption="app/serializers/rest/status_edit_serializer.rb" >}}

52
content/en/entities/StatusSource.md Normal file
View File

@ -0,0 +1,52 @@
---
title: StatusSource
description: Represents a status's source as plain text.
menu:
docs:
parent: entities
aliases: [
"/entities/statussource",
"/entities/StatusSource",
"/api/entities/statussource",
"/api/entities/StatusSource",
]
---
## Example
```json
{
"id": "108942703571991143",
"text": "this is a status that will be edited",
"spoiler_text": ""
}
```
## Attributes
### `id` {#id}
**Description:** ID of the status in the database.\
**Type:** String (cast from an integer but not guaranteed to be a number)\
**Version history:**\
3.5.0 - added
### `text` {#text}
**Description:** The plain text used to compose the status.\
**Type:** String\
**Version history:**\
3.5.0 - added
### `spoiler_text` {#spoiler_text}
**Description:** The plain text used to compose the status's subject or content warning.\
**Type:** String\
**Version history:**\
3.5.0 - added
## See also
{{< page-relref ref="methods/statuses#source" caption="GET /api/v1/statuses/:id/source" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/status_source_serializer.rb" caption="app/serializers/rest/status_source_serializer.rb" >}}

57
content/en/entities/Suggestion.md Normal file
View File

@ -0,0 +1,57 @@
---
title: Suggestion
description: Represents a suggested account to follow and an associated reason for the suggestion.
menu:
docs:
parent: entities
aliases: [
"/entities/suggestion",
"/entities/Suggestion",
"/api/entities/suggestion",
"/api/entities/Suggestion",
]
---
## Example
```json
{
"source": "staff",
"account": {
"id": "109031732217496096",
"username": "alice",
"acct": "alice",
// ...
}
}
```
## Attributes
### `source` {#source}
**Description:** The reason this account is being suggested.\
**Type:** String (Enumerable oneOf)\
`staff` = This account was manually recommended by your administration team\
`past_interactions` = You have interacted with this account previously\
`global` = This account has many reblogs, favourites, and active local followers within the last 30 days\
**Version history:**\
3.4.0 - added
### `account` {#account}
**Description:** The account being recommended to follow.\
**Type:** [Account]({{< relref "entities/Account" >}})\
**Version history:**\
3.4.0 - added
## See also
{{< page-relref ref="methods/suggestions#v2" caption="GET /api/v2/suggestions" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/suggestion_serializer.rb" caption="app/serializers/rest/suggestion_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/account_suggestions.rb" caption="app/models/account_suggestions.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/account_suggestions/" caption="app/models/account_suggestions/" >}}

205
content/en/entities/Tag.md Normal file
View File

@ -0,0 +1,205 @@
---
title: Tag
description: Represents a hashtag used within the content of a status.
menu:
docs:
parent: entities
aliases: [
"/entities/tag",
"/entities/Tag",
"/api/entities/tag",
"/api/entities/Tag",
]
---
## Example
```json
{
"name": "nowplaying",
"url": "https://mastodon.social/tags/nowplaying",
"history": [
{
"day": "1574553600",
"uses": "200",
"accounts": "31"
},
{
"day": "1574467200",
"uses": "272",
"accounts": "39"
},
{
"day": "1574380800",
"uses": "345",
"accounts": "40"
},
{
"day": "1574294400",
"uses": "366",
"accounts": "46"
},
{
"day": "1574208000",
"uses": "226",
"accounts": "32"
},
{
"day": "1574121600",
"uses": "217",
"accounts": "42"
},
{
"day": "1574035200",
"uses": "214",
"accounts": "34"
}
],
"following": false
}
```
## Attributes
### `name` {#name}
**Description:** The value of the hashtag after the # sign.\
**Type:** String\
**Version history:**\
0.9.0 - added
### `url` {#url}
**Description:** A link to the hashtag on the instance.\
**Type:** String (URL)\
**Version history:**\
0.9.0 - added
### `history` {#history}
**Description:** Usage statistics for given days (typically the past week).\
**Type:** Array of Hash\
**Version history:**\
2.4.1 - added
#### `history[][day]` {#history-day}
**Description:** UNIX timestamp on midnight of the given day.\
**Type:** String (UNIX timestamp)\
**Version history:**\
2.4.1 - added
#### `history[][uses]` {#history-uses}
**Description:** The counted usage of the tag within that day.\
**Type:** String (cast from an integer)\
**Version history:**\
2.4.1 - added
#### `history[][accounts]` {#history-accounts}
**Description:** The total of accounts using the tag within that day.\
**Type:** String (cast from an integer)\
**Version history:**\
2.4.1 - added
### `following` {{%optional%}} {#following}
**Description:** Whether the current token's authorized user is following this tag.\
**Type:** Boolean\
**Version history:**\
4.0.0 - added
## Admin::Tag attributes {#admin}
```json
{
"name": "caturday",
"url": "https://mastodon.example/tags/caturday",
"history": [
{
"day": "1669507200",
"accounts": "53",
"uses": "56"
},
{
"day": "1669420800",
"accounts": "142",
"uses": "171"
},
{
"day": "1669334400",
"accounts": "11",
"uses": "11"
},
{
"day": "1669248000",
"accounts": "8",
"uses": "9"
},
{
"day": "1669161600",
"accounts": "8",
"uses": "20"
},
{
"day": "1669075200",
"accounts": "11",
"uses": "11"
},
{
"day": "1668988800",
"accounts": "17",
"uses": "22"
}
],
"id": "802",
"trendable": true,
"usable": true,
"requires_review": false
}
```
### `id` {#id}
**Description:** The ID of the Tag in the database.\
**Type:** String (cast from integer, but not guaranteed to be a number)\
**Version history:**\
3.5.0 - added
### `trendable` {#trendable}
**Description:** Whether the hashtag has been approved to trend.\
**Type:** Boolean\
**Version history:**\
3.5.0 - added
### `usable` {#usable}
**Description:** Whether the hashtag has not been disabled from auto-linking.\
**Type:** Boolean\
**Version history:**\
3.5.0 - added
### `requires_review` {#requires_review}
**Description:** Whether the hashtag has not been reviewed yet to approve or deny its trending.\
**Type:** Boolean\
**Version history:**\
3.5.0 - added
## See also
{{< page-relref ref="entities/Search#tags" caption="Search (`tags` attribute)" >}}
{{< page-relref ref="methods/tags" caption="tags API methods" >}}
{{< page-relref ref="methods/featured_tags#suggestions" caption="GET /api/v1/featured_tags/suggestions" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/tag_serializer.rb" caption="app/serializers/rest/tag_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/tag_serializer.rb" caption="app/serializers/rest/admin/tag_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/tag.rb" caption="app/models/tag.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/trends/history.rb" caption="app/models/trends/history.rb" >}}

31
content/en/entities/token.md → content/en/entities/Token.md
View File

@ -4,11 +4,17 @@ description: Represents an OAuth token used for authenticating with the API and
menu:
docs:
parent: entities
aliases: [
"/entities/token",
"/entities/Token",
"/api/entities/token",
"/api/entities/Token",
]
---
## Example
```javascript
```json
{
"access_token": "ZA-Yj3aBD8U8Cm7lKUp-lm9O9BmDgdhHzDeqsY8tlL0",
"token_type": "Bearer",
@ -23,33 +29,36 @@ menu:
**Description:** An OAuth token to be used for authorization.\
**Type:** String\
**Version history:** Added in 0.1.0
**Version history:**\
0.1.0 - added
### `token_type` {#token_type}
**Description:** The OAuth token type. Mastodon uses `Bearer` tokens.\
**Type:** String\
**Version history:** Added in 0.1.0
**Version history:**\
0.1.0 - added
### `scope` {#scope}
**Description:** The OAuth scopes granted by this token, space-separated.\
**Type:** String\
**Version history:** Added in 0.1.0
**Version history:**\
0.1.0 - added
### `created_at` {#created_at}
**Description:** When the token was generated.\
**Type:** Number \(UNIX Timestamp\)\
**Version history:** Added in 0.1.0
**Type:** Number (UNIX Timestamp)\
**Version history:**\
0.1.0 - added
## See also
* [Example authorization code flow]({{< relref "../client/token.md#example-authorization-code-flow" >}})
* [OAuth Scopes]({{< relref "../api/oauth-scopes.md" >}})
* [POST /oauth/token]({{< relref "../methods/apps/oauth.md#obtain-a-token" >}})
{{< page-ref page="methods/apps/oauth.md" >}}
{{< page-relref ref="oauth-scopes" caption="OAuth Scopes" >}}
{{< page-relref ref="methods/oauth" caption="oauth methods" >}}
{{< page-ref page="client/token" >}}
{{< page-ref page="client/authorized" >}}

50
content/en/entities/Translation.md Normal file
View File

@ -0,0 +1,50 @@
---
title: Translation
description: Represents the result of machine translating some status content
menu:
docs:
parent: entities
aliases: [
"/api/entities/Translation",
"/api/entities/translation",
]
---
## Example
```json
{
"content": "<p>Hola mundo</p>",
"detected_source_language": "en",
"provider": "DeepL.com"
}
```
## Attributes
### `content` {#content}
**Description:** The translated text of the status.\
**Type:** String (HTML)\
**Version history:**\
4.0.0 - added
### `detected_source_language` {#detected_source_language}
**Description:** The language of the source text, as auto-detected by the machine translation provider.\
**Type:** String (ISO 639 language code)\
**Version history:**\
4.0.0 - added
### `provider` {#provider}
**Description:** The service that provided the machine translation.
**Type:** String\
**Version history:**\
4.0.0 - added
## See also
{{< page-relref ref="methods/statuses#translate" caption="POST /api/v1/statuses/:id/translate" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/translation_serializer.rb" caption="app/serializers/rest/translation_serializer.rb" >}}

92
content/en/entities/V1_Filter.md Normal file
View File

@ -0,0 +1,92 @@
---
title: V1::Filter
description: Represents a user-defined filter for determining which statuses should not be shown to the user. Contains a single keyword or phrase.
menu:
docs:
parent: entities
aliases: [
"/entities/v1_filter/",
"/entities/V1_Filter",
"/api/entities/v1_filter/",
"/api/entities/V1_Filter",
]
---
## Example
```json
{
"id": "8449",
"phrase": "test",
"context": [
"home",
"notifications",
"public",
"thread"
],
"whole_word": false,
"expires_at": "2019-11-26T09:08:06.254Z",
"irreversible": true
}
```
## Attributes
### `id` {#id}
**Description:** The ID of the filter in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
2.4.3 - added
### `phrase` {#phrase}
**Description:** The text to be filtered.\
**Type:** String\
**Version history:**\
2.4.3 - added
### `context` {#context}
**Description:** The contexts in which the filter should be applied.\
**Type:** Array of String (Enumerable anyOf)\
`home` = home timeline and lists\
`notifications` = notifications timeline\
`public` = public timelines\
`thread` = expanded thread of a detailed status\
`account` = when viewing a profile\
**Version history:**\
2.4.3 - added\
3.1.0 - added `account`
### `expires_at` {#expires_at}
**Description:** When the filter should no longer be applied.\
**Type:** {{<nullable>}} String (ISO 8601 Datetime), or null if the filter does not expire\
**Version history:**\
2.4.3 - added
### `irreversible` {#irreversible}
**Description:** Should matching entities in home and notifications be dropped by the server? See [implementation guidelines for filters]({{< relref "api/guidelines#filters" >}}).\
**Type:** Boolean\
**Version history:**\
2.4.3 - added
### `whole_word` {#whole_word}
**Description:** Should the filter consider word boundaries? See [implementation guidelines for filters]({{< relref "api/guidelines#filters" >}}).\
**Type:** Boolean\
**Version history:**\
2.4.3 - added
## See also
{{< page-relref ref="api/guidelines#filters" caption="Implementation guidelines for filters" >}}
{{< page-relref ref="methods/filters#v1" caption="v1 filters API" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/v1/filter_serializer.rb" caption="app/serializers/rest/v1/filter_serializer.rb" >}}

422
content/en/entities/V1_Instance.md Normal file
View File

@ -0,0 +1,422 @@
---
title: V1::Instance
description: Represents the software instance of Mastodon running on this domain.
menu:
docs:
parent: entities
aliases: [
"/entities/v1_instance",
"/entities/V1_Instance",
"/api/entities/v1_instance",
"/api/entities/V1_Instance",
]
---
## Example
```json
{
"uri":"mastodon.social",
"title":"Mastodon",
"short_description":"The original server operated by the Mastodon gGmbH non-profit",
"description":"",
"email":"staff@mastodon.social",
"version":"3.5.3",
"urls":{
"streaming_api":"wss://mastodon.social"
},
"stats":{
"user_count":812303,
"status_count":38151616,
"domain_count":25255
},
"thumbnail":"https://files.mastodon.social/site_uploads/files/000/000/001/original/vlcsnap-2018-08-27-16h43m11s127.png",
"languages":[
"en"
],
"registrations":false,
"approval_required":false,
"invites_enabled":true,
"configuration":{
"statuses":{
"max_characters":500,
"max_media_attachments":4,
"characters_reserved_per_url":23
},
"media_attachments":{
"supported_mime_types":[
"image/jpeg",
"image/png",
"image/gif",
"image/webp",
"video/webm",
"video/mp4",
"video/quicktime",
"video/ogg",
"audio/wave",
"audio/wav",
"audio/x-wav",
"audio/x-pn-wave",
"audio/vnd.wave",
"audio/ogg",
"audio/vorbis",
"audio/mpeg",
"audio/mp3",
"audio/webm",
"audio/flac",
"audio/aac",
"audio/m4a",
"audio/x-m4a",
"audio/mp4",
"audio/3gpp",
"video/x-ms-asf"
],
"image_size_limit":10485760,
"image_matrix_limit":16777216,
"video_size_limit":41943040,
"video_frame_rate_limit":60,
"video_matrix_limit":2304000
},
"polls":{
"max_options":4,
"max_characters_per_option":50,
"min_expiration":300,
"max_expiration":2629746
}
},
"contact_account":{
"id":"1",
"username":"Gargron",
"acct":"Gargron",
"display_name":"Eugen",
"locked":false,
"bot":false,
"discoverable":true,
"group":false,
"created_at":"2016-03-16T00:00:00.000Z",
"note":"\u003cp\u003eFounder, CEO and lead developer \u003cspan class=\"h-card\"\u003e\u003ca href=\"https://mastodon.social/@Mastodon\" class=\"u-url mention\"\u003e@\u003cspan\u003eMastodon\u003c/span\u003e\u003c/a\u003e\u003c/span\u003e, Germany.\u003c/p\u003e",
"url":"https://mastodon.social/@Gargron",
"avatar":"https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg",
"avatar_static":"https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg",
"header":"https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg",
"header_static":"https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg",
"followers_count":118944,
"following_count":305,
"statuses_count":72309,
"last_status_at":"2022-08-24",
"emojis":[
],
"fields":[
{
"name":"Patreon",
"value":"\u003ca href=\"https://www.patreon.com/mastodon\" target=\"_blank\" rel=\"nofollow noopener noreferrer me\"\u003e\u003cspan class=\"invisible\"\u003ehttps://www.\u003c/span\u003e\u003cspan class=\"\"\u003epatreon.com/mastodon\u003c/span\u003e\u003cspan class=\"invisible\"\u003e\u003c/span\u003e\u003c/a\u003e",
"verified_at":null
}
]
},
"rules":[
{
"id":"1",
"text":"Sexually explicit or violent media must be marked as sensitive when posting"
},
{
"id":"2",
"text":"No racism, sexism, homophobia, transphobia, xenophobia, or casteism"
},
{
"id":"3",
"text":"No incitement of violence or promotion of violent ideologies"
},
{
"id":"4",
"text":"No harassment, dogpiling or doxxing of other users"
},
{
"id":"5",
"text":"No content illegal in Germany"
},
{
"id":"7",
"text":"Do not share intentionally false or misleading information"
}
]
}
```
## Attributes
### `uri` {#uri}
**Description:** The domain name of the instance.\
**Type:** String\
**Version history:**\
1.1.0 - added
### `title` {#title}
**Description:** The title of the website.\
**Type:** String\
**Version history:**\
1.1.0 - added
### `short_description` {#short_description}
**Description:** A short, plain-text description defined by the admin.\
**Type:** String\
**Version history:**\
2.9.2 - added
### `description` {#description}
**Description:** An HTML-permitted description of the Mastodon site.\
**Type:** String\
**Version history:**\
1.1.0 - added
### `email` {#email}
**Description:** An email that may be contacted for any inquiries.\
**Type:** String\
**Version history:**\
1.1.0 - added
### `version` {#version}
**Description:** The version of Mastodon installed on the instance.\
**Type:** String\
**Version history:**\
1.3.0 - added
### `urls` {#urls}
**Description:** URLs of interest for clients apps.\
**Type:** Hash\
**Version history:**\
1.4.2 - added
#### `urls[streaming_api]` {#streaming_api}
**Description:** The Websockets URL for connecting to the streaming API.\
**Type:** String (URL)\
**Version history:**\
1.4.2 - added
### `stats` {#stats}
**Description:** Statistics about how much information the instance contains.\
**Type:** Hash\
**Version history:**\
1.6.0 - added
#### `stats[user_count]` {#user_count}
**Description:** Total users on this instance.\
**Type:** Integer\
**Version history:**\
1.6.0 - added
#### `stats[status_count]` {#status_count}
**Description:** Total statuses on this instance.\
**Type:** Integer\
**Version history:**\
1.6.0 - added
#### `stats[domain_count]` {#domain_count}
**Description:** Total domains discovered by this instance.\
**Type:** Integer\
**Version history:**\
1.6.0 - added
### `thumbnail` {#thumbnail}
**Description:** Banner image for the website.\
**Type:** {{<nullable>}} String (URL)\
**Version history:**\
1.6.1 - added
### `languages` {#languages}
**Description:** Primary languages of the website and its staff.\
**Type:** Array of String (ISO 639-1 two-letter code)\
**Version history:**\
2.3.0 - added
### `registrations` {#registrations}
**Description:** Whether registrations are enabled.\
**Type:** Boolean\
**Version history:**\
2.7.2 - added
### `approval_required` {#approval_required}
**Description:** Whether registrations require moderator approval.\
**Type:** Boolean\
**Version history:**\
2.9.2 - added
### `invites_enabled` {#invites_enabled}
**Description:** Whether invites are enabled.\
**Type:** Boolean\
**Version history:**\
3.1.4 - added
### `configuration` {#configuration}
**Description:** Configured values and limits for this website.\
**Type:** Hash\
**Version history:**\
3.4.2 - added
#### `configuration[accounts]` {#accounts}
**Description:** Limits related to accounts.\
**Type:** Hash\
**Version history:**\
4.0.0 - added
##### `configuration[accounts][max_featured_tags]` {#max_featured_tags}
**Description:** The maximum number of featured tags allowed for each account.\
**Type:** Integer\
**Version history:**\
4.0.0 - added
#### `configuration[statuses]` {#statuses}
**Description:** Limits related to authoring statuses.\
**Type:** Hash\
**Version history:**\
3.4.2 - added
##### `configuration[statuses][max_characters]` {#max_characters}
**Description:** The maximum number of allowed characters per status.\
**Type:** Integer\
**Version history:**\
3.4.2 - added
##### `configuration[statuses][max_media_attachments]` {#max_media_attachments}
**Description:** The maximum number of media attachments that can be added to a status.\
**Type:** Integer\
**Version history:**\
3.4.2 - added
##### `configuration[statuses][characters_reserved_per_url]` {#characters_reserved_per_url}
**Description:** Each URL in a status will be assumed to be exactly this many characters.\
**Type:** Integer\
**Version history:**\
3.4.2 - added
#### `configuration[media_attachments]` {#media_attachments}
**Description:** Hints for which attachments will be accepted.\
**Type:** Hash\
**Version history:**\
3.4.2 - added
##### `configuration[media_attachments][supported_mime_types]` {#supported_mime_types}
**Description:** Contains MIME types that can be uploaded.\
**Type:** Array of String\
**Version history:**\
3.4.2 - added
##### `configuration[media_attachments][image_size_limit]` {#image_size_limit}
**Description:** The maximum size of any uploaded image, in bytes.\
**Type:** Integer\
**Version history:**\
3.4.2 - added
##### `configuration[media_attachments][image_matrix_limit]` {#image_matrix_limit}
**Description:** The maximum number of pixels (width times height) for image uploads.\
**Type:** Integer\
**Version history:**\
3.4.2 - added
##### `configuration[media_attachments][video_size_limit]` {#video_size_limit}
**Description:** The maximum size of any uploaded video, in bytes.\
**Type:** Integer\
**Version history:**\
3.4.2 - added
##### `configuration[media_attachments][video_frame_rate_limit]` {#video_frame_rate_limit}
**Description:** The maximum frame rate for any uploaded video.\
**Type:** Integer\
**Version history:**\
3.4.2 - added
##### `configuration[media_attachments][video_matrix_limit]` {#video_matrix_limit}
**Description:** The maximum number of pixels (width times height) for video uploads.\
**Type:** Integer\
**Version history:**\
3.4.2 - added
#### `configuration[polls]` {#polls}
**Description:** Limits related to polls.\
**Type:** Hash\
**Version history:**\
3.4.2 - added
##### `configuration[polls][max_options]` {#max_options}
**Description:** Each poll is allowed to have up to this many options.\
**Type:** Integer\
**Version history:**\
3.4.2 - added
##### `configuration[polls][max_characters_per_option]` {#max_characters_per_option}
**Description:** Each poll option is allowed to have this many characters.\
**Type:** Integer\
**Version history:**\
3.4.2 - added
##### `configuration[polls][min_expiration]` {#min_expiration}
**Description:** The shortest allowed poll duration, in seconds.\
**Type:** Integer\
**Version history:**\
3.4.2 - added
##### `configuration[polls][max_expiration]` {#max_expiration}
**Description:** The longest allowed poll duration, in seconds.\
**Type:** Integer\
**Version history:**\
3.4.2 - added
### `contact_account` {#contact_account}
**Description:** A user that can be contacted, as an alternative to `email`.\
**Type:** [Account]({{< relref "entities/Account" >}})\
**Version history:**\
2.3.0 - added
### `rules` {#rules}
**Description:** An itemized list of rules for this website.\
**Type:** Array of [Rule]({{< relref "entities/Rule" >}})\
**Version history:**\
3.4.0 - added
## See also
{{< page-relref ref="methods/instance#v1" caption="GET /api/v1/instance" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/v1/instance_serializer.rb" caption="app/serializers/rest/v1/instance_serializer.rb" >}}

148
content/en/entities/WebPushSubscription.md Normal file
View File

@ -0,0 +1,148 @@
---
title: WebPushSubscription
description: Represents a subscription to the push streaming server.
menu:
docs:
parent: entities
aliases: [
"/entities/pushsubscription",
"/entities/PushSubscription",
"/entities/webpushsubscription",
"/entities/WebPushSubscription",
"/api/entities/pushsubscription",
"/api/entities/PushSubscription",
"/api/entities/webpushsubscription",
"/api/entities/WebPushSubscription",
]
---
## Example
```json
{
"id": 328183,
"endpoint": "https://yourdomain.example/listener",
"alerts": {
"follow": false,
"favourite": false,
"reblog": false,
"mention": true,
"poll": false
},
"server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M="
}
```
## Attributes
### `id` {#id}
**Description:** The ID of the Web Push subscription in the database.\
**Type:** String (cast from an integer, but not guaranteed to be a number)\
**Version history:**\
2.4.0 - added
### `endpoint` {#endpoint}
**Description:** Where push alerts will be sent to.\
**Type:** String (URL)\
**Version history:**\
2.4.0 - added
### `server_key` {#server_key}
**Description:** The streaming server's VAPID key.\
**Type:** String\
**Version history:**\
2.4.0 - added
### `alerts` {#alerts}
**Description:** Which alerts should be delivered to the `endpoint`.\
**Type:** Hash\
**Version history:**\
2.4.0 - added\
2.8.0 - added `alerts[poll]`\
3.1.0 - added `alerts[follow_request]`\
3.3.0 - added `alerts[status]`\
3.5.0 - added `alerts[update]` and `alerts[admin.sign_up]`\
4.0.0 - added `alerts[admin.report]`
#### `alerts[mention]` {#mention}
**Description:** Receive a push notification when someone else has mentioned you in a status?\
**Type:** Boolean\
**Version history:**\
2.4.0 - added
#### `alerts[status]` {#status}
**Description:** Receive a push notification when a subscribed account posts a status?\
**Type:** Boolean\
**Version history:**\
3.3.0 - added
#### `alerts[reblog]` {#reblog}
**Description:** Receive a push notification when a status you created has been boosted by someone else?\
**Type:** Boolean\
**Version history:**\
2.4.0 - added
#### `alerts[follow]` {#follow}
**Description:** Receive a push notification when someone has followed you?\
**Type:** Boolean\
**Version history:**\
2.4.0 - added
#### `alerts[follow_request]` {#follow_request}
**Description:** Receive a push notification when someone has requested to followed you?\
**Type:** Boolean\
**Version history:**\
3.1.0 - added
#### `alerts[favourite]` {#favourite}
**Description:** Receive a push notification when a status you created has been favourited by someone else?\
**Type:** Boolean\
**Version history:**\
2.4.0 - added
#### `alerts[poll]` {#poll}
**Description:** Receive a push notification when a poll you voted in or created has ended?\
**Type:** Boolean\
**Version history:**\
2.8.0 - added
#### `alerts[update]` {#update}
**Description:** Receive a push notification when a status you interacted with has been edited?\
**Type:** Boolean\
**Version history:**\
3.5.0 - added
#### `alerts[admin.sign_up]` {#admin-sign_up}
**Description:** Receive a push notification when a new user has signed up?\
**Type:** Boolean\
**Version history:**\
3.5.0 - added
#### `alerts[admin.report]` {#admin-report}
**Description:** Receive a push notification when a new report has been filed?\
**Type:** Boolean\
**Version history:**\
4.0.0 - added
## See also
{{< page-relref ref="methods/push" caption="push API methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/web_push_subscription_serializer.rb" caption="app/serializers/rest/web_push_subscription_serializer.rb" >}}

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

@ -1,265 +0,0 @@
---
title: Account
description: Represents a user of Mastodon and their associated profile.
menu:
docs:
parent: entities
---
## Example
```javascript
{
"id": "23634",
"username": "noiob",
"acct": "noiob@awoo.space",
"display_name": "ikea shark fan account",
"locked": false,
"bot": false,
"created_at": "2017-02-08T02:00:53.274Z",
"note": "<p>:ms_rainbow_flag:​ :ms_bisexual_flagweb:​ :ms_nonbinary_flag:​ <a href=\"https://awoo.space/tags/awoo\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>awoo</span}.space <a href=\"https://awoo.space/tags/admin\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>admin</span} ~ <a href=\"https://awoo.space/tags/bi\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>bi</span} ~ <a href=\"https://awoo.space/tags/nonbinary\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>nonbinary</span} ~ compsci student ~ likes video <a href=\"https://awoo.space/tags/games\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>games</span} and weird/ old electronics and will post obsessively about both ~ avatar by <span class=\"h-card\"><a href=\"https://weirder.earth/@dzuk\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>dzuk</span}</span></p>",
"url": "https://awoo.space/@noiob",
"avatar": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png",
"avatar_static": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png",
"header": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png",
"header_static": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png",
"followers_count": 547,
"following_count": 404,
"statuses_count": 28468,
"last_status_at": "2019-11-17T00:02:23.693Z",
"emojis": [
{
"shortcode": "ms_rainbow_flag",
"url": "https://files.mastodon.social/custom_emojis/images/000/028/691/original/6de008d6281f4f59.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/028/691/static/6de008d6281f4f59.png",
"visible_in_picker": true
},
{
"shortcode": "ms_bisexual_flag",
"url": "https://files.mastodon.social/custom_emojis/images/000/050/744/original/02f94a5fca7eaf78.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/050/744/static/02f94a5fca7eaf78.png",
"visible_in_picker": true
},
{
"shortcode": "ms_nonbinary_flag",
"url": "https://files.mastodon.social/custom_emojis/images/000/105/099/original/8106088bd4782072.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/105/099/static/8106088bd4782072.png",
"visible_in_picker": true
}
],
"fields": [
{
"name": "Pronouns",
"value": "they/them",
"verified_at": null
},
{
"name": "Alt",
"value": "<span class=\"h-card\"><a href=\"https://cybre.space/@noiob\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>noiob</span}</span>",
"verified_at": null
},
{
"name": "Bots",
"value": "<span class=\"h-card\"><a href=\"https://botsin.space/@darksouls\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>darksouls</span}</span>, <span class=\"h-card\"><a href=\"https://botsin.space/@nierautomata\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>nierautomata</span}</span>, <span class=\"h-card\"><a href=\"https://mastodon.social/@fedi\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>fedi</span}</span>, code for <span class=\"h-card\"><a href=\"https://botsin.space/@awoobot\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>awoobot</span}</span>",
"verified_at": null
},
{
"name": "Website",
"value": "<a href=\"http://shork.xyz\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">http://</span><span class=\"\">shork.xyz</span><span class=\"invisible\"></span}",
"verified_at": "2019-11-10T10:31:10.744+00:00"
}
]
}
```
## Base attributes
### **`id`** {#id}
**Description:** The account id`header`.\
**Type:** String \(cast from an integer, but not guaranteed to be a number\)\
**Version history:**\
0.1.0 - added
### `username` {#username}
**Description:** The username of the account, not including domain.\
**Type:** String\
**Version history:**\
0.1.0 - added
### `acct` {#acct}
**Description:** The Webfinger account URI.
Equal to `username` for local users, or `username@domain` for remote users.\
**Type:** String\
**Version history:**\
0.1.0 - added
### `url` {#url}
**Description:** The location of the user's profile page.\
**Type:** String \(HTTPS URL\)\
**Version history:**\
0.1.0 - added
## Display attributes
### `display_name` {#display_name}
**Description:** The profile's display name.\
**Type:** String\
**Version history:**\
0.1.0 - added
### `note` {#note}
**Description:** The profile's bio / description.\
**Type:** String \(HTML\)\
**Version history:**\
0.1.0 - added
### `avatar` {#avatar}
**Description:** An image icon that is shown next to statuses and in the profile.\
**Type:** String \(URL\)\
**Version history:**\
0.1.0 - added
### `avatar_static` {#avatar_static}
**Description:** A static version of the avatar.
Equal to `avatar` if its value is a static image; different if `avatar` is an animated GIF.\
**Type:** String \(URL\)\
**Version history:**\
1.1.2 - added
### `header` {#header}
**Description:** An image banner that is shown above the profile and in profile cards.\
**Type:** String \(URL\)\
**Version history:**\
0.1.0 - added
### `header_static` {#header_static}
**Description:** A static version of the header.
Equal to `header` if its value is a static image; different if `header` is an animated GIF.\
**Type:** String \(URL\)\
**Version history:**\
1.1.2 - added
### `locked` {#locked}
**Description:** Whether the account manually approves follow requests.\
**Type:** Boolean\
**Version history:**\
0.1.0 - added
### `emojis` {#emojis}
**Description:** Custom emoji entities to be used when rendering the profile. If none, an empty array will be returned.\
**Type:** Array of [Emoji]({{< relref "emoji.md" >}})\
**Version history:**\
2.4.0 - added
### `discoverable` {#discoverable}
**Description:** Whether the account has opted into discovery features such as the profile directory.\
**Type:** Boolean\
**Version history:**\
3.1.0 - added
## Statistical attributes
### `created_at` {#created_at}
**Description:** When the account was created.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:**\
0.1.0 - added
### `last_status_at` {#last_status_at}
**Description:** When the most recent status was posted.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:**\
3.0.0 - added\
3.1.0 - now returns date only, no time
### `statuses_count` {#statuses_count}
**Description:** How many statuses are attached to this account.\
**Type:** Number\
**Version history:**\
0.1.0 - added
### `followers_count` {#followers_count}
**Description:** The reported followers of this profile.\
**Type:** Number\
**Version history:**\
0.1.0 - added
### `following_count` {#following_count}
**Description:** The reported follows of this profile.\
**Type:** Number\
**Version history:**\
0.1.0 - added
## Optional attributes
### `moved` {#moved}
**Description:** Indicates that the profile is currently inactive and that its user has moved to a new account.\
**Type:** [Account]({{< relref "account.md" >}})\
**Version history:**\
2.1.0 - added
### `fields` {#fields}
**Description:** Additional metadata attached to a profile as name-value pairs.\
**Type:** Array of [Field]({{< relref "field.md" >}})\
**Version history:**\
2.4.0 - added
### `bot` {#bot}
**Description:** A presentational flag. Indicates that the account may perform automated actions, may not be monitored, or identifies as a robot.\
**Type:** Boolean\
**Version history:**\
2.4.0 - added
### `source` {#source}
**Description:** An extra entity to be used with API methods to [verify credentials]({{< relref "../methods/accounts/#verify-account-credentials" >}}) and [update credentials]({{< relref "../methods/accounts/#update-account-credentials" >}}).\
**Type:** [Source]({{< relref "source.md" >}})\
**Version history:**\
2.4.0 - added
### `suspended` {#suspended}
**Description:** An extra entity returned when an account is suspended.\
**Type:** Boolean\
**Version history:**\
3.3.0 - added
### `mute_expires_at` {#mute_expires_at}
**Description:** When a timed mute will expire, if applicable.\
**Type:** String \(ISO 8601 Datetime\)\
**Version history:**\
3.3.0 - added
## See also
{{< page-ref page="methods/accounts.md" >}}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/account_serializer.rb" caption="app/serializers/rest/account\_serializer.rb" >}}

Some files were not shown because too many files have changed in this diff Show More