Requests that require it can be authenticated with an OAuth token, the _pleroma_key
cookie, or HTTP Basic Authentication.
Request parameters can be passed via query strings or as form data. Files must be uploaded as multipart/form-data
.
The /api/v1/pleroma/*
path is backwards compatible with /api/pleroma/*
(/api/pleroma/*
will be deprecated in the future).
/api/v1/pleroma/emoji
GET
{
"girlpower": {
"tags": [
"Finmoji"
],
"image_url": "/finmoji/128px/girlpower-128.png"
},
"education": {
"tags": [
"Finmoji"
],
"image_url": "/finmoji/128px/education-128.png"
},
"finnishlove": {
"tags": [
"Finmoji"
],
"image_url": "/finmoji/128px/finnishlove-128.png"
}
}
/api/v1/custom_emojis
but in a different format/api/v1/pleroma/follow_import
POST
list
: STRING or FILE containing a whitespace-separated list of accounts to follow/api/v1/pleroma/blocks_import
POST
list
: STRING or FILE containing a whitespace-separated list of accounts to block/api/v1/pleroma/mutes_import
POST
list
: STRING or FILE containing a whitespace-separated list of accounts to mute/api/v1/pleroma/captcha
GET
type
{"type": "kocaptcha", "token": "whatever", "url": "https://captcha.kotobank.ch/endpoint", "seconds_valid": 300}
/api/v1/pleroma/delete_account
POST
password
: user's password{"status": "success"}
if the deletion was successful, {"error": "[error message]"}
otherwise{"error": "Invalid password."}
/api/v1/pleroma/disable_account
POST
password
: user's password{"status": "success"}
if the account was successfully disabled, {"error": "[error message]"}
otherwise{"error": "Invalid password."}
/api/v1/pleroma/accounts/mfa
GET
read:security
{"enabled": "false", "totp": false }
/api/v1/pleroma/accounts/mfa/setup/totp
GET
write:security
{"key": [secret_key], "provisioning_uri": "[qr code uri]" }
when successful, otherwise returns HTTP 422 {"error": "error_msg"}
/api/v1/pleroma/accounts/mfa/confirm/totp
POST
write:security
password
: user's passwordcode
: token from TOTP App{}
if the enable was successful, HTTP 422 {"error": "[error message]"}
otherwise/api/v1/pleroma/accounts/mfa/totp
DELETE
write:security
password
: user's password{}
if the disable was successful, HTTP 422 {"error": "[error message]"}
otherwise{"error": "Invalid password."}
/api/v1/pleroma/accounts/mfa/backup_codes
GET
write:security
{"codes": codes}
when successful, otherwise HTTP 422 {"error": "[error message]"}
/api/v1/pleroma/admin/
See Admin-API
/api/v1/pleroma/notifications/read
POST
id
: a single notification id to readmax_id
: read all notifications up to this idmax_id
, only the first 80 read notifications will be returned./api/v1/pleroma/accounts/:id/subscribe
POST
id
: account id to subscribe to{"error": "error_msg"}
{
"id": "abcdefg",
"following": true,
"followed_by": false,
"blocking": false,
"muting": false,
"muting_notifications": false,
"subscribing": true,
"requested": false,
"domain_blocking": false,
"showing_reblogs": true,
"endorsed": false
}
/api/v1/pleroma/accounts/:id/unsubscribe
POST
id
: account id to unsubscribe from{"error": "error_msg"}
{
"id": "abcdefg",
"following": true,
"followed_by": false,
"blocking": false,
"muting": false,
"muting_notifications": false,
"subscribing": false,
"requested": false,
"domain_blocking": false,
"showing_reblogs": true,
"endorsed": false
}
/api/v1/pleroma/accounts/:id/favourites
GET
id
: the id of the account for whom to return resultslimit
: optional, the number of records to retrievesince_id
: optional, returns results that are more recent than the specified idmax_id
: optional, returns results that are older than the specified id{"error": "error_msg"}
[
{
"account": {
"id": "9hptFmUF3ztxYh3Svg",
"url": "https://pleroma.example.org/users/nick2",
"username": "nick2",
...
},
"application": {"name": "Web", "website": null},
"bookmarked": false,
"card": null,
"content": "This is :moominmamma: note 0",
"created_at": "2019-04-15T15:42:15.000Z",
"emojis": [],
"favourited": false,
"favourites_count": 1,
"id": "9hptFmVJ02khbzYJaS",
"in_reply_to_account_id": null,
"in_reply_to_id": null,
"language": null,
"media_attachments": [],
"mentions": [],
"muted": false,
"pinned": false,
"pleroma": {
"content": {"text/plain": "This is :moominmamma: note 0"},
"conversation_id": 13679,
"local": true,
"spoiler_text": {"text/plain": "2hu"}
},
"reblog": null,
"reblogged": false,
"reblogs_count": 0,
"replies_count": 0,
"sensitive": false,
"spoiler_text": "2hu",
"tags": [{"name": "2hu", "url": "/tag/2hu"}],
"uri": "https://pleroma.example.org/objects/198ed2a1-7912-4482-b559-244a0369e984",
"url": "https://pleroma.example.org/notice/9hptFmVJ02khbzYJaS",
"visibility": "public"
}
]
/api/v1/pleroma/accounts/update_*
/api/v1/pleroma/accounts/update_avatar
: Set/clear user avatar image/api/v1/pleroma/accounts/update_banner
: Set/clear user banner image/api/v1/pleroma/accounts/update_background
: Set/clear user background image/api/v1/pleroma/accounts/confirmation_resend
POST
email
: email of that needs to be verified/api/v1/pleroma/mascot
Method GET
Authentication: required
Response: JSON. Returns a mastodon media attachment entity.
Example response:
{
"id": "abcdefg",
"url": "https://pleroma.example.org/media/abcdefg.png",
"type": "image",
"pleroma": {
"mime_type": "image/png"
}
}
PUT
file
: Multipart image{"error": "error_msg"}
{
"id": "abcdefg",
"url": "https://pleroma.example.org/media/abcdefg.png",
"type": "image",
"pleroma": {
"mime_type": "image/png"
}
}
POST /api/v1/upload
.
Can only accept images - any attempt to upload non-image files will be met with HTTP 415 Unsupported Media Type
./api/pleroma/notification_settings
PUT
block_from_strangers
: BOOLEAN field, blocks notifications from accounts you do not followhide_notification_contents
: BOOLEAN field. When set to true, it removes the contents of a message from the push notification.{"status": "success"}
if the update was successful, otherwise returns {"error": "error_msg"}
/api/v1/pleroma/healthcheck
GET
{
"pool_size": 0, # database connection pool
"active": 0, # active processes
"idle": 0, # idle processes
"memory_used": 0.00, # Memory used
"healthy": true, # Instance state
"job_queue_stats": {} # Job queue stats
}
/api/v1/pleroma/change_email
POST
password
: user's passwordemail
: new email{"status": "success"}
if the change was successful, {"error": "[error message]"}
otherwisePleroma Conversations have the same general structure that Mastodon Conversations have. The behavior differs in the following ways when using these endpoints:
Conversations have the additional field recipients
under the pleroma
key. This holds a list of all the accounts that will receive a message in this conversation.
The status posting endpoint takes an additional parameter, in_reply_to_conversation_id
, which, when set, will set the visiblity to direct and address only the people who are the recipients of that Conversation.
⚠ Conversation IDs can be found in direct messages with the pleroma.direct_conversation_id
key, do not confuse it with pleroma.conversation_id
.
GET /api/v1/pleroma/conversations/:id/statuses
GET
GET /api/v1/pleroma/conversations/:id
GET
PATCH /api/v1/pleroma/conversations/:id
PATCH
recipients
: 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.POST /api/v1/pleroma/conversations/read
POST
GET /api/v1/pleroma/emoji/pack?name=:name
GET
page
: page number for files (default 1)page_size
: page size for files (default 30)files
, files_count
and pack
keys with 200 status or 404 if the pack does not exist.{
"files": {...},
"files_count": 0, // emoji count in pack
"pack": {...}
}
POST /api/v1/pleroma/emoji/pack?name=:name
POST
name
: pack namePATCH /api/v1/pleroma/emoji/pack?name=:name
PATCH
name
: pack namemetadata
: metadata to replace the old one
license
: Pack licensehomepage
: Pack home page urldescription
: Pack descriptionfallback-src
: Fallback url to download pack fromfallback-src-sha256
: SHA256 encoded for fallback pack archiveshare-files
: is pack allowed for sharing (boolean)DELETE /api/v1/pleroma/emoji/pack?name=:name
DELETE
name
: pack nameGET /api/v1/pleroma/emoji/packs/import
GET
GET /api/v1/pleroma/emoji/packs/remote
GET
url
: url of the instance to get packs frompage
: page number for packs (default 1)page_size
: page size for packs (default 50)POST /api/v1/pleroma/emoji/packs/download
POST
url
: url of the instance to download fromname
: pack to download from that instanceas
: (optional) name how to save packPOST /api/v1/pleroma/emoji/packs/files?name=:name
POST
name
: pack namefile
: file needs to be uploaded with the multipart request or link to remote file.shortcode
: (optional) shortcode for new emoji, must be unique for all emoji. If not sended, shortcode will be taken from original filename.filename
: (optional) new emoji file name. If not specified will be taken from original filename.PATCH /api/v1/pleroma/emoji/packs/files?name=:name
PATCH
name
: pack nameshortcode
: emoji file shortcodenew_shortcode
: new emoji file shortcodenew_filename
: new filename for emoji fileforce
: (optional) with true value to overwrite existing emoji with new shortcodeDELETE /api/v1/pleroma/emoji/packs/files?name=:name
DELETE
name
: pack nameshortcode
: emoji file shortcodeGET /api/v1/pleroma/emoji/packs
GET
page
: page number for packs (default 1)page_size
: page size for packs (default 50)packs
key with JSON hashmap of pack name to pack contents and count
key for count of packs.{
"packs": {
"pack_name": {...}, // pack contents
...
},
"count": 0 // packs count
}
GET /api/v1/pleroma/emoji/packs/archive?name=:name
GET
name
: pack nameGET /api/v1/pleroma/accounts/:id/scrobbles
GET
[
{
"account": {...},
"id": "1234",
"title": "Some Title",
"artist": "Some Artist",
"album": "Some Album",
"length": 180000,
"created_at": "2019-09-28T12:40:45.000Z"
}
]
POST /api/v1/pleroma/scrobble
POST
title
: the title of the media playingalbum
: the album of the media playing [optional]artist
: the artist of the media playing [optional]length
: the length of the media playing [optional]Emoji reactions work a lot like favourites do. They make it possible to react to a post with a single emoji character. To detect the presence of this feature, you can check pleroma_emoji_reactions
entry in the features list of nodeinfo.
PUT /api/v1/pleroma/statuses/:id/reactions/:emoji
PUT
emoji
: A unicode RGI emoji or a regional indicatorDELETE /api/v1/pleroma/statuses/:id/reactions/:emoji
DELETE
emoji
: A unicode RGI emoji or a regional indicatorGET /api/v1/pleroma/statuses/:id/reactions
GET
[
{"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]},
{"name": "☕", "count": 1, "me": false, "accounts": [{"id" => "abc..."}]}
]
GET /api/v1/pleroma/statuses/:id/reactions/:emoji
GET
[
{"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]}
]
POST /api/v1/pleroma/backups
POST
[{
"content_type": "application/zip",
"file_size": 0,
"inserted_at": "2020-09-10T16:18:03.000Z",
"processed": false,
"url": "https://example.com/media/backups/archive-foobar-20200910T161803-QUhx6VYDRQ2wfV0SdA2Pfj_2CLM_ATUlw-D5l5TJf4Q.zip"
}]
GET /api/v1/pleroma/backups
GET
[{
"content_type": "application/zip",
"file_size": 55457,
"inserted_at": "2020-09-10T16:18:03.000Z",
"processed": true,
"url": "https://example.com/media/backups/archive-foobar-20200910T161803-QUhx6VYDRQ2wfV0SdA2Pfj_2CLM_ATUlw-D5l5TJf4Q.zip"
}]