Pleroma logo
Documentation Powered by ReDoc

Pleroma API (2.9.1-271-g29be5018)

Download OpenAPI specification:Download

This is documentation for client Pleroma API. Most of the endpoints and entities come from Mastodon API and have custom extensions on top.

While this document aims to be a complete guide to the client API Pleroma exposes, the details are still being worked out. Some endpoints may have incomplete or poorly worded documentation. You might want to check the following resources if something is not clear:

Please report such occurrences on our issue tracker. Feel free to submit API questions or proposals there too!

Authentication

oAuth

Security Scheme Type OAuth2
password OAuth Flow
Token URL: /oauth/token
Scopes:
  • follow -

    Manage relationships

  • push -

    Web Push API subscriptions

  • read -

    Read everything

  • write -

    Write everything

Account actions

Endorse

Adds the given account to endorsed accounts list.

Authorizations:
oAuth (followwrite:accounts)
path Parameters
id
required
string
Example: 123

Account ID or nickname

Responses

Response samples

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

Mute

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).

Authorizations:
oAuth (followwrite:mutes)
path Parameters
id
required
string
Example: 123

Account ID or nickname

query Parameters
boolean or string or integer
Default: true

Mute notifications in addition to statuses? Defaults to true.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

duration
integer Nullable

Expire the mute in expires_in seconds. Default 0 for infinity

expires_in
integer Nullable
Default: 0

Deprecated, use duration instead

boolean or string or integer Nullable
Default: true

Mute notifications in addition to statuses? Defaults to true.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "expires_in": 86400,
  • "notifications": true
}

Response samples

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

Subscribe Deprecated

Receive notifications for all statuses posted by the account. Deprecated, use notify: true in follow operation instead.

Authorizations:
oAuth (followwrite:follows)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Account ID

Responses

Response samples

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

Set a private note about a user.

Create a note for the given account.

Authorizations:
oAuth (followwrite:accounts)
path Parameters
id
required
string
Example: 123

Account ID or nickname

query Parameters
comment
string

Account note body

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

comment
string

Account note body

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "comment": "Example note"
}

Response samples

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

Unendorse

Removes the given account from endorsed accounts list.

Authorizations:
oAuth (followwrite:accounts)
path Parameters
id
required
string
Example: 123

Account ID or nickname

Responses

Response samples

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

Remove from followers

Remove the given account from followers

Authorizations:
oAuth (followwrite:follows)
path Parameters
id
required
string
Example: 123

Account ID or nickname

Responses

Response samples

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

Block

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

Authorizations:
oAuth (followwrite:blocks)
path Parameters
id
required
string
Example: 123

Account ID or nickname

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

duration
integer Nullable

Expire the mute in duration seconds. Default 0 for infinity

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "duration": 86400
}

Response samples

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

Unblock

Unblock the given account.

Authorizations:
oAuth (followwrite:blocks)
path Parameters
id
required
string
Example: 123

Account ID or nickname

Responses

Response samples

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

Unmute

Unmute the given account.

Authorizations:
oAuth (followwrite:mutes)
path Parameters
id
required
string
Example: 123

Account ID or nickname

Responses

Response samples

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

Unfollow

Unfollow the given account

Authorizations:
oAuth (followwrite:follows)
path Parameters
id
required
string
Example: 123

Account ID or nickname

Responses

Response samples

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

Unsubscribe Deprecated

Stop receiving notifications for all statuses posted by the account. Deprecated, use notify: false in follow operation instead.

Authorizations:
oAuth (followwrite:follows)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Account ID

Responses

Response samples

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

Follow

Follow the given account

Authorizations:
oAuth (followwrite:follows)
path Parameters
id
required
string
Example: 123

Account ID or nickname

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

boolean or string or integer
Default: false

Receive notifications for all statuses posted by the account? Defaults to false.

boolean or string or integer
Default: true

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

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "notify": true,
  • "reblogs": true
}

Response samples

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

Follow by URI

Authorizations:
oAuth (followwrite:follows)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

uri
required
string <uri> Nullable

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{}

Response samples

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

Retrieve account information

Relationship with current account

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

Authorizations:
oAuth (read:follows)
query Parameters
Array of strings or string
Example: id=123

Account IDs

Responses

Response samples

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

Favorites

Only returns data if the user has opted into sharing it. See hide_favorites in Update account credentials.

Authorizations:
oAuth (read:favourites)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Account ID

query Parameters
max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Find a user by nickname

query Parameters
acct
string

User nickname

Responses

Response samples

Content type
application/json
{
  • "acct": "string",
  • "avatar": "http://example.com",
  • "avatar_static": "http://example.com",
  • "block_expires_at": "2019-08-24T14:15:22Z",
  • "bot": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "display_name": "string",
  • "emojis": [],
  • "fields": [
    ],
  • "follow_requests_count": 0,
  • "followers_count": 0,
  • "following_count": 0,
  • "header": "http://example.com",
  • "header_static": "http://example.com",
  • "id": "string",
  • "is_active": true,
  • "is_confirmed": true,
  • "local": true,
  • "locked": true,
  • "mute_expires_at": "2019-08-24T14:15:22Z",
  • "nickname": "string",
  • "note": "string",
  • "pleroma": {
    },
  • "roles": {
    },
  • "source": {
    },
  • "statuses_count": 0,
  • "url": "http://example.com",
  • "username": "string"
}

Followers that you follow

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

Authorizations:
oAuth (read:follows)
query Parameters
Array of strings or string
Example: id=123

Account IDs

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Followers

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

Authorizations:
oAuth (read:accounts)
path Parameters
id
required
string
Example: 123

Account ID or nickname

query Parameters
id
string

ID of the resource owner

boolean or string or integer (BooleanLike)

Embed relationships into accounts. If this parameter is not set account's pleroma.relationship is going to be null.

max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Endorsements

Returns endorsed accounts

path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Account ID

query Parameters
boolean or string or integer (BooleanLike)

Embed relationships into accounts. If this parameter is not set account's pleroma.relationship is going to be null.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Endorsements

Returns endorsed accounts

Authorizations:
oAuth (read:accounts)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Account

View information about a profile.

path Parameters
id
required
string
Example: 123

Account ID or nickname

query Parameters
boolean or string or integer (BooleanLike)

Embed relationships into accounts. If this parameter is not set account's pleroma.relationship is going to be null.

Responses

Response samples

Content type
application/json
{
  • "acct": "string",
  • "avatar": "http://example.com",
  • "avatar_static": "http://example.com",
  • "block_expires_at": "2019-08-24T14:15:22Z",
  • "bot": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "display_name": "string",
  • "emojis": [],
  • "fields": [
    ],
  • "follow_requests_count": 0,
  • "followers_count": 0,
  • "following_count": 0,
  • "header": "http://example.com",
  • "header_static": "http://example.com",
  • "id": "string",
  • "is_active": true,
  • "is_confirmed": true,
  • "local": true,
  • "locked": true,
  • "mute_expires_at": "2019-08-24T14:15:22Z",
  • "nickname": "string",
  • "note": "string",
  • "pleroma": {
    },
  • "roles": {
    },
  • "source": {
    },
  • "statuses_count": 0,
  • "url": "http://example.com",
  • "username": "string"
}

Statuses

Statuses posted to the given account. Public (for public statuses only), or user token + read:statuses (for private statuses the user is authorized to see)

path Parameters
id
required
string
Example: 123

Account ID or nickname

query Parameters
boolean or string or integer (BooleanLike)

Include only pinned statuses

tagged
string

With tag

boolean or string or integer (BooleanLike)

Include only statuses with media attached

boolean or string or integer (BooleanLike)

Include statuses from muted accounts.

boolean or string or integer (BooleanLike)

Exclude reblogs

boolean or string or integer (BooleanLike)

Exclude replies

exclude_visibilities
Array of strings (VisibilityScope)
Items Enum: "public" "unlisted" "local" "private" "direct" "list"

Exclude visibilities

boolean or string or integer (BooleanLike)

Include reactions from muted accounts.

max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Lists containing this account

User lists that you have added this account to.

Authorizations:
oAuth (read:lists)
path Parameters
id
required
string
Example: 123

Account ID or nickname

Responses

Response samples

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

Birthday reminders

Birthday reminders about users you follow.

Authorizations:
oAuth (read:accounts)
query Parameters
day
integer

Day of users' birthdays

month
integer

Month of users' birthdays

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Following

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

Authorizations:
oAuth (read:accounts)
path Parameters
id
required
string
Example: 123

Account ID or nickname

query Parameters
id
string

ID of the resource owner

boolean or string or integer (BooleanLike)

Embed relationships into accounts. If this parameter is not set account's pleroma.relationship is going to be null.

max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Scrobbles

Creates a new Listen activity for an account Deprecated

Authorizations:
oAuth (write)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

album
string

The album of the media playing

artist
string

The artist of the media playing

externalLink
string

Deprecated, use external_link instead

external_link
string

A URL referencing the media playing

length
integer

The length of the media playing

title
required
string

The title of the media playing

visibility
string
Default: "public"
Enum: "public" "unlisted" "local" "private" "direct" "list"

Scrobble visibility

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{}

Response samples

Content type
application/json
{
  • "account": {
    },
  • "album": "Some Album",
  • "artist": "Some Artist",
  • "created_at": "2019-09-28T12:40:45.000Z",
  • "external_link": "https://www.last.fm/music/Some+Artist/_/Some+Title",
  • "id": "1234",
  • "length": 180000,
  • "title": "Some Title"
}

Requests a list of current and recent Listen activities for an account Deprecated

Authorizations:
oAuth (read)
path Parameters
id
required
string
Example: 123

Account ID or nickname

query Parameters
max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Chat administration

Get chat's messages

Authorizations:
oAuth (admin:read:chats)
path Parameters
id
required
string

The ID of the Chat

query Parameters
max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

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

Delete an individual chat message

Authorizations:
oAuth (admin:write:chats)
path Parameters
id
required
string

The ID of the Chat

message_id
required
string

The ID of the message

Responses

Response samples

Content type
application/json
{}

Create a chat

Authorizations:
oAuth (admin:read)
path Parameters
id
required
string
Example: 1234

The id of the chat

Responses

Response samples

Content type
application/json
{}

Emoji pack administration

Imports packs from filesystem

Authorizations:
oAuth (admin:write)

Responses

Response samples

Content type
application/json
[
  • "string"
]

Delete emoji file from pack

Authorizations:
oAuth (admin:write)
query Parameters
name
required
string
Example: name=cofe

Pack Name

shortcode
required
string
Example: shortcode=cofe

File shortcode

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Add new file to the pack

Authorizations:
oAuth (admin:write)
query Parameters
name
required
string
Example: name=cofe

Pack Name

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

force
boolean
Default: false

With true value to overwrite existing emoji with new shortcode

new_filename
required
string

New filename for emoji file

new_shortcode
required
string

New emoji file shortcode

shortcode
required
string

Emoji file shortcode

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "force": false,
  • "new_filename": "string",
  • "new_shortcode": "string",
  • "shortcode": "string"
}

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Add new file to the pack

Authorizations:
oAuth (admin:write)
query Parameters
name
required
string
Example: name=cofe

Pack Name

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

required
string or string

File needs to be uploaded with the multipart request or link to remote file

filename
string

New emoji file name. If not specified will be taken from original filename.

shortcode
string

Shortcode for new emoji, must be unique for all emoji. If not sended, shortcode will be taken from original filename.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "file": "string",
  • "filename": "string",
  • "shortcode": "string"
}

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Download pack from another instance

Authorizations:
oAuth (admin:write)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

as
string <uri>

Save as

name
required
string <uri>

Pack Name

url
required
string <uri>

URL of the instance to download from

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{}

Response samples

Content type
application/json
"ok"

Make request to another instance for emoji packs list

Authorizations:
oAuth (admin:write)
query Parameters
url
required
string <uri>

URL of the instance

page
integer
Default: 1

Page

page_size
integer
Default: 30

Number of emoji to return

Responses

Response samples

Content type
application/json
{
  • "count": 1,
  • "packs": {
    }
}

Delete a custom emoji pack

