Authentication is required and the user must be an admin.
Configuration options:
[:auth, :enforce_oauth_admin_scope_usage]
— OAuth admin scope requirement toggle.
If true
, admin actions explicitly demand admin OAuth scope(s) presence in OAuth token (client app must support admin scopes).
If false
and token doesn't have admin scope(s), is_admin
user flag grants access to admin-specific actions.
Note that client app needs to explicitly support admin scopes and request them when obtaining auth token.GET /api/pleroma/admin/users
query
: string search term (e.g. nickname, domain, nickname@domain)filters
: string comma-separated string of filters:
local
: only local usersexternal
: only external usersactive
: only active usersdeactivated
: only deactivated usersis_admin
: users with admin roleis_moderator
: users with moderator rolepage
: integer page numberpage_size
: integer number of users per page (default is 50
)tags
: [string] tags listname
: string user display nameemail
: string user emailhttps://mypleroma.org/api/pleroma/admin/users?query=john&filters=local,active&page=1&page_size=10&tags[]=some_tag&tags[]=another_tag&name=display_name&email=email@example.com
{
"page_size": integer,
"count": integer,
"users": [
{
"deactivated": bool,
"id": integer,
"nickname": string,
"roles": {
"admin": bool,
"moderator": bool
},
"local": bool,
"tags": array,
"avatar": string,
"display_name": string
},
...
]
}
DELETE /api/pleroma/admin/users
nickname
DELETE /api/pleroma/admin/users
nicknames
POST
users
: [
{
nickname
,
email
,
password
}
]POST /api/pleroma/admin/users/follow
follower
: The nickname of the followerfollowed
: The nickname of the followedPOST /api/pleroma/admin/users/unfollow
follower
: The nickname of the followerfollowed
: The nickname of the followedPATCH /api/pleroma/admin/users/:nickname/toggle_activation
nickname
{
"deactivated": bool,
"id": integer,
"nickname": string
}
PUT /api/pleroma/admin/users/tag
nicknames
(array)tags
(array)DELETE /api/pleroma/admin/users/tag
nicknames
(array)tags
(array)GET /api/pleroma/admin/users/:nickname/permission_group
{
"is_moderator": bool,
"is_admin": bool
}
GET /api/pleroma/admin/users/:nickname/permission_group/:permission_group
Note: Available :permission_group
is currently moderator and admin. 404 is returned when the permission group doesn’t exist.
{
"is_moderator": bool,
"is_admin": bool
}
POST /api/pleroma/admin/users/:nickname/permission_group/:permission_group
{"error": "…"}
POST /api/pleroma/admin/users/permission_group/:permission_group
nicknames
: nicknames array{"error": "…"}
DELETE /api/pleroma/admin/users/:nickname/permission_group/:permission_group
DELETE /api/pleroma/admin/users/:nickname/permission_group/:permission_group
{"error": "…"}
DELETE /api/pleroma/admin/users/permission_group/:permission_group
nicknames
: nicknames array{"error": "…"}
PATCH /api/pleroma/admin/users/activate
nicknames
: nicknames array{
users: [
{
// user object
}
]
}
PATCH /api/pleroma/admin/users/deactivate
nicknames
: nicknames array{
users: [
{
// user object
}
]
}
GET /api/pleroma/admin/users/:nickname_or_id
nickname
or id
Not found
GET /api/pleroma/admin/users/:nickname_or_id/statuses
nickname
or id
page_size
: number of statuses to return (default is 20
)godmode
: true
/false
– allows to see private statuseswith_reblogs
: true
/false
– allows to see reblogs (default is false)Not found
GET /api/pleroma/admin/instances/:instance/statuses
instance
: instance namepage_size
: number of statuses to return (default is 20
)godmode
: true
/false
– allows to see private statuseswith_reblogs
: true
/false
– allows to see reblogs (default is false)Not found
GET /api/pleroma/admin/statuses
page_size
: number of statuses to return (default is 20
)local_only
: excludes remote statusesgodmode
: true
/false
– allows to see private statuseswith_reblogs
: true
/false
– allows to see reblogs (default is false)Not found
POST /api/pleroma/admin/relay
relay_url
DELETE /api/pleroma/admin/relay
relay_url
GET /api/pleroma/admin/relay
POST /api/pleroma/admin/users/invite_token
max_use
(integer)expires_at
(date string e.g. “2019-04-07”){
"id": integer,
"token": string,
"used": boolean,
"expires_at": date,
"uses": integer,
"max_use": integer,
"invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
}
GET /api/pleroma/admin/users/invites
{
"invites": [
{
"id": integer,
"token": string,
"used": boolean,
"expires_at": date,
"uses": integer,
"max_use": integer,
"invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
},
...
]
}
POST /api/pleroma/admin/users/revoke_invite
token
{
"id": integer,
"token": string,
"used": boolean,
"expires_at": date,
"uses": integer,
"max_use": integer,
"invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
}
POST /api/pleroma/admin/users/email_invite
email
name
, optionalGET /api/pleroma/admin/users/:nickname/password_reset
{
"token": "base64 reset token",
"link": "https://pleroma.social/api/pleroma/password_reset/url-encoded-base64-token"
}
PATCH /api/pleroma/admin/users/force_password_reset
nicknames
204
)GET /api/pleroma/admin/reports
state
: string the state of reports. Valid values are open
, closed
and resolved
limit
: integer the number of records to retrievepage
: integer page numberpage_size
: integer number of log entries per page (default is 50
){"error": "error_msg"}
when requested by anonymous or non-adminaccount
: the user who has been reportedactor
: the user who has sent the reportstatuses
: list of statuses that have been included to the report{
"totalReports" : 1,
"reports": [
{
"account": {
"acct": "user",
"avatar": "https://pleroma.example.org/images/avi.png",
"avatar_static": "https://pleroma.example.org/images/avi.png",
"bot": false,
"created_at": "2019-04-23T17:32:04.000Z",
"display_name": "User",
"emojis": [],
"fields": [],
"followers_count": 1,
"following_count": 1,
"header": "https://pleroma.example.org/images/banner.png",
"header_static": "https://pleroma.example.org/images/banner.png",
"id": "9i6dAJqSGSKMzLG2Lo",
"locked": false,
"note": "",
"pleroma": {
"confirmation_pending": false,
"hide_favorites": true,
"hide_followers": false,
"hide_follows": false,
"is_admin": false,
"is_moderator": false,
"relationship": {},
"tags": []
},
"source": {
"note": "",
"pleroma": {},
"sensitive": false
},
"tags": ["force_unlisted"],
"statuses_count": 3,
"url": "https://pleroma.example.org/users/user",
"username": "user"
},
"actor": {
"acct": "lain",
"avatar": "https://pleroma.example.org/images/avi.png",
"avatar_static": "https://pleroma.example.org/images/avi.png",
"bot": false,
"created_at": "2019-03-28T17:36:03.000Z",
"display_name": "Roger Braun",
"emojis": [],
"fields": [],
"followers_count": 1,
"following_count": 1,
"header": "https://pleroma.example.org/images/banner.png",
"header_static": "https://pleroma.example.org/images/banner.png",
"id": "9hEkA5JsvAdlSrocam",
"locked": false,
"note": "",
"pleroma": {
"confirmation_pending": false,
"hide_favorites": false,
"hide_followers": false,
"hide_follows": false,
"is_admin": false,
"is_moderator": false,
"relationship": {},
"tags": []
},
"source": {
"note": "",
"pleroma": {},
"sensitive": false
},
"tags": ["force_unlisted"],
"statuses_count": 1,
"url": "https://pleroma.example.org/users/lain",
"username": "lain"
},
"content": "Please delete it",
"created_at": "2019-04-29T19:48:15.000Z",
"id": "9iJGOv1j8hxuw19bcm",
"state": "open",
"statuses": [
{
"account": { ... },
"application": {
"name": "Web",
"website": null
},
"bookmarked": false,
"card": null,
"content": "<span class=\"h-card\"><a data-user=\"9hEkA5JsvAdlSrocam\" class=\"u-url mention\" href=\"https://pleroma.example.org/users/lain\">@<span>lain</span></a></span> click on my link <a href=\"https://www.google.com/\">https://www.google.com/</a>",
"created_at": "2019-04-23T19:15:47.000Z",
"emojis": [],
"favourited": false,
"favourites_count": 0,
"id": "9i6mQ9uVrrOmOime8m",
"in_reply_to_account_id": null,
"in_reply_to_id": null,
"language": null,
"media_attachments": [],
"mentions": [
{
"acct": "lain",
"id": "9hEkA5JsvAdlSrocam",
"url": "https://pleroma.example.org/users/lain",
"username": "lain"
},
{
"acct": "user",
"id": "9i6dAJqSGSKMzLG2Lo",
"url": "https://pleroma.example.org/users/user",
"username": "user"
}
],
"muted": false,
"pinned": false,
"pleroma": {
"content": {
"text/plain": "@lain click on my link https://www.google.com/"
},
"conversation_id": 28,
"in_reply_to_account_acct": null,
"local": true,
"spoiler_text": {
"text/plain": ""
}
},
"reblog": null,
"reblogged": false,
"reblogs_count": 0,
"replies_count": 0,
"sensitive": false,
"spoiler_text": "",
"tags": [],
"uri": "https://pleroma.example.org/objects/8717b90f-8e09-4b58-97b0-e3305472b396",
"url": "https://pleroma.example.org/notice/9i6mQ9uVrrOmOime8m",
"visibility": "direct"
}
]
}
]
}
GET /api/pleroma/admin/grouped_reports
date
: date of the latest reportaccount
: the user who has been reported (see /api/pleroma/admin/reports
for reference)status
: reported status (see /api/pleroma/admin/reports
for reference)actors
: users who had reported this status (see /api/pleroma/admin/reports
for reference)reports
: reports (see /api/pleroma/admin/reports
for reference) "reports": [
{
"date": "2019-10-07T12:31:39.615149Z",
"account": { ... },
"status": { ... },
"actors": [{ ... }, { ... }],
"reports": [{ ... }]
}
]
GET /api/pleroma/admin/reports/:id
id
{"error": "error_msg"}
"Not found"
PATCH /api/pleroma/admin/reports
`reports`: [
{
`id`, // required, report id
`state` // required, the new state. Valid values are `open`, `closed` and `resolved`
},
...
]
On failure:
[
{
`id`, // report id
`error` // error message
}
]
On success: 204
, empty response
POST /api/pleroma/admin/reports/:id/notes
id
: required, report idcontent
: required, the message"Invalid parameters"
when status
is missing204
, empty responsePOST /api/pleroma/admin/reports/:report_id/notes/:id
report_id
: required, report idid
: required, note id"Invalid parameters"
when status
is missing204
, empty responsePUT /api/pleroma/admin/statuses/:id
id
sensitive
: optional, valid values are true
or false
visibility
: optional, valid values are public
, private
and unlisted
"Unsupported visibility"
{"error": "error_msg"}
"Not found"
DELETE /api/pleroma/admin/statuses/:id
id
{"error": "error_msg"}
"Not found"
{}
GET /api/pleroma/admin/restart
"To use this endpoint you need to enable configuration from database."
{}
GET /api/pleroma/admin/config
If need_reboot
flag exists in response, instance must be restarted, so reboot time settings can take effect.
Only works when configuration from database is enabled.
only_db
: true (optional, get only saved in database settings)"To use this endpoint you need to enable configuration from database."
{
"configs": [
{
"group": ":pleroma",
"key": "Pleroma.Upload",
"value": []
}
],
"need_reboot": true
}
need_reboot - optional, if were changed reboot time settings.
POST /api/pleroma/admin/config
If need_reboot
flag exists in response, instance must be restarted, so reboot time settings can take effect.
Only works when configuration from database is enabled.
Some modifications are necessary to save the config settings correctly:
Pleroma.
, Phoenix.
, Tesla.
or strings like Oban
, Ueberauth
will be converted to modules;"Pleroma.Upload" -> Pleroma.Upload
"Oban" -> Oban
:
will be converted to atoms;":pleroma" -> :pleroma
tuple
key and array value will be converted to tuples;{"tuple": ["string", "Pleroma.Upload", []]} -> {"string", Pleroma.Upload, []}
[{"tuple": [":key1", "value"]}, {"tuple": [":key2", "value"]}] -> [key1: "value", key2: "value"]
Most of the settings will be applied in runtime
, this means that you don't need to restart the instance. But some settings are applied in compile time
and require a reboot of the instance, such as:
all settings inside these keys:
:hackney_pools
:connections_pool
:pools
:chat
partially settings inside these keys:
:seconds_valid
in Pleroma.Captcha
:proxy_remote
in Pleroma.Upload
:upload_limit
in :instance
Params:
configs
- array of config objectsgroup
- string (required)key
- string (required)value
- string, [], {} or {“tuple”: []} (required)delete
- true (optional, if setting must be deleted)subkeys
- array of strings (optional, only works when delete=true
parameter is passed, otherwise will be ignored)When a value have several nested settings, you can delete only some nested settings by passing a parameter subkeys
, without deleting all settings by key.
[subkey: val1, subkey2: val2, subkey3: val3] \\ initial value
{"group": ":pleroma", "key": "some_key", "delete": true, "subkeys": [":subkey", ":subkey3"]} \\ passing json for deletion
[subkey2: val2] \\ value after deletion
Most of the settings can be partially updated through merge old values with new values, except settings value of which is list or is not keyword.
Example of setting without keyword in value:
config :tesla, :adapter, Tesla.Adapter.Hackney
List of settings which support only full update by key:
@full_key_update [
{:pleroma, :ecto_repos},
{:quack, :meta},
{:mime, :types},
{:cors_plug, [:max_age, :methods, :expose, :headers]},
{:auto_linker, :opts},
{:swarm, :node_blacklist},
{:logger, :backends}
]
List of settings which support only full update by subkey:
@full_subkey_update [
{:pleroma, :assets, :mascots},
{:pleroma, :emoji, :groups},
{:pleroma, :workers, :retries},
{:pleroma, :mrf_subchain, :match_actor},
{:pleroma, :mrf_keyword, :replace}
]
Settings without explicit key must be sended in separate config object params.
config :quack,
level: :debug,
meta: [:all],
...
{
"configs": [
{"group": ":quack", "key": ":level", "value": ":debug"},
{"group": ":quack", "key": ":meta", "value": [":all"]},
...
]
}
{
"configs": [
{
"group": ":pleroma",
"key": "Pleroma.Upload",
"value": [
{"tuple": [":uploader", "Pleroma.Uploaders.Local"]},
{"tuple": [":filters", ["Pleroma.Upload.Filter.Dedupe"]]},
{"tuple": [":link_name", true]},
{"tuple": [":proxy_remote", false]},
{"tuple": [":proxy_opts", [
{"tuple": [":redirect_on_failure", false]},
{"tuple": [":max_body_length", 1048576]},
{"tuple": [":http", [
{"tuple": [":follow_redirect", true]},
{"tuple": [":pool", ":upload"]},
]]}
]
]},
{"tuple": [":dispatch", {
"tuple": ["/api/v1/streaming", "Pleroma.Web.MastodonAPI.WebsocketHandler", []]
}]}
]
}
]
}
"To use this endpoint you need to enable configuration from database."
{
"configs": [
{
"group": ":pleroma",
"key": "Pleroma.Upload",
"value": [...]
}
],
"need_reboot": true
}
need_reboot - optional, if were changed reboot time settings.
GET /api/pleroma/admin/config/descriptions
Loads json generated from config/descriptions.exs
.
[{
"group": ":pleroma", // string
"key": "ModuleName", // string
"type": "group", // string or list with possible values,
"description": "Upload general settings", // string
"children": [
{
"key": ":uploader", // string or module name `Pleroma.Upload`
"type": "module",
"description": "Module which will be used for uploads",
"suggestions": ["module1", "module2"]
},
{
"key": ":filters",
"type": ["list", "module"],
"description": "List of filter modules for uploads",
"suggestions": [
"module1", "module2", "module3"
]
}
]
}]
GET /api/pleroma/admin/moderation_log
page
: integer page numberpage_size
: integer number of log entries per page (default is 50
)start_date
: datetime (ISO 8601) filter logs by creation date, start from start_date
. Accepts datetime in ISO 8601 format (YYYY-MM-DDThh:mm:ss), e.g. 2005-08-09T18:31:42
end_date
: datetime (ISO 8601) filter logs by creation date, end by from end_date
. Accepts datetime in ISO 8601 format (YYYY-MM-DDThh:mm:ss), e.g. 2005-08-09T18:31:42user_id
: integer filter logs by actor's idsearch
: string search logs by the log message[
{
"data": {
"actor": {
"id": 1,
"nickname": "lain"
},
"action": "relay_follow"
},
"time": 1502812026, // timestamp
"message": "[2017-08-15 15:47:06] @nick0 followed relay: https://example.org/relay" // log message
}
]
POST /api/pleroma/admin/reload_emoji
PATCH /api/pleroma/admin/users/confirm_email
nicknames
PATCH /api/pleroma/admin/users/resend_confirmation_email
nicknames
GET /api/pleroma/admin/stats
{
"status_visibility": {
"direct": 739,
"private": 9,
"public": 17,
"unlisted": 14
}
}