Mastodon logo
API docs by Redocly

Mastodon API (4.4.0)

Download OpenAPI specification:

License: GFDL-1.3

Unofficial documentation for the Mastodon API. Generated with mastodon-openapi from 0e8dbc3.

Official Mastodon API documentation

accounts

Register an account

Creates a user and account records. Returns an account access token for the app that initiated the request. The app should save this token for later, and should wait for the user to confirm their account by clicking a link in their email inbox.

Version history:

2.7.0 - added
3.0.0 - added reason parameter
3.4.0 - added details to failure response
4.4.0 - added date_of_birth parameter

Official Mastodon API documentation
Authorizations:
OAuth2ClientCredentials
Request Body schema: application/json
required

JSON request body parameters

agreement
required
boolean

Whether the user agrees to the local rules, terms, and policies. These should be presented to the user in order to allow them to consent before setting this parameter to TRUE.

email
required
string

The email address to be used for login

locale
required
string

The language of the confirmation email that will be sent.

password
required
string

The password to be used for login

username
required
string

The desired username for the account

date_of_birth
string <date>

String ([Date]), required if the server has a minimum age requirement.

reason
string

If registrations require manual approval, this text will be reviewed by moderators.

Responses

Request samples

Content type
application/json
{
  • "agreement": true,
  • "email": "string",
  • "locale": "string",
  • "password": "string",
  • "username": "string",
  • "date_of_birth": "2019-08-24",
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "ZA-Yj3aBD8U8Cm7lKUp-lm9O9BmDgdhHzDeqsY8tlL0",
  • "token_type": "Bearer",
  • "scope": "read write follow push",
  • "created_at": 1573979017
}

Get multiple accounts

View information about multiple profiles.

Version history:

4.3.0 - added

Official Mastodon API documentation
query Parameters
id
Array of strings

The IDs of the accounts.

Responses

Response samples

Content type
application/json
[]

Get account

View information about a profile.

Version history:

0.0.0 - added
2.4.0 - returns 410 if account is suspended
3.3.0 - returns an Account with suspended: true instead of 410

Official Mastodon API documentation
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[]

Block account

[Blocks]({{< relref "user/moderating#block">}}) the given account.

Version history:

0.0.0 - added
3.5.0 - deprecated follow scope. now additionally accepts write

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "id": "3",
  • "following": false,
  • "showing_reblogs": false,
  • "notifying": false,
  • "followed_by": false,
  • "blocking": true,
  • "blocked_by": false,
  • "muting": false,
  • "muting_notifications": false,
  • "requested": false,
  • "domain_blocking": false,
  • "endorsed": false
}

Feature account on your profile

Add the given account to the user's featured profiles.

Version history:

4.4.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "id": "3",
  • "following": false,
  • "showing_reblogs": false,
  • "notifying": false,
  • "followed_by": false,
  • "blocking": true,
  • "blocked_by": false,
  • "muting": false,
  • "muting_notifications": false,
  • "requested": false,
  • "domain_blocking": false,
  • "endorsed": false
}

Get featured accounts

Accounts that the user is currently featuring on their profile.

Version history:

4.4.0 - added

Official Mastodon API documentation
path Parameters
id
required
string

id parameter

query Parameters
limit
integer
Default: 40

Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.

max_id
string

Internal parameter. Use HTTP Link header for pagination.

since_id
string

Internal parameter. Use HTTP Link header for pagination.

Responses

Response samples

Content type
application/json
[]

Get account's featured tags

Tags featured by this account.

Version history:

3.3.0 - added

Official Mastodon API documentation
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Follow account

Follow the given account. Can also be used to update whether to show reblogs or enable notifications.

Version history:

0.0.0 - added
3.3.0 - added notify
3.5.0 - deprecated follow scope. now additionally accepts write
4.0.0 - added languages

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Request Body schema: application/json
optional

JSON request body parameters

languages
Array of strings

Array of String (ISO 639-1 language two-letter code). Filter received statuses for these languages. If not provided, you will receive this account's posts in all languages.

notify
boolean
Default: false

Receive notifications when this account posts a status? Defaults to false.

reblogs
boolean
Default: true

Receive this account's reblogs in home timeline? Defaults to true.

Responses

Request samples

Content type
application/json
{
  • "languages": [
    ],
  • "notify": false,
  • "reblogs": true
}

Response samples

Content type
application/json
{
  • "id": "3",
  • "following": false,
  • "showing_reblogs": false,
  • "notifying": false,
  • "followed_by": false,
  • "blocking": true,
  • "blocked_by": false,
  • "muting": false,
  • "muting_notifications": false,
  • "requested": false,
  • "domain_blocking": false,
  • "endorsed": false
}

Get account's followers

Accounts which follow the given account, if network is not hidden by the account owner.

Version history:

0.0.0 - added
3.3.0 - both min_id and max_id can be used at the same time now
4.0.0 - no longer requires an app token + read:accounts

Official Mastodon API documentation
path Parameters
id
required
string

id parameter

query Parameters
limit
integer
Default: 40

Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.

max_id
string

Internal parameter. Use HTTP Link header for pagination.

min_id
string

Internal parameter. Use HTTP Link header for pagination.

since_id
string

Internal parameter. Use HTTP Link header for pagination.

Responses

Response samples

Content type
application/json
[]

Get account's following

Accounts which the given account is following, if network is not hidden by the account owner.

Version history:

0.0.0 - added
3.3.0 - both min_id and max_id can be used at the same time now
4.0.0 - no longer requires an app token + read:accounts

Official Mastodon API documentation
path Parameters
id
required
string

id parameter

query Parameters
limit
integer
Default: 40

Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.

max_id
string

Internal parameter. Use HTTP Link header for pagination.

min_id
string

Internal parameter. Use HTTP Link header for pagination.

since_id
string

Internal parameter. Use HTTP Link header for pagination.

Responses

Response samples

Content type
application/json
[]

Identity proofs Deprecated

Version history:

2.8.0 - added
3.5.0 - deprecated. now returns an empty array.

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[]

Get lists containing this account

User lists that you have added this account to.

Version history:

2.1.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Mute account

Mute the given account. Clients should filter statuses and notifications from this account, if received (e.g. due to a boost in the Home timeline).

Version history:

0.0.0 - added
3.3.0 - added duration
3.5.0 - deprecated follow scope. now additionally accepts write

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Request Body schema: application/json
optional

JSON request body parameters

duration
integer
Default: 0

How long the mute should last, in seconds. Defaults to 0 (indefinite).

notifications
boolean
Default: true

Mute notifications in addition to statuses? Defaults to true.

Responses

Request samples

Content type
application/json
{
  • "duration": 0,
  • "notifications": true
}

Response samples

Content type
application/json
{
  • "id": "3",
  • "following": false,
  • "showing_reblogs": false,
  • "notifying": false,
  • "followed_by": false,
  • "blocking": true,
  • "blocked_by": false,
  • "muting": false,
  • "muting_notifications": false,
  • "requested": false,
  • "domain_blocking": false,
  • "endorsed": false
}

Set private note on profile

Sets a private note on a user.

Version history:

3.2.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Request Body schema: application/json
optional

JSON request body parameters

comment
string

The comment to be set on that user. Provide an empty string or leave out this parameter to clear the currently set note.

Responses

Request samples

Content type
application/json
{
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "id": "3",
  • "following": false,
  • "showing_reblogs": false,
  • "notifying": false,
  • "followed_by": false,
  • "blocking": true,
  • "blocked_by": false,
  • "muting": false,
  • "muting_notifications": false,
  • "requested": false,
  • "domain_blocking": false,
  • "endorsed": false
}

Feature account on your profile Deprecated

Add the given account to the user's featured profiles. (Featured profiles are currently shown on the user's own public profile.)

Version history:

2.5.0 - added
4.0.0 - calling this method is now idempotent
4.4.0 - deprecated in favor of /api/v1/accounts/:id/endorse

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "id": "3",
  • "following": false,
  • "showing_reblogs": false,
  • "notifying": false,
  • "followed_by": false,
  • "blocking": true,
  • "blocked_by": false,
  • "muting": false,
  • "muting_notifications": false,
  • "requested": false,
  • "domain_blocking": false,
  • "endorsed": false
}

Remove account from followers

Remove the given account from your followers.

Version history:

3.5.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "id": "3",
  • "following": false,
  • "showing_reblogs": false,
  • "notifying": false,
  • "followed_by": false,
  • "blocking": true,
  • "blocked_by": false,
  • "muting": false,
  • "muting_notifications": false,
  • "requested": false,
  • "domain_blocking": false,
  • "endorsed": false
}

Get account's statuses

Statuses posted to the given account.

Version history:

0.0.0 - added
1.4.2 - add only_media and exclude_replies
1.6.0 - add pinned
2.6.0 - add min_id
2.7.0 - add exclude_reblogs and allow unauthed use
2.8.0 - add tagged parameter
3.3.0 - both min_id and max_id can be used at the same time now

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

query Parameters
exclude_reblogs
boolean

Filter out boosts from the response.

exclude_replies
boolean

Filter out statuses in reply to a different account.

limit
integer
Default: 20

Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.

max_id
string

All results returned will be lesser than this ID. In effect, sets an upper bound on results.

min_id
string

Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.

only_media
boolean

Filter out statuses without attachments.

pinned
boolean

Filter for pinned statuses only. Defaults to false, which includes all statuses. Pinned statuses do not receive special priority in the order of the returned results.

since_id
string

All results returned will be greater than this ID. In effect, sets a lower bound on results.

tagged
string

Filter for statuses using a specific hashtag.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Unblock account

Unblock the given account.

Version history:

0.0.0 - added
3.5.0 - deprecated follow scope. now additionally accepts write

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "id": "3",
  • "following": false,
  • "showing_reblogs": false,
  • "notifying": false,
  • "followed_by": false,
  • "blocking": true,
  • "blocked_by": false,
  • "muting": false,
  • "muting_notifications": false,
  • "requested": false,
  • "domain_blocking": false,
  • "endorsed": false
}