Authorizations:
oAuth (admin:write)
query Parameters
name
required
string
Example: name=cofe

Pack Name

Responses

Response samples

Content type
application/json
"ok"

Updates (replaces) pack metadata

Authorizations:
oAuth (admin:write)
query Parameters
name
required
string
Example: name=cofe

Pack Name

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

object

Metadata to replace the old one

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{}

Response samples

Content type
application/json
{}

Create an empty pack

Authorizations:
oAuth (admin:write)
query Parameters
name
required
string
Example: name=cofe

Pack Name

Responses

Response samples

Content type
application/json
"ok"

Frontend management

Retrieve a list of available frontends

Authorizations:
oAuth (admin:read)

Responses

Response samples

Content type
application/json
[]

Install a frontend

Authorizations:
oAuth (admin:read)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

build_dir
string
build_url
string
file
string
name
required
string
ref
string

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "build_dir": "string",
  • "build_url": "string",
  • "file": "string",
  • "name": "string",
  • "ref": "string"
}

Response samples

Content type
application/json
[]

Instance configuration

Retrieve config description

Authorizations:
oAuth (admin:read)
query Parameters
admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve instance configuration

Authorizations:
oAuth (admin:read)
query Parameters
only_db
boolean
Default: false

Get only saved in database settings

admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
{
  • "configs": [
    ],
  • "need_reboot": true
}

Update instance configuration

Authorizations:
oAuth (admin:write)
query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

Array of objects

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "configs": [
    ]
}

Response samples

Content type
application/json
{
  • "configs": [
    ],
  • "need_reboot": true
}

Instance documents

Delete an instance document

Authorizations:
oAuth (admin:write)
path Parameters
name
required
string

The document name

query Parameters
admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
{}

Retrieve an instance document

Authorizations:
oAuth (admin:read)
path Parameters
name
required
string

The document name

query Parameters
admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
{
  • "error": "Something went wrong"
}

Update an instance document

Authorizations:
oAuth (admin:write)
path Parameters
name
required
string

The document name

query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

file
required
string <binary>

The file to be uploaded, using multipart form data.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "file": "string"
}

Response samples

Content type
application/json
{}

Instance rule management

Delete rule

Authorizations:
oAuth (admin:write)
path Parameters
id
required
string

Rule ID

Responses

Response samples

Content type
application/json
{ }

Modify existing rule

Authorizations:
oAuth (admin:write)
path Parameters
id
required
string

Rule ID

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

hint
string
priority
integer
text
string

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "hint": "string",
  • "priority": 0,
  • "text": "string"
}

Response samples

Content type
application/json
{
  • "hint": "string",
  • "id": "string",
  • "priority": 0,
  • "text": "string"
}

Retrieve list of instance rules

Authorizations:
oAuth (admin:read)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create new rule

Authorizations:
oAuth (admin:write)
query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

hint
string
priority
integer
text
required
string

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "hint": "string",
  • "priority": 0,
  • "text": "string"
}

Response samples

Content type
application/json
{
  • "hint": "string",
  • "id": "string",
  • "priority": 0,
  • "text": "string"
}

Invites

Create an account registration invite token

Authorizations:
oAuth (admin:write:invites)
query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

expires_at
string <date>
max_use
integer

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "expires_at": "2020-04-20",
  • "max_use": 0
}

Response samples

Content type
application/json
{
  • "expires_at": null,
  • "id": 123,
  • "invite_type": "one_time",
  • "max_use": null,
  • "token": "kSQtDj_GNy2NZsL9AQDFIsHN5qdbguB6qRg3WHw6K1U=",
  • "used": true,
  • "uses": 0
}

Get a list of generated invites

Authorizations:
oAuth (admin:read:invites)
query Parameters
admin_token
string

Allows authorization via admin token.

Responses

Response samples

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

Sends registration invite via email

Authorizations:
oAuth (admin:write:invites)
query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

email
required
string <email>
name
string

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "email": "user@example.com",
  • "name": "string"
}

Response samples

Content type
application/json
""

Revoke invite by token

Authorizations:
oAuth (admin:write:invites)
query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

token
required
string

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "expires_at": null,
  • "id": 123,
  • "invite_type": "one_time",
  • "max_use": null,
  • "token": "kSQtDj_GNy2NZsL9AQDFIsHN5qdbguB6qRg3WHw6K1U=",
  • "used": true,
  • "uses": 0
}

MediaProxy cache

Remove a banned MediaProxy URL

Authorizations:
oAuth (admin:write:media_proxy_caches)
query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

urls
required
Array of strings <uri>

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{}

Response samples

Content type
application/json
{ }

Retrieve a list of banned MediaProxy URLs

Authorizations:
oAuth (admin:read:media_proxy_caches)
query Parameters
query
string

Page

page
integer
Default: 1

Page

page_size
integer
Default: 50

Number of statuses to return

admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
{}

Purge a URL from MediaProxy cache and optionally ban it

Authorizations:
oAuth (admin:write:media_proxy_caches)
query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

ban
boolean
Default: true
urls
required
Array of strings <uri>

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{}

Response samples

Content type
application/json
{ }

OAuth application management

Retrieve a list of OAuth applications

Authorizations:
oAuth (admin:write)
query Parameters
name
string

App name

client_id
string

Client ID

page
integer
Default: 1

Page

trusted
boolean
Default: false

Trusted apps

page_size
integer
Default: 50

Number of apps to return

admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
{
  • "apps": [],
  • "count": 1,
  • "page_size": 50
}

Create an OAuth application

Authorizations:
oAuth (admin:write)
query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

name
required
string

Application Name

redirect_uris
required
string

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
Array of strings

oAuth scopes

trusted
boolean Nullable
Default: false

Is the app trusted?

website
string Nullable

A URL to the homepage of the app

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{}

Response samples

Content type
application/json
{}

Delete OAuth application

Authorizations:
oAuth (admin:write)
path Parameters
id
required
integer
Example: 1337

App ID

query Parameters
admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
""

Update OAuth application

Authorizations:
oAuth (admin:write)
path Parameters
id
required
integer
Example: 1337

App ID

query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

name
string

Application Name

redirect_uris
string

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
Array of strings

oAuth scopes

trusted
boolean Nullable
Default: false

Is the app trusted?

website
string Nullable

A URL to the homepage of the app

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{}

Response samples

Content type
application/json
{}

Relays

Unfollow a relay

Authorizations:
oAuth (admin:write:follows)
query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

force
boolean
Default: false
relay_url
string <uri>

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{}

Response samples

Content type
application/json
"http://mastodon.example.org/users/admin"

Retrieve a list of relays

Authorizations:
oAuth (admin:read)
query Parameters
admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
{}

Follow a relay

Authorizations:
oAuth (admin:write:follows)
query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

relay_url
string <uri>

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{}

Response samples

Content type
application/json
{}

Report management

Retrieve a list of reports

Authorizations:
oAuth (admin:read:reports)
query Parameters
state
string
Enum: "open" "closed" "resolved"

Filter by report state

rule_id
string

Filter by selected rule id

limit
integer

The number of records to retrieve

page
integer
Default: 1

Page number

page_size
integer
Default: 50

Number number of log entries per page

admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
{
  • "reports": [
    ],
  • "total": 0
}

Change state of specified reports

Authorizations:
oAuth (admin:write:reports)
query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

required
Array of objects

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "reports": {
    }
}

Response samples

Content type
application/json
""

Retrieve a report

Authorizations:
oAuth (admin:read:reports)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Report ID

query Parameters
admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
{
  • "account": {
    },
  • "actor": {
    },
  • "content": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "notes": [
    ],
  • "rules": [
    ],
  • "state": "open",
  • "statuses": [
    ]
}

Add a note to the report

Authorizations:
oAuth (admin:write:reports)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Report ID

query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

content
string

The message

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "content": "string"
}

Response samples

Content type
application/json
""

Delete note attached to the report

Authorizations:
oAuth (admin:write:reports)
path Parameters
report_id
required
string

Report ID

id
required
string

Note ID

query Parameters
admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
""

Status administration

Get all statuses

Authorizations:
oAuth (admin:read:statuses)
query Parameters
godmode
boolean
Default: false

Allows to see private statuses

local_only
boolean
Default: false

Excludes remote statuses

with_reblogs
boolean
Default: false

Allows to see reblogs

page
integer
Default: 1

Page

page_size
integer
Default: 50

Number of statuses to return

admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete status

Authorizations:
oAuth (admin:write:statuses)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

query Parameters
admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
{ }

Get status

Authorizations:
oAuth (admin:read:statuses)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

query Parameters
admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
Example
Status
Status
{
  • "account": {
    },
  • "application": null,
  • "bookmarked": false,
  • "card": null,
  • "content": "foobar",
  • "created_at": "2020-04-07T19:48:51.000Z",
  • "emojis": [ ],
  • "favourited": false,
  • "favourites_count": 0,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "in_reply_to_account_id": null,
  • "in_reply_to_id": null,
  • "language": null,
  • "media_attachments": [ ],
  • "mentions": [ ],
  • "muted": false,
  • "pinned": false,
  • "pleroma": {
    },
  • "poll": null,
  • "reblog": null,
  • "reblogged": false,
  • "reblogs_count": 0,
  • "replies_count": 0,
  • "sensitive": false,
  • "spoiler_text": "",
  • "tags": [ ],
  • "uri": "http://localhost:4001/objects/0f5dad44-0e9e-4610-b377-a2631e499190",
  • "url": "http://localhost:4001/notice/9toJCu5YZW7O7gfvH6",
  • "visibility": "private"
}

Change the scope of a status

Authorizations:
oAuth (admin:write:statuses)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

sensitive
boolean

Mark status and attached media as sensitive?

visibility
string (VisibilityScope)
Enum: "public" "unlisted" "local" "private" "direct" "list"

Status visibility

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "sensitive": "false",
  • "visibility": "private"
}

Response samples

Content type
application/json
{
  • "account": {
    },
  • "application": null,
  • "bookmarked": false,
  • "card": null,
  • "content": "foobar",
  • "created_at": "2020-04-07T19:48:51.000Z",
  • "emojis": [ ],
  • "favourited": false,
  • "favourites_count": 0,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "in_reply_to_account_id": null,
  • "in_reply_to_id": null,
  • "language": null,
  • "media_attachments": [ ],
  • "mentions": [ ],
  • "muted": false,
  • "pinned": false,
  • "pleroma": {
    },
  • "poll": null,
  • "reblog": null,
  • "reblogged": false,
  • "reblogs_count": 0,
  • "replies_count": 0,
  • "sensitive": false,
  • "spoiler_text": "",
  • "tags": [ ],
  • "uri": "http://localhost:4001/objects/0f5dad44-0e9e-4610-b377-a2631e499190",
  • "url": "http://localhost:4001/notice/9toJCu5YZW7O7gfvH6",
  • "visibility": "private"
}

User administration

Deactivates multiple users

Authorizations:
oAuth (admin:write:accounts)
query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

nicknames
Array of strings

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "nicknames": [
    ]
}

Response samples

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

Unfollow

Authorizations:
oAuth (admin:write:follows)
query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

followed
string

Followed nickname

follower
string

Follower nickname

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "followed": "string",
  • "follower": "string"
}

Response samples

Content type
application/json
"string"

Toggle user activation

Authorizations:
oAuth (admin:write:accounts)
path Parameters
nickname
required
string

User nickname

query Parameters
admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
{
  • "actor_type": "string",
  • "avatar": "http://example.com",
  • "display_name": "string",
  • "email": "user@example.com",
  • "id": "string",
  • "is_active": true,
  • "is_approved": true,
  • "is_confirmed": true,
  • "local": true,
  • "nickname": "string",
  • "registration_reason": "string",
  • "roles": {
    },
  • "tags": [
    ],
  • "url": "http://example.com"
}

Unsuggest multiple users

Authorizations:
oAuth (admin:write:accounts)
query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

nicknames
Array of strings

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "nicknames": [
    ]
}

Response samples

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

Approve multiple users

Authorizations:
oAuth (admin:write:accounts)
query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

nicknames
Array of strings

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "nicknames": [
    ]
}

