6 |
7 | The documentation currently uses [Hugo](https://github.com/gohugoio/hugo) to generate a static site from Markdown. Use `hugo serve` to test the site locally. If build errors occur, ensure your Hugo version is the same as [docs.joinmastodon.org](https://github.com/mastodon/documentation/blob/main/.github/workflows/deploy.yml#L43).
8 |
9 | View the live documentation at [https://docs.joinmastodon.org](https://docs.joinmastodon.org)
10 |
11 | ## Contributing
12 |
13 | Please read the [Contributing to Mastodon](https://github.com/mastodon/.github/blob/main/CONTRIBUTING.md) guide.
14 |
--------------------------------------------------------------------------------
/archetypes/default.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "{{ replace .Name "-" " " | title }}"
3 | date: {{ .Date }}
4 | draft: true
5 | ---
6 |
7 |
--------------------------------------------------------------------------------
/archetypes/entities.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "{{ replace .Name "-" " " | title }}"
3 | description:
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/api/entities/SOMETHING",
9 | "/api/entities/something",
10 | ]
11 | ---
12 |
13 | ## Example
14 |
15 | ```json
16 | ```
17 |
18 | ## Attributes
19 |
20 | ### `id` {#id}
21 |
22 | **Description:** The ID of the SOMETHING in the database.\
23 | **Type:** String (cast from an integer, but not guaranteed to be a number)\
24 | **Version history:**\
25 | x.x.x - added
26 |
27 | ## See also
28 |
29 | {{< page-relref ref="methods/SOMETHING#anchor" caption="POST /api/v1/something/" >}}
30 |
31 | {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/SOMETHING_serializer.rb" caption="app/serializers/rest/SOMETHING_serializer.rb" >}}
--------------------------------------------------------------------------------
/assets/main.js:
--------------------------------------------------------------------------------
1 | (function () {
2 | 'use strict';
3 |
4 | const onLoaded = () => {
5 | // Nothing for now
6 | };
7 |
8 | if (['interactive', 'complete'].indexOf(document.readyState) !== -1) {
9 | onLoaded();
10 | } else {
11 | document.addEventListener('DOMContentLoaded', onLoaded);
12 | }
13 | })();
14 |
--------------------------------------------------------------------------------
/assets/manrope.scss:
--------------------------------------------------------------------------------
1 | @font-face {
2 | font-family: "Manrope";
3 | font-style: normal;
4 | font-weight: 100 900;
5 | src:
6 | url("/webfonts/manrope/manrope-variable.woff2") format("woff2 supports variations"),
7 | url("/webfonts/manrope/manrope-variable.woff2") format("woff2-variations");
8 | }
9 |
--------------------------------------------------------------------------------
/assets/roboto-mono.scss:
--------------------------------------------------------------------------------
1 | @font-face {
2 | font-family: 'Roboto Mono';
3 | src:
4 | local('Roboto Mono'),
5 | url('./webfonts/roboto-mono/robotomono-regular-webfont.woff2') format('woff2'),
6 | url('./webfonts/roboto-mono/robotomono-regular-webfont.woff') format('woff'),
7 | url('./webfonts/roboto-mono/robotomono-regular-webfont.ttf') format('truetype'),
8 | url('./webfonts/roboto-mono/robotomono-regular-webfont.svg#roboto_monoregular') format('svg');
9 | font-weight: 400;
10 | font-display: swap;
11 | font-style: normal;
12 | }
13 |
--------------------------------------------------------------------------------
/assets/roboto.scss:
--------------------------------------------------------------------------------
1 | @font-face {
2 | font-family: 'Roboto';
3 | src:
4 | local('Roboto Italic'),
5 | url('./webfonts/roboto/roboto-italic-webfont.woff2') format('woff2'),
6 | url('./webfonts/roboto/roboto-italic-webfont.woff') format('woff'),
7 | url('./webfonts/roboto/roboto-italic-webfont.ttf') format('truetype'),
8 | url('./webfonts/roboto/roboto-italic-webfont.svg#roboto-italic-webfont') format('svg');
9 | font-weight: normal;
10 | font-display: swap;
11 | font-style: italic;
12 | }
13 |
14 | @font-face {
15 | font-family: 'Roboto';
16 | src:
17 | local('Roboto Bold'),
18 | url('./webfonts/roboto/roboto-bold-webfont.woff2') format('woff2'),
19 | url('./webfonts/roboto/roboto-bold-webfont.woff') format('woff'),
20 | url('./webfonts/roboto/roboto-bold-webfont.ttf') format('truetype'),
21 | url('./webfonts/roboto/roboto-bold-webfont.svg#roboto-bold-webfont') format('svg');
22 | font-weight: bold;
23 | font-display: swap;
24 | font-style: normal;
25 | }
26 |
27 | @font-face {
28 | font-family: 'Roboto';
29 | src:
30 | local('Roboto Medium'),
31 | url('./webfonts/roboto/roboto-medium-webfont.woff2') format('woff2'),
32 | url('./webfonts/roboto/roboto-medium-webfont.woff') format('woff'),
33 | url('./webfonts/roboto/roboto-medium-webfont.ttf') format('truetype'),
34 | url('./webfonts/roboto/roboto-medium-webfont.svg#roboto-medium-webfont') format('svg');
35 | font-weight: 500;
36 | font-display: swap;
37 | font-style: normal;
38 | }
39 |
40 | @font-face {
41 | font-family: 'Roboto';
42 | src:
43 | local('Roboto'),
44 | url('./webfonts/roboto/roboto-regular-webfont.woff2') format('woff2'),
45 | url('./webfonts/roboto/roboto-regular-webfont.woff') format('woff'),
46 | url('./webfonts/roboto/roboto-regular-webfont.ttf') format('truetype'),
47 | url('./webfonts/roboto/roboto-regular-webfont.svg#roboto-regular-webfont') format('svg');
48 | font-weight: normal;
49 | font-display: swap;
50 | font-style: normal;
51 | }
52 |
--------------------------------------------------------------------------------
/content/en/admin/optional.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Installing optional features
3 | menu:
4 | docs:
5 | weight: 40
6 | parent: admin
7 | identifier: admin-optional
8 | ---
9 |
10 | Mastodon offers a few optional features that can be used if needed.
11 |
12 | - [Object storage](./object-storage/)
13 | - [Hidden services](./tor/)
14 | - [Single Sign On](./sso/)
15 |
--------------------------------------------------------------------------------
/content/en/admin/optional/captcha.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Captcha
3 | description: Mitigating automated signup bots
4 | menu:
5 | docs:
6 | weight: 30
7 | parent: admin-optional
8 | ---
9 |
10 | As of Mastodon 4.2, using CAPTCHA technology is supported to help mitigate against bots signing up for new accounts.
11 | With CAPTCHA enabled, new registrations will be required to complete a challenge response as part of the e-mail verification process.
12 |
13 | 
14 |
15 | {{< hint style="danger" >}}
16 | For some people, the use of a central CAPTCHA service may be a security and privacy concern.
17 | In addition, CAPTCHA can make the registration process significantly less accessible, particularly for individuals with visual impairments, such as those who are blind or have low vision.
18 | {{}}
19 |
20 | Currently, hCaptcha is the only available provider supported by Mastodon.
21 | Other providers may be added in the future.
22 |
23 | ## hCaptcha
24 |
25 | - Create a free hCaptcha account at [hcaptcha.com](https://www.hcaptcha.com)
26 | - After completing registration, use the hCaptcha dashboard to add a new site with your Mastodon server domain and obtain a Site Key
27 | - From the Account Settings menu in hCaptcha, obtain your Secret Key
28 | - Add the values to your Mastodon environment configuration as `HCAPTCHA_SITE_KEY` and `HCAPTCHA_SECRET_KEY`
29 | - Restart the Mastodon services running on your server
30 | - From the Mastodon web interface navigate to **Administration** > **Server settings** > **Registrations** and check the box labled "Require new users to solve a CAPTCHA to confirm their account"
31 |
32 | 
33 |
--------------------------------------------------------------------------------
/content/en/admin/optional/sso.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Single Sign On
3 | menu:
4 | docs:
5 | weight: 40
6 | parent: admin-optional
7 | ---
8 |
9 | {{< hint style="danger" >}}
10 | This page is under construction.
11 |
12 | For the moment, please refer to [this pull request](https://github.com/mastodon/mastodon/pull/16221)
13 | {{< /hint >}}
14 |
15 |
--------------------------------------------------------------------------------
/content/en/admin/setup.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Setting up your new instance
3 | description: Things to do after installing Mastodon
4 | menu:
5 | docs:
6 | weight: 50
7 | parent: admin
8 | ---
9 |
10 | ## Creating an admin account {#admin}
11 |
12 | ### In the browser {#admin-gui}
13 |
14 | 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`:
15 |
16 | ```bash
17 | RAILS_ENV=production bin/tootctl accounts modify alice --role Owner
18 | ```
19 |
20 | {{}}
21 | 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.
22 | {{}}
23 |
24 | ### From the command line {#admin-cli}
25 |
26 | You can create a new account using the command-line interface.
27 |
28 | ```bash
29 | RAILS_ENV=production bin/tootctl accounts create \
30 | alice \
31 | --email alice@example.com \
32 | --confirmed \
33 | --role Owner
34 | ```
35 |
36 | A randomly generated password will be shown in the terminal.
37 |
38 | ## Filling in server information {#info}
39 |
40 | 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.
41 |
42 | | Setting | Meaning |
43 | | :--- | :--- |
44 | | Contact username | Your username so people know who owns the server |
45 | | Business email | An email address so people locked out of their accounts, or people without accounts, can contact you |
46 | | Instance description | Why did you start this server? Who is it for? What makes it different? |
47 | | Custom extended information | You can put all sorts of information in here but a **code of conduct** is recommended |
48 |
49 | After you fill these in, click “Save changes”.
50 |
--------------------------------------------------------------------------------
/content/en/api/datetime-format.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Datetime formats
3 | description: Datetime formats
4 | menu:
5 | docs:
6 | weight: 10
7 | parent: api
8 | ---
9 |
10 | ## Datetime {#datetime}
11 |
12 | A "datetime" specifies an instant in time.
13 |
14 | The string representation of a datetime uses the "Internet Date/Time Format" defined in [RFC3339 section 5.6](https://www.rfc-editor.org/rfc/rfc3339#section-5.6).
15 |
16 | To summarise, that is the following mandatory components:
17 |
18 | ```
19 | [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[s][TZD]
20 | ```
21 |
22 | where:
23 |
24 | - `[YYYY]` = four-digit year
25 | - `[MM]` = two-digit month (01=January, etc.)
26 | - `[DD]` = two-digit day of month (01 through 31)
27 | - `[hh]` = two digits of hour (00 through 23) (24 NOT allowed)
28 | - `[mm]` = two digits of minute (00 through 59)
29 | - `[ss]` = two digits of second (00 through 60)
30 | - `[s]` = one or more digits representing a decimal fraction of a second
31 | - `[TZD]` = time zone designator (either `Z` for UTC, or `+[hh]:[mm]` or `-[hh]:[mm]` to represent an offset from UTC)
32 |
33 | For example, `1994-11-05T13:15:30.000Z` (equivalent to `1994-11-05T08:15:30-05:00`).
34 |
35 | See [RFC3339 section 5.6](https://www.rfc-editor.org/rfc/rfc3339#section-5.6) for the complete [ABNF grammar](https://www.rfc-editor.org/rfc/rfc2234).
36 |
37 | ### Interoperability
38 |
39 | - The date and time portions are always separated by an uppercase `T` (not lowercase, not a space).
40 | - The timezone designator `Z` is always uppercase, not lowercase.
41 | - The fractional (`[s]`) part of the second is represented with at least one digit and at most three digits.
42 | - A field may be presented as a datetime while having lower resolution. E.g., the server clamps the value to the midnight on the date in question.
43 |
44 | ## Date {#date}
45 |
46 | A "date" specifies the calendar date an activity occurred, in UTC.
47 |
48 | The string representation of a date uses the complete, extended calendar date representation from ISO 8601, the International Standard for the representation of dates and times (section 5.2.1.1). This is also the "Complete date" format from [W3C Date and Time formats](https://www.w3.org/TR/NOTE-datetime).
49 |
50 | That is the following mandatory components:
51 |
52 | ```
53 | [YYYY]-[MM]-[DD]
54 | ```
55 |
56 | - `[YYYY]` = four-digit year
57 | - `[MM]` = two-digit month (01=January, etc.)
58 | - `[DD]` = two-digit day of month (01 through 31)
59 |
60 | ### Interoperability
61 |
62 | - The year, month, and date components are always separated by a `-`.
63 |
64 |
--------------------------------------------------------------------------------
/content/en/api/oauth-tokens.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: OAuth Tokens
3 | description: Defining what token types are used throughout this documentation
4 | menu:
5 | docs:
6 | weight: 15
7 | parent: api
8 | ---
9 |
10 | ## OAuth Tokens
11 |
12 | Mastodon supports two different types of OAuth Tokens: App tokens and User tokens. Throughout this documentation you will see these token types referenced in the `OAuth` field for API endpoints.
13 |
14 | The `OAuth` field also references Public, in which case no OAuth access token needs to be supplied to access the API endpoint.
15 |
16 | ### App tokens
17 |
18 | In order to receive an App token, you must perform a [client credentials grant flow]({{}}), which gives you a token that can be used to interact with the API on behalf of the OAuth Application. Currently the only API endpoints that accepts this token type are:
19 |
20 | - [`GET /api/v1/apps/verify_credentials`]({{}})
21 | - [`POST /api/v1/accounts`]({{}})
22 |
23 | ### User tokens
24 |
25 | In order to create a User token, you must perform a [authorization code grant flow]({{}}), which gives you an access token that is associated with the user who approves the access grant request.
26 |
27 | Many Mastodon APIs require User tokens and specific scopes to access them.
28 |
--------------------------------------------------------------------------------
/content/en/api/rate-limits.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Rate limits
3 | description: Defining how often you can call the REST API
4 | menu:
5 | docs:
6 | weight: 30
7 | parent: api
8 | ---
9 |
10 | ## Headers
11 |
12 | Rate limit information is returned in the response headers:
13 |
14 | `X-RateLimit-Limit`
15 | : Number of requests permitted per time period
16 |
17 | `X-RateLimit-Remaining`
18 | : Number of requests you can still make
19 |
20 | `X-RateLimit-Reset`
21 | : Timestamp when your rate limit will reset
22 |
23 | {{< hint style="info" >}}
24 | An API method can be subject to multiple overlapping rate limits. The headers return information about the one you are closest to exceeding.
25 | {{}}
26 |
27 | ## Limits
28 |
29 | By default, the following limits are hardcoded:
30 |
31 | ### Per account
32 |
33 | All endpoints and methods can be called 300 times within 5 minutes.
34 |
35 | #### Uploading media
36 |
37 | `POST /api/v1/media` can be called 30 times within 30 minutes.
38 |
39 | #### Deleting statuses
40 |
41 | Either `DELETE /api/v1/statuses/:id` or `POST /api/v1/statuses/:id/unreblog` can be called 30 times within 30 minutes.
42 |
43 | ### Per IP
44 |
45 | All endpoints and methods can be called 300 times within 5 minutes.
46 |
47 | #### Creating accounts
48 |
49 | `POST /api/v1/accounts` can be called 5 times within 30 minutes.
50 |
--------------------------------------------------------------------------------
/content/en/dev/code.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Code structure
3 | description: Where to find certain parts of the codebase.
4 | menu:
5 | docs:
6 | weight: 30
7 | parent: dev
8 | ---
9 |
10 | ### Code structure {#structure}
11 |
12 | 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.
13 |
14 | #### Ruby {#ruby}
15 |
16 | `app/controllers`
17 | : Code that binds business logic to templates
18 |
19 | `app/helpers`
20 | : Code that can be used from views, i.e. common operations
21 |
22 | `app/lib`
23 | : Code that doesn’t fit in the other categories
24 |
25 | `app/models`
26 | : Representation of data entities and their associated methods
27 |
28 | `app/policies`
29 | : Permission checks and other validations, before calling related methods
30 |
31 | `app/serializers`
32 | : Code that generates JSON from models
33 |
34 | `app/services`
35 | : Complex logical operations involving multiple models
36 |
37 | `app/views`
38 | : Templates for generating HTML or other output
39 |
40 | `app/workers`
41 | : Code that executes outside the request-response cycle
42 |
43 | `spec`
44 | : Automated test suite
45 |
46 | #### JavaScript {#javascript}
47 |
48 | `app/javascript/mastodon`
49 | : Code for the frontend React.js application
50 |
51 | `app/javascript/packs`
52 | : Code for non-React.js pages
53 |
54 | #### CSS and other assets {#assets}
55 |
56 | `app/javascript/images`
57 | : Images
58 |
59 | `app/javascript/styles`
60 | : Code that turns into CSS via Sass
61 |
62 | #### Localizations {#localizations}
63 |
64 | `config/locales`
65 | : Server-side localizations in the YML format
66 |
67 | `app/javascript/mastodon/locales`
68 | : Client-side localizations in the JSON format
69 |
70 | All locale files are normalized to ensure consistent formatting and key order, which minimizes changesets in version control.
71 |
72 | - Run `bundle exec i18n-tasks normalize` to normalize server-side translations
73 | - Run `yarn run i18n:extract` to extract and normalize client-side translations into `en.json`
74 |
--------------------------------------------------------------------------------
/content/en/dev/disclosure.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Bug bounties and responsible disclosure
3 | description: What to do if you found a serious bug
4 | menu:
5 | docs:
6 | weight: 9999
7 | parent: dev
8 | ---
9 |
10 | 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.
11 |
12 | 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.
13 |
14 | {{< hint style="info" >}}
15 | A "vulnerability in Mastodon" is a vulnerability in the code distributed through our main source code repository on GitHub. Vulnerabilities that are specific to a given installation (e.g. misconfiguration) should be reported to the owner of that installation and not us.
16 | {{< /hint >}}
17 |
--------------------------------------------------------------------------------
/content/en/dev/overview.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Technical overview
3 | description: A description of Mastodon's architecture.
4 | menu:
5 | docs:
6 | weight: 10
7 | parent: dev
8 | ---
9 |
10 |
13 |
14 | 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.
15 |
16 | 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.
17 |
18 | Tutorials for installing these dependencies can be found on the “Installing from source” page in the Running Mastodon section of the documentation. After following the installation guide in the Running Mastodon section, see the “Setting up a dev environment” page for further instructions on how to configure your environment for development.
19 |
20 | ### Environments {#environments}
21 |
22 | An “environment” is a set of configuration values intended for a specific use case. Some environments could be: development, in which you intend to change the code; test, in which you intend to run the automated test suite; staging, which is meant to preview the code to end-users; and production, which is intended to face end-users. Mastodon comes with configurations for development, testing and production.
23 |
24 | The default value of `RAILS_ENV` is `development`, so you don’t need to set anything extra to run Mastodon in development mode. In fact, all of Mastodon’s configuration has correct defaults for the development environment, so you do not need an `.env` file unless you need to customize something. Here are some of the different behaviours between the development environment and the production environment:
25 |
26 | - Ruby code reloads itself when you change it, which means you don’t need to restart the Rails server process to see changes
27 | - All errors you encounter show stack traces in the browser, rather than being hidden behind a generic error page
28 | - Webpack runs continuously and re-compiles JS and CSS assets when you change any of the front-end files, and the pages automatically reload
29 | - Caching is disabled by default
30 | - An admin account with the e-mail `admin@localhost:3000` and password `mastodonadmin` is created automatically during `db:seed`
31 |
32 | It should be noted that the Docker configuration distributed with Mastodon is optimized for the production environment, and so is an extremely bad fit for development. The Vagrant configuration, on the other hand, is meant specifically for development and not production use.
33 |
--------------------------------------------------------------------------------
/content/en/entities/AccountWarning.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: AccountWarning
3 | description: Moderation warning against a particular account.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/AccountWarning",
9 | "/api/entities/AccountWarning",
10 | ]
11 | ---
12 |
13 | ## Attributes
14 |
15 | ### `id` {#id}
16 |
17 | **Description:** The ID of the account warning in the database.\
18 | **Type:** String (cast from integer)\
19 | **Version history:**\
20 | 4.3.0 - added
21 |
22 | ### `action` {#action}
23 |
24 | **Description:** Action taken against the account.\
25 | **Type:** String (Enumerable oneOf)\
26 | `none` = No action was taken, this is a simple warning\
27 | `disable` = The account has been disabled\
28 | `mark_statuses_as_sensitive` = Specific posts from the target account have been marked as sensitive\
29 | `delete_statuses` = Specific statuses from the target account have been deleted\
30 | `sensitive` = All posts from the target account are marked as sensitive\
31 | `silence` = The target account has been limited\
32 | `suspend` = The target account has been suspended\
33 | **Version history:**\
34 | 4.3.0 - added
35 |
36 | ### `text` {#text}
37 |
38 | **Description:** Message from the moderator to the target account.\
39 | **Type:** String\
40 | **Version history:**\
41 | 4.3.0 - added
42 |
43 | ### `status_ids` {#status_ids}
44 |
45 | **Description:** List of status IDs that are relevant to the warning. When `action` is `mark_statuses_as_sensitive` or `delete_statuses`, those are the affected statuses.\
46 | **Type:** {{}} Array of String (cast from integer), or null\
47 | **Version history:**\
48 | 4.3.0 - added
49 |
50 | ### `target_account` {#target_account}
51 |
52 | **Description:** Account against which a moderation decision has been taken.\
53 | **Type:** [Account]({{< relref "entities/Account" >}})\
54 | **Version history:**\
55 | 4.3.0 - added
56 |
57 | ### `appeal` {#appeal}
58 |
59 | **Description:** Appeal submitted by the target account, if any.\
60 | **Type:** {{}} [Appeal]({{< relref "entities/Appeal" >}}), or null\
61 | **Version history:**\
62 | 4.3.0 - added
63 |
64 | ### `created_at` {#created_at}
65 |
66 | **Description:** When the event took place.\
67 | **Type:** String ([Datetime](/api/datetime-format#datetime))\
68 | **Version history:**\
69 | 4.3.0 - added
70 |
--------------------------------------------------------------------------------
/content/en/entities/Admin_CanonicalEmailBlock.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Admin::CanonicalEmailBlock
3 | description: Represents a canonical email block (hashed).
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/admin-canonicalemailblock",
9 | "/entities/Admin-CanonicalEmailBlock",
10 | "/entities/admin_canonicalemailblock",
11 | "/entities/Admin_CanonicalEmailBlock",
12 | "/api/entities/admin-canonicalemailblock",
13 | "/api/entities/Admin-CanonicalEmailBlock",
14 | "/api/entities/admin_canonicalemailblock",
15 | "/api/entities/Admin_CanonicalEmailBlock",
16 | ]
17 | ---
18 |
19 | ## Example
20 |
21 | ```json
22 | {
23 | "id": "2",
24 | "canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c"
25 | }
26 | ```
27 |
28 | ## Attributes
29 |
30 | ### `id` {#id}
31 |
32 | **Description:** The ID of the email block in the database.\
33 | **Type:** String (cast from an integer, but not guaranteed to be a number)\
34 | **Version history:**\
35 | 4.0.0 - added
36 |
37 | ### `canonical_email_hash` {#canonical_email_hash}
38 |
39 | **Description:** The SHA256 hash of the canonical email address.\
40 | **Type:** String (SHA256)\
41 | **Version history:**\
42 | 4.0.0 - added
43 |
44 | ## See also
45 |
46 | {{< page-relref ref="methods/admin/canonical_email_blocks" caption="admin/canonical_email_blocks API methods" >}}
47 |
48 | {{< 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" >}}
--------------------------------------------------------------------------------
/content/en/entities/Admin_DomainAllow.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Admin::DomainAllow
3 | description: Represents a domain allowed to federate.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/admin-domainallow",
9 | "/entities/Admin-DomainAllow",
10 | "/entities/admin_domainallow",
11 | "/entities/Admin_DomainAllow",
12 | "/api/entities/admin-domainallow",
13 | "/api/entities/Admin-DomainAllow",
14 | "/api/entities/admin_domainallow",
15 | "/api/entities/Admin_DomainAllow",
16 | ]
17 | ---
18 |
19 | ## Example
20 |
21 | ```json
22 | {
23 | "id": "1",
24 | "domain": "mastodon.social",
25 | "created_at": "2022-09-14T21:23:02.755Z"
26 | }
27 | ```
28 |
29 | ## Attributes
30 |
31 | ### `id` {#id}
32 |
33 | **Description:** The ID of the DomainAllow in the database.\
34 | **Type:** String (cast from an integer, but not guaranteed to be a number)\
35 | **Version history:**\
36 | 4.0.0 - added
37 |
38 | ### `domain` {#domain}
39 |
40 | **Description:** The domain that is allowed to federate.\
41 | **Type:** String\
42 | **Version history:**\
43 | 4.0.0 - added
44 |
45 | ### `created_at` {#created_at}
46 |
47 | **Description:** When the domain was allowed to federate.\
48 | **Type:** String ([Datetime](/api/datetime-format#datetime))\
49 | **Version history:**\
50 | 4.0.0 - added
51 |
52 | ## See also
53 |
54 | {{< page-relref page="methods/admin/domain_allows" caption="admin/domain_allows API methods" >}}
55 |
56 | {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/domain_allow_serializer.rb" caption="app/serializers/rest/admin/domain_allow_serializer.rb" >}}
--------------------------------------------------------------------------------
/content/en/entities/Admin_Ip.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Admin::Ip
3 | description: Represents an IP address associated with a user.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/admin-ip",
9 | "/entities/Admin-Ip",
10 | "/entities/admin_ip",
11 | "/entities/Admin_Ip",
12 | "/api/entities/admin-ip",
13 | "/api/entities/Admin-Ip",
14 | "/api/entities/admin_ip",
15 | "/api/entities/Admin_Ip",
16 | ]
17 | ---
18 |
19 | ## Example
20 |
21 | ```json
22 | {
23 | "ip": "192.168.42.1",
24 | "used_at": "2022-09-15T01:38:58.851Z"
25 | }
26 | ```
27 |
28 | ## Attributes
29 |
30 | ### `ip` {#id}
31 |
32 | **Description:** The IP address.\
33 | **Type:** String (IP address)\
34 | **Version history:**\
35 | 3.5.0 - added
36 |
37 | ### `used_at` {#used_at}
38 |
39 | **Description:** The timestamp of when the IP address was last used for this account.\
40 | **Type:** String ([Datetime](/api/datetime-format#datetime))\
41 | **Version history:**\
42 | 3.5.0 - added
43 |
44 | ## See also
45 |
46 | {{< page-relref ref="entities/Admin_Account#ips" caption="Admin::Account (`ips` attribute)" >}}
47 |
48 | {{< 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" >}}
--------------------------------------------------------------------------------
/content/en/entities/Admin_IpBlock.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Admin::IpBlock
3 | description: Represents an IP address range that cannot be used to sign up.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/admin-ipblock",
9 | "/entities/Admin-IpBlock",
10 | "/entities/admin_ipblock",
11 | "/entities/Admin_IpBlock",
12 | "/api/entities/admin-ipblock",
13 | "/api/entities/Admin-IpBlock",
14 | "/api/entities/admin_ipblock",
15 | "/api/entities/Admin_IpBlock",
16 | ]
17 | ---
18 |
19 | ## Example
20 |
21 | ```json
22 | {
23 | "id": "1",
24 | "ip": "8.8.8.8/32",
25 | "severity": "no_access",
26 | "comment": "",
27 | "created_at": "2022-11-16T07:22:00.501Z",
28 | "expires_at": null
29 | }
30 | ```
31 |
32 | ## Attributes
33 |
34 | ### `id` {#id}
35 |
36 | **Description:** The ID of the DomainBlock in the database.\
37 | **Type:** String (cast from an integer, but not guaranteed to be a number)\
38 | **Version history:**\
39 | 4.0.0 - added
40 |
41 | ### `ip` {#ip}
42 |
43 | **Description:** The IP address range that is not allowed to federate.\
44 | **Type:** String (IP address and prefix)\
45 | **Version history:**\
46 | 4.0.0 - added
47 |
48 | ### `severity` {#severity}
49 |
50 | **Description:** The associated policy with this IP block.\
51 | **Type:** String (Enumerable, oneOf)\
52 | `sign_up_requires_approval` = Any signup from this IP range will create a pending account\
53 | `sign_up_block` = Any signup from this IP range will be rejected\
54 | `no_access` = Any activity from this IP range will be rejected entirely\
55 | **Version history:**\
56 | 4.0.0 - added
57 |
58 | ### `comment` {#comment}
59 |
60 | **Description:** The recorded reason for this IP block.\
61 | **Type:** String\
62 | **Version history:**\
63 | 4.0.0 - added
64 |
65 | ### `created_at` {#created_at}
66 |
67 | **Description:** When the IP block was created.\
68 | **Type:** String ([Datetime](/api/datetime-format#datetime))\
69 | **Version history:**\
70 | 4.0.0 - added
71 |
72 | ### `expires_at` {#expires_at}
73 |
74 | **Description:** When the IP block will expire.\
75 | **Type:** {{}} String ([Datetime](/api/datetime-format#datetime))\
76 | **Version history:**\
77 | 4.0.0 - added
78 |
79 | ## See also
80 |
81 | {{< page-relref page="methods/admin/ip_blocks" caption="admin/ip_blocks API methods" >}}
82 |
83 | {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/ip_block_serializer.rb" caption="app/serializers/rest/admin/ip_block_serializer.rb" >}}
--------------------------------------------------------------------------------
/content/en/entities/Appeal.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Appeal
3 | description: Appeal against a moderation action.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/Appeal",
9 | "/api/entities/Appeal",
10 | ]
11 | ---
12 |
13 | ## Attributes
14 |
15 | ### `text` {#text}
16 |
17 | **Description:** Text of the appeal from the moderated account to the moderators.\
18 | **Type:** String\
19 | **Version history:**\
20 | 4.3.0 - added
21 |
22 | ### `state` {#state}
23 |
24 | **Description:** State of the appeal.\
25 | **Type:** String (Enumerable oneOf)\
26 | `approved` = The appeal has been approved by a moderator\
27 | `rejected` = The appeal has been rejected by a moderator\
28 | `pending` = The appeal has been submitted, but neither approved nor rejected yet\
29 | **Version history:**\
30 | 4.3.0 - added
31 |
--------------------------------------------------------------------------------
/content/en/entities/Context.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Context
3 | description: Represents the tree around a given status. Used for reconstructing threads of statuses.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/context",
9 | "/entities/Context",
10 | "/api/entities/context",
11 | "/api/entities/Context",
12 | ]
13 | ---
14 |
15 | ## Example
16 |
17 | ```json
18 | {
19 | "ancestors": [
20 | {
21 | "id": "103188938570975982",
22 | "created_at": "2019-11-23T19:44:00.124Z",
23 | "in_reply_to_id": null,
24 | // ...
25 | },
26 | {
27 | "id": "103188971072973252",
28 | "created_at": "2019-11-23T19:52:23.398Z",
29 | "in_reply_to_id": "103188938570975982",
30 | // ...
31 | },
32 | {
33 | "id": "103188982235527758",
34 | "created_at": "2019-11-23T19:55:08.208Z",
35 | "in_reply_to_id": "103188971072973252",
36 | // ...
37 | }
38 | ],
39 | "descendants": [
40 | {
41 | "id": "103189026958574542",
42 | "created_at": "2019-11-23T20:06:36.011Z",
43 | "in_reply_to_id": "103189005915505698",
44 | // ...
45 | }
46 | ]
47 | }
48 | ```
49 |
50 | ## Attributes
51 |
52 | ### `ancestors` {#ancestors}
53 |
54 | **Description:** Parents in the thread.\
55 | **Type:** Array of [Status]({{< relref "entities/Status" >}})\
56 | **Version history:**\
57 | 0.6.0 - added
58 |
59 | ### `descendants` {#descendants}
60 |
61 | **Description:** Children in the thread.\
62 | **Type:** Array of [Status]({{< relref "entities/Status" >}})\
63 | **Version history:**\
64 | 0.6.0 - added
65 |
66 | ## See also
67 |
68 | {{< page-relref ref="methods/statuses#context" caption="GET /api/v1/statuses/:id/context" >}}
69 |
70 | {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/context_serializer.rb" caption="app/serializers/rest/context_serializer.rb" >}}
--------------------------------------------------------------------------------
/content/en/entities/Conversation.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Conversation
3 | description: Represents a conversation with "direct message" visibility.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/conversation",
9 | "/entities/Conversation",
10 | "/api/entities/conversation",
11 | "/api/entities/Conversation",
12 | ]
13 | ---
14 |
15 | ## Example
16 |
17 | ```json
18 | {
19 | "id": "418450",
20 | "unread": true,
21 | "accounts": [
22 | {
23 | "id": "482403",
24 | "username": "amic",
25 | "acct": "amic@nulled.red",
26 | // ...
27 | }
28 | ],
29 | "last_status": {
30 | "id": "103196583826321184",
31 | "created_at": "2019-11-25T04:08:24.000Z",
32 | "in_reply_to_id": "103196540587943467",
33 | "in_reply_to_account_id": "14715",
34 | // ...
35 | }
36 | }
37 | ```
38 |
39 | ## Attributes
40 |
41 | ### `id` {#id}
42 |
43 | **Description:** The ID of the conversation in the database.\
44 | **Type:** String (cast from an integer, but not guaranteed to be a number)\
45 | **Version history:**\
46 | 2.6.0 - added
47 |
48 | ### `unread` {#unread}
49 |
50 | **Description:** Is the conversation currently marked as unread?\
51 | **Type:** Boolean\
52 | **Version history:**\
53 | 2.6.0 - added
54 |
55 | ### `accounts` {#accounts}
56 |
57 | **Description:** Participants in the conversation.\
58 | **Type:** Array of [Account]({{< relref "entities/Account" >}})\
59 | **Version history:**\
60 | 2.6.0 - added
61 |
62 | ### `last_status` {#last_status}
63 |
64 | **Description:** The last status in the conversation.\
65 | **Type:** {{}} [Status]({{< relref "entities/Status" >}})\
66 | **Version history:**\
67 | 2.6.0 - added
68 |
69 | ## See also
70 |
71 | {{< page-relref ref="methods/conversations" caption="conversations API methods" >}}
72 |
73 | {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/conversation_serializer.rb" caption="app/serializers/rest/conversation_serializer.rb" >}}
74 |
75 |
76 |
77 |
78 |
79 |
--------------------------------------------------------------------------------
/content/en/entities/CustomEmoji.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: CustomEmoji
3 | description: Represents a custom emoji.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/emoji",
9 | "/entities/Emoji",
10 | "/entities/customemoji",
11 | "/entities/CustomEmoji",
12 | "/api/entities/emoji",
13 | "/api/entities/Emoji",
14 | "/api/entities/customemoji",
15 | "/api/entities/CustomEmoji",
16 | ]
17 | ---
18 |
19 | ## Example
20 |
21 | ```json
22 | {
23 | "shortcode": "blobaww",
24 | "url": "https://files.mastodon.social/custom_emojis/images/000/011/739/original/blobaww.png",
25 | "static_url": "https://files.mastodon.social/custom_emojis/images/000/011/739/static/blobaww.png",
26 | "visible_in_picker": true,
27 | "category": "Blobs"
28 | }
29 | ```
30 |
31 | ## Attributes
32 |
33 | ### `shortcode` {#shortcode}
34 |
35 | **Description:** The name of the custom emoji.\
36 | **Type:** String\
37 | **Version history:**\
38 | 2.0.0 - added
39 |
40 | ### `url` {#url}
41 |
42 | **Description:** A link to the custom emoji.\
43 | **Type:** String (URL)\
44 | **Version history:**\
45 | 2.0.0 - added
46 |
47 | ### `static_url` {#static_url}
48 |
49 | **Description:** A link to a static copy of the custom emoji.\
50 | **Type:** String (URL)\
51 | **Version history:**\
52 | 2.0.0 - added
53 |
54 | ### `visible_in_picker` {#visible_in_picker}
55 |
56 | **Description:** Whether this Emoji should be visible in the picker or unlisted.\
57 | **Type:** Boolean\
58 | **Version history:**\
59 | 2.0.0 - added
60 |
61 | ### `category` {#category}
62 |
63 | **Description:** Used for sorting custom emoji in the picker.\
64 | **Type:** {{}} String\
65 | **Version history:**\
66 | 3.0.0 - added
67 |
68 | ## See also
69 |
70 | {{< page-relref ref="methods/custom_emojis" caption="GET /api/v1/custom_emojis" >}}
71 |
72 | {{< page-relref ref="entities/Status#emojis" caption="Status (`emojis` attribute)" >}}
73 |
74 | {{< page-relref ref="entities/Announcement#emojis" caption="Announcement (`emojis` attribute)" >}}
75 |
76 | {{< 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" >}}
77 |
78 |
79 |
80 |
81 |
82 |
--------------------------------------------------------------------------------
/content/en/entities/DomainBlock.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: DomainBlock
3 | description: Represents a domain that is blocked by the instance.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/domainblock",
9 | "/entities/DomainBlock",
10 | "/api/entities/domainblock",
11 | "/api/entities/DomainBlock",
12 | ]
13 | ---
14 |
15 | ## Example
16 |
17 | ```json
18 | {
19 | "domain":"daji******.com",
20 | "digest":"3752f63a7079d60c2de5dceb8bd7608e86a15544eb78a494a482041c3684b37f",
21 | "severity":"suspend",
22 | "comment":"Inappropriate content"
23 | }
24 | ```
25 |
26 | ## Attributes
27 |
28 | ### `domain` {#domain}
29 |
30 | **Description:** The domain which is blocked. This may be obfuscated or partially censored.\
31 | **Type:** String\
32 | **Version history:**\
33 | 4.0.0 - added
34 |
35 | ### `digest` {#digest}
36 |
37 | **Description:** The SHA256 hash digest of the domain string.\
38 | **Type:** String (SHA256)\
39 | **Version history:**\
40 | 4.0.0 - added
41 |
42 | ### `severity` {#severity}
43 |
44 | **Description:** The level to which the domain is blocked.\
45 | **Type:** String (Enumerable, oneOf)\
46 | `silence` = Users from this domain will be hidden from timelines, threads, and notifications (unless you follow the user).\
47 | `suspend` = Incoming messages from this domain will be rejected and dropped entirely.\
48 | **Version history:**\
49 | 4.0.0 - added
50 |
51 | ### `comment` {{%optional%}} {#comment}
52 |
53 | **Description:** An optional reason for the domain block.\
54 | **Type:** String\
55 | **Version history:**\
56 | 4.0.0 - added
57 |
58 | ## See also
59 |
60 | {{< page-relref ref="methods/instance#domain_blocks" caption="GET /api/v1/instance/domain_blocks" >}}
61 |
62 | {{< 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" >}}
63 |
--------------------------------------------------------------------------------
/content/en/entities/EncryptedMessage.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: EncryptedMessage
3 | description: Represents an encrypted message.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/encryptedmessage",
9 | "/entities/EncryptedMessage",
10 | "/entities/encryptedmessage",
11 | "/entities/EncryptedMessage",
12 | ]
13 | draft: true
14 | ---
15 |
16 | {{< hint style="info" >}}
17 | This entity is currently unused.
18 | {{}}
19 |
20 | ## Example
21 |
22 | ```json
23 | ```
24 |
25 | ## Attributes
26 |
27 | ### `id` {#id}
28 |
29 | **Description:** The ID of the EncryptedMessage in the database.\
30 | **Type:** String (cast from an integer, but not guaranteed to be a number)\
31 | **Version history:**\
32 | 3.2.0 - added
33 |
34 | ### `account_id` {#account_id}
35 |
36 | **Description:** The ID of the Account that sent this message.\
37 | **Type:** String (cast from an integer, but not guaranteed to be a number)\
38 | **Version history:**\
39 | 3.2.0 - added
40 |
41 | ### `device_id` {#device_id}
42 |
43 | **Description:** The ID of the Device that sent this message.\
44 | **Type:** String (cast from an integer, but not guaranteed to be a number)\
45 | **Version history:**\
46 | 3.2.0 - added
47 |
48 | ### `type` {#type}
49 |
50 | **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).\
51 | **Type:** String (Enumerable, oneOf)\
52 | `0` = Pre-key message (used to establish a new session)\
53 | `1` = Normal encrypted message (part of an existing session)\
54 | **Version history:**\
55 | 3.2.0 - added
56 |
57 | ### `body` {#body}
58 |
59 | **Description:** The encrypted message content.\
60 | **Type:** String\
61 | **Version history:**\
62 | 3.2.0 - added
63 |
64 | ### `digest` {#digest}
65 |
66 | **Description:** An HMAC SHA-256 digest hash of the message.\
67 | **Type:** String (SHA256)\
68 | **Version history:**\
69 | 3.2.0 - added
70 |
71 | ### `message_franking` {#message_franking}
72 |
73 | **Description:** A signed value to be used when reporting the message body for its content.\
74 | **Type:** String\
75 | **Version history:**\
76 | 3.2.0 - added
77 |
78 | ### `created_at` {#created_at}
79 |
80 | **Description:** A timestamp for when the message was created.\
81 | **Type:** String ([Datetime](/api/datetime-format#datetime))\
82 | **Version history:**\
83 | 3.2.0 - added
84 |
85 | ## See also
86 |
87 | {{< 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" >}}
88 |
89 | {{< caption-link url="https://github.com/mastodon/mastodon/pull/13820" caption="Add end-to-end encryption API (#13820)" >}}
90 |
91 |
--------------------------------------------------------------------------------
/content/en/entities/ExtendedDescription.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: ExtendedDescription
3 | description: Represents an extended description for the instance, to be shown on its about page.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/extendeddescription",
9 | "/entities/ExtendedDescription",
10 | "/api/entities/extendeddescription",
11 | "/api/entities/ExtendedDescription",
12 | ]
13 | ---
14 |
15 | ## Example
16 |
17 | ```json
18 | {
19 | "updated_at":"2022-11-03T04:09:07Z",
20 | "content":"
For inquiries not related specifically to the operation of this server, such as press inquiries, please contact press@joinmastodon.org.
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.
\n\n
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.
\n\n
Impressum
\n\n
Mastodon gGmbH \nMühlenstraße 8a \n14167 Berlin \nGermany
\n\n
E-Mail-Adresse: hello@joinmastodon.org
\n\n
Vertretungsberechtigt: Eugen Rochko (Geschäftsführer)
Handelsregister \nGeführt bei: Amtsgericht Charlottenburg \nNummer: HRB 230086 B
\n"
21 | }
22 | ```
23 |
24 | ## Attributes
25 |
26 | ### `updated_at` {#updated_at}
27 |
28 | **Description:** A timestamp of when the extended description was last updated.\
29 | **Type:** String ([Datetime](/api/datetime-format#datetime))\
30 | **Version history:**\
31 | 4.0.0 - added
32 |
33 | ### `content` {#content}
34 |
35 | **Description:** The rendered HTML content of the extended description.\
36 | **Type:** String (HTML)\
37 | **Version history:**\
38 | 4.0.0 - added
39 |
40 | ## See also
41 |
42 | {{< page-relref ref="methods/instance#extended_description" caption="GET /api/v1/instance/extended_description" >}}
43 |
44 | {{< 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" >}}
--------------------------------------------------------------------------------
/content/en/entities/FamiliarFollowers.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: FamiliarFollowers
3 | description: Represents a subset of your follows who also follow some other user.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/familiarfollowers",
9 | "/entities/FamiliarFollowers",
10 | "/api/entities/familiarfollowers",
11 | "/api/entities/FamiliarFollowers",
12 | ]
13 | ---
14 |
15 | ## Example
16 |
17 | ```json
18 | [
19 | {
20 | "id":"1",
21 | "accounts":[
22 | {
23 | "id":"1087990",
24 | "username":"moss",
25 | "acct":"moss@goblin.camp",
26 | // ...
27 | },
28 | {
29 | "id":"1092723",
30 | "username":"vivianrose",
31 | "acct":"vivianrose",
32 | // ...
33 | },
34 | // ...
35 | ]
36 | },
37 | {
38 | "id":"2",
39 | "accounts":[]
40 | }
41 | ]
42 | ```
43 |
44 | ## Attributes
45 |
46 | ### `id` {#id}
47 |
48 | **Description:** The ID of the Account in the database.\
49 | **Type:** String (cast from an integer, but not guaranteed to be a number)\
50 | **Version history:**\
51 | 3.5.0 - added
52 |
53 | ### `accounts` {#accounts}
54 |
55 | **Description:** Accounts you follow that also follow this account.\
56 | **Type:** Array of [Account]({{< relref "entities/Account" >}})\
57 | **Version history:**\
58 | 3.5.0 - added
59 |
60 | ## See also
61 |
62 | {{< page-relref ref="methods/accounts#familiar_followers" caption="GET /api/v1/accounts/:id/familiar_followers" >}}
63 |
64 | {{< 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" >}}
--------------------------------------------------------------------------------
/content/en/entities/FeaturedTag.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: FeaturedTag
3 | description: Represents a hashtag that is featured on a profile.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/featuredtag",
9 | "/entities/FeaturedTag",
10 | "/api/entities/featuredtag",
11 | "/api/entities/FeaturedTag",
12 | ]
13 | ---
14 |
15 | ## Example
16 |
17 | ```json
18 | {
19 | "id": "627",
20 | "name": "nowplaying",
21 | "url": "https://mastodon.social/@trwnh/tagged/nowplaying",
22 | "statuses_count": "70",
23 | "last_status_at": "2022-08-29"
24 | }
25 | ```
26 |
27 | ## Attributes
28 |
29 | ### `id` {#id}
30 |
31 | **Description:** The internal ID of the featured tag in the database.\
32 | **Type:** String (cast from integer but not guaranteed to be a number)\
33 | **Version history:**\
34 | 3.0.0 - added
35 |
36 | ### `name` {#name}
37 |
38 | **Description:** The name of the hashtag being featured.\
39 | **Type:** String\
40 | **Version history:**\
41 | 3.0.0 - added
42 |
43 | ### `url` {#url}
44 |
45 | **Description:** A link to all statuses by a user that contain this hashtag.\
46 | **Type:** String (URL)\
47 | **Version history:**\
48 | 3.3.0 - added
49 |
50 | ### `statuses_count` {#statuses_count}
51 |
52 | **Description:** The number of authored statuses containing this hashtag.\
53 | **Type:** String\
54 | **Version history:**\
55 | 3.0.0 - added
56 |
57 | ### `last_status_at` {#last_status_at}
58 |
59 | **Description:** The date of the last authored status containing this hashtag.\
60 | **Type:** String ([Date](/api/datetime-format#date))\
61 | **Version history:**\
62 | 3.0.0 - added
63 |
64 | ## See also
65 |
66 | {{< page-relref ref="methods/featured_tags" caption="featured_tags API methods" >}}
67 |
68 | {{< 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" >}}
69 |
70 |
71 |
72 |
73 |
74 |
--------------------------------------------------------------------------------
/content/en/entities/FilterKeyword.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: FilterKeyword
3 | description: Represents a keyword that, if matched, should cause the filter action to be taken.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/filterkeyword",
9 | "/entities/FilterKeyword",
10 | "/api/entities/filterkeyword",
11 | "/api/entities/FilterKeyword",
12 | ]
13 | ---
14 |
15 | ## Example
16 |
17 | ```json
18 | {
19 | "id": "1197",
20 | "keyword": "bad word",
21 | "whole_word": false
22 | }
23 | ```
24 |
25 | ## Attributes
26 |
27 | ### `id` {#id}
28 |
29 | **Description:** The ID of the FilterKeyword in the database.\
30 | **Type:** String (cast from an integer, but not guaranteed to be a number)\
31 | **Version history:**\
32 | 4.0.0 - added
33 |
34 | ### `keyword` {#keyword}
35 |
36 | **Description:** The phrase to be matched against.\
37 | **Type:** String\
38 | **Version history:**\
39 | 4.0.0 - added
40 |
41 | ### `whole_word` {#whole_word}
42 |
43 | **Description:** Should the filter consider word boundaries? See [implementation guidelines for filters]({{< relref "api/guidelines#filters" >}}).\
44 | **Type:** Boolean\
45 | **Version history:**\
46 | 4.0.0 - added
47 |
48 | ## See also
49 |
50 | {{< page-relref ref="api/guidelines#filters" caption="Implementation guidelines for filters" >}}
51 |
52 | {{< page-relref ref="methods/filters" caption="/api/v2/filters methods" >}}
53 |
54 | {{< 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" >}}
--------------------------------------------------------------------------------
/content/en/entities/FilterResult.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: FilterResult
3 | description: Represents a filter whose keywords matched a given status.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/filterresult",
9 | "/entities/FilterResult",
10 | "/api/entities/filterresult",
11 | "/api/entities/FilterResult",
12 | ]
13 | ---
14 |
15 | ## Example
16 |
17 | ```json
18 | {
19 | "filter": {
20 | "id": "3",
21 | "title": "Hide completely",
22 | "context": [
23 | "home"
24 | ],
25 | "expires_at": "2022-09-20T17:27:39.296Z",
26 | "filter_action": "hide"
27 | },
28 | "keyword_matches": [
29 | "bad word"
30 | ],
31 | "status_matches": [
32 | "109031743575371913"
33 | ]
34 | }
35 | ```
36 |
37 | ## Attributes
38 |
39 | ### `filter` {#filter}
40 |
41 | **Description:** The filter that was matched.\
42 | **Type:** [Filter]({{< relref "entities/Filter" >}})\
43 | **Version history:**\
44 | 4.0.0 - added
45 |
46 | ### `keyword_matches` {#keyword_matches}
47 |
48 | **Description:** The keyword within the filter that was matched.\
49 | **Type:** {{}} Array of String, or null\
50 | **Version history:**\
51 | 4.0.0 - added
52 |
53 | ### `status_matches` {#status_matches}
54 |
55 | **Description:** The status ID within the filter that was matched.\
56 | **Type:** {{}} Array of String, or null\
57 | **Version history:**\
58 | 4.0.0 - added
59 |
60 | ## See also
61 |
62 | {{< page-relref ref="api/guidelines#filters" caption="Implementation guidelines for filters" >}}
63 |
64 | {{< page-relref ref="methods/filters" caption="/api/v2/filters methods" >}}
65 |
66 | {{< 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" >}}
67 |
--------------------------------------------------------------------------------
/content/en/entities/FilterStatus.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: FilterStatus
3 | description: Represents a status ID that, if matched, should cause the filter action to be taken.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/filterstatus",
9 | "/entities/FilterStatus",
10 | "/api/entities/filterstatus",
11 | "/api/entities/FilterStatus",
12 | ]
13 | ---
14 |
15 | ## Example
16 |
17 | ```json
18 | {
19 | "id": "1",
20 | "status_id": "109031743575371913"
21 | }
22 | ```
23 |
24 | ## Attributes
25 |
26 | ### `id` {#id}
27 |
28 | **Description:** The ID of the FilterStatus in the database.\
29 | **Type:** String (cast from an integer, but not guaranteed to be a number)\
30 | **Version history:**\
31 | 4.0.0 - added
32 |
33 | ### `status_id` {#keyword}
34 |
35 | **Description:** The ID of the Status that will be filtered.\
36 | **Type:** String (cast from an integer, but not guaranteed to be a number)\
37 | **Version history:**\
38 | 4.0.0 - added
39 |
40 | ## See also
41 |
42 | {{< page-relref ref="api/guidelines#filters" caption="Implementation guidelines for filters" >}}
43 |
44 | {{< page-relref ref="methods/filters" caption="/api/v2/filters methods" >}}
45 |
46 | {{< 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" >}}
--------------------------------------------------------------------------------
/content/en/entities/IdentityProof.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: IdentityProof
3 | description: Represents a proof from an external identity provider.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/identityproof",
9 | "/entities/IdentityProof",
10 | "/api/entities/identityproof",
11 | "/api/entities/IdentityProof",
12 | ]
13 | ---
14 |
15 | {{< hint style="danger" >}}
16 | 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.
17 | {{< /hint >}}
18 |
19 | ```json
20 | {
21 | "provider": "Keybase",
22 | "provider_username": "gargron",
23 | "updated_at": "2019-07-21T20:14:39.596Z",
24 | "proof_url": "https://keybase.io/gargron/sigchain#5cfc20c7018f2beefb42a68836da59a792e55daa4d118498c9b1898de7e845690f",
25 | "profile_url": "https://keybase.io/gargron"
26 | }
27 | ```
28 |
29 | ## Attributes
30 |
31 | ### `provider` {#provider}
32 |
33 | **Description:** The name of the identity provider.\
34 | **Type:** String\
35 | **Version history:**\
36 | 2.8.0 - added
37 |
38 | ### `provider_username` {#provider_username}
39 |
40 | **Description:** The account owner's username on the identity provider's service.\
41 | **Type:** String\
42 | **Version history:**\
43 | 2.8.0 - added
44 |
45 | ### `updated_at` {#updated_at}
46 |
47 | **Description:** When the identity proof was last updated.\
48 | **Type:** String ([Datetime](/api/datetime-format#datetime))\
49 | **Version history:**\
50 | 2.8.0 - added
51 |
52 | ### `proof_url` {#proof_url}
53 |
54 | **Description:** A link to a statement of identity proof, hosted by the identity provider.\
55 | **Type:** String (URL)\
56 | **Version history:**\
57 | 2.8.0 - added
58 |
59 | ### `profile_url` {#profile_url}
60 |
61 | **Description:** The account owner's profile URL on the identity provider.\
62 | **Type:** String (URL)\
63 | **Version history:**\
64 | 2.8.0 - added
65 |
66 | ## See also
67 |
68 | {{< page-relref ref="methods/accounts#identity_proofs" caption="GET /api/v1/accounts/:id/identity_proofs" >}}
69 |
70 | {{< caption-link url="https://github.com/mastodon/mastodon/pull/17045" caption="Remove Keybase integration (#17045)" >}}
71 |
72 |
73 |
74 |
75 |
76 |
--------------------------------------------------------------------------------
/content/en/entities/List.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: List
3 | description: Represents a list of some users that the authenticated user follows.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/list",
9 | "/entities/List",
10 | "/api/entities/list",
11 | "/api/entities/List",
12 | ]
13 | ---
14 |
15 | ## Example
16 |
17 | ```json
18 | {
19 | "id": "12249",
20 | "title": "Friends"
21 | }
22 | ```
23 |
24 | ## Attributes
25 |
26 | ### `id` {#id}
27 |
28 | **Description:** The internal database ID of the list.\
29 | **Type:** String (cast from an integer, but not guaranteed to be a number)\
30 | **Version history:**\
31 | 2.1.0 - added
32 |
33 | ### `title` {#title}
34 |
35 | **Description:** The user-defined title of the list.\
36 | **Type:** String\
37 | **Version history:**\
38 | 2.1.0 - added
39 |
40 | ### `replies_policy` {#replies_policy}
41 |
42 | **Description:** Which replies should be shown in the list.\
43 | **Type:** String (Enumerable oneOf)\
44 | `followed` = Show replies to any followed user\
45 | `list` = Show replies to members of the list\
46 | `none` = Show replies to no one\
47 | **Version history:**\
48 | 3.3.0 - added
49 |
50 | ## See also
51 |
52 | {{< page-relref ref="methods/accounts#lists" caption="GET /api/v1/accounts/:id/lists" >}}
53 |
54 | {{< page-relref ref="methods/lists" caption="lists API methods" >}}
55 |
56 | {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/list_serializer.rb" caption="app/serializers/rest/list_serializer.rb" >}}
57 |
58 |
59 |
60 |
--------------------------------------------------------------------------------
/content/en/entities/Marker.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Marker
3 | description: Represents the last read position within a user's timelines.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/marker",
9 | "/entities/Marker",
10 | "/api/entities/marker",
11 | "/api/entities/Marker",
12 | ]
13 | ---
14 |
15 | ## Example
16 |
17 | ```json
18 | {
19 | "last_read_id": "103194548672408537",
20 | "version": 462,
21 | "updated_at": "2019-11-24T19:39:39.337Z"
22 | }
23 | ```
24 |
25 | ## Attributes
26 |
27 | ### `last_read_id` {#last_read_id}
28 |
29 | **Description:** The ID of the most recently viewed entity.\
30 | **Type:** String (cast from integer but not guaranteed to be a number)\
31 | 3.0.0 - added
32 |
33 | ### `version` {#version}
34 |
35 | **Description:** An incrementing counter, used for locking to prevent write conflicts.\
36 | **Type:** Integer\
37 | **Version history:**\
38 | 3.0.0 - added
39 |
40 | ### `updated_at` {#updated_at}
41 |
42 | **Description:** The timestamp of when the marker was set.\
43 | **Type:** String ([Datetime](/api/datetime-format#datetime))\
44 | 3.0.0 - added
45 |
46 | ## See also
47 |
48 | {{< page-relref ref="methods/markers" caption="markers API methods" >}}
49 |
50 | {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/marker_serializer.rb" caption="app/serializers/rest/marker_serializer.rb" >}}
51 |
52 |
53 |
54 |
--------------------------------------------------------------------------------
/content/en/entities/Preferences.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Preferences
3 | description: Represents a user's preferences.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/preferences",
9 | "/entities/Preferences",
10 | "/api/entities/preferences",
11 | "/api/entities/Preferences",
12 | ]
13 | ---
14 |
15 | ## Example
16 |
17 | ```json
18 | {
19 | "posting:default:visibility": "public",
20 | "posting:default:sensitive": false,
21 | "posting:default:language": null,
22 | "reading:expand:media": "default",
23 | "reading:expand:spoilers": false
24 | }
25 | ```
26 |
27 | ## Attributes
28 |
29 | ### `posting:default:visibility` {#posting-default-visibility}
30 |
31 | **Description:** Default visibility for new posts. Equivalent to [CredentialAccount#source\[privacy\]]({{< relref "entities/Account#source-privacy" >}}).\
32 | **Type:** String (Enumerable, oneOf)\
33 | `public` = Public post\
34 | `unlisted` = Unlisted post\
35 | `private` = Followers-only post\
36 | `direct` = Direct post\
37 | **Version history:**\
38 | 2.8.0 - added
39 |
40 | ### `posting:default:sensitive` {#posting-default-sensitive}
41 |
42 | **Description:** Default sensitivity flag for new posts. Equivalent to [CredentialAccount#source\[sensitive\]]({{< relref "entities/Account#source-sensitive" >}}).\
43 | **Type:** Boolean\
44 | **Version history:**\
45 | 2.8.0 - added
46 |
47 | ### `posting:default:language` {#posting-default-language}
48 |
49 | **Description:** Default language for new posts. Equivalent to [CredentialAccount#source\[language\]]({{< relref "entities/Account#source-language" >}})\
50 | **Type:** {{}} String (ISO 639-1 language two-letter code), or null\
51 | **Version history:**\
52 | 2.8.0 - added
53 |
54 | ### `reading:expand:media` {#reading-expand-media}
55 |
56 | **Description:** Whether media attachments should be automatically displayed or blurred/hidden.\
57 | **Type:** String (Enumerable, oneOf)\
58 | `default` = Hide media marked as sensitive\
59 | `show_all` = Always show all media by default, regardless of sensitivity\
60 | `hide_all` = Always hide all media by default, regardless of sensitivity\
61 | **Version history:**\
62 | 2.8.0 - added
63 |
64 | ### `reading:expand:spoilers` {#reading-expand-spoilers}
65 |
66 | **Description:** Whether CWs should be expanded by default.\
67 | **Type:** Boolean\
68 | **Version history:**\
69 | 2.8.0 - added
70 |
71 | ## See also
72 |
73 | {{< page-relref ref="methods/preferences" caption="preferences API methods" >}}
74 |
75 | {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/preferences_serializer.rb" caption="app/serializers/rest/preferences_serializer.rb" >}}
76 |
77 |
78 |
79 |
--------------------------------------------------------------------------------
/content/en/entities/PreviewCardAuthor.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: PreviewCardAuthor
3 | description: Represents an author in a rich preview card.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/PreviewCardAuthor",
9 | ]
10 | ---
11 |
12 | ## Attributes
13 |
14 | ### `name` {#name}
15 |
16 | **Description:** The original resource author's name. Replaces the deprecated `author_name` attribute of the preview card.\
17 | **Type:** String\
18 | **Version history:**\
19 | 4.3.0 - added
20 |
21 | ### `url` {#url}
22 |
23 | **Description:** A link to the author of the original resource. Replaces the deprecated `author_url` attribute of the preview card.\
24 | **Type:** String (URL)\
25 | **Version history:**\
26 | 4.3.0 - added
27 |
28 | ### `account` {{%nullable%}} {#account}
29 |
30 | **Description:** The fediverse account of the author.\
31 | **Type:** [Account]({{< relref "entities/Account">}})\
32 | **Version history:**\
33 | 4.3.0 - added
34 |
35 | ## See also
36 |
37 | {{< page-relref ref="entities/PreviewCard#authors" caption="PreviewCard (`authors` attribute)" >}}
38 |
39 | {{< 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" >}}
40 |
--------------------------------------------------------------------------------
/content/en/entities/PrivacyPolicy.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: PrivacyPolicy
3 | description: Represents the privacy policy of the instance.
4 | menu:
5 | docs:
6 | parent: entities
7 | aliases: [
8 | "/entities/privacypolicy",
9 | "/entities/PrivacyPolicy",
10 | "/api/entities/privacypolicy",
11 | "/api/entities/PrivacyPolicy",
12 | ]
13 | ---
14 |
15 | ## Example
16 |
17 | ```json
18 | {
19 | "updated_at": "2022-10-07T00:00:00+00:00",
20 | "content": "
This privacy policy describes how example.com ("example.com", "we", "us") collects,\nprotects and uses the personally identifiable information you may provide\nthrough the example.com website or its API.
\n\n
What information do we collect?
\n\n
\n
Basic account information: If you register on this server, you may be\nasked to enter a username, an e-mail address and a password.
\n
Posts, following and other public information: The list of people you\nfollow is listed publicly, the same is true for your followers.
\n
Direct and followers-only posts: All posts are stored and processed on the\nserver. You may\ntoggle an option to approve and reject new followers manually in the settings.\nPlease keep in mind that the operators of the server and any receiving\nserver may view such messages, and that recipients may screenshot, copy or\notherwise re-share them. Do not share any sensitive information over\nMastodon.
\n
IPs and other metadata: When you log in, we record the IP address you log\nin from, as well as the name of your browser application.
{{ if (eq (.Get "style") "warning") }}{{ end }}{{ if (eq (.Get "style") "success") }}{{ end }}{{ if (eq (.Get "style") "info") }}{{ end }}{{ if (eq (.Get "style") "danger") }}{{ end }}
5 |