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
.
/api/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/pleroma/follow_import
POST
list
: STRING or FILE containing a whitespace-separated list of accounts to follow/api/pleroma/captcha
GET
type
{"type": "kocaptcha", "token": "whatever", "url": "https://captcha.kotobank.ch/endpoint"}
/api/pleroma/delete_account
POST
password
: user's password{"status": "success"}
if the deletion was successful, {"error": "[error message]"}
otherwise{"error": "Invalid password."}
/api/pleroma/disable_account
POST
password
: user's password{"status": "success"}
if the account was successfully disabled, {"error": "[error message]"}
otherwise{"error": "Invalid password."}
/api/pleroma/accounts/mfa
GET
read:security
{"enabled": "false", "totp": false }
/api/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/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/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/pleroma/accounts/mfa/backup_codes
GET
write:security
{"codes": codes}
when successful, otherwise HTTP 422 {"error": "[error message]"}
/api/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
followers
: BOOLEAN field, receives notifications from followersfollows
: BOOLEAN field, receives notifications from people the user followsremote
: BOOLEAN field, receives notifications from people on remote instanceslocal
: BOOLEAN field, receives notifications from people on the local instanceprivacy_option
: 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/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/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/pleroma/emoji/packs/import
GET
GET /api/pleroma/emoji/packs/remote
GET
url
: url of the instance to get packs fromPOST /api/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/pleroma/emoji/packs/:name
POST
PATCH /api/pleroma/emoji/packs/:name
PATCH
metadata
: 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/pleroma/emoji/packs/:name
DELETE
POST /api/pleroma/emoji/packs/:name/files
POST
file
: 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/pleroma/emoji/packs/:name/files
PATCH
shortcode
: 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/pleroma/emoji/packs/:name/files
DELETE
shortcode
: emoji file shortcodeGET /api/pleroma/emoji/packs
GET
GET /api/pleroma/emoji/packs/:name
GET
files
and pack
keys with 200 status or 404 if the pack does not existGET /api/pleroma/emoji/packs/:name/archive
GET
GET /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 single character unicode emojiDELETE /api/v1/pleroma/statuses/:id/reactions/:emoji
DELETE
emoji
: A single character unicode emojiGET /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..."}]}
]