Response samples

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

Activate multiple users

Authorizations:
oAuth (admin:write:accounts)
query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

nicknames
Array of strings

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "nicknames": [
    ]
}

Response samples

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

Removes a single or multiple users

Authorizations:
oAuth (admin:write:accounts)
query Parameters
nickname
string

User nickname

admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

nicknames
Array of strings

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "nicknames": [
    ]
}

Response samples

Content type
application/json
[
  • "string"
]

List users

Authorizations:
oAuth (admin:read:accounts)
query Parameters
filters
string

Comma separated list of filters

query
string

Search users query

name
string

Search by display name

email
string

Search by email

page
integer

Page Number

page_size
integer

Number of users to return per page

actor_types
Array of strings (ActorType)
Items Enum: "Application" "Group" "Organization" "Person" "Service"

Filter by actor type

tags
Array of strings

Filter by tags

admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "page_size": 0,
  • "users": [
    ]
}

Create a single or multiple users

Authorizations:
oAuth (admin:write:accounts)
query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

Array of objects

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "users": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Show user

Authorizations:
oAuth (admin:read:accounts)
path Parameters
nickname
required
string

User nickname or ID

query Parameters
admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
{
  • "actor_type": "string",
  • "avatar": "http://example.com",
  • "display_name": "string",
  • "email": "user@example.com",
  • "id": "string",
  • "is_active": true,
  • "is_approved": true,
  • "is_confirmed": true,
  • "local": true,
  • "nickname": "string",
  • "registration_reason": "string",
  • "roles": {
    },
  • "tags": [
    ],
  • "url": "http://example.com"
}

Suggest multiple users

Authorizations:
oAuth (admin:write:accounts)
query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

nicknames
Array of strings

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "nicknames": [
    ]
}

Response samples

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

Follow

Authorizations:
oAuth (admin:write:follows)
query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

followed
string

Followed nickname

follower
string

Follower nickname

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "followed": "string",
  • "follower": "string"
}

Response samples

Content type
application/json
"string"

Announcement management

Delete one announcement

Authorizations:
oAuth (admin:write)
path Parameters
id
required
string

announcement id

query Parameters
admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
{ }

Display one announcement

Authorizations:
oAuth (admin:read)
path Parameters
id
required
string

announcement id

query Parameters
admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
{
  • "all_day": true,
  • "content": "string",
  • "emojis": [ ],
  • "ends_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "mentions": [ ],
  • "pleroma": {
    },
  • "published_at": "2019-08-24T14:15:22Z",
  • "reactions": [ ],
  • "read": true,
  • "starts_at": "2019-08-24T14:15:22Z",
  • "statuses": [ ],
  • "tags": [ ],
  • "updated_at": "2019-08-24T14:15:22Z"
}

Change one announcement

Authorizations:
oAuth (admin:write)
path Parameters
id
required
string

announcement id

query Parameters
admin_token
string

Allows authorization via admin token.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

all_day
boolean
content
string
ends_at
string <date-time> Nullable
starts_at
string <date-time> Nullable

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "all_day": true,
  • "content": "string",
  • "ends_at": "2019-08-24T14:15:22Z",
  • "starts_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "all_day": true,
  • "content": "string",
  • "emojis": [ ],
  • "ends_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "mentions": [ ],
  • "pleroma": {
    },
  • "published_at": "2019-08-24T14:15:22Z",
  • "reactions": [ ],
  • "read": true,
  • "starts_at": "2019-08-24T14:15:22Z",
  • "statuses": [ ],
  • "tags": [ ],
  • "updated_at": "2019-08-24T14:15:22Z"
}

Retrieve a list of announcements

Authorizations:
oAuth (admin:read)
query Parameters
limit
integer >= 1

the maximum number of announcements to return

offset
integer >= 0

the offset of the first announcement to return

admin_token
string

Allows authorization via admin token.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create one announcement

Authorizations:
oAuth (admin:write)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

all_day
boolean
content
required
string
ends_at
string <date-time> Nullable
starts_at
string <date-time> Nullable

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "all_day": true,
  • "content": "string",
  • "ends_at": "2019-08-24T14:15:22Z",
  • "starts_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "all_day": true,
  • "content": "string",
  • "emojis": [ ],
  • "ends_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "mentions": [ ],
  • "pleroma": {
    },
  • "published_at": "2019-08-24T14:15:22Z",
  • "reactions": [ ],
  • "read": true,
  • "starts_at": "2019-08-24T14:15:22Z",
  • "statuses": [ ],
  • "tags": [ ],
  • "updated_at": "2019-08-24T14:15:22Z"
}

Applications

List applications

List the OAuth applications for the current user

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an application

Create a new application to obtain OAuth2 credentials

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

client_name
required
string

A name for your application.

redirect_uris
required
string

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
Default: "read"

Space separated list of scopes

website
string Nullable

A URL to the homepage of your app

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{}

Response samples

Content type
application/json
{
  • "client_id": "TWhM-tNSuncnqN7DBJmoyeLnk6K3iJJ71KKXxgL1hPM",
  • "client_secret": "ZEaFUFmF0umgBX1qKJDjaU99Q31lDkOU8NutzTOoliw",
  • "id": "123",
  • "name": "My App",
  • "vapid_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=",
  • "website": "https://myapp.com/"
}

Verify the application works

Confirm that the app's OAuth2 credentials work.

Authorizations:
oAuth (read)

Responses

Response samples

Content type
application/json
{
  • "name": "My App",
  • "vapid_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=",
  • "website": "https://myapp.com/"
}

Push subscriptions

Remove current subscription

Removes the current Web Push API subscription.

Authorizations:
oAuth (push)

Responses

Response samples

Content type
application/json
{ }

Get current subscription

View the PushSubscription currently associated with this access token.

Authorizations:
oAuth (push)

Responses

Response samples

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

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.

Authorizations:
oAuth (push)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

object Nullable
required
object

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "data": {
    },
  • "subscription": {
    }
}

Response samples

Content type
application/json
{
  • "alerts": {
    },
  • "endpoint": "https://yourdomain.example/listener",
  • "id": "328_183",
  • "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.

Authorizations:
oAuth (push)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

object Nullable

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "data": {
    }
}

Response samples

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

Account credentials

Change account email

Authorizations:
oAuth (write:accounts)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

email
required
string

New email. Set to blank to remove the user's email.

password
required
string

Current password

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Verify account credentials

Test to make sure that the user token works.

Authorizations:
oAuth (read:accounts)

Responses

Response samples

Content type
application/json
{
  • "acct": "string",
  • "avatar": "http://example.com",
  • "avatar_static": "http://example.com",
  • "block_expires_at": "2019-08-24T14:15:22Z",
  • "bot": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "display_name": "string",
  • "emojis": [],
  • "fields": [
    ],
  • "follow_requests_count": 0,
  • "followers_count": 0,
  • "following_count": 0,
  • "header": "http://example.com",
  • "header_static": "http://example.com",
  • "id": "string",
  • "is_active": true,
  • "is_confirmed": true,
  • "local": true,
  • "locked": true,
  • "mute_expires_at": "2019-08-24T14:15:22Z",
  • "nickname": "string",
  • "note": "string",
  • "pleroma": {
    },
  • "roles": {
    },
  • "source": {
    },
  • "statuses_count": 0,
  • "url": "http://example.com",
  • "username": "string"
}

Move account

Authorizations:
oAuth (write:accounts)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

password
required
string

Current password

target_account
required
string

The nickname of the target account to move to

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "password": "string",
  • "target_account": "string"
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Delete an alias from this account

Authorizations:
oAuth (write:accounts)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

alias
required
string

The nickname of the account to delete from aliases

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "alias": "string"
}

Response samples

Content type
application/json
{
  • "status": "success"
}

List account aliases

Authorizations:
oAuth (read:accounts)

Responses

Response samples

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

Add an alias to this account

Authorizations:
oAuth (write:accounts)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

alias
required
string

The nickname of the account to add to aliases

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "alias": "string"
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Update account credentials

Update the user's display and preferences.

Authorizations:
oAuth (write:accounts)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

boolean or string or integer Nullable

Whether the user accepts receiving chat messages.

actor_type
string (ActorType)
Enum: "Application" "Group" "Organization" "Person" "Service"
boolean or string or integer Nullable

Allows automatically follow moved following accounts

also_known_as
Array of strings Nullable

List of alternate ActivityPub IDs

avatar
string <binary> Nullable

Avatar image encoded using multipart/form-data

avatar_description
string Nullable

Avatar image description.

string or string Nullable

User's birthday

boolean or string or integer Nullable

Whether the account has a bot flag.

default_scope
string (VisibilityScope)
Enum: "public" "unlisted" "local" "private" "direct" "list"

Status visibility

boolean or string or integer Nullable

Discovery (listing, indexing) of this account by external services (search bots etc.) is allowed.

display_name
string Nullable

The display name to use for the profile.

Array of AccountAttributeField (objects) or object Nullable
header
string <binary> Nullable

Header image encoded using multipart/form-data

header_description
string Nullable

Header image description.

boolean or string or integer Nullable

user's favorites timeline will be hidden

boolean or string or integer Nullable

user's followers will be hidden

boolean or string or integer Nullable

user's follower count will be hidden

boolean or string or integer Nullable

user's follows will be hidden

boolean or string or integer Nullable

user's follow count will be hidden

boolean or string or integer Nullable

Whether manual approval of follow requests is required.

boolean or string or integer Nullable

html tags are stripped from all statuses requested from the API

note
string

The account bio.

pleroma_background_image
string <binary> Nullable

Sets the background image of the user.

pleroma_settings_store
object Nullable

Opaque user settings to be saved on the backend.

boolean or string or integer Nullable

User's birthday will be visible

boolean or string or integer Nullable

user's role (e.g admin, moderator) will be exposed to anyone in the API

boolean or string or integer Nullable

Skip filtering out broken threads

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "actor_type": "Person",
  • "allow_following_move": false,
  • "also_known_as": [],
  • "birthday": "2001-02-12",
  • "bot": false,
  • "default_scope": "private",
  • "discoverable": false,
  • "display_name": "cofe",
  • "fields_attributes": [
    ],
  • "hide_favorites": false,
  • "hide_followers": true,
  • "hide_followers_count": false,
  • "hide_follows": false,
  • "hide_follows_count": false,
  • "no_rich_text": false,
  • "note": "foobar",
  • "pleroma_settings_store": {
    },
  • "show_birthday": false,
  • "show_role": false,
  • "skip_thread_containment": false
}

Response samples

Content type
application/json
{
  • "acct": "string",
  • "avatar": "http://example.com",
  • "avatar_static": "http://example.com",
  • "block_expires_at": "2019-08-24T14:15:22Z",
  • "bot": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "display_name": "string",
  • "emojis": [],
  • "fields": [
    ],
  • "follow_requests_count": 0,
  • "followers_count": 0,
  • "following_count": 0,
  • "header": "http://example.com",
  • "header_static": "http://example.com",
  • "id": "string",
  • "is_active": true,
  • "is_confirmed": true,
  • "local": true,
  • "locked": true,
  • "mute_expires_at": "2019-08-24T14:15:22Z",
  • "nickname": "string",
  • "note": "string",
  • "pleroma": {
    },
  • "roles": {
    },
  • "source": {
    },
  • "statuses_count": 0,
  • "url": "http://example.com",
  • "username": "string"
}

Disable Account

Authorizations:
oAuth (write:accounts)
query Parameters
password
string

Password

Responses

Response samples

Content type
application/json
{
  • "status": "success"
}

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.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

required
boolean or string or integer

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.

bio
string Nullable
Default: ""

Bio

string or string Nullable

User's birthday

captcha_answer_data
string Nullable

Provider-specific captcha data

captcha_solution
string Nullable

Provider-specific captcha solution

captcha_token
string Nullable

Provider-specific captcha token

email
string <email> Nullable

The email address to be used for login. Required when account_activation_required is enabled.

fullname
string Nullable

Full name

language
string Nullable

User's preferred language for emails

locale
string Nullable

The language of the confirmation email that will be sent

password
required
string <password>

The password to be used for login

reason
string Nullable

