Commit 94e55470 authored by Marcin Mikołajczak's avatar Marcin Mikołajczak

remove non-translated files

Signed-off-by: 's avatarMarcin Mikołajczak <me@m4sk.in>
parent 1ebd819b
......@@ -13,10 +13,10 @@ enableGitInfo = true
contentDir = "content/en"
languageName = "English"
weight = 1
[languages.pl]
contentDir = "content/pl"
languageName = "Polski"
weight = 1
[languages.pl]
contentDir = "content/pl"
languageName = "Polski"
weight = 1
[menu]
[[menu.docs]]
......
This diff is collapsed.
---
title: Authentication
description: How to authenticate with OAuth 2 on Mastodon
menu:
docs:
parent: api
weight: 1
---
Mastodon is federated, therefore you can't be expected to manually register your application on all potential servers your users might want to login on. For this reason, there is an open app registration API, so obtaining OAuth 2 credentials for OAuth 2 authorization can be automated.
Make sure that you allow your users to specify the domain they want to connect to before login. Use that domain to acquire a client id/secret for OAuth 2 and then proceed with normal OAuth 2 also using that domain to build the URLs.
Mastodon supports the following OAuth 2 flows:
- **Authorization code flow**: For end-users
- **Password grant flow**: For bots and other single-user applications
- **Client credentials flow**: For applications that do not act on behalf of users
This diff is collapsed.
---
title: Guidelines
description: Guidelines that app developers for Mastodon should follow
menu:
docs:
parent: api
weight: -1
---
## Login
**The user must be able to login to any Mastodon server from the app**. This means you must ask for either the full handle, or server domain, and use the app registrations API to dynamically obtain OAuth2 credentials.
## Usernames
**Decentralization must be transparent to the user**. It should be possible to see that a given user is from another server, by e.g. displaying their `acct` (username and domain) somewhere.
## Formatting
Plain text is not available for content from remote servers, and plain text syntax rules may vary wildly between Mastodon and other fediverse applications. For certain attributes, such as the content of statuses, **Mastodon provides sanitized HTML**.
### HTML tags
You may expect these tags to appear in the content: `<p>`, `<br>`, `<span>`, `<a>`
### Mentions and hashtags
Mentions and hashtags are `<a>` tags. To give those links their semantic meaning and add special handling, such as opening a mentioned profile within your app instead of as a web page, metadata is included with the status, which can be matched to a particular tag.
### Custom emoji
Custom emoji remain in their plain text shortcode form. Metadata about the determined custom emoji is included with the status, and the shortcodes must be matched against the text to display the images.
### Other links
Links in Mastodon are not shortened using URL shorteners. However, URLs in text always count for 23 characters, and are intended to be shortened visually. For that purpose, a link is marked up like this:
```html
<a href="https://example.com/page/that/is/very/long">
<span class="invisible">https://</span>
<span class="ellipsis">example.com/page</span>
<span class="invisible">/that/is/very/long</span>
</a>
```
The spans with the `invisible` class can be hidden. The middle span is intended to remain visible. It may have no class if the URL is not very long, otherwise it will have an `ellipsis` class. No ellipsis (`…`) character is inserted in the markup, instead, you are expected to insert it yourself if you need it in your app.
## Filters
Clients must do their own text filtering based on filters returned from the API. The server will apply `irreversible` filters for home and notifications context, but anything else is still up to the client to filter!
Expired filters are not deleted by the server. They should no longer be applied but they are still stored by the server. It is up to clients to delete those filters eventually.
---
title: Libraries
description: List of libraries that work with the Mastodon API in various programming languages
menu:
docs:
parent: api
weight: -1
---
## Apex (Salesforce)
- [apex-mastodon](https://github.com/tzmfreedom/apex-mastodon)
## C# (.NET Standard)
- [Mastodot](https://github.com/yamachu/Mastodot)
- [Mastonet](https://github.com/glacasa/Mastonet)
- [TootNet](https://github.com/cucmberium/TootNet)
- [mastodon-api-cs](https://github.com/pawotter/mastodon-api-cs)
- [Mastodon.Net](https://github.com/Tlaster/Mastodon.Net)
## C++
- [mastodon-cpp](https://github.com/tastytea/mastodon-cpp)
## Crystal
- [mastodon.cr](https://github.com/decors/mastodon.cr)
## Common Lisp
- [tooter](https://github.com/Shinmera/tooter)
## Elixir
- [hunter](https://github.com/milmazz/hunter)
## Go
- [go-mastodon](https://github.com/mattn/go-mastodon)
- [madon](https://github.com/McKael/madon)
## Haskell
- [hastodon](https://github.com/syucream/hastodon)
## Java
- [mastodon4j](https://github.com/sys1yagi/mastodon4j)
## JavaScript
- [libodonjs](https://github.com/Zatnosk/libodonjs)
## JavaScript (Browser)
- [mastodon.js](https://github.com/Kirschn/mastodon.js)
## JavaScript (Node.js)
- [node-mastodon](https://github.com/jessicahayley/node-mastodon)
- [mastodon-api](https://github.com/vanita5/mastodon-api)
## Perl
- [Mastodon::Client](https://metacpan.org/pod/Mastodon::Client)
## PHP
- [Mastodon API for Laravel](https://github.com/kawax/laravel-mastodon-api)
- [Mastodon-api-php](https://github.com/yks118/Mastodon-api-php)
- [Composer based php API wrapper](https://github.com/r-daneelolivaw/mastodon-api-php)
- [MastodonOAuthPHP](https://github.com/TheCodingCompany/MastodonOAuthPHP)
- [Phediverse Mastodon REST Client](https://github.com/phediverse/mastodon-rest)
- [TootoPHP](https://framagit.org/MaxKoder/TootoPHP)
- [oauth2-mastodon](https://github.com/lrf141/oauth2-mastodon)
- [Mastodon Wordpress API](https://github.com/L1am0/mastodon_wordpress_api)
## Python
- [Mastodon.py](https://github.com/halcy/Mastodon.py)
## R
- [mastodon](https://github.com/ThomasChln/mastodon)
## Ruby
- [mastodon-api](https://github.com/tootsuite/mastodon-api)
## Rust
- [mammut](https://github.com/Aaronepower/mammut)
- [elefren](https://github.com/pwoolcoc/elefren)
## Scala
- [scaladon](https://github.com/schwitzerm/scaladon)
## Swift
- [MastodonKit](https://github.com/ornithocoder/MastodonKit)
---
title: Parameters
description: Specifics of parameter passing to the Mastodon API
menu:
docs:
parent: api
weight: 3
---
## Parameter format
Query strings, form data, and JSON submitted via POST body is equally understood by the API. It is expected that query strings are used for GET requests, and form data or JSON is used for all other requests.
## Arrays
An array parameter must encoded using bracket notation, e.g. `array[0]=foo&array[1]=bar` would be translated into:
```ruby
array = [
'foo',
'bar',
]
```
## Booleans
A boolean value is considered false for the values `0`, `f`, `F`, `false`, `FALSE`, `off`, `OFF`, considered to not be provided for empty strings, and considered to be true for all other values.
## Files
File uploads must be encoded using `multipart/form-data`.
## Nested parameters
Some parameters need to be nested. For that, bracket notation must also be used. For example, `source[privacy]=public&source[language]=en` would be translated into:
```ruby
source = {
privacy: 'public',
language: 'en',
}
```
This can be combined with arrays as well.
---
title: Permissions
description: Overview of OAuth 2 access scopes in Mastodon
menu:
docs:
parent: api
weight: 2
---
The API is divided up into access scopes:
|Scope|Parent(s)|Added in|
|:----|---------|:------:|
|`write`||0.9.0|
|`write:accounts`|`write`|2.4.3|
|`write:blocks`|`write`, `follow`|2.4.3|
|`write:favourites`|`write`|2.4.3|
|`write:filters`|`write`|2.4.3|
|`write:follows`|`write`, `follow`|2.4.3|
|`write:lists`|`write`|2.4.3|
|`write:media`|`write`|2.4.3|
|`write:mutes`|`write`, `follow`|2.4.3|
|`write:notifications`|`write`|2.4.3|
|`write:reports`|`write`|2.4.3|
|`write:statuses`|`write`|2.4.3|
|`read`||0.9.0|
|`read:accounts`|`read`|2.4.3|
|`read:blocks`|`read`, `follow`|2.4.3|
|`read:favourites`|`read`|2.4.3|
|`read:filters`|`read`|2.4.3|
|`read:follows`|`read`, `follow`|2.4.3|
|`read:lists`|`read`|2.4.3|
|`read:mutes`|`read`, `follow`|2.4.3|
|`read:notifications`|`read`|2.4.3|
|`read:reports`|`read`|2.4.3|
|`read:search`|`read`|2.4.3|
|`read:statuses`|`read`|2.4.3|
|`follow`||0.9.0|
|`push`||2.4.0|
The scopes are hierarchical, i.e. if you have access to `read`, you automatically have access to `read:accounts`. **It is recommended that you request as little as possible for your application.**
Multiple scopes can be requested at the same time: During app creation with the `scopes` param, and during the authorization phase with the `scope` query param (space-separate the scopes).
> **Note:** Mind the `scope` vs `scopes` difference. This is because `scope` is a standard OAuth parameter name, so it is used in the OAuth methods. Mastodon's own REST API uses the more appropriate `scopes`.
If you do not specify a `scope` in your authorization request, or a `scopes` in your app creation request, the resulting access token / app will default to `read` access.
The set of scopes saved during app creation must include all the scopes that you will request in the authorization request, otherwise authorization will fail.
---
title: Web Push API
overview: How to use the Web Push API in Mastodon to receive push notifications in a native or browser app
menu:
docs:
parent: api
weight: 5
---
Mastodon natively supports the [Web Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API). You can utilize the same mechanisms for your native app. It requires running a proxy server that connects to Android's and Apple's proprietary notification gateways. However, the proxy server does not have access to the contents of the notifications. For a reference, see [Mozilla's web push server](https://github.com/mozilla-services/autopush), or more practically, see:
- [toot-relay](https://github.com/DagAgren/toot-relay)
- [PushToFCM](https://github.com/tateisu/PushToFCM)
Using the Web Push API requires your app to have the `push` scope. To create a new Web Push API subscription, use [POST /api/v1/push/subscription]({{< relref "notifications.md#post-api-v1-push-subscription" >}}).
---
title: Accounts
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/accounts/:id
Returns [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="No" user="No" scope="read read:accounts" version="0.0.0" >}}
## GET /api/v1/accounts/verify_credentials
User's own account.
Returns [Account]({{< relref "entities.md#account" >}}) with an extra [`source` attribute]({{< relref "entities.md#source" >}}).
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:accounts" version="0.0.0" >}}
## PATCH /api/v1/accounts/update_credentials
Update user's own account.
Returns [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="0.0.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `display_name` | Display name | Optional |
| `note` | Biography | Optional |
| `avatar` | Avatar encoded using `multipart/form-data` | Optional |
| `header` | Header image encoded using `multipart/form-data` | Optional |
| `locked` | Enable follow requests | Optional |
| `source[privacy]` | Default post privacy preference | Optional |
| `source[sensitive]`| Whether to mark statuses as sensitive by default | Optional |
| `source[language]` | Override language on statuses by default (ISO6391) | Optional |
| `fields_attributes` | Profile metadata (max. 4) | Optional |
## GET /api/v1/accounts/:id/followers
Accounts which follow the given account.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="No" scope="read read:accounts" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 40 |
### Pagination
{{< api_pagination >}}
## GET /api/v1/accounts/:id/following
Accounts which the given account is following.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="No" scope="read read:accounts" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 40 |
### Pagination
{{< api_pagination >}}
## GET /api/v1/accounts/:id/statuses
An account's statuses.
Returns array of [Status]({{< relref "entities.md#status" >}})
### Resource information
{{< api_method_info auth="Yes" user="No" scope="read read:statuses" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `only_media` | Only return statuses that have media attachments | Optional |false|
| `pinned` | Only return statuses that have been pinned | Optional |false|
| `exclude_replies` | Skip statuses that reply to other statuses | Optional |false|
| `max_id` | Return results older than ID | Optional ||
| `since_id` | Return results newer than ID | Optional ||
| `min_id` | Return results immediately newer than ID | Optional ||
| `limit` | Maximum number of results | Optional | 20 |
### Pagination
{{< api_dynamic_pagination >}}
## POST /api/v1/accounts/:id/follow
Follow an account.
Returns [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write:follows follow" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `reblogs` | Whether the followed account's reblogs will show up in the home timeline | Optional | true |
## POST /api/v1/accounts/:id/unfollow
Unfollow an account.
Returns [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write:follows follow" version="0.0.0" >}}
## GET /api/v1/accounts/relationships
Relationship of the user to the given accounts in regards to following, blocking, muting, etc.
Returns array of [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:follows" version="0.0.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `id` | Array of account IDs | Required |
## GET /api/v1/accounts/search
Search for matching accounts by username, domain and display name.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:accounts" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `q` | What to search for | Required ||
| `limit` | Maximum number of results | Optional | 40 |
| `resolve` | Attempt WebFinger look-up | Optional | false |
| `following` | Only who the user is following | Optional | false |
---
title: Apps
menu:
docs:
parent: rest-api
weight: 10
---
## POST /api/v1/apps
Create a new application to obtain OAuth2 credentials.
Returns [App]({{< relref "entities.md#app" >}}) with `client_id` and `client_secret`
### Resource information
{{< api_method_info auth="No" user="No" version="0.0.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `client_name` | Name of your application | Required |
| `redirect_uris` | Where the user should be redirected after authorization | Required |
| `scopes` | Space separated list of [scopes]({{< relref "permissions.md" >}}) | Required |
| `website` | URL to the homepage of your app | Optional |
> To display the authorization code to the end-user instead of redirecting to a web page, use `urn:ietf:wg:oauth:2.0:oob` in `redirect_uris`
## GET /api/v1/apps/verify_credentials
Confirm that the app's OAuth2 credentials work.
Returns [App]({{< relref "entities.md#app" >}})
### Resource information
{{< api_method_info auth="Yes" user="No" version="0.0.0" >}}
---
title: Blocks
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/blocks
Accounts the user has blocked.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read:blocks follow" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 40 |
### Pagination
{{< api_pagination >}}
## POST /api/v1/accounts/:id/block
Block an account.
Returns [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write:blocks follow" version="0.0.0" >}}
## POST /api/v1/accounts/:id/unblock
Unblock an account.
Returns [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write:blocks follow" version="0.0.0" >}}
---
title: Custom emoji
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/custom_emojis
Custom emojis that are available on the server.
Returns array of [Emoji]({{< relref "entities.md#emoji" >}})
### Resource information
{{< api_method_info auth="No" user="No" version="0.0.0" >}}
---
title: Domain blocks
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/domain_blocks
Domains the user has blocked.
Returns array of string.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:blocks follow" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 40 |
### Pagination
{{< api_pagination >}}
## POST /api/v1/domain_blocks
Block a domain to hide all public posts from it, all notifications from it, and remove all followers from it.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:blocks follow" version="0.0.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `domain` | Domain to block| Required |
## DELETE /api/v1/domain_blocks
Remove a domain block.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:blocks follow" version="0.0.0" >}}
### Parameters
|Name|Description|Required|
|----|-----------|:------:|
| `domain` | Domain to unblock| Required |
---
title: Endorsements
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/endorsements
Accounts the user chose to endorse.
Returns array of [Account]({{< relref "entities.md#account" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:account" version="0.0.0" >}}
### Pagination
{{< api_pagination >}}
## POST /api/v1/accounts/:id/pin
Endorse an account, i.e. choose to feature the account on the user's public profile.
Returns [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="0.0.0" >}}
## POST /api/v1/accounts/:id/unpin
Undo endorse of an account.
Returns [Relationship]({{< relref "entities.md#relationship" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="0.0.0" >}}
---
title: Favourites
menu:
docs:
parent: rest-api
weight: 10
---
## GET /api/v1/favourites
Statuses the user has favourited.
Returns array of [Status]({{< relref "entities.md#status" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:favourites" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 20 |
### Pagination
{{< api_pagination >}}
## POST /api/v1/statuses/:id/favourite
Favourite a status.
Returns [Status]({{< relref "entities.md#status" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:favourites" version="0.0.0" >}}
## POST /api/v1/statuses/:id/unfavourite
Undo the favourite of a status.
Returns [Status]({{< relref "entities.md#status" >}})
---
title: Filters
menu:
docs:
parent: rest-api
weight: 10
---