Unfeature account from profile

Remove the given account from the user's featured profiles.

Version history:

4.4.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "id": "3",
  • "following": false,
  • "showing_reblogs": false,
  • "notifying": false,
  • "followed_by": false,
  • "blocking": true,
  • "blocked_by": false,
  • "muting": false,
  • "muting_notifications": false,
  • "requested": false,
  • "domain_blocking": false,
  • "endorsed": false
}

Unfollow account

Unfollow the given account.

Version history:

0.0.0 - added
3.5.0 - deprecated follow scope. now additionally accepts write

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "id": "3",
  • "following": false,
  • "showing_reblogs": false,
  • "notifying": false,
  • "followed_by": false,
  • "blocking": true,
  • "blocked_by": false,
  • "muting": false,
  • "muting_notifications": false,
  • "requested": false,
  • "domain_blocking": false,
  • "endorsed": false
}

Unmute account

Unmute the given account.

Version history:

0.0.0 - added
3.5.0 - deprecated follow scope. now additionally accepts write

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "id": "3",
  • "following": false,
  • "showing_reblogs": false,
  • "notifying": false,
  • "followed_by": false,
  • "blocking": true,
  • "blocked_by": false,
  • "muting": false,
  • "muting_notifications": false,
  • "requested": false,
  • "domain_blocking": false,
  • "endorsed": false
}

Unfeature account from profile Deprecated

Remove the given account from the user's featured profiles.

Version history:

2.5.0 - added
4.4.0 - deprecated in favor of /api/v1/accounts/:id/unendorse

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "id": "3",
  • "following": false,
  • "showing_reblogs": false,
  • "notifying": false,
  • "followed_by": false,
  • "blocking": true,
  • "blocked_by": false,
  • "muting": false,
  • "muting_notifications": false,
  • "requested": false,
  • "domain_blocking": false,
  • "endorsed": false
}

Find familiar followers

Obtain a list of all accounts that follow a given account, filtered for accounts you follow.

Version history:

3.5.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
id
Array of strings

Find familiar followers for the provided account IDs.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Lookup account ID from Webfinger address

Quickly lookup a username to see if it is available, skipping WebFinger resolution.

Version history:

3.4.0 - added

Official Mastodon API documentation
query Parameters
acct
required
string

The username or Webfinger address to lookup.

Responses

Response samples

Content type
application/json
[]

Check relationships to other accounts

Find out whether a given account is followed, blocked, muted, etc.

Version history:

0.0.0 - added
4.3.0 - added with_suspended parameter

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
id
Array of strings

Check relationships for the provided account IDs.

with_suspended
boolean
Default: false

Whether relationships should be returned for suspended users, defaults to false.

Responses

Response samples

Content type
application/json
{
  • "id": "3",
  • "following": false,
  • "showing_reblogs": false,
  • "notifying": false,
  • "followed_by": false,
  • "blocking": true,
  • "blocked_by": false,
  • "muting": false,
  • "muting_notifications": false,
  • "requested": false,
  • "domain_blocking": false,
  • "endorsed": false
}

Search for matching accounts

Search for matching accounts by username or display name.

Version history:

0.0.0 - added
2.8.0 - add limit, offset and following

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
q
required
string

Search query for accounts.

following
boolean
Default: false

Limit the search to users you are following. Defaults to false.

limit
integer
Default: 40

Maximum number of results. Defaults to 40 accounts. Max 80 accounts.

offset
integer

Skip the first n results.

resolve
boolean
Default: false

Attempt WebFinger lookup. Defaults to false. Use this when q is an exact address.

Responses

Response samples

Content type
application/json
[]

Update account credentials

Update the user's display and preferences.

Version history:

1.1.1 - added
2.3.0 - added locked parameter
2.4.0 - added source[privacy,sensitive] parameters
2.4.2 - added source[language] parameter
2.7.0 - added discoverable parameter
4.1.0 - added hide_collections parameter
4.2.0 - added indexable parameter
4.4.0 (mastodon [API version] 3) - added attribution_domains parameter

Official Mastodon API documentation
Authorizations:
OAuth2
Request Body schema: application/json
optional

JSON request body parameters

attribution_domains
Array of strings

Domains of websites allowed to credit the account.

avatar
string

Avatar image encoded using multipart/form-data

bot
boolean

Whether the account has a bot flag.

discoverable
boolean

Whether the account should be shown in the profile directory.

display_name
string

The display name to use for the profile.

fields_attributes
object

The profile fields to be set. Inside this hash, the key is an integer cast to a string (although the exact integer does not matter), and the value is another hash including name and value. By default, max 4 fields.

header
string

Header image encoded using multipart/form-data

hide_collections
boolean

Whether to hide followers and followed accounts.

indexable
boolean

Whether public posts should be searchable to anyone.

locked
boolean

Whether manual approval of follow requests is required.

note
string

The account bio.

object

Object containing properties

Responses

Request samples

Content type
application/json
{
  • "attribution_domains": [
    ],
  • "avatar": "string",
  • "bot": true,
  • "discoverable": true,
  • "display_name": "string",
  • "fields_attributes": { },
  • "header": "string",
  • "hide_collections": true,
  • "indexable": true,
  • "locked": true,
  • "note": "string",
  • "source": {
    }
}

Response samples

Content type
application/json
{}

Verify account credentials

Test to make sure that the user token works.

Version history:

0.0.0 - added
4.3.0 - added profile scope

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{}

announcements

View all announcements

See all currently active announcements set by admins.

Version history:

3.1.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[]

Dismiss an announcement

Allows a user to mark the announcement as read.

Version history:

3.1.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Add a reaction to an announcement

React to an announcement with an emoji.

Version history:

3.1.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

name
required
string

name parameter

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Remove a reaction from an announcement

Undo a react emoji to an announcement.

Version history:

3.1.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

name
required
string

name parameter

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

apps

Create an application

Create a new application to obtain OAuth2 credentials.

Version history:

0.0.0 - added
2.7.2 - now returns vapid_key
4.3.0 - deprecated vapid_key, please see [api/v2/instance]
4.3.0 - added support for multiple redirect_uris in Form data parameters
4.3.0 - added redirect_uris response property
4.3.0 - deprecated redirect_uri response property, since this can be a non-URI if multiple redirect_uris are registered, use redirect_uris instead
4.3.0 - changed entity type from [Application] to [CredentialApplication]

Official Mastodon API documentation
Request Body schema: application/json
required

JSON request body parameters

client_name
required
string

A name for your application

redirect_uris
required
Array of strings <uri> [ items <uri > ]

Where the user should be redirected after authorization. To display the authorization code to the user instead of redirecting to a web page, use urn:ietf:wg:oauth:2.0:oob in this parameter.

scopes
string <scopes>
Default: "read"

Space separated list of scopes. If none is provided, defaults to read. See [OAuth Scopes] for a list of possible scopes.

website
string

A URL to the homepage of your app

Responses

Request samples

Content type
application/json
{
  • "client_name": "string",
  • "redirect_uris": [],
  • "scopes": "read",
  • "website": "string"
}

Response samples

Content type
application/json
{
  • "id": "563419",
  • "name": "Test Application",
  • "website": "https://app.example",
  • "scopes": [
    ],
  • "redirect_uri": "urn:ietf:wg:oauth:2.0:oob",
  • "redirect_uris": [
    ],
  • "client_id": "TWhM-tNSuncnqN7DBJmoyeLnk6K3iJJ71KKXxgL1hPM",
  • "client_secret": "ZEaFUFmF0umgBX1qKJDjaU99Q31lDkOU8NutzTOoliw"
}

Verify your app works

Confirm that the app's OAuth2 credentials work.

Version history:

2.0.0 - added
2.7.2 - now returns vapid_key
4.3.0 - deprecated vapid_key, please see [api/v2/instance]
4.3.0 - removed needing read scope to access this API, now any valid App token can be used
4.3.0 - added scopes and redirect_uris properties

Official Mastodon API documentation
Authorizations:
OAuth2ClientCredentials

Responses

Response samples

Content type
application/json
{}

blocks

View blocked users

Returns your blocked accounts.

Version history:

0.0.0 - added
3.3.0 - both min_id and max_id can be used at the same time now

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
limit
integer
Default: 40

Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.

max_id
string

Internal parameter. Use HTTP Link header for pagination.

min_id
string

Internal parameter. Use HTTP Link header for pagination.

since_id
string

Internal parameter. Use HTTP Link header for pagination.

Responses

Response samples

Content type
application/json
[]

bookmarks

View bookmarked statuses

Statuses the user has bookmarked.

Version history:

3.1.0 - added
3.3.0 - both min_id and max_id can be used at the same time now

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
limit
integer
Default: 20

Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.

max_id
string

Internal parameter. Use HTTP Link header for pagination.

min_id
string

Internal parameter. Use HTTP Link header for pagination.

since_id
string

Internal parameter. Use HTTP Link header for pagination.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

conversations

View all conversations

Version history:

2.6.0 - added
3.3.0 - both min_id and max_id can be used at the same time now

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
limit
integer
Default: 20

Maximum number of results to return. Defaults to 20 conversations. Max 40 conversations.

max_id
string

Internal parameter. Use HTTP Link header for pagination.

min_id
string

Internal parameter. Use HTTP Link header for pagination.

since_id
string

Internal parameter. Use HTTP Link header for pagination.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Remove a conversation

Removes a conversation from your list of conversations.

Version history:

2.6.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Mark a conversation as read

Version history:

2.6.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

custom_emojis

View all custom emoji

Returns custom emojis that are available on the server.

Version history:

2.0.0 - added
3.0.0 - optional category added to response

Official Mastodon API documentation

Responses

Response samples

Content type
application/json
[]

directory

View profile directory

List accounts visible in the directory.

Version history:

3.0.0 - added