Text that will be reviewed by moderators if registrations require manual approval

token
string Nullable

Invite token required when the registrations aren't public

username
required
string

The desired username for the account

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "agreement": "true",
  • "bio": "☕️",
  • "email": "cofe@example.com",
  • "password": "secret",
  • "username": "cofe"
}

Response samples

Content type
application/json
{
  • "access_token": "i9hAVVzGld86Pl5JtLtizKoXVvtTlSCJvwaugCxvZzk",
  • "created_at": 1585918714,
  • "expires_in": 600,
  • "me": "https://gensokyo.2hu/users/raymoo",
  • "refresh_token": "i9hAVVzGld86Pl5JtLtizKoXVvtTlSCJvwaugCxvZzz",
  • "scope": "read write follow push",
  • "token_type": "Bearer"
}

Delete Account

Authorizations:
oAuth (write:accounts)
query Parameters
password
string

Password

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

password
string <password>

The user's own password for confirmation.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "password": "prettyp0ony1313"
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Change account password

Authorizations:
oAuth (write:accounts)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

new_password
required
string

New password

new_password_confirmation
required
string

New password, confirmation

password
required
string

Current password

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "new_password": "string",
  • "new_password_confirmation": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Resend confirmation email

Expects email or nickname.

query Parameters
email
string
Example: email=cofe@cofe.io

Email of that needs to be verified

nickname
string
Example: nickname=cofefe

Nickname of user that needs to be verified

Responses

Response samples

Content type
application/json
""

Backups

List backups

Authorizations:
oAuth (read:backups)

Responses

Response samples

Content type
application/json
[]

Create a backup

Authorizations:
oAuth (read:backups)

Responses

Response samples

Content type
application/json
[]

Blocks and mutes

Retrieve list of mutes

Accounts the user has muted.

Authorizations:
oAuth (followread:mutes)
query Parameters
boolean or string or integer (BooleanLike)

Embed relationships into accounts. If this parameter is not set account's pleroma.relationship is going to be null.

max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve list of blocks

View your blocks. See also accounts/:id/{block,unblock}

Authorizations:
oAuth (read:blocks)
query Parameters
boolean or string or integer (BooleanLike)

Embed relationships into accounts. If this parameter is not set account's pleroma.relationship is going to be null.

max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Data import

Import follows

Authorizations:
oAuth (write:follow)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

required
string or string

STRING or FILE containing a whitespace-separated list of accounts to import.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "list": "string"
}

Response samples

Content type
application/json
"ok"

Import mutes

Authorizations:
oAuth (write:mutes)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

required
string or string

STRING or FILE containing a whitespace-separated list of accounts to import.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "list": "string"
}

Response samples

Content type
application/json
"ok"

Import blocks

Authorizations:
oAuth (write:blocks)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

required
string or string

STRING or FILE containing a whitespace-separated list of accounts to import.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "list": "string"
}

Response samples

Content type
application/json
"ok"

Domain blocks

Unblock a domain

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

Authorizations:
oAuth (followwrite:blocks)
query Parameters
domain
string

Domain name

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

domain
string

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "domain": "facebook.com"
}

Response samples

Content type
application/json
{ }

Retrieve a list of blocked domains

Authorizations:
oAuth (followread:blocks)

Responses

Response samples

Content type
application/json
[
  • "google.com",
  • "facebook.com"
]

Block a domain

Block a domain to:

  • hide all public posts from it
  • hide all notifications from it
  • remove all followers from it
  • prevent following new users from it (but does not remove existing follows)
Authorizations:
oAuth (followwrite:blocks)
query Parameters
domain
string

Domain name

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

domain
string

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "domain": "facebook.com"
}

Response samples

Content type
application/json
{ }

Follow requests

Reject follow request

Authorizations:
oAuth (followwrite:follows)
path Parameters
id
required
string
Example: 123

Conversation ID

Responses

Response samples

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

Retrieve follow requests

Authorizations:
oAuth (read:followsfollow)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Accept follow request

Authorizations:
oAuth (followwrite:follows)
path Parameters
id
required
string
Example: 123

Conversation ID

Responses

Response samples

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

Mascot

Retrieve mascot

Authorizations:
oAuth (read:accounts)

Responses

Response samples

Content type
application/json
{}

Set or clear mascot

Behaves exactly the same as POST /api/v1/upload. Can only accept images - any attempt to upload non-image files will be met with HTTP 415 Unsupported Media Type.

Authorizations:
oAuth (write:accounts)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

file
string <binary>

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "file": "string"
}

Response samples

Content type
application/json
{}

Markers

Get saved timeline position

Authorizations:
oAuth (read:statuses)
query Parameters
timeline
Array of strings
Items Enum: "home" "notifications"

Array of markers to fetch. If not provided, an empty object will be returned.

Responses

Response samples

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

Save position in timeline

Authorizations:
oAuth (followwrite:blocks)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

object Nullable
object Nullable

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "home": {
    }
}

Response samples

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

Notifications

Retrieve a notification

View information about a notification with a given ID.

Authorizations:
oAuth (read:notifications)
path Parameters
id
required
string
Example: 123

Notification ID

Responses

Response samples

Content type
application/json
{
  • "account": {
    },
  • "created_at": "2019-11-23T07:49:02.064Z",
  • "group-key": "ungrouped-34975861",
  • "id": "34975861",
  • "pleroma": {
    },
  • "status": {
    },
  • "type": "mention"
}

Dismiss a single notification Deprecated

Clear a single notification from the server.

Authorizations:
oAuth (write:notifications)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

id
string

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "id": "string"
}

Response samples

Content type
application/json
{ }

Dismiss all notifications

Clear all notifications from the server.

Authorizations:
oAuth (write:notifications)

Responses

Response samples

Content type
application/json
{ }

Retrieve a list of 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.

Authorizations:
oAuth (read:notifications)
query Parameters
exclude_types
Array of strings
Items Enum: "follow" "favourite" "reblog" "mention" "pleroma:emoji_reaction" "pleroma:chat_mention" "pleroma:report" "move" "follow_request" "poll" "status" "update" "admin.sign_up" "admin.report"

Array of types to exclude

account_id
string

Return only notifications received from this account

exclude_visibilities
Array of strings (VisibilityScope)
Items Enum: "public" "unlisted" "local" "private" "direct" "list"

Exclude the notifications for activities with the given visibilities

include_types
Array of strings
Items Enum: "follow" "favourite" "reblog" "mention" "pleroma:emoji_reaction" "pleroma:chat_mention" "pleroma:report" "move" "follow_request" "poll" "status" "update" "admin.sign_up" "admin.report"

Deprecated, use types instead

types
Array of strings
Items Enum: "follow" "favourite" "reblog" "mention" "pleroma:emoji_reaction" "pleroma:chat_mention" "pleroma:report" "move" "follow_request" "poll" "status" "update" "admin.sign_up" "admin.report"

Include the notifications for activities with the given types

boolean or string or integer (BooleanLike)

Include the notifications from muted users

max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Mark notifications as read

Query parameters are mutually exclusive.

Authorizations:
oAuth (write:notifications)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

id
integer

A single notification ID to read

max_id
integer

Read all notifications up to this ID

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "id": 0,
  • "max_id": 0
}

Response samples

Content type
application/json
"string"

Dismiss a notification

Clear a single notification from the server.

Authorizations:
oAuth (write:notifications)
path Parameters
id
required
string
Example: 123

Notification ID

Responses

Response samples

Content type
application/json
{ }

Dismiss multiple notifications

Authorizations:
oAuth (write:notifications)
query Parameters
ids
required
Array of strings

Array of notification IDs to dismiss

Responses

Response samples

Content type
application/json
{ }

Filters

Remove a filter

Authorizations:
oAuth (write:filters)
path Parameters
id
required
string
Example: 123

Filter ID

Responses

Response samples

Content type
application/json
{ }

Filter

Authorizations:
oAuth (read:filters)
path Parameters
id
required
string
Example: 123

Filter ID

Responses

Response samples

Content type
application/json
{
  • "context": [
    ],
  • "expires_at": null,
  • "id": "5580",
  • "irreversible": true,
  • "phrase": "@twitter.com",
  • "whole_word": false
}

Update a filter

Authorizations:
oAuth (write:filters)
path Parameters
id
required
string
Example: 123

Filter ID

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

context
required
Array of strings
Items Enum: "home" "notifications" "public" "thread"

Array of enumerable strings home, notifications, public, thread. At least one context must be specified.

expires_in
integer Nullable

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

boolean or string or integer Nullable

Should the server irreversibly drop matching entities from home and notifications?

phrase
required
string

The text to be filtered

boolean or string or integer Nullable
Default: true

Consider word boundaries?

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "context": [
    ],
  • "phrase": "knights"
}

Response samples

Content type
application/json
{
  • "context": [
    ],
  • "expires_at": null,
  • "id": "5580",
  • "irreversible": true,
  • "phrase": "@twitter.com",
  • "whole_word": false
}

All filters

Authorizations:
oAuth (read:filters)

Responses

Response samples

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

Create a filter

Authorizations:
oAuth (write:filters)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

context
required
Array of strings
Items Enum: "home" "notifications" "public" "thread"

Array of enumerable strings home, notifications, public, thread. At least one context must be specified.

expires_in
integer Nullable

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

boolean or string or integer Nullable
Default: false

Should the server irreversibly drop matching entities from home and notifications?

phrase
required
string

The text to be filtered

boolean or string or integer Nullable
Default: true

Consider word boundaries?

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "context": [
    ],
  • "phrase": "knights"
}

Response samples

Content type
application/json
{
  • "context": [
    ],
  • "expires_at": null,
  • "id": "5580",
  • "irreversible": true,
  • "phrase": "@twitter.com",
  • "whole_word": false
}

Settings

Update Notification Settings

Authorizations:
oAuth (write:accounts)
query Parameters
boolean or string or integer (BooleanLike)

blocks notifications from accounts you do not follow

boolean or string or integer (BooleanLike)

removes the contents of a message from the push notification

Responses

Response samples

Content type
application/json
{
  • "status": "success"
}

Get settings for an application

Get synchronized settings for an application

Authorizations:
oAuth (read:accounts)
path Parameters
app
required
string
Example: pleroma-fe

Application name

Responses

Response samples

Content type
application/json
{ }

Update settings for an application

Update synchronized settings for an application

Authorizations:
oAuth (write:accounts)
path Parameters
app
required
string
Example: pleroma-fe

Application name

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

object (SettingsUpdateRequest)

The settings object to be merged with the current settings. To remove a field, set it to null.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "config1": true,
  • "config2_to_unset": null
}

Response samples

Content type
application/json
{ }

Custom emojis

List all custom emojis

Responses

Response samples

Content type
application/json
{
  • "firefox": {
    }
}

Retrieve a list of custom emojis

Returns custom emojis that are available on the server.

Responses

Response samples

Content type
application/json
[]

Instance misc

Retrieve list of instance rules

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve instance information

Information about the server

Responses

Response samples

Content type
application/json
{
  • "avatar_upload_limit": 2000000,
  • "background_image": "/static/image.png",
  • "background_upload_limit": 4000000,
  • "banner_upload_limit": 4000000,
  • "description": "Pleroma: An efficient and flexible fediverse server",
  • "email": "lain@lain.com",
  • "languages": [
    ],
  • "max_toot_chars": 5000,
  • "poll_limits": {
    },
  • "registrations": false,
  • "rules": {
    },
  • "stats": {
    },
  • "thumbnail": "https://lain.com/instance/thumbnail.jpeg",
  • "title": "lain.com",
  • "upload_limit": 16000000,
  • "uri": "https://lain.com",
  • "urls": {
    },
  • "version": "2.7.2 (compatible; Pleroma 2.0.50-536-g25eec6d7-develop)"
}

Retrieve list of known instances

Responses

Response samples

Content type
application/json
[
  • "pleroma.site",
  • "lain.com",
  • "bikeshed.party"
]

Retrieve federation status

Information about instances deemed unreachable by the server

Responses

Response samples

Content type
application/json
{
  • "unreachable": {
    }
}

Retrieve supported languages matrix

Responses

Response samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}