Official Mastodon API documentation
query Parameters
limit
integer
Default: 40

How many accounts to load. Defaults to 40 accounts. Max 80 accounts.

local
boolean

If true, returns only local accounts.

offset
integer

Skip the first n results.

order
string

Use active to sort by most recently posted statuses (default) or new to sort by most recently created profiles.

Responses

Response samples

Content type
application/json
[]

domain_blocks

Get domain blocks

View domains the user has blocked.

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
limit
integer
Default: 100

Maximum number of results to return. Defaults to 100 domain blocks. Max 200 domain blocks.

max_id
string

Internal parameter. Use HTTP Link header for pagination.

min_id
string

Internal parameter. Use HTTP Link header for pagination.

since_id
string

Internal parameter. Use HTTP Link header for pagination.

Responses

Response samples

Content type
application/json
[
  • "nsfw.social",
  • "artalley.social"
]

Block a domain

Block a domain to:

Official Mastodon API documentation
Authorizations:
OAuth2
Request Body schema: application/json
required

JSON request body parameters

domain
required
string

Domain to block.

Responses

Request samples

Content type
application/json
{
  • "domain": "string"
}

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Unblock a domain

Remove a domain block, if it exists in the user's array of blocked domains.

Version history:

1.4.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
Request Body schema: application/json
required

JSON request body parameters

domain
required
string

Domain to unblock.

Responses

Request samples

Content type
application/json
{
  • "domain": "string"
}

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

emails

Resend confirmation email

Resend a new confirmation email. If an email is provided, updates the unconfirmed user's email before resending the confirmation email.

Version history:

3.4.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
Request Body schema: application/json
optional

JSON request body parameters

email
string

If provided, updates the unconfirmed user's email before resending the confirmation email.

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

endorsements

View currently featured profiles

Accounts that the user is currently featuring on their profile.

Version history:

2.5.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
limit
integer
Default: 40

Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.

max_id
string

Internal parameter. Use HTTP Link header for pagination.

since_id
string

Internal parameter. Use HTTP Link header for pagination.

Responses

Response samples

Content type
application/json
[]

favourites

View favourited statuses

Statuses the user has favourited.

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
limit
integer
Default: 20

Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.

max_id
string

Internal parameter. Use HTTP Link header for pagination.

min_id
string

Internal parameter. Use HTTP Link header for pagination.

since_id
string

Internal parameter. Use HTTP Link header for pagination.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

featured_tags

View your featured tags

List all hashtags featured on your profile.

Version history:

3.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Feature a tag

Promote a hashtag on your profile.

Version history:

3.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
Request Body schema: application/json
required

JSON request body parameters

name
required
string

The hashtag to be featured, without the hash sign.

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Unfeature a tag

Stop promoting a hashtag on your profile.

Version history:

3.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

View suggested tags to feature

Shows up to 10 recently-used tags.

Version history:

3.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

filters

View your filters Deprecated

Version history:

2.4.3 - added
4.0.0 - deprecated. For compatibility purposes, now returns a List of V1::Filter, with each V1::Filter representing one FilterKeyword (with the keyword being presented in the phrase attribute)

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create a filter Deprecated

Version history:

2.4.3 - added
3.1.0 - added account context to filter in profile views
4.0.0 - deprecated. For compatibility purposes, now returns a V1::Filter representing one FilterKeyword (with the keyword being presented in the phrase attribute). This method will create a Filter that contains only one FilterKeyword. The title of the Filter and the keyword of the FilterKeyword will be set equal to the phrase provided.

Official Mastodon API documentation
Authorizations:
OAuth2
Request Body schema: application/json
required

JSON request body parameters

context
required
Array of strings (FilterContext)
Items Enum: "account" "home" "notifications" "public" "thread"

Where the filter should be applied. Specify at least one of home, notifications, public, thread, account.

phrase
required
string

The text to be filtered.

expires_in
integer

Number of seconds from now that the filter should expire. Otherwise, null for a filter that doesn't expire.

irreversible
boolean
Default: false

Should the server irreversibly drop matching entities from home and notifications? Defaults to false.

whole_word
boolean
Default: false

Should the filter consider word boundaries for this keyword? Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "context": [
    ],
  • "phrase": "string",
  • "expires_in": 0,
  • "irreversible": false,
  • "whole_word": false
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

View a single filter Deprecated

Version history:

2.4.3 - added
4.0.0 - deprecated. For compatibility purposes, now returns a V1::Filter representing one FilterKeyword (with the keyword being presented in the phrase attribute)

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Update a filter Deprecated

Replaces a filter's parameters in-place.

Version history:

2.4.3 - added
3.1.0 - added account context to filter in profile views
4.0.0 - deprecated. For compatibility purposes, now returns a V1::Filter representing one FilterKeyword (with the keyword being presented in the phrase attribute). This method will return an error if you attempt to change expires_in, irreversible, or context for a filter with multiple keywords. Changing phrase and whole_word is always safe.

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Request Body schema: application/json
required

JSON request body parameters

context
required
Array of strings (FilterContext)
Items Enum: "account" "home" "notifications" "public" "thread"

Specify at least one of home, notifications, public, thread, account.

phrase
required
string

The text to be filtered.

expires_in
integer

Number of seconds from now that the filter should expire. Otherwise, null for a filter that doesn't expire.

irreversible
boolean
Default: false

Should the server irreversibly drop matching entities from home and notifications? Defaults to false.

whole_word
boolean
Default: false

Should the filter consider word boundaries? Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "context": [
    ],
  • "phrase": "string",
  • "expires_in": 0,
  • "irreversible": false,
  • "whole_word": false
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Remove a filter Deprecated

Version history:

2.4.3 - added
4.0.0 - deprecated. This method will delete only the FilterKeyword from its parent Filter. To delete the parent Filter, you must use the v2 filters API.

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

View all filters

Obtain a list of all filter groups for the current user.

Version history:

4.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a filter

Create a filter group with the given parameters.

Version history:

4.0.0 - added
4.4.0 (mastodon [API version] 5) - added blur value to filter_action attribute

Official Mastodon API documentation
Authorizations:
OAuth2
Request Body schema: application/json
required

JSON request body parameters

context
required
Array of strings (FilterContext)
Items Enum: "account" "home" "notifications" "public" "thread"

Where the filter should be applied. Specify at least one of home, notifications, public, thread, account.

title
required
string

The name of the filter group.

expires_in
integer

How many seconds from now should the filter expire?

filter_action
string

The policy to be applied when the filter is matched. Specify warn, hide or blur.

Array of objects

Array of objects with properties: keyword, whole_word, id, _destroy

Responses

Request samples

Content type
application/json
{
  • "context": [
    ],
  • "title": "string",
  • "expires_in": 0,
  • "filter_action": "string",
  • "keywords_attributes": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

View keywords added to a filter

List all keywords attached to the current filter group.

Version history:

4.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
filter_id
required
string

filter_id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a keyword to a filter

Add the given keyword to the specified filter group

Version history:

4.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
filter_id
required
string

filter_id parameter

Request Body schema: application/json
required

JSON request body parameters

keyword
required
string

The keyword to be added to the filter group.

whole_word
boolean

Whether the keyword should consider word boundaries.

Responses

Request samples

Content type
application/json
{
  • "keyword": "string",
  • "whole_word": true
}

Response samples

Content type
application/json
[
  • {
    }
]

View all status filters

Obtain a list of all status filters within this filter group.

Version history:

4.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
filter_id
required
string

filter_id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a status to a filter group

Add a status filter to the current filter group.

Version history:

4.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
filter_id
required
string

filter_id parameter

Request Body schema: application/json
required

JSON request body parameters

status_id
required
string

The status ID to be added to the filter group.

Responses

Request samples

Content type
application/json
{
  • "status_id": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

View a specific filter

Obtain a single filter group owned by the current user.

Version history:

4.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update a filter

Update a filter group with the given parameters.

Version history:

4.0.0 - added
4.4.0 (mastodon [API version] 5) - added blur value to filter_action attribute

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Request Body schema: application/json
optional

JSON request body parameters

context
Array of strings (FilterContext)
Items Enum: "account" "home" "notifications" "public" "thread"

Where the filter should be applied. Specify at least one of home, notifications, public, thread, account.

expires_in
integer

How many seconds from now should the filter expire?

filter_action
string

The policy to be applied when the filter is matched. Specify warn, hide or blur.

Array of objects

Array of objects with properties: keyword, whole_word, id, _destroy

title
string

The name of the filter group.

Responses

Request samples

Content type
application/json
{
  • "context": [
    ],
  • "expires_in": 0,
  • "filter_action": "string",
  • "keywords_attributes": [
    ],
  • "title": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Delete a filter

Delete a filter group with the given id.

Version history:

4.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

View a single keyword

Get one filter keyword by the given id.

Version history:

4.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Edit a keyword within a filter

Update the given filter keyword.

Version history:

4.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Request Body schema: application/json
required

JSON request body parameters

keyword
required
string

The keyword to be added to the filter group.

whole_word
boolean

Whether the keyword should consider word boundaries.

Responses

Request samples

Content type
application/json
{
  • "keyword": "string",
  • "whole_word": true
}

Response samples

Content type
application/json
[
  • {
    }
]

Remove keywords from a filter

Deletes the given filter keyword.

Version history:

4.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

View a single status filter

Obtain a single status filter.

Version history:

4.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Remove a status from a filter group

Remove a status filter from the current filter group.

Version history:

4.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

follow_requests

View pending follow requests

Version history:

0.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
limit
integer
Default: 40

Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.

max_id
string

Internal parameter. Use HTTP Link header for pagination.

since_id
string

Internal parameter. Use HTTP Link header for pagination.

Responses

Response samples

Content type
application/json
[]

Accept follow request

Version history:

0.0.0 - added
3.0.0 - now returns Relationship instead of nothing

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
account_id
required
string

account_id parameter

Responses

Response samples

Content type
application/json
{
  • "id": "3",
  • "following": false,
  • "showing_reblogs": false,
  • "notifying": false,
  • "followed_by": false,
  • "blocking": true,
  • "blocked_by": false,
  • "muting": false,
  • "muting_notifications": false,
  • "requested": false,
  • "domain_blocking": false,
  • "endorsed": false
}

Reject follow request

Version history:

0.0.0 - added
3.0.0 - now returns Relationship instead of nothing

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
account_id
required
string

account_id parameter

Responses

Response samples

Content type
application/json
{
  • "id": "3",
  • "following": false,
  • "showing_reblogs": false,
  • "notifying": false,
  • "followed_by": false,
  • "blocking": true,
  • "blocked_by": false,
  • "muting": false,
  • "muting_notifications": false,
  • "requested": false,
  • "domain_blocking": false,
  • "endorsed": false
}

followed_tags

View all followed tags

List your followed hashtags.

Version history:

4.0.0 - added
4.1.0 - add pagination headers

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
limit
integer
Default: 100

Maximum number of results to return. Defaults to 100 tags. Max 200 tags.

max_id
string

Internal parameter. Use HTTP Link header for pagination.

min_id
string

Internal parameter. Use HTTP Link header for pagination.

since_id
string

Internal parameter. Use HTTP Link header for pagination.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

health

Get basic health status as JSON

Version history:

3.0.0 - added

Official Mastodon API documentation

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

instance

View server information (v1) Deprecated

Obtain general information about the server. See [api/v2/instance]({{< relref "methods/Instance#v2">}}) instead.

Version history:

1.1.0 - added
3.0.0 - requires user token if instance is in whitelist mode
3.1.4 - added invites_enabled to response
3.4.0 - added rules
3.4.2 - added configuration
4.0.0 - deprecated. added configuration[accounts].

Official Mastodon API documentation

Responses

Response samples

Content type
application/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": {
    },
  • "stats": {
    },
  • "thumbnail": "https://files.mastodon.social/site_uploads/files/000/000/001/original/vlcsnap-2018-08-27-16h43m11s127.png",
  • "languages": [
    ],
  • "registrations": false,
  • "approval_required": false,
  • "invites_enabled": true,
  • "configuration": {
    },
  • "contact_account": {},
  • "rules": [
    ]
}

Weekly activity

Instance activity over the last 3 months, binned weekly.

Version history:

2.1.2 - added
3.0.0 - requires user token if instance is in whitelist mode

Official Mastodon API documentation

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

View moderated servers

Obtain a list of domains that have been blocked.

Version history:

4.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

View extended description

Obtain an extended description of this server

Version history:

4.0.0 - added

Official Mastodon API documentation

Responses

Response samples

Content type
application/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"
}

List of connected domains

Domains that this instance is aware of.

Version history:

2.1.2 - added
3.0.0 - requires user token if instance is in whitelist mode

Official Mastodon API documentation

Responses

Response samples

Content type
application/json
[
  • "string"
]

View privacy policy

Obtain the contents of this server's privacy policy.

Version history:

4.0.0 - added

Official Mastodon API documentation

Responses

Response samples

Content type
application/json
{
  • "updated_at": "2022-10-07T00:00:00+00:00",
  • "content": "<p>This privacy policy describes how example.com (&quot;example.com&quot;, &quot;we&quot;, &quot;us&quot;) collects,\nprotects and uses the personally identifiable information you may provide\nthrough the example.com website or its API.</p>\n\n<h1>What information do we collect?</h1>\n\n<ul>\n<li><strong>Basic account information</strong>: If you register on this server, you may be\nasked to enter a username, an e-mail address and a password.</li>\n<li><strong>Posts, following and other public information</strong>: The list of people you\nfollow is listed publicly, the same is true for your followers.</li>\n<li><strong>Direct and followers-only posts</strong>: All posts are stored and processed on the\nserver. You may\ntoggle an option to approve and reject new followers manually in the settings.\n<strong>Please keep in mind that the operators of the server and any receiving\nserver may view such messages</strong>, and that recipients may screenshot, copy or\notherwise re-share them. <strong>Do not share any sensitive information over\nMastodon.</strong></li>\n<li><strong>IPs and other metadata</strong>: When you log in, we record the IP address you log\nin from, as well as the name of your browser application.</li>\n</ul>\n\n<hr>\n\n<p>This document is CC-BY-SA. Originally adapted from the <a href=\"https://github.com/discourse/discourse\">Discourse privacy\npolicy</a>.</p>\n"
}

List of rules

Rules that the users of this service should follow.

Version history:

3.4.0 - added

Official Mastodon API documentation

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

View terms of service

Obtain the contents of this server's terms of service, if configured.

Version history:

4.4.0 - added

Official Mastodon API documentation

Responses

Response samples

Content type
application/json
{
  • "effective_date": "2025-04-15",
  • "effective": true,
  • "content": "<p>Foo bar newer</p>\n",
  • "succeeded_by": null
}

View a specific version of the terms of service

Obtain the contents of this server's terms of service, for a specified date, if configured.

Version history:

4.4.0 - added

Official Mastodon API documentation
path Parameters
date
required
string

date parameter

Responses

Response samples

Content type
application/json
{
  • "effective_date": "2025-04-15",
  • "effective": true,
  • "content": "<p>Foo bar newer</p>\n",
  • "succeeded_by": null
}

View translation languages

Translation language pairs supported by the translation engine used by the server.

Version history:

4.2.0 - added

Official Mastodon API documentation

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

View server information

Obtain general information about the server.

Version history:

4.0.0 - added
4.3.0 - added configuration.vapid.public_key

Official Mastodon API documentation

Responses

Response samples

Content type
application/json
{}

lists

View your lists

Fetch all lists that the user owns.

Version history:

2.1.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a list

Create a new list.

Version history:

2.1.0 - added
3.3.0 - added replies_policy
4.2.0 - added exclusive

Official Mastodon API documentation
Authorizations:
OAuth2
Request Body schema: application/json
required

JSON request body parameters

title
required
string

The title of the list to be created.

exclusive
boolean

Whether members of this list need to get removed from the “Home” feed.

replies_policy
string (PolicyEnum)
Default: "list"
Enum: "followed" "list" "none"

One of followed, list, or none. Defaults to list.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "exclusive": true,
  • "replies_policy": "followed"
}

Response samples

Content type
application/json
[
  • {
    }
]

Show a single list

Fetch the list with the given ID.

Version history:

2.1.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update a list

Change the properties of a list.

Version history:

2.1.0 - added
3.3.0 - added replies_policy 4.2.0 - added exclusive

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Request Body schema: application/json
required

JSON request body parameters

title
required
string

The title of the list to be created.

exclusive
boolean

Whether members of this list need to get removed from the “Home” feed.

replies_policy
string (PolicyEnum)
Default: "list"
Enum: "followed" "list" "none"

One of followed, list, or none. Defaults to list.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "exclusive": true,
  • "replies_policy": "followed"
}

Response samples

Content type
application/json
[
  • {
    }
]

Delete a list

Version history:

2.1.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

View accounts in a list

Version history:

2.1.0 - added
3.3.0 - both min_id and max_id can be used at the same time now

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

query Parameters
limit
integer
Default: 40

Maximum number of results. Defaults to 40 accounts. Max 80 accounts. Set to 0 in order to get all accounts without pagination.

max_id
string

Internal parameter. Use HTTP Link header for pagination.

min_id
string

Internal parameter. Use HTTP Link header for pagination.

since_id
string

Internal parameter. Use HTTP Link header for pagination.

Responses

Response samples

Content type
application/json
[]

Add accounts to a list

Add accounts to the given list. Note that the user must be following these accounts.

Version history:

2.1.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Request Body schema: application/json
required

JSON request body parameters

account_ids
required
Array of strings

The accounts that should be added to the list.

Responses

Request samples

Content type
application/json
{
  • "account_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Remove accounts from list

Remove accounts from the given list.

Version history:

2.1.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Request Body schema: application/json
required

JSON request body parameters

account_ids
required
Array of strings

The accounts that should be removed from the list.

Responses

Request samples

Content type
application/json
{
  • "account_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

markers

Get saved timeline positions

Get current positions in timelines.

Version history:

3.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
timeline
Array of strings
Items Enum: "home" "notifications"

Specify the timeline(s) for which markers should be fetched. Possible values: home, notifications. If not provided, an empty object will be returned.

Responses

Response samples

Content type
application/json
{
  • "notifications": {
    },
  • "home": {
    }
}

Save your position in a timeline

Save current position in timeline.

Version history:

3.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
Request Body schema: application/json
optional

JSON request body parameters

object

Object containing properties

object

Object containing properties

Responses

Request samples

Content type
application/json
{
  • "home": {
    },
  • "notifications": {
    }
}

Response samples

Content type
application/json
{
  • "notifications": {
    },
  • "home": {
    }
}

media

Upload media as an attachment (v1) Deprecated

Creates an attachment to be used with a new status. This method will return after the full sized media is done processing.

Version history:

0.0.0 - added
2.3.0 - add focus parameter
3.1.3 - deprecated in favor of [POST /api/v2/media], which is equal to v1 in all aspects, except it returns HTTP 202, and the returned JSON object has a url of null. This is because while the thumbnail is prepared synchronously, the full version of the media attachment will be processed in the background.
3.2.0 - add thumbnail parameter

Official Mastodon API documentation
Authorizations:
OAuth2
Request Body schema: multipart/form-data
required

Multipart form data parameters

file
required
string <binary>

The file to be attached, encoded using multipart form data. The file must have a MIME type.

description
string

A plain-text description of the media, for accessibility purposes.

focus
string

Two floating points (x,y), comma-delimited, ranging from -1.0 to 1.0. See [Focal points for cropping media thumbnails] for more information.

thumbnail
string <binary>

The custom thumbnail of the media to be attached, encoded using multipart form data.

Responses

Response samples

Content type
application/json
{}

Get media attachment

Get a media attachment, before it is attached to a status and posted, but after it is accepted for processing. Use this method to check that the full-sized media has finished processing.

Version history:

3.1.3 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{}

Delete media attachment

Delete a media attachment that is not currently attached to a status.

Version history:

  • 4.4.0 (mastodon [API version] 4) - added
Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Update media attachment

Update a MediaAttachment's parameters, before it is attached to a status and posted.

Version history:

0.0.0 - added
2.3.0 - add focus parameter
3.2.0 - added thumbnail

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Request Body schema: multipart/form-data
optional

Multipart form data parameters

description
string

A plain-text description of the media, for accessibility purposes.

focus
string

Two floating points (x,y), comma-delimited, ranging from -1.0 to 1.0. See [Focal points for cropping media thumbnails] for more information.

thumbnail
string <binary>

The custom thumbnail of the media to be attached, encoded using multipart form data.

Responses

Response samples

Content type
application/json
{}

Upload media as an attachment (async)

Creates a media attachment to be used with a new status. The full sized media will be processed asynchronously in the background for large uploads.

Version history:

3.1.3 - added
3.2.0 - add thumbnail parameter
4.0.0 - Smaller media formats (image) will be processed synchronously and return 200 instead of 202. Larger media formats (video, gifv, audio) will continue to be processed asynchronously and return 202.

Official Mastodon API documentation
Authorizations:
OAuth2
Request Body schema: multipart/form-data
required

Multipart form data parameters

file
required
string <binary>

The file to be attached, encoded using multipart form data. The file must have a MIME type.

description
string

A plain-text description of the media, for accessibility purposes.

focus
string

Two floating points (x,y), comma-delimited, ranging from -1.0 to 1.0. See [Focal points for cropping media thumbnails] for more information.

thumbnail
string <binary>

The custom thumbnail of the media to be attached, encoded using multipart form data.

Responses

Response samples

Content type
application/json
{}

mutes

View muted accounts

Accounts the user has muted.

Version history:

0.0.0 - added
3.3.0 - added mute_expires_at

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
limit
integer
Default: 40

Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.

max_id
string

Internal parameter. Use HTTP Link header for pagination.

since_id
string

Internal parameter. Use HTTP Link header for pagination.

Responses

Response samples

Content type
application/json
[]

notifications

Get all notifications

Notifications concerning the user. This API returns Link headers containing links to the next/previous page. However, the links can also be constructed dynamically using query params and id values.

Version history:

0.0.0 - added
2.6.0 - added min_id
2.9.0 - added account_id
3.1.0 - added follow_request type
3.3.0 - added status type; both min_id and max_id can be used at the same time now
3.5.0 - added types; add update and admin.sign_up types
4.0.0 - added admin.report type
4.1.0 - notification limit changed from 15 (max 30) to 40 (max 80)
4.3.0 - added include_filtered parameter

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
account_id
string

Return only notifications received from the specified account.

exclude_types
Array of strings (TypesEnum)
Items Enum: "admin.report" "admin.sign_up" "favourite" "follow" "follow_request" "mention" "poll" "reblog" "status" "update"

Types to exclude from the results.

include_filtered
boolean
Default: false

Whether to include notifications filtered by the user's [NotificationPolicy]. Defaults to false.

limit
integer
Default: 40

Maximum number of results to return. Defaults to 40 notifications. Max 80 notifications.

max_id
string

All results returned will be lesser than this ID. In effect, sets an upper bound on results.

min_id
string

Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.

since_id
string

All results returned will be greater than this ID. In effect, sets a lower bound on results.

types
Array of strings (TypesEnum)
Items Enum: "admin.report" "admin.sign_up" "favourite" "follow" "follow_request" "mention" "poll" "reblog" "status" "update"

Types to include in the result.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get a single notification

View information about a notification with a given ID.

Version history:

0.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Dismiss a single notification

Dismiss a single notification from the server.

Version history:

1.3.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Dismiss all notifications

Clear all notifications from the server.

Version history:

0.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Get all notification requests

Notification requests for notifications filtered by the user's policy. This API returns Link headers containing links to the next/previous page.

Version history:

4.3.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
limit
integer
Default: 40

Maximum number of results to return. Defaults to 40 notification requests. Max 80 notification requests.

max_id
string

All results returned will be lesser than this ID. In effect, sets an upper bound on results.

min_id
string

Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.

since_id
string

All results returned will be greater than this ID. In effect, sets a lower bound on results.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a single notification request

View information about a notification request with a given ID.

Version history:

4.3.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Accept a single notification request

Accept a notification request, which merges the filtered notifications from that user back into the main notification and accepts any future notification from them.

Version history:

4.3.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Dismiss a single notification request

Dismiss a notification request, which hides it and prevent it from contributing to the pending notification requests count.

Version history:

4.3.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Accept multiple notification requests

Accepts multiple notification requests, which merges the filtered notifications from those users back into the main notifications and accepts any future notification from them.

Version history:

4.3.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Dismiss multiple notification requests

Dismiss multiple notification requests, which hides them and prevent them from contributing to the pending notification requests count.

Version history:

4.3.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Check if accepted notification requests have been merged

Check whether accepted notification requests have been merged.

Version history:

4.3.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Get the number of unread notifications

Get the (capped) number of unread notifications for the current user.

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
account_id
string

Only count unread notifications received from the specified account.

exclude_types
Array of strings

Types of notifications that should not count towards unread notifications.

limit
integer
Default: 100

Maximum number of results to return. Defaults to 100 notifications. Max 1000 notifications.

types
Array of strings

Types of notifications that should count towards unread notifications.

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Get all grouped notifications

Return grouped notifications concerning the user. This API returns Link headers containing links to the next/previous page. However, the links can also be constructed dynamically using query params and id values.

Version history:

4.3.0-beta.1 - added
4.3.0-beta.2 - deprecated

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
account_id
string

Return only notifications received from the specified account.

exclude_types
Array of strings (TypesEnum)
Items Enum: "admin.report" "admin.sign_up" "favourite" "follow" "follow_request" "mention" "poll" "reblog" "status" "update"

Types to exclude from the results.

expand_accounts
string

One of full (default) or partial_avatars. When set to partial_avatars, some accounts will not be rendered in full in the returned accounts list but will be instead returned in stripped-down form in the partial_accounts list. The most recent account in a notification group is always rendered in full in the accounts attribute.

grouped_types
Array of strings (TypesEnum)
Items Enum: "admin.report" "admin.sign_up" "favourite" "follow" "follow_request" "mention" "poll" "reblog" "status" "update"

Restrict which notification types can be grouped. Use this if there are notification types for which your client does not support grouping. If omitted, the server will group notifications of all types it supports (currently, favourite and reblog). If you do not want any notification grouping, use [GET /api/v1/notifications] instead.

limit
integer
Default: 40

Maximum number of results to return. Defaults to 40 notifications. Max 80 notification groups.

max_id
string

All results returned will be about notifications strictly older than this notification ID. In effect, sets an upper bound on results.

min_id
string

Returns results about notifications immediately newer than this notification ID. In effect, sets a cursor at this ID and paginates forward.

since_id
string

All results returned will be about notifications strictly newer than this notification ID. In effect, sets a lower bound on results.

types
Array of strings (TypesEnum)
Items Enum: "admin.report" "admin.sign_up" "favourite" "follow" "follow_request" "mention" "poll" "reblog" "status" "update"

Types to include in the result.

Responses

Response samples

Content type
application/json
{
  • "accounts": [
    ],
  • "statuses": [
    ],
  • "notification_groups": [
    ]
}

Get a single notification group

View information about a specific notification group with a given group key.

Version history:

4.3.0-beta.1 - added
4.3.0-beta.2 - deprecated

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
group_key
required
string

group_key parameter

Responses

Response samples

Content type
application/json
{
  • "accounts": [
    ],
  • "statuses": [
    ],
  • "notification_groups": [
    ]
}

Dismiss a single notification group

Dismiss a single notification group from the server.

Version history:

4.3.0-beta.1 - added
4.3.0-beta.2 - deprecated

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
group_key
required
string

group_key parameter

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Get the number of unread notifications

Get the (capped) number of unread notification groups for the current user.

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
account_id
string

Only count unread notifications received from the specified account.

exclude_types
Array of strings

Types of notifications that should not count towards unread notifications.

grouped_types
Array of strings

Restrict which notification types can be grouped. Use this if there are notification types for which your client does not support grouping. If omitted, the server will group notifications of all types it supports (currently, favourite and reblog). If you do not want any notification grouping, use [GET /api/v1/notifications/unread_count] instead.

limit
integer
Default: 100

Maximum number of results to return. Defaults to 100 notifications. Max 1000 notifications.

types
Array of strings

Types of notifications that should count towards unread notifications.

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Get all grouped notifications

Return grouped notifications concerning the user. This API returns Link headers containing links to the next/previous page. However, the links can also be constructed dynamically using query params and id values.

Version history:

4.3.0 (mastodon [API version] 2) - added
4.4.0 - added admin.sign_up to grouped notification types

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
account_id
string

Return only notifications received from the specified account.

exclude_types
Array of strings (TypesEnum)
Items Enum: "admin.report" "admin.sign_up" "favourite" "follow" "follow_request" "mention" "poll" "reblog" "status" "update"

Types to exclude from the results.

expand_accounts
string

One of full (default) or partial_avatars. When set to partial_avatars, some accounts will not be rendered in full in the returned accounts list but will be instead returned in stripped-down form in the partial_accounts list. The most recent account in a notification group is always rendered in full in the accounts attribute.

grouped_types
Array of strings (TypesEnum)
Items Enum: "admin.report" "admin.sign_up" "favourite" "follow" "follow_request" "mention" "poll" "reblog" "status" "update"

Restrict which notification types can be grouped. Use this if there are notification types for which your client does not support grouping. If omitted, the server will group notifications of all types it supports (currently, favourite, follow, reblog and admin.sign_up). If you do not want any notification grouping, use [GET /api/v1/notifications] instead. Notifications that would be grouped if not for this parameter will instead be returned as individual single-notification groups with a unique group_key that can be assumed to be of the form ungrouped-{notification_id}. Please note that neither the streaming API nor the individual notification APIs are aware of this parameter and will always include a “proper” group_key that can be different from what is returned here, meaning that you may have to ignore group_key for such notifications that you do not want grouped and use ungrouped-{notification_id} instead for consistency.

include_filtered
boolean
Default: false

Whether to include notifications filtered by the user's [NotificationPolicy]. Defaults to false.

limit
integer
Default: 40

Maximum number of results to return. Defaults to 40 notifications. Max 80 notification groups.

max_id
string

All results returned will be about notifications strictly older than this notification ID. In effect, sets an upper bound on results.

min_id
string

Returns results about notifications immediately newer than this notification ID. In effect, sets a cursor at this ID and paginates forward.

since_id
string

All results returned will be about notifications strictly newer than this notification ID. In effect, sets a lower bound on results.

types
Array of strings (TypesEnum)
Items Enum: "admin.report" "admin.sign_up" "favourite" "follow" "follow_request" "mention" "poll" "reblog" "status" "update"

Types to include in the result.

Responses

Response samples

Content type
application/json
{
  • "accounts": [
    ],
  • "statuses": [
    ],
  • "notification_groups": [
    ]
}

Get a single notification group

View information about a specific notification group with a given group key.

Version history:

4.3.0 (mastodon [API version] 2) - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
group_key
required
string

group_key parameter

Responses

Response samples

Content type
application/json
{
  • "accounts": [
    ],
  • "statuses": [
    ],
  • "notification_groups": [
    ]
}

Get accounts of all notifications in a notification group

Version history:

4.3.0 (mastodon [API version] 2) - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
group_key
required
string

group_key parameter

Responses

Response samples

Content type
application/json
[]

Dismiss a single notification group

Dismiss a single notification group from the server.

Version history:

4.3.0 (mastodon [API version] 2) - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
group_key
required
string

group_key parameter

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Get the filtering policy for notifications

Notifications filtering policy for the user.

Version history:

4.3.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "filter_not_following": false,
  • "filter_not_followers": false,
  • "filter_new_accounts": false,
  • "filter_private_mentions": true,
  • "summary": {
    }
}

Get the number of unread notifications

Get the (capped) number of unread notification groups for the current user.

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
account_id
string

Only count unread notifications received from the specified account.

exclude_types
Array of strings

Types of notifications that should not count towards unread notifications.

grouped_types
Array of strings

Restrict which notification types can be grouped. Use this if there are notification types for which your client does not support grouping. If omitted, the server will group notifications of all types it supports (currently, favourite, follow and reblog). If you do not want any notification grouping, use [GET /api/v1/notifications/unread_count] instead.

limit
integer
Default: 100

Maximum number of results to return. Defaults to 100 notifications. Max 1000 notifications.

types
Array of strings

Types of notifications that should count towards unread notifications.

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

oauth

Authorize a user

Displays an authorization form to the user. If approved, it will create and return an authorization code, then redirect to the desired redirect_uri, or show the authorization code if urn:ietf:wg:oauth:2.0:oob was requested. The authorization code can be used while requesting a token to obtain access to user-level methods.

Version history:

0.1.0 - added
2.6.0 - added force_login
3.5.0 - added lang
4.3.0 - added support for PKCE parameters

Official Mastodon API documentation
query Parameters
client_id
required
string

The client ID, obtained during app registration.

redirect_uri
required
string

Set a URI to redirect the user to. If this parameter is set to urn:ietf:wg:oauth:2.0:oob then the authorization code will be shown instead. Must match one of the redirect_uris declared during app registration.

response_type
required
string

Should be set equal to code.

code_challenge
string

The [PKCE code challenge] for the authorization request.

code_challenge_method
string

Must be S256, as this is the only code challenge method that is supported by Mastodon for PKCE.

force_login
boolean

Forces the user to re-login, which is necessary for authorizing with multiple accounts from the same instance.

lang
string

The ISO 639-1 two-letter language code to use while rendering the authorization form.

scope
string
Default: "read"

List of requested [OAuth scopes], separated by spaces (or by pluses, if using query parameters). Must be a subset of scopes declared during app registration. If not provided, defaults to read.

state
string

Arbitrary value to passthrough to your server when the user authorizes or rejects the authorization request.

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Revoke a token

Revoke an access token to make it no longer valid for use.

Version history:

0.1.0 - added

Official Mastodon API documentation
Request Body schema: application/json
required

JSON request body parameters

client_id
required
string

The client ID, obtained during app registration.

client_secret
required
string

The client secret, obtained during app registration.

token
required
string

The previously obtained token, to be invalidated.

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "client_secret": "string",
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Obtain a token

Obtain an access token, to be used during API calls that are not public.

Version history:

0.1.0 - added
4.3.0 - added support for PKCE parameter

Official Mastodon API documentation
Request Body schema: application/json
required

JSON request body parameters

client_id
required
string

The client ID, obtained during app registration.

client_secret
required
string

The client secret, obtained during app registration.

code
required
string

A user authorization code, obtained from the redirect after an [Authorization request] is approved. May alternatively be displayed to the user if urn:ietf:wg:oauth:2.0:oob is used as the redirect_uri.

grant_type
required
string

Set equal to authorization_code if code is provided in order to gain user-level access. Otherwise, set equal to client_credentials to obtain app-level access only.

redirect_uri
required
string

Must match the redirect_uri used during the [Authorization request].

code_verifier
string

Required if [PKCE] is used during the authorization request. This is the code verifier which was used to create the code_challenge using the code_challenge_method for the authorization request.

scope
string
Default: "read"

When grant_type is set to client_credentials, the list of requested OAuth scopes, separated by spaces (or pluses, if using query parameters). Must be a subset of the scopes requested at the time the application was created. If omitted, it defaults to read. Has no effect when grant_type is authorization_code.

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "client_secret": "string",
  • "code": "string",
  • "grant_type": "string",
  • "redirect_uri": "string",
  • "code_verifier": "string",
  • "scope": "read"
}

Response samples

Content type
application/json
{
  • "access_token": "ZA-Yj3aBD8U8Cm7lKUp-lm9O9BmDgdhHzDeqsY8tlL0",
  • "token_type": "Bearer",
  • "scope": "read write follow push",
  • "created_at": 1573979017
}

Retrieve user information

Retrieves standardised OIDC claims about the currently authenticated user.\

Version history:

4.4.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

oembed

Get OEmbed info as JSON

Version history:

1.0.0 - added

Official Mastodon API documentation
query Parameters
url
required
string

URL of a status.

maxheight
integer
Default: "null"

Height of the iframe. Defaults to null

maxwidth
integer
Default: 400

Width of the iframe. Defaults to 400

Responses

Response samples

Content type
application/json
{
  • "type": "rich",
  • "version": "1.0",
  • "title": "New status by trwnh",
  • "author_name": "infinite love ⴳ",
  • "author_url": "https://mastodon.social/@trwnh",
  • "provider_name": "mastodon.social",
  • "provider_url": "https://mastodon.social/",
  • "cache_age": 86400,
  • "html": "<iframe src=\"https://mastodon.social/@trwnh/99664077509711321/embed\" class=\"mastodon-embed\" style=\"max-width: 100%; border: 0\" width=\"400\" allowfullscreen=\"allowfullscreen\"></iframe><script src=\"https://mastodon.social/embed.js\" async=\"async\"></script>",
  • "width": 400,
  • "height": null
}

polls

View a poll

View a poll attached to a status.

Version history:

2.8.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/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": [
    ],
  • "options": [
    ],
  • "emojis": [ ]
}

Vote on a poll

Vote on a poll attached to a status.

Version history:

2.8.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Request Body schema: application/json
required

JSON request body parameters

choices
required
Array of integers

Provide your own votes as an index for each option (starting from 0).

Responses

Request samples

Content type
application/json
{
  • "choices": [
    ]
}

Response samples

Content type
application/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": [
    ],
  • "options": [
    ],
  • "emojis": [ ]
}

preferences

View user preferences

Preferences defined by the user in their account settings.

Version history:

2.8.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

push

Subscribe to push notifications

Add a Web Push API subscription to receive notifications. Each access token can have one push subscription. If you create a new subscription, the old subscription is deleted.

Version history:

2.4.0 - added
3.3.0 - added data[alerts][status]
3.4.0 - added data[policy]
3.5.0 - added data[alerts][update] and data[alerts][admin.sign_up]
4.0.0 - added data[alerts][admin.report]
4.3.0 - added stricter request parameter validation, invalid endpoint URLs and subscription keys will now result in an error, previously these would be accepted, but silently fail.
4.4.0 - added subscription[standard]

Official Mastodon API documentation
Authorizations:
OAuth2
Request Body schema: application/json
required

JSON request body parameters

required
object

Object containing properties

object

Object containing properties

Responses

Request samples

Content type
application/json
{
  • "subscription": {
    },
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "id": 328183,
  • "endpoint": "https://yourdomain.example/listener",
  • "standard": true,
  • "alerts": {
    },
  • "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M="
}

Get current subscription

View the PushSubscription currently associated with this access token.

Version history:

2.4.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "id": 328183,
  • "endpoint": "https://yourdomain.example/listener",
  • "standard": true,
  • "alerts": {
    },
  • "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M="
}

Change types of notifications

Updates the current push subscription. Only the data part can be updated. To change fundamentals, a new subscription must be created instead.

Version history:

2.4.0 - added
3.3.0 - added data[alerts][status]
3.4.0 - added policy
3.5.0 - added data[alerts][update] and data[alerts][admin.sign_up]
4.0.0 - added data[alerts][admin.report]