Retrieve instance information

Information about the server

Responses

Response samples

Content type
application/json
{
  • "configuration": {
    },
  • "description": "string",
  • "domain": "string",
  • "email": "user@example.com",
  • "languages": [
    ],
  • "registrations": {
    },
  • "source_url": "string",
  • "stats": {
    },
  • "thumbnail": {
    },
  • "title": "string",
  • "urls": { },
  • "usage": {
    },
  • "version": "string"
}

Chats

Retrieve chat's messages

Authorizations:
oAuth (read:chats)
path Parameters
id
required
string

The ID of the Chat

query Parameters
max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

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

Post a message to the chat

Authorizations:
oAuth (write:chats)
path Parameters
id
required
string

The ID of the Chat

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

content
string

The content of your message. Optional if media_id is present

media_id
string

The id of an upload

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "content": "Hey wanna buy feet pics?",
  • "media_id": "134234"
}

Response samples

Content type
application/json
{}

Mark a message as read

Authorizations:
oAuth (write:chats)
path Parameters
id
required
string

The ID of the Chat

message_id
required
string

The ID of the message

Responses

Response samples

Content type
application/json
{}

Retrieve list of chats (unpaginated) Deprecated

Deprecated due to no support for pagination. Using /api/v2/pleroma/chats instead is recommended.

Authorizations:
oAuth (read:chats)
query Parameters
boolean or string or integer (BooleanLike)

Include chats from muted users

Responses

Response samples

Content type
application/json
[]

Mark all messages in the chat as read

Authorizations:
oAuth (write:chats)
path Parameters
id
required
string

The ID of the Chat

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

last_read_id
required
string

The content of your message.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "last_read_id": "abcdef12456"
}

Response samples

Content type
application/json
{}

Retrieve list of chats

Authorizations:
oAuth (read:chats)
query Parameters
boolean or string or integer (BooleanLike)

Include chats from muted users

max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[]

Delete message

Authorizations:
oAuth (write:chats)
path Parameters
id
required
string

The ID of the Chat

message_id
required
string

The ID of the message

Responses

Response samples

Content type
application/json
{}

Create a chat

Authorizations:
oAuth (write:chats)
path Parameters
id
required
string
Example: someflakeid

The account id of the recipient of this chat

Responses

Response samples

Content type
application/json
{}

Retrieve a chat

Authorizations:
oAuth (read)
path Parameters
id
required
string
Example: 1234

The id of the chat

Responses

Response samples

Content type
application/json
{}

Conversations

Remove conversation

Authorizations:
oAuth (write:conversations)
path Parameters
id
required
string
Example: 123

Conversation ID

Responses

Response samples

Content type
application/json
{ }

Marks all conversations as read

Authorizations:
oAuth (write:conversations)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List of conversations

Authorizations:
oAuth (read:statuses)
query Parameters
recipients
Array of strings (FlakeID)

Only return conversations with the given recipients (a list of user ids)

max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Mark conversation as read

Authorizations:
oAuth (write:conversations)
path Parameters
id
required
string
Example: 123

Conversation ID

Responses

Response samples

Content type
application/json
{
  • "accounts": [
    ],
  • "id": "418450",
  • "last_status": {
    },
  • "unread": true
}

Timeline for conversation

Authorizations:
oAuth (read:statuses)
path Parameters
id
required
string
Example: 123

Conversation ID

query Parameters
max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Conversation

Authorizations:
oAuth (read:statuses)
path Parameters
id
required
string
Example: 123

Conversation ID

Responses

Response samples

Content type
application/json
{
  • "accounts": [
    ],
  • "id": "418450",
  • "last_status": {
    },
  • "unread": true
}

Update conversation

Change set of recipients for the conversation.

Authorizations:
oAuth (write:conversations)
path Parameters
id
required
string
Example: 123

Conversation ID

query Parameters
recipients
required
Array of strings (FlakeID)

A list of ids of users that should receive posts to this conversation. This will replace the current list of recipients, so submit the full list. The owner of owner of the conversation will always be part of the set of recipients, though.

Responses

Response samples

Content type
application/json
{
  • "accounts": [
    ],
  • "id": "418450",
  • "last_status": {
    },
  • "unread": true
}

Emoji reactions

Remove a reaction to a post with a unicode emoji

Authorizations:
oAuth (write:statuses)
path Parameters
id
required
string (FlakeID)

Status ID

emoji
required
string

A single character unicode emoji

Responses

Response samples

Content type
application/json
{
  • "account": {
    },
  • "application": null,
  • "bookmarked": false,
  • "card": null,
  • "content": "foobar",
  • "created_at": "2020-04-07T19:48:51.000Z",
  • "emojis": [ ],
  • "favourited": false,
  • "favourites_count": 0,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "in_reply_to_account_id": null,
  • "in_reply_to_id": null,
  • "language": null,
  • "media_attachments": [ ],
  • "mentions": [ ],
  • "muted": false,
  • "pinned": false,
  • "pleroma": {
    },
  • "poll": null,
  • "reblog": null,
  • "reblogged": false,
  • "reblogs_count": 0,
  • "replies_count": 0,
  • "sensitive": false,
  • "spoiler_text": "",
  • "tags": [ ],
  • "uri": "http://localhost:4001/objects/0f5dad44-0e9e-4610-b377-a2631e499190",
  • "url": "http://localhost:4001/notice/9toJCu5YZW7O7gfvH6",
  • "visibility": "private"
}

Get an object of emoji to account mappings with accounts that reacted to the post

Authorizations:
oAuth (read:statuses)
path Parameters
id
required
string (FlakeID)

Status ID

emoji
string

Filter by a single unicode emoji

query Parameters
with_muted
boolean

Include reactions from muted acccounts.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

React to a post with a unicode emoji

Authorizations:
oAuth (write:statuses)
path Parameters
id
required
string (FlakeID)

Status ID

emoji
required
string

A single character unicode emoji

Responses

Response samples

Content type
application/json
{
  • "account": {
    },
  • "application": null,
  • "bookmarked": false,
  • "card": null,
  • "content": "foobar",
  • "created_at": "2020-04-07T19:48:51.000Z",
  • "emojis": [ ],
  • "favourited": false,
  • "favourites_count": 0,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "in_reply_to_account_id": null,
  • "in_reply_to_id": null,
  • "language": null,
  • "media_attachments": [ ],
  • "mentions": [ ],
  • "muted": false,
  • "pinned": false,
  • "pleroma": {
    },
  • "poll": null,
  • "reblog": null,
  • "reblogged": false,
  • "reblogs_count": 0,
  • "replies_count": 0,
  • "sensitive": false,
  • "spoiler_text": "",
  • "tags": [ ],
  • "uri": "http://localhost:4001/objects/0f5dad44-0e9e-4610-b377-a2631e499190",
  • "url": "http://localhost:4001/notice/9toJCu5YZW7O7gfvH6",
  • "visibility": "private"
}

Get an object of emoji to account mappings with accounts that reacted to the post

Authorizations:
oAuth (read:statuses)
path Parameters
id
required
string (FlakeID)

Status ID

emoji
string

Filter by a single unicode emoji

query Parameters
with_muted
boolean

Include reactions from muted acccounts.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Lists

Remove accounts from list

Authorizations:
oAuth (write:lists)
path Parameters
id
required
string
Example: 123

List ID

query Parameters
account_ids
Array of strings

Array of account IDs

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

account_ids
Array of strings (FlakeID)

Array of account IDs

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "account_ids": [
    ]
}

Response samples

Content type
application/json
{ }

Retrieve accounts in list

Authorizations:
oAuth (read:lists)
path Parameters
id
required
string
Example: 123

List ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add accounts to list

Add accounts to the given list.

Authorizations:
oAuth (write:lists)
path Parameters
id
required
string
Example: 123

List ID

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

account_ids
Array of strings (FlakeID)

Array of account IDs

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "account_ids": [
    ]
}

Response samples

Content type
application/json
{ }

Retrieve a list of lists

Fetch all lists that the user owns

Authorizations:
oAuth (read:lists)

Responses

Response samples

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

Create a list

Fetch the list with the given ID. Used for verifying the title of a list.

Authorizations:
oAuth (write:lists)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

title
required
string

List title

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "id": "12249",
  • "title": "Friends"
}

Delete a list

Authorizations:
oAuth (write:lists)
path Parameters
id
required
string
Example: 123

List ID

Responses

Response samples

Content type
application/json
{ }

Retrieve a list

Fetch the list with the given ID. Used for verifying the title of a list.

Authorizations:
oAuth (read:lists)
path Parameters
id
required
string
Example: 123

List ID

Responses

Response samples

Content type
application/json
{
  • "id": "12249",
  • "title": "Friends"
}

Update a list

Change the title of a list

Authorizations:
oAuth (write:lists)
path Parameters
id
required
string
Example: 123

List ID

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

title
required
string

List title

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "id": "12249",
  • "title": "Friends"
}

Polls

View a poll

Authorizations:
oAuth (read:statuses)
path Parameters
id
required
string (FlakeID)
Example: 123

Poll ID

Responses

Response samples

Content type
application/json
{
  • "emojis": [ ],
  • "expired": true,
  • "expires_at": "2019-12-05T04:05:08.302Z",
  • "id": "34830",
  • "multiple": false,
  • "options": [
    ],
  • "own_votes": [
    ],
  • "pleroma": {
    },
  • "voted": true,
  • "voters_count": 10,
  • "votes_count": 10
}

Vote on a poll

Authorizations:
oAuth (write:statuses)
path Parameters
id
required
string (FlakeID)
Example: 123

Poll ID

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

choices
required
Array of integers

Array of own votes containing index for each option (starting from 0)

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "choices": [
    ]
}

Response samples

Content type
application/json
{
  • "emojis": [ ],
  • "expired": true,
  • "expires_at": "2019-12-05T04:05:08.302Z",
  • "id": "34830",
  • "multiple": false,
  • "options": [
    ],
  • "own_votes": [
    ],
  • "pleroma": {
    },
  • "voted": true,
  • "voters_count": 10,
  • "votes_count": 10
}

Timelines

Bookmarked statuses

Statuses the user has bookmarked

Authorizations:
oAuth (read:bookmarks)
query Parameters
folder_id
string (FlakeID)

If provided, only display bookmarks from given folder

max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Favourited statuses

Statuses the user has favourited. Please note that you have to use the link headers to paginate this. You can not build the query parameters yourself.

Authorizations:
oAuth (read:favourites)
query Parameters
max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Direct timeline

View statuses with a “direct” scope addressed to the account. Using this endpoint is discouraged, please use conversations or chats.

Authorizations:
oAuth (read:statuses)
query Parameters
boolean or string or integer (BooleanLike)

Include activities by muted users

max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Establish streaming connection

Receive statuses in real-time via WebSocket.

You can specify the access token on the query string or through the sec-websocket-protocol header. Using the query string to authenticate is considered unsafe and should not be used unless you have to (e.g. to maintain your client's compatibility with Mastodon).

You may specify a stream on the query string. If you do so and you are connecting to a stream that requires logged-in users, you must specify the access token at the time of the connection (i.e. via query string or header).

Otherwise, you have the option to authenticate after you have established the connection through client-sent events.

The "Request body" section below describes what events clients can send through WebSocket, and the "Responses" section describes what events server will send through WebSocket.

Authorizations:
oAuth (read:statusesread:notifications)
query Parameters
instance
string (Domain name)
Example: instance=example.org

Domain name of the instance. Required when stream is public:remote or public:remote:media.

list
string (List id)
Example: list=some-id

The id of the list. Required when stream is list.

stream
string
Enum: "public" "public:local" "public:media" "public:local:media" "public:remote" "public:remote:media" "user" "user:pleroma_chat" "user:notification" "direct" "list" "hashtag"

The name of the stream.

tag
string (Hashtag name)
Example: tag=mew

The name of the hashtag. Required when stream is hashtag.

access_token
string
Example: access_token=some token

An OAuth access token with corresponding permissions.

header Parameters
connection
required
string

connection header

upgrade
required
string

upgrade header

sec-websocket-key
required
string

sec-websocket-key header

sec-websocket-version
required
string

sec-websocket-version header

sec-websocket-protocol
string
Example: some token

An OAuth access token with corresponding permissions.

Request Body schema: application/json

Client-sent events

One of
instance
string (Domain name)

Domain name of the instance. Required when stream is public:remote or public:remote:media.

list
string (List id)

The id of the list. Required when stream is list.

stream
required
string
Enum: "public" "public:local" "public:media" "public:local:media" "public:remote" "public:remote:media" "user" "user:pleroma_chat" "user:notification" "direct" "list" "hashtag"

The name of the stream.

tag
string (Hashtag name)

The name of the hashtag. Required when stream is hashtag.

type
required
string
Value: "subscribe"

Type of the event.

Responses

Request samples

Content type
application/json
Example
Subscribe
Subscribe
Unsubscribe
Authenticate
{
  • "list": "1",
  • "stream": "list",
  • "type": "subscribe"
}

Response samples

Content type
application/json
Example
New status
New status
Edit
Notification
Chat update
Follow relationships update
Conversation update
Delete
Server response
{
  • "event": "update",
  • "payload": "{\"account\":{\"acct\":\"nick6\",\"avatar\":\"http://localhost:4001/images/avi.png\",\"avatar_static\":\"http://localhost:4001/images/avi.png\",\"bot\":false,\"created_at\":\"2020-04-07T19:48:51.000Z\",\"display_name\":\"Test テスト User 6\",\"emojis\":[],\"fields\":[],\"followers_count\":1,\"following_count\":0,\"header\":\"http://localhost:4001/images/banner.png\",\"header_static\":\"http://localhost:4001/images/banner.png\",\"id\":\"9toJCsKN7SmSf3aj5c\",\"is_locked\":false,\"note\":\"Tester Number 6\",\"pleroma\":{\"background_image\":null,\"hide_favorites\":true,\"hide_followers\":false,\"hide_followers_count\":false,\"hide_follows\":false,\"hide_follows_count\":false,\"is_admin\":false,\"is_confirmed\":true,\"is_moderator\":false,\"relationship\":{\"blocked_by\":false,\"blocking\":false,\"domain_blocking\":false,\"endorsed\":false,\"followed_by\":false,\"following\":true,\"id\":\"9toJCsKN7SmSf3aj5c\",\"muting\":false,\"muting_notifications\":false,\"note\":\"\",\"notifying\":false,\"requested\":false,\"showing_reblogs\":true,\"subscribing\":false},\"skip_thread_containment\":false,\"tags\":[]},\"source\":{\"fields\":[],\"note\":\"Tester Number 6\",\"pleroma\":{\"actor_type\":\"Person\",\"discoverable\":false},\"sensitive\":false},\"statuses_count\":1,\"url\":\"http://localhost:4001/users/nick6\",\"username\":\"nick6\"},\"application\":null,\"bookmarked\":false,\"card\":null,\"content\":\"foobar\",\"created_at\":\"2020-04-07T19:48:51.000Z\",\"emojis\":[],\"favourited\":false,\"favourites_count\":0,\"id\":\"9toJCu5YZW7O7gfvH6\",\"in_reply_to_account_id\":null,\"in_reply_to_id\":null,\"language\":null,\"media_attachments\":[],\"mentions\":[],\"muted\":false,\"pinned\":false,\"pleroma\":{\"content\":{\"text/plain\":\"foobar\"},\"context\":\"http://localhost:4001/objects/8b4c0c80-6a37-4d2a-b1b9-05a19e3875aa\",\"conversation_id\":345972,\"direct_conversation_id\":null,\"emoji_reactions\":[],\"expires_at\":null,\"in_reply_to_account_acct\":null,\"local\":true,\"quotes_count\":0,\"spoiler_text\":{\"text/plain\":\"\"},\"thread_muted\":false},\"poll\":null,\"reblog\":null,\"reblogged\":false,\"reblogs_count\":0,\"replies_count\":0,\"sensitive\":false,\"spoiler_text\":\"\",\"tags\":[],\"uri\":\"http://localhost:4001/objects/0f5dad44-0e9e-4610-b377-a2631e499190\",\"url\":\"http://localhost:4001/notice/9toJCu5YZW7O7gfvH6\",\"visibility\":\"private\"}",
  • "stream": [
    ]
}

Hashtag timeline

View public statuses containing the given hashtag

Authorizations:
oAuth (read:statuses)
path Parameters
tag
required
string

Content of a #hashtag, not including # symbol.

query Parameters
any
Array of strings

Statuses that also includes any of these tags

all
Array of strings

Statuses that also includes all of these tags

none
Array of strings

Statuses that do not include these tags

boolean or string or integer
Default: false

Show only local statuses?

boolean or string or integer
Default: false

Show only statuses with media attached?

boolean or string or integer
Default: false

Show only remote statuses?

boolean or string or integer (BooleanLike)

Include activities by muted users

exclude_visibilities
Array of strings (VisibilityScope)
Items Enum: "public" "unlisted" "local" "private" "direct" "list"

Exclude the statuses with the given visibilities

max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Home timeline

View statuses from followed users

Authorizations:
oAuth (read:statuses)
query Parameters
boolean or string or integer
Default: false

Show only local statuses?

boolean or string or integer
Default: false

Show only remote statuses?

boolean or string or integer
Default: false

Show only statuses with media attached?

boolean or string or integer (BooleanLike)

Include activities by muted users

exclude_visibilities
Array of strings (VisibilityScope)
Items Enum: "public" "unlisted" "local" "private" "direct" "list"

Exclude the statuses with the given visibilities

reply_visibility
string
Enum: "following" "self"

Filter replies. Possible values: without parameter (default) shows all replies, following - replies directed to you or users you follow, self - replies directed to you.

max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Public timeline

Authorizations:
oAuth (read:statuses)
query Parameters
boolean or string or integer
Default: false

Show only local statuses?

instance
string

Show only statuses from the given domain

boolean or string or integer
Default: false

Show only statuses with media attached?

boolean or string or integer
Default: false

Show only remote statuses?

boolean or string or integer (BooleanLike)

Include activities by muted users

exclude_visibilities
Array of strings (VisibilityScope)
Items Enum: "public" "unlisted" "local" "private" "direct" "list"

Exclude the statuses with the given visibilities

reply_visibility
string
Enum: "following" "self"

Filter replies. Possible values: without parameter (default) shows all replies, following - replies directed to you or users you follow, self - replies directed to you.

max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List timeline

View statuses in the given list timeline

Authorizations:
oAuth (read:lists)
path Parameters
list_id
required
string

Local ID of the list in the database

query Parameters
boolean or string or integer (BooleanLike)

Include activities by muted users

boolean or string or integer
Default: false

Show only local statuses?

boolean or string or integer
Default: false

Show only remote statuses?

boolean or string or integer
Default: false

Show only statuses with media attached?

exclude_visibilities
Array of strings (VisibilityScope)
Items Enum: "public" "unlisted" "local" "private" "direct" "list"

Exclude the statuses with the given visibilities

max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve status information

Status history

View history of a status

Authorizations:
oAuth (read:statuses)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Reblogged by

View who reblogged a given status

Authorizations:
oAuth (read:accounts)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Translate status

Translate status with an external API

Authorizations:
oAuth (read:statuses)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

lang
string Nullable

Translation target language.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "lang": "string"
}

Response samples

Content type
application/json
{
  • "content": "Software für die nächste Generation der sozialen Medien.",
  • "detected_source_language": "en",
  • "provider": "Deepl"
}

Multiple statuses

Authorizations:
oAuth (read:statuses)
query Parameters
id
Array of strings (FlakeID)

Array of status IDs

ids
Array of strings (FlakeID)

Deprecated, use id instead

boolean or string or integer (BooleanLike)

Include reactions from muted acccounts.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Favourited by

View who favourited a given status

Authorizations:
oAuth (read:accounts)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Status

View information about a status

Authorizations:
oAuth (read:statuses)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

query Parameters
boolean or string or integer (BooleanLike)

Include reactions from muted acccounts.

Responses

Response samples

Content type
application/json
{
  • "account": {
    },
  • "application": null,
  • "bookmarked": false,
  • "card": null,
  • "content": "foobar",
  • "created_at": "2020-04-07T19:48:51.000Z",
  • "emojis": [ ],
  • "favourited": false,
  • "favourites_count": 0,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "in_reply_to_account_id": null,
  • "in_reply_to_id": null,
  • "language": null,
  • "media_attachments": [ ],
  • "mentions": [ ],
  • "muted": false,
  • "pinned": false,
  • "pleroma": {
    },
  • "poll": null,
  • "reblog": null,
  • "reblogged": false,
  • "reblogs_count": 0,
  • "replies_count": 0,
  • "sensitive": false,
  • "spoiler_text": "",
  • "tags": [ ],
  • "uri": "http://localhost:4001/objects/0f5dad44-0e9e-4610-b377-a2631e499190",
  • "url": "http://localhost:4001/notice/9toJCu5YZW7O7gfvH6",
  • "visibility": "private"
}

Parent and child statuses

View statuses above and below this status in the thread

Authorizations:
oAuth (read:statuses)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

Responses

Response samples

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

Quoted by

View quotes for a given status

Authorizations:
oAuth (read:statuses)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

query Parameters
max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Status source

View source of a status

Authorizations:
oAuth (read:statuses)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

Responses

Response samples

Content type
application/json
{
  • "content_type": "string",
  • "id": "string",
  • "spoiler_text": "string",
  • "text": "string"
}

Scheduled statuses

Cancel a scheduled status

Authorizations:
oAuth (write:statuses)
path Parameters
id
required
string (FlakeID)
Example: 123

Poll ID

Responses

Response samples

Content type
application/json
{ }

View a single scheduled status

Authorizations:
oAuth (read:statuses)
path Parameters
id
required
string (FlakeID)
Example: 123

Poll ID

Responses

Response samples

Content type
application/json
{
  • "id": "3221",
  • "media_attachments": [
    ],
  • "params": {
    },
  • "scheduled_at": "2019-12-05T12:33:01.000Z"
}

Schedule a status

Authorizations:
oAuth (write:statuses)
path Parameters
id
required
string (FlakeID)
Example: 123

Poll ID

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

scheduled_at
string <date-time>

ISO 8601 Datetime at which the status will be published. Must be at least 5 minutes into the future.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "scheduled_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": "3221",
  • "media_attachments": [
    ],
  • "params": {
    },
  • "scheduled_at": "2019-12-05T12:33:01.000Z"
}

View scheduled statuses

Authorizations:
oAuth (read:statuses)
query Parameters
max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Search

Search results

Authorizations:
oAuth (read:search)
query Parameters
account_id
string (FlakeID)

If provided, statuses returned will be authored only by this account

type
string
Enum: "accounts" "hashtags" "statuses"

Search type

q
required
string

What to search for

boolean or string or integer
Default: false

Attempt WebFinger lookup

boolean or string or integer
Default: false

Only include accounts that the user is following

boolean or string or integer (BooleanLike)

Embed relationships into accounts. If this parameter is not set account's pleroma.relationship is going to be null.

max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

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

Search results Deprecated

Authorizations:
oAuth (read:search)
query Parameters
account_id
string (FlakeID)

If provided, statuses returned will be authored only by this account

type
string
Enum: "accounts" "hashtags" "statuses"

Search type

q
required
string

The search query

boolean or string or integer
Default: false

Attempt WebFinger lookup

boolean or string or integer
Default: false

Only include accounts that the user is following

offset
integer

Offset

boolean or string or integer (BooleanLike)

Embed relationships into accounts. If this parameter is not set account's pleroma.relationship is going to be null.

max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

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

Status actions

Unmute conversation

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

Authorizations:
oAuth (write:mutes)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

Responses

Response samples

Content type
application/json
{
  • "account": {
    },
  • "application": null,
  • "bookmarked": false,
  • "card": null,
  • "content": "foobar",
  • "created_at": "2020-04-07T19:48:51.000Z",
  • "emojis": [ ],
  • "favourited": false,
  • "favourites_count": 0,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "in_reply_to_account_id": null,
  • "in_reply_to_id": null,
  • "language": null,
  • "media_attachments": [ ],
  • "mentions": [ ],
  • "muted": false,
  • "pinned": false,
  • "pleroma": {
    },
  • "poll": null,
  • "reblog": null,
  • "reblogged": false,
  • "reblogs_count": 0,
  • "replies_count": 0,
  • "sensitive": false,
  • "spoiler_text": "",
  • "tags": [ ],
  • "uri": "http://localhost:4001/objects/0f5dad44-0e9e-4610-b377-a2631e499190",
  • "url": "http://localhost:4001/notice/9toJCu5YZW7O7gfvH6",
  • "visibility": "private"
}

Undo reblog

Undo a reshare of a status

Authorizations:
oAuth (write:statuses)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

Responses

Response samples

Content type
application/json
{
  • "account": {
    },
  • "application": null,
  • "bookmarked": false,
  • "card": null,
  • "content": "foobar",
  • "created_at": "2020-04-07T19:48:51.000Z",
  • "emojis": [ ],
  • "favourited": false,
  • "favourites_count": 0,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "in_reply_to_account_id": null,
  • "in_reply_to_id": null,
  • "language": null,
  • "media_attachments": [ ],
  • "mentions": [ ],
  • "muted": false,
  • "pinned": false,
  • "pleroma": {
    },
  • "poll": null,
  • "reblog": null,
  • "reblogged": false,
  • "reblogs_count": 0,
  • "replies_count": 0,
  • "sensitive": false,
  • "spoiler_text": "",
  • "tags": [ ],
  • "uri": "http://localhost:4001/objects/0f5dad44-0e9e-4610-b377-a2631e499190",
  • "url": "http://localhost:4001/notice/9toJCu5YZW7O7gfvH6",
  • "visibility": "private"
}

Unpin from profile

Unfeature a status from the top of your profile

Authorizations:
oAuth (write:accounts)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

Responses

Response samples

Content type
application/json
{
  • "account": {
    },
  • "application": null,
  • "bookmarked": false,
  • "card": null,
  • "content": "foobar",
  • "created_at": "2020-04-07T19:48:51.000Z",
  • "emojis": [ ],
  • "favourited": false,
  • "favourites_count": 0,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "in_reply_to_account_id": null,
  • "in_reply_to_id": null,
  • "language": null,
  • "media_attachments": [ ],
  • "mentions": [ ],
  • "muted": false,
  • "pinned": false,
  • "pleroma": {
    },
  • "poll": null,
  • "reblog": null,
  • "reblogged": false,
  • "reblogs_count": 0,
  • "replies_count": 0,
  • "sensitive": false,
  • "spoiler_text": "",
  • "tags": [ ],
  • "uri": "http://localhost:4001/objects/0f5dad44-0e9e-4610-b377-a2631e499190",
  • "url": "http://localhost:4001/notice/9toJCu5YZW7O7gfvH6",
  • "visibility": "private"
}

Undo bookmark

Remove a status from your private bookmarks

Authorizations:
oAuth (write:bookmarks)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

Responses

Response samples

Content type
application/json
{
  • "account": {
    },
  • "application": null,
  • "bookmarked": false,
  • "card": null,
  • "content": "foobar",
  • "created_at": "2020-04-07T19:48:51.000Z",
  • "emojis": [ ],
  • "favourited": false,
  • "favourites_count": 0,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "in_reply_to_account_id": null,
  • "in_reply_to_id": null,
  • "language": null,
  • "media_attachments": [ ],
  • "mentions": [ ],
  • "muted": false,
  • "pinned": false,
  • "pleroma": {
    },
  • "poll": null,
  • "reblog": null,
  • "reblogged": false,
  • "reblogs_count": 0,
  • "replies_count": 0,
  • "sensitive": false,
  • "spoiler_text": "",
  • "tags": [ ],
  • "uri": "http://localhost:4001/objects/0f5dad44-0e9e-4610-b377-a2631e499190",
  • "url": "http://localhost:4001/notice/9toJCu5YZW7O7gfvH6",
  • "visibility": "private"
}

Publish new status

Post a new status

Authorizations:
oAuth (write:statuses)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

content_type
string Nullable

The MIME type of the status, it is transformed into HTML by the backend. You can get the list of the supported MIME types with the nodeinfo endpoint.

expires_in
integer Nullable

The number of seconds the posted activity should expire in. When a posted activity expires it will be deleted from the server, and a delete request for it will be federated. This needs to be longer than an hour.

in_reply_to_conversation_id
string Nullable

Will reply to a given conversation, addressing only the people who are part of the recipient set of that conversation. Sets the visibility to direct.

in_reply_to_id
string Nullable

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

language
string Nullable

ISO 639 language code for this status.

media_ids
Array of strings Nullable

Array of Attachment ids to be attached as media.

object Nullable
boolean or string or integer Nullable

If set to true the post won't be actually posted, but the status entity would still be rendered back. This could be useful for previewing rich text/custom emoji, for example

quote_id
string Nullable

ID of the status being quoted, if any

scheduled_at
string <date-time> Nullable

ISO 8601 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.

boolean or string or integer Nullable

Mark status and attached media as sensitive?

spoiler_text
string Nullable

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

status
string Nullable

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

to
Array of strings Nullable

A list of nicknames (like lain@soykaf.club or lain on the local server) that will be used to determine who is going to be addressed by this post. Using this will disable the implicit addressing by mentioned names in the status body, only the people in the to list will be addressed. The normal rules for for post visibility are not affected by this and will still apply

VisibilityScope (string) or string Nullable

Visibility of the posted status. Besides standard MastoAPI values (direct, private, unlisted or public) it can be used to address a List by setting it to list:LIST_ID

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "poll": {
    },
  • "sensitive": "false",
  • "status": "What time is it?"
}

Response samples

Content type
application/json
Example
Status
Status
ScheduledStatus
{
  • "account": {
    },
  • "application": null,
  • "bookmarked": false,
  • "card": null,
  • "content": "foobar",
  • "created_at": "2020-04-07T19:48:51.000Z",
  • "emojis": [ ],
  • "favourited": false,
  • "favourites_count": 0,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "in_reply_to_account_id": null,
  • "in_reply_to_id": null,
  • "language": null,
  • "media_attachments": [ ],
  • "mentions": [ ],
  • "muted": false,
  • "pinned": false,
  • "pleroma": {
    },
  • "poll": null,
  • "reblog": null,
  • "reblogged": false,
  • "reblogs_count": 0,
  • "replies_count": 0,
  • "sensitive": false,
  • "spoiler_text": "",
  • "tags": [ ],
  • "uri": "http://localhost:4001/objects/0f5dad44-0e9e-4610-b377-a2631e499190",
  • "url": "http://localhost:4001/notice/9toJCu5YZW7O7gfvH6",
  • "visibility": "private"
}

Mute conversation

Do not receive notifications for the thread that this status is part of.

Authorizations:
oAuth (write:mutes)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

query Parameters
expires_in
integer
Default: 0

Expire the mute in expires_in seconds. Default 0 for infinity

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

expires_in
integer Nullable
Default: 0

Expire the mute in expires_in seconds. Default 0 for infinity

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "expires_in": 0
}

Response samples

Content type
application/json
{
  • "account": {
    },
  • "application": null,
  • "bookmarked": false,
  • "card": null,
  • "content": "foobar",
  • "created_at": "2020-04-07T19:48:51.000Z",
  • "emojis": [ ],
  • "favourited": false,
  • "favourites_count": 0,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "in_reply_to_account_id": null,
  • "in_reply_to_id": null,
  • "language": null,
  • "media_attachments": [ ],
  • "mentions": [ ],
  • "muted": false,
  • "pinned": false,
  • "pleroma": {
    },
  • "poll": null,
  • "reblog": null,
  • "reblogged": false,
  • "reblogs_count": 0,
  • "replies_count": 0,
  • "sensitive": false,
  • "spoiler_text": "",
  • "tags": [ ],
  • "uri": "http://localhost:4001/objects/0f5dad44-0e9e-4610-b377-a2631e499190",
  • "url": "http://localhost:4001/notice/9toJCu5YZW7O7gfvH6",
  • "visibility": "private"
}

Delete

Delete one of your own statuses

Authorizations:
oAuth (write:statuses)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

Responses

Response samples

Content type
application/json
{
  • "account": {
    },
  • "application": null,
  • "bookmarked": false,
  • "card": null,
  • "content": "foobar",
  • "created_at": "2020-04-07T19:48:51.000Z",
  • "emojis": [ ],
  • "favourited": false,
  • "favourites_count": 0,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "in_reply_to_account_id": null,
  • "in_reply_to_id": null,
  • "language": null,
  • "media_attachments": [ ],
  • "mentions": [ ],
  • "muted": false,
  • "pinned": false,
  • "pleroma": {
    },
  • "poll": null,
  • "reblog": null,
  • "reblogged": false,
  • "reblogs_count": 0,
  • "replies_count": 0,
  • "sensitive": false,
  • "spoiler_text": "",
  • "tags": [ ],
  • "uri": "http://localhost:4001/objects/0f5dad44-0e9e-4610-b377-a2631e499190",
  • "url": "http://localhost:4001/notice/9toJCu5YZW7O7gfvH6",
  • "visibility": "private"
}

Update status

Change the content of a status

Authorizations:
oAuth (write:statuses)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

content_type
string Nullable

The MIME type of the status, it is transformed into HTML by the backend. You can get the list of the supported MIME types with the nodeinfo endpoint.

media_ids
Array of strings Nullable

Array of Attachment ids to be attached as media.

object Nullable
boolean or string or integer Nullable

Mark status and attached media as sensitive?

spoiler_text
string Nullable

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

status
string Nullable

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

to
Array of strings Nullable

A list of nicknames (like lain@soykaf.club or lain on the local server) that will be used to determine who is going to be addressed by this post. Using this will disable the implicit addressing by mentioned names in the status body, only the people in the to list will be addressed. The normal rules for for post visibility are not affected by this and will still apply

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "poll": {
    },
  • "sensitive": "false",
  • "status": "What time is it?"
}

Response samples

Content type
application/json
{
  • "account": {
    },
  • "application": null,
  • "bookmarked": false,
  • "card": null,
  • "content": "foobar",
  • "created_at": "2020-04-07T19:48:51.000Z",
  • "emojis": [ ],
  • "favourited": false,
  • "favourites_count": 0,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "in_reply_to_account_id": null,
  • "in_reply_to_id": null,
  • "language": null,
  • "media_attachments": [ ],
  • "mentions": [ ],
  • "muted": false,
  • "pinned": false,
  • "pleroma": {
    },
  • "poll": null,
  • "reblog": null,
  • "reblogged": false,
  • "reblogs_count": 0,
  • "replies_count": 0,
  • "sensitive": false,
  • "spoiler_text": "",
  • "tags": [ ],
  • "uri": "http://localhost:4001/objects/0f5dad44-0e9e-4610-b377-a2631e499190",
  • "url": "http://localhost:4001/notice/9toJCu5YZW7O7gfvH6",
  • "visibility": "private"
}

Undo favourite

Remove a status from your favourites list

Authorizations:
oAuth (write:favourites)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

Responses

Response samples

Content type
application/json
{
  • "account": {
    },
  • "application": null,
  • "bookmarked": false,
  • "card": null,
  • "content": "foobar",
  • "created_at": "2020-04-07T19:48:51.000Z",
  • "emojis": [ ],
  • "favourited": false,
  • "favourites_count": 0,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "in_reply_to_account_id": null,
  • "in_reply_to_id": null,
  • "language": null,
  • "media_attachments": [ ],
  • "mentions": [ ],
  • "muted": false,
  • "pinned": false,
  • "pleroma": {
    },
  • "poll": null,
  • "reblog": null,
  • "reblogged": false,
  • "reblogs_count": 0,
  • "replies_count": 0,
  • "sensitive": false,
  • "spoiler_text": "",
  • "tags": [ ],
  • "uri": "http://localhost:4001/objects/0f5dad44-0e9e-4610-b377-a2631e499190",
  • "url": "http://localhost:4001/notice/9toJCu5YZW7O7gfvH6",
  • "visibility": "private"
}

Bookmark

Privately bookmark a status

Authorizations:
oAuth (write:bookmarks)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

folder_id
string Nullable

ID of bookmarks folder, if any

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "folder_id": "string"
}

Response samples

Content type
application/json
{
  • "account": {
    },
  • "application": null,
  • "bookmarked": false,
  • "card": null,
  • "content": "foobar",
  • "created_at": "2020-04-07T19:48:51.000Z",
  • "emojis": [ ],
  • "favourited": false,
  • "favourites_count": 0,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "in_reply_to_account_id": null,
  • "in_reply_to_id": null,
  • "language": null,
  • "media_attachments": [ ],
  • "mentions": [ ],
  • "muted": false,
  • "pinned": false,
  • "pleroma": {
    },
  • "poll": null,
  • "reblog": null,
  • "reblogged": false,
  • "reblogs_count": 0,
  • "replies_count": 0,
  • "sensitive": false,
  • "spoiler_text": "",
  • "tags": [ ],
  • "uri": "http://localhost:4001/objects/0f5dad44-0e9e-4610-b377-a2631e499190",
  • "url": "http://localhost:4001/notice/9toJCu5YZW7O7gfvH6",
  • "visibility": "private"
}

Pin to profile

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

Authorizations:
oAuth (write:accounts)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

Responses

Response samples

Content type
application/json
{
  • "account": {
    },
  • "application": null,
  • "bookmarked": false,
  • "card": null,
  • "content": "foobar",
  • "created_at": "2020-04-07T19:48:51.000Z",
  • "emojis": [ ],
  • "favourited": false,
  • "favourites_count": 0,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "in_reply_to_account_id": null,
  • "in_reply_to_id": null,
  • "language": null,
  • "media_attachments": [ ],
  • "mentions": [ ],
  • "muted": false,
  • "pinned": false,
  • "pleroma": {
    },
  • "poll": null,
  • "reblog": null,
  • "reblogged": false,
  • "reblogs_count": 0,
  • "replies_count": 0,
  • "sensitive": false,
  • "spoiler_text": "",
  • "tags": [ ],
  • "uri": "http://localhost:4001/objects/0f5dad44-0e9e-4610-b377-a2631e499190",
  • "url": "http://localhost:4001/notice/9toJCu5YZW7O7gfvH6",
  • "visibility": "private"
}

Reblog

Share a status

Authorizations:
oAuth (write:statuses)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

visibility
string
Enum: "public" "unlisted" "local" "private" "direct" "list"

Status visibility

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "visibility": "public"
}

Response samples

Content type
application/json
{
  • "account": {
    },
  • "application": null,
  • "bookmarked": false,
  • "card": null,
  • "content": "foobar",
  • "created_at": "2020-04-07T19:48:51.000Z",
  • "emojis": [ ],
  • "favourited": false,
  • "favourites_count": 0,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "in_reply_to_account_id": null,
  • "in_reply_to_id": null,
  • "language": null,
  • "media_attachments": [ ],
  • "mentions": [ ],
  • "muted": false,
  • "pinned": false,
  • "pleroma": {
    },
  • "poll": null,
  • "reblog": null,
  • "reblogged": false,
  • "reblogs_count": 0,
  • "replies_count": 0,
  • "sensitive": false,
  • "spoiler_text": "",
  • "tags": [ ],
  • "uri": "http://localhost:4001/objects/0f5dad44-0e9e-4610-b377-a2631e499190",
  • "url": "http://localhost:4001/notice/9toJCu5YZW7O7gfvH6",
  • "visibility": "private"
}

Favourite

Add a status to your favourites list

Authorizations:
oAuth (write:favourites)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Status ID

Responses

Response samples

Content type
application/json
{
  • "account": {
    },
  • "application": null,
  • "bookmarked": false,
  • "card": null,
  • "content": "foobar",
  • "created_at": "2020-04-07T19:48:51.000Z",
  • "emojis": [ ],
  • "favourited": false,
  • "favourites_count": 0,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "in_reply_to_account_id": null,
  • "in_reply_to_id": null,
  • "language": null,
  • "media_attachments": [ ],
  • "mentions": [ ],
  • "muted": false,
  • "pinned": false,
  • "pleroma": {
    },
  • "poll": null,
  • "reblog": null,
  • "reblogged": false,
  • "reblogs_count": 0,
  • "replies_count": 0,
  • "sensitive": false,
  • "spoiler_text": "",
  • "tags": [ ],
  • "uri": "http://localhost:4001/objects/0f5dad44-0e9e-4610-b377-a2631e499190",
  • "url": "http://localhost:4001/notice/9toJCu5YZW7O7gfvH6",
  • "visibility": "private"
}

Media attachments

Upload media as attachment

Creates an attachment to be used with a new status.

Authorizations:
oAuth (write:media)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

description
string

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

file
required
string <binary>

The file to be attached, using multipart form data.

focus
string

Two floating points (x,y), comma-delimited, ranging from -1.0 to 1.0.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "description": "string",
  • "file": "string",
  • "focus": "string"
}

Response samples

Content type
application/json
{
  • "description": null,
  • "id": "1638338801",
  • "pleroma": {
    },
  • "preview_url": "someurl",
  • "remote_url": "someurl",
  • "text_url": "someurl",
  • "type": "image",
  • "url": "someurl"
}

Upload media as attachment (v2)

Creates an attachment to be used with a new status.

Authorizations:
oAuth (write:media)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

description
string

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

file
required
string <binary>

The file to be attached, using multipart form data.

focus
string

Two floating points (x,y), comma-delimited, ranging from -1.0 to 1.0.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "description": "string",
  • "file": "string",
  • "focus": "string"
}

Response samples

Content type
application/json
{
  • "description": null,
  • "id": "1638338801",
  • "pleroma": {
    },
  • "preview_url": "someurl",
  • "remote_url": "someurl",
  • "text_url": "someurl",
  • "type": "image",
  • "url": "someurl"
}

Attachment

Authorizations:
oAuth (read:media)
path Parameters
id
required
string

The ID of the Attachment entity

Responses

Response samples

Content type
application/json
{
  • "description": null,
  • "id": "1638338801",
  • "pleroma": {
    },
  • "preview_url": "someurl",
  • "remote_url": "someurl",
  • "text_url": "someurl",
  • "type": "image",
  • "url": "someurl"
}

Update attachment

Creates an attachment to be used with a new status.

Authorizations:
oAuth (write:media)
path Parameters
id
required
string

The ID of the Attachment entity

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

description
string

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

file
string <binary>

The file to be attached, using multipart form data.

focus
string

Two floating points (x,y), comma-delimited, ranging from -1.0 to 1.0.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "description": "string",
  • "file": "string",
  • "focus": "string"
}

Response samples

Content type
application/json
{
  • "description": null,
  • "id": "1638338801",
  • "pleroma": {
    },
  • "preview_url": "someurl",
  • "remote_url": "someurl",
  • "text_url": "someurl",
  • "type": "image",
  • "url": "someurl"
}

Bookmark folders

All bookmark folders

Authorizations:
oAuth (read:bookmarks)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a bookmark folder

Authorizations:
oAuth (write:bookmarks)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

emoji
string Nullable

Folder emoji

name
string

Folder name

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "emoji": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "emoji": null,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "name": "Read later"
}

Delete a bookmark folder

Authorizations:
oAuth (write:bookmarks)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Bookmark Folder ID

Responses

Response samples

Content type
application/json
{
  • "emoji": null,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "name": "Read later"
}

Update a bookmark folder

Authorizations:
oAuth (write:bookmarks)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Bookmark Folder ID

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

emoji
string Nullable

Folder emoji

name
string Nullable

Folder name

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "emoji": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "emoji": null,
  • "id": "9toJCu5YZW7O7gfvH6",
  • "name": "Read later"
}

Tags

Follow a hashtag

Follow a hashtag

Authorizations:
oAuth (write:follows)
path Parameters
id
required
string

Name of the hashtag

Responses

Response samples

Content type
application/json
{}

Followed hashtags

View a list of hashtags the currently authenticated user is following

Authorizations:
oAuth (read:follows)
query Parameters
max_id
integer

Return items older than this ID

min_id
integer

Return the oldest items newer than this ID

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[]

Hashtag

View a hashtag

Authorizations:
oAuth (read)
path Parameters
id
required
string

Name of the hashtag

Responses

Response samples

Content type
application/json
{}

Unfollow a hashtag

Unfollow a hashtag

Authorizations:
oAuth (write:follows)
path Parameters
id
required
string

Name of the hashtag

Responses

Response samples

Content type
application/json
{}

Emoji packs

Requests a local pack archive from the instance

query Parameters
name
required
string
Example: name=cofe

Pack Name

Responses

Response samples

Content type
application/json
{
  • "error": "Something went wrong"
}

Show emoji pack

query Parameters
name
required
string
Example: name=cofe

Pack Name

page
integer
Default: 1

Page

page_size
integer
Default: 30

Number of emoji to return

Responses

Response samples

Content type
application/json
{
  • "files": {
    },
  • "pack": {
    }
}

Lists local custom emoji packs

query Parameters
page
integer
Default: 1

Page

page_size
integer
Default: 50

Number of emoji packs to return

Responses

Response samples

Content type
application/json
{
  • "count": 1,
  • "packs": {
    }
}

Reports

Get an individual report

Authorizations:
oAuth (read:reports)
path Parameters
id
required
string (FlakeID)
Example: 9umDrYheeY451cQnEe

Report ID

Responses

Response samples

Content type
application/json
{
  • "account": {
    },
  • "actor": {
    },
  • "content": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "state": "open",
  • "statuses": [
    ]
}

Get a list of your own reports

Authorizations:
oAuth (read:reports)
query Parameters
state
string
Enum: "open" "closed" "resolved"

Filter by report state

limit
integer

The number of records to retrieve

page
integer
Default: 1

Page number

page_size
integer
Default: 50

Number number of log entries per page

Responses

Response samples

Content type
application/json
{
  • "reports": [
    ],
  • "total": 0
}

File a report

Report problematic users to your moderators

Authorizations:
oAuth (followwrite:reports)
Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

account_id
required
string

ID of the account to report

comment
string Nullable

Reason for the report

boolean or string or integer Nullable
Default: false

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

rule_ids
Array of strings Nullable

Array of rules

status_ids
Array of strings Nullable

Array of Statuses to attach to the report, for context

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "account_id": "123",
  • "comment": "bad status!",
  • "forward": "false",
  • "rule_ids": [
    ],
  • "status_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "action_taken": false,
  • "id": "123"
}

Suggestions

Follow suggestions (Not implemented)

Responses

Response samples

Content type
application/json
[ ]

Remove a suggestion

path Parameters
account_id
required
string

Account to dismiss

Responses

Response samples

Content type
application/json
{ }

Follow suggestions

Responses

Response samples

Content type
application/json
[ ]

Announcements

Mark one announcement as read

Authorizations:
oAuth (write:accounts)
path Parameters
id
required
string

announcement id

Responses

Response samples

Content type
application/json
{ }

Retrieve a list of announcements

Authorizations:
oAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Remote interaction

Remote interaction

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data

Parameters

ap_id
required
string

Profile or status ActivityPub ID

profile
required
string

Remote profile webfinger

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
multipart/form-data
{
  • "ap_id": "string",
  • "profile": "string"
}

Response samples

Content type
application/json
{ }

Show remote subscribe form

Responses

Remote Subscribe

Responses

Others

Quick status check on the instance

Authorizations:
oAuth (write:accounts)

Responses

Response samples

Content type
application/json
{ }

Profile directory

query Parameters
order
string

Order by recent activity or account creation

boolean or string or integer (BooleanLike)

Include local users only

max_id
string

Return items older than this ID

min_id
string

Return the oldest items newer than this ID

since_id
string

Return the newest items newer than this ID

offset
integer
Default: 0

Return items past this number of items

limit
integer
Default: 20

Maximum number of items to return. Will be ignored if it's more than 40

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a captcha

Responses

Response samples

Content type
application/json
{ }

Dump frontend configurations

Responses

Response samples

Content type
application/json
{
  • "property1": { },
  • "property2": { }
}