Official Mastodon API documentation
Authorizations:
OAuth2
Request Body schema: application/json
optional

JSON request body parameters

object

Object containing properties

policy
string

Specify whether to receive push notifications from all, followed, follower, or none users.

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "policy": "string"
}

Response samples

Content type
application/json
{
  • "id": 328183,
  • "endpoint": "https://yourdomain.example/listener",
  • "standard": true,
  • "alerts": {
    },
  • "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M="
}

Remove current subscription

Removes the current Web Push API subscription.

Version history:

2.4.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

reports

File a report

Report problematic accounts and contents to your moderators.

Version history:

1.1 - added
2.3.0 - add forward parameter
3.5.0 - add category and rule_ids parameters
4.0.0 - category is now optional if rule_ids is provided
4.2.0 - add legal category

Official Mastodon API documentation
Authorizations:
OAuth2
Request Body schema: application/json
required

JSON request body parameters

account_id
required
string

ID of the account to report.

category
string
Default: "other"
Enum: "spam" "legal" "violation" "other"

Specify if the report is due to spam, legal (illegal content), violation of enumerated instance rules, or some other reason. Defaults to other. Will be set to violation if rule_ids[] is provided (regardless of any category value you provide).

comment
string

The reason for the report. Default maximum of 1000 characters.

forward
boolean
Default: false

If the account is remote, should the report be forwarded to the remote admin? Defaults to false.

rule_ids
Array of strings

For violation category reports, specify the ID of the exact rules broken. Rules and their IDs are available via [GET /api/v1/instance/rules] and [GET /api/v1/instance]. See [Handling and sorting IDs] for more information.

status_ids
Array of strings

You can attach statuses to the report to provide additional context.

Responses

Request samples

Content type
application/json
{
  • "account_id": "string",
  • "category": "spam",
  • "comment": "string",
  • "forward": false,
  • "rule_ids": [
    ],
  • "status_ids": [
    ]
}

Response samples

Content type
application/json
{}

scheduled_statuses

View scheduled statuses

Version history:

2.7.0 - added
3.3.0 - both min_id and max_id can be used at the same time now

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
limit
integer
Default: 20

Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.

max_id
string

All results returned will be lesser than this ID. In effect, sets an upper bound on results.

min_id
string

Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.

since_id
string

All results returned will be greater than this ID. In effect, sets a lower bound on results.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

View a single scheduled status

Version history:

2.7.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update a scheduled status's publishing date

Version history:

2.7.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Request Body schema: application/json
optional

JSON request body parameters

scheduled_at
string <date-time>

[Datetime] at which the status will be published. Must be at least 5 minutes into the future.

Responses

Request samples

Content type
application/json
{
  • "scheduled_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
[
  • {
    }
]

Cancel a scheduled status

Version history:

2.7.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

search

Perform a search

Perform a search for content in accounts, statuses and hashtags with the given parameters.

Version history:

2.4.1 - added, limit hardcoded to 5
2.8.0 - add type, limit, offset, min_id, max_id, account_id
3.0.0 - add exclude_unreviewed param
3.3.0 - min_id and max_id can be used together
4.0.0 - no longer requires a user token. Without a valid user token, you cannot use the resolve or offset parameters.

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
q
required
string

The search query.

account_id
string

If provided, will only return statuses authored by this account.

exclude_unreviewed
boolean
Default: false

Filter out unreviewed tags? Defaults to false. Use true when trying to find trending tags.

following
boolean
Default: false

Only include accounts that the user is following? Defaults to false.

limit
integer
Default: 20

Maximum number of results to return, per type. Defaults to 20 results per category. Max 40 results per category.

max_id
string

All results returned will be lesser than this ID. In effect, sets an upper bound on results.

min_id
string

Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.

offset
integer

Skip the first n results.

resolve
boolean

Only relevant if type includes accounts or if query is a HTTPS URL. In the first case, if true and (a) the search query is for a remote account (e.g., someaccount@someother.server) and (b) the local server does not know about the account, [WebFinger] is used to try and resolve the account at someother.server. This provides the best recall at higher latency. If false, only accounts the server knows about are returned. In the second case, if true, resolving the URL and returning the matching status is attempted. If false, this resolving logic is circumvented and a regular search is performed instead.

type
string

Specify whether to search for only accounts, hashtags, statuses

Responses

Response samples

Content type
application/json
{}

statuses

Post a new status

Publish a status with the given parameters.

Version history:

0.0.0 - added
2.7.0 - scheduled_at added
2.8.0 - poll added

Official Mastodon API documentation
Authorizations:
OAuth2
header Parameters
Idempotency-Key
object

Provide this header with any arbitrary string to prevent duplicate submissions of the same status. Consider using a hash or UUID generated client-side. Idempotency keys are stored for up to 1 hour.

Request Body schema: application/json
required

JSON request body parameters for creating a status. Different types of statuses have different requirements.

One of
in_reply_to_id
string

ID of the status being replied to, if status is a reply.

language
string

ISO 639-1 language code for this status.

scheduled_at
string <date-time>

[Datetime] at which to schedule a status. Providing this parameter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future.

sensitive
boolean
Default: false

Mark status and attached media as sensitive? Defaults to false.

spoiler_text
string

Text to be shown as a warning or subject before the actual content. Statuses are generally collapsed behind this field.

visibility
string (VisibilityEnum)
Enum: "direct" "private" "public" "unlisted"

Sets the visibility of the posted status to public, unlisted, private, direct.

status
required
string

The text content of the status. If media_ids is provided, this becomes optional. Attaching a poll is optional while status is provided.

Responses

Request samples

Content type
application/json
Example
{
  • "in_reply_to_id": "string",
  • "language": "string",
  • "scheduled_at": "2019-08-24T14:15:22Z",
  • "sensitive": false,
  • "spoiler_text": "string",
  • "visibility": "direct",
  • "status": "string"
}

Response samples

Content type
application/json
{
  • "id": "103254962155278888",
  • "created_at": "2019-12-05T11:34:47.196Z",
  • "content": "<p>test content</p>",
  • "application": {
    }
}

View multiple statuses

Obtain information about multiple statuses.

Version history:

4.3.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
id
Array of strings

The IDs of the Statuses in the database.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

View a single status

Obtain information about a status.

Version history:

0.0.0 - added
2.7.0 - public statuses no longer require token

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete a status

Delete one of your own statuses.

Version history:

0.0.0 - added
2.9.0 - return source properties, for use with delete and redraft
4.4.0 (mastodon [API version] 4) - added delete_media optional parameter

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

query Parameters
delete_media
boolean

Whether to immediately delete the post's media attachments. If omitted or false, media attachments may be kept for approximately 24 hours so they can be re-used in a new post.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Edit a status

Edit a given status to change its text, sensitivity, media attachments, or poll. Note that editing a poll’s options or changing whether it is multiple choice will reset the votes.

Version history:

3.5.0 - added
4.0.0 - add language

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Request Body schema: application/json
optional

JSON request body parameters

language
string

ISO 639-1 language code for the status.

media_attributes[]
Array of strings

Each array includes id, description, and focus.

media_ids
Array of strings

Include Attachment IDs to be attached as media. If provided, status becomes optional, and poll cannot be used.

object

Object containing properties

sensitive
boolean

Whether the status should be marked as sensitive.

spoiler_text
string

The plain text subject or content warning of the status.

status
string

The plain text content of the status.

Responses

Request samples

Content type
application/json
{
  • "language": "string",
  • "media_attributes[]": [
    ],
  • "media_ids": [
    ],
  • "poll": {
    },
  • "sensitive": true,
  • "spoiler_text": "string",
  • "status": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Bookmark a status

Privately bookmark a status.

Version history:

3.1.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Fetch preview card Deprecated

Version history:

0.0.0 - added
2.6.0 - deprecated in favor of card property inlined on Status entity
3.0.0 - removed

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{}

Get parent and child statuses in context

View statuses above and below this status in the thread.

Version history:

0.0.0 - added
4.0.0 - limit unauthenticated requests

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "ancestors": [
    ],
  • "descendants": [
    ]
}

Favourite a status

Add a status to your favourites list.

Version history:

0.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

See who favourited a status

View who favourited a given status.

Version history:

0.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

query Parameters
limit
integer
Default: 40

Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.

max_id
string

Internal parameter. Use HTTP Link header for pagination.

since_id
string

Internal parameter. Use HTTP Link header for pagination.

Responses

Response samples

Content type
application/json
[]

View edit history of a status

Get all known versions of a status, including the initial and current states.

Version history:

3.5.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Mute a conversation

Do not receive notifications for the thread that this status is part of. Must be a thread in which you are a participant.

Version history:

1.4.2 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Pin status to profile

Feature one of your own public statuses at the top of your profile.

Version history:

1.6.0 - added
3.5.0 - you can now pin private posts

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Boost a status

Reshare a status on your own profile.

Version history:

0.0.0 - added
2.8.0 - add visibility parameter

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Request Body schema: application/json
optional

JSON request body parameters

visibility
string
Default: "public"

Any visibility except limited or direct (i.e. public, unlisted, private). Defaults to public.

Responses

Request samples

Content type
application/json
{
  • "visibility": "public"
}

Response samples

Content type
application/json
[
  • {
    }
]

See who boosted a status

View who boosted a given status.

Version history:

0.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

query Parameters
limit
integer
Default: 40

Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.

max_id
string

Internal parameter. Use HTTP Link header for pagination.

since_id
string

Internal parameter. Use HTTP Link header for pagination.

Responses

Response samples

Content type
application/json
[]

View status source

Obtain the source properties for a status so that it can be edited.

Version history:

3.5.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2ClientCredentials
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
{
  • "id": "108942703571991143",
  • "text": "this is a status that will be edited",
  • "spoiler_text": ""
}

Translate a status

Translate the status content into some language.

Version history:

4.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2ClientCredentials
path Parameters
id
required
string

id parameter

Request Body schema: application/json
optional

JSON request body parameters

lang
string

String (ISO 639-1 language code). The status content will be translated into this language. Defaults to the user's current locale.

Responses

Request samples

Content type
application/json
{
  • "lang": "string"
}

Response samples

Content type
application/json
{
  • "content": "<p>Hello world</p>",
  • "spoiler_text": "Greatings ahead",
  • "media_attachments": [
    ],
  • "poll": null,
  • "detected_source_language": "es",
  • "provider": "DeepL.com"
}

Undo bookmark of a status

Remove a status from your private bookmarks.

Version history:

3.1.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Undo favourite of a status

Remove a status from your favourites list.

Version history:

0.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Unmute a conversation

Start receiving notifications again for the thread that this status is part of.

Version history:

1.4.2 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Unpin status from profile

Unfeature a status from the top of your profile.

Version history:

1.6.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Undo boost of a status

Undo a reshare of a status.

Version history:

0.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

streaming

Watch for direct messages

Returns events for received direct messages.

Version history:

2.4.0 - added
2.6.0 - now returns conversation instead of update

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Watch the public timeline for a hashtag

Returns all public statuses for a particular hashtag

Version history:

1.0.0 - added
3.5.0 - now returns status.update
4.2.0 - changed to require a User token, removing Public and App token access [#23989]

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
tag
required
string

The name of the hashtag to watch.

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Watch the local timeline for a hashtag

Returns all local public statuses for a particular hashtag

Version history:

1.1.0 - added
3.5.0 - now returns status.update
4.2.0 - changed to require a User token, removing Public and App token access [#23989]

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
tag
required
string

The name of the hashtag to watch.

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Check if the server is alive

Verify that the streaming service is alive before connecting to it

Version history:

2.5.0 - added

Official Mastodon API documentation

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Watch for list updates

Returns statuses for a list

Version history:

2.1.0 - added
3.5.0 - now returns status.update
4.2.0 - changed to require a User token, removing Public and App token access [#23989]

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
list
required
string

The ID of the list to watch.

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Watch the federated timeline

Returns all public statuses

Version history:

1.0.0 - added
2.4.0 - add only_media parameter
3.5.0 - now returns status.update
4.2.0 - changed to require a User token, removing Public and App token access [#23989]

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
only_media
boolean

If true, return only statuses with media attachments.

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Watch the local timeline

Returns all local public statuses

Version history:

1.1.0 - added
2.4.0 - add only_media parameter
3.5.0 - now returns status.update
4.2.0 - changed to require a User token, removing Public and App token access [#23989]

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
only_media
boolean

If true, return only statuses with media attachments.

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Watch for remote statuses

Returns all public statuses from remote servers.

Version history:

3.1.4 - added
3.5.0 - now returns status.update
4.2.0 - changed to require a User token, removing Public and App token access [#23989]

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
only_media
boolean

If true, return only statuses with media attachments.

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Watch your home timeline and notifications

Returns events that are relevant to the authorized user, i.e. home timeline and notifications

Version history:

1.0.0 - added
1.4.2 - now returns notification
2.4.3 - now returns filters_changed
3.1.0 - now returns announcement, announcement.reaction, announcement.delete
3.5.0 - now returns status.update

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

Watch your notifications

Returns events for received notifications

Version history:

1.4.2 - added

Official Mastodon API documentation
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

suggestions

View follow suggestions (v1) Deprecated

Accounts the user has had past positive interactions with, but is not yet following.

Version history:

2.4.3 - added
3.4.0 - deprecated

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
limit
integer
Default: 40

Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.

Responses

Response samples

Content type
application/json
[]

Remove a suggestion

Remove an account from follow suggestions.

Version history:

2.4.3 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
account_id
required
string

account_id parameter

Responses

Response samples

Content type
application/json
{
  • "error": "The access token is invalid"
}

View follow suggestions (v2)

Accounts that are promoted by staff, or that the user has had past positive interactions with, but is not yet following.

Version history:

3.4.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
limit
integer
Default: 40

Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

tags

Feature a hashtag

Feature the hashtag on your profile.

Version history:

4.4.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Unfeature a hashtag

Stop featuring the hashtag on your profile.

Version history:

4.4.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
id
required
string

id parameter

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

View information about a single tag

Show a hashtag and its associated information

Version history:

4.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
name
required
string

name parameter

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Follow a hashtag

Follow a hashtag. Posts containing a followed hashtag will be inserted into your home timeline.

Version history:

4.0.0 - added
4.1.0 - this action is now idempotent

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
name
required
string

name parameter

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Unfollow a hashtag

Unfollow a hashtag. Posts containing this hashtag will no longer be inserted into your home timeline.

Version history:

4.0.0 - added

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
name
required
string

name parameter

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

timelines

View direct timeline Deprecated

View statuses with a "direct" privacy, from your account or in your notifications.

Version history:

x.x.x - added
2.6.0 - add min_id. deprecated in favor of [Conversations API]
3.0.0 - removed

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
limit
integer
Default: 20

Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.

max_id
string

All results returned will be lesser than this ID. In effect, sets an upper bound on results.

min_id
string

Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.

since_id
string

All results returned will be greater than this ID. In effect, sets a lower bound on results.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

View home timeline

View statuses from followed users and hashtags.

Version history:

0.0.0 - added
2.6.0 - add min_id
3.3.0 - both min_id and max_id can be used at the same time now
4.0.0 - as users can now follow hashtags, statuses from non-followed users may appear in the timeline

Official Mastodon API documentation
Authorizations:
OAuth2
query Parameters
limit
integer
Default: 20

Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.

max_id
string

All results returned will be lesser than this ID. In effect, sets an upper bound on results.

min_id
string

Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.

since_id
string

All results returned will be greater than this ID. In effect, sets a lower bound on results.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

View list timeline

View statuses in the given list timeline.

Version history:

2.1.0 - added
2.6.0 - add min_id
3.3.0 - both min_id and max_id can be used at the same time now

Official Mastodon API documentation
Authorizations:
OAuth2
path Parameters
list_id
required
string

list_id parameter

query Parameters
limit
integer
Default: 20

Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.

max_id
string

All results returned will be lesser than this ID. In effect, sets an upper bound on results.

min_id
string

Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.

since_id
string

All results returned will be greater than this ID. In effect, sets a lower bound on results.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

View public timeline

View public statuses.

Version history:

0.0.0 - added
2.3.0 - added only_media
2.6.0 - add min_id
3.0.0 - auth is required if public preview is disabled
3.1.4 - added remote
3.3.0 - both min_id and max_id can be used at the same time now

Official Mastodon API documentation
Authorizations:
OAuth2ClientCredentials
query Parameters
limit
integer
Default: 20

Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.

local
boolean
Default: false

Show only local statuses? Defaults to false.

max_id
string

All results returned will be lesser than this ID. In effect, sets an upper bound on results.

min_id
string

Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.

only_media
boolean
Default: false

Show only statuses with media attached? Defaults to false.

remote
boolean
Default: false

Show only remote statuses? Defaults to false.

since_id
string

All results returned will be greater than this ID. In effect, sets a lower bound on results.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

View hashtag timeline

View public statuses containing the given hashtag.

Version history:

0.0.0 - added
2.3.0 - added only_media
2.6.0 - add min_id
2.7.0 - add any[], all[], none[] for additional tags
3.0.0 - auth is required if public preview is disabled
3.3.0 - both min_id and max_id can be used at the same time now. add remote

Official Mastodon API documentation
Authorizations:
OAuth2ClientCredentials
path Parameters
hashtag
required
string

hashtag parameter

query Parameters
all
Array of strings

Return statuses that contain all of these additional tags.

any
Array of strings

Return statuses that contain any of these additional tags.

limit
integer
Default: 20

Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.

local
boolean
Default: false

Return only local statuses? Defaults to false.

max_id
string

All results returned will be lesser than this ID. In effect, sets an upper bound on results.

min_id
string

Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.

none
Array of strings

Return statuses that contain none of these additional tags.

only_media
boolean
Default: false

Return only statuses with media attachments? Defaults to false.

remote
boolean
Default: false

Return only remote statuses? Defaults to false.

since_id
string

All results returned will be greater than this ID. In effect, sets a lower bound on results.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

trends

View trending statuses

Statuses that have been interacted with more than others.

Version history:

3.5.0 - added

Official Mastodon API documentation
query Parameters
limit
integer
Default: 20

Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.

offset
integer

Skip the first n results.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

View trending tags

Tags that are being used more frequently within the past week.

Version history:

3.0.0 - added
3.5.0 - method signature changed from GET /api/v1/trends to GET /api/v1/trends/tags. The former is a deprecated alias that may be removed in the future.

Official Mastodon API documentation
query Parameters
limit
integer
Default: 10

Maximum number of results to return. Defaults to 10 tags. Max 20 tags.

offset
integer

Skip the first n results.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

well-known

Discover OAuth Server Configuration

Returns the OAuth 2 Authorization Server Metadata for the Mastodon server, as defined by RFC 8414.

Version history:

4.3.0 - added
4.4.0 - added userinfo_endpoint

Official Mastodon API documentation

Responses

Response samples

Content type
application/json
{
  • "issuer": "https://social.example/",
  • "service_documentation": "https://docs.joinmastodon.org/",
  • "authorization_endpoint": "https://social.example/oauth/authorize",
  • "token_endpoint": "https://social.example/oauth/token",
  • "app_registration_endpoint": "https://social.example/api/v1/apps",
  • "revocation_endpoint": "https://social.example/oauth/revoke",
  • "userinfo_endpoint": "https://social.example/oauth/userinfo",
  • "scopes_supported": [
    ],
  • "response_types_supported": [
    ],
  • "response_modes_supported": [
    ],
  • "code_challenge_methods_supported": [
    ],
  • "grant_types_supported": [
    ],
  • "token_endpoint_auth_methods_supported": [
    ]
}