marcin mikołajczak 3419e2cbdd Correct response in AdminAPI docs

Signed-off-by: marcin mikołajczak <git@mkljczk.pl>

2024-08-28 18:28:22 +02:00

39 KiB

Raw Permalink Blame History

Admin API

Authentication is required and the user must be an admin.

The /api/v1/pleroma/admin/* path is backwards compatible with /api/pleroma/admin/* (/api/pleroma/admin/* will be deprecated in the future).

`GET /api/v1/pleroma/admin/users`

List users

Query Params:
- optional query: string search term (e.g. nickname, domain, nickname@domain)
- optional filters: string comma-separated string of filters:
  - local: only local users
  - external: only external users
  - active: only active users
  - need_approval: only unapproved users
  - unconfirmed: only unconfirmed users
  - deactivated: only deactivated users
  - is_admin: users with admin role
  - is_moderator: users with moderator role
- optional page: integer page number
- optional page_size: integer number of users per page (default is 50)
- optional tags: [string] tags list
- optional actor_types: [string] actor type list (Person, Service, Application)
- optional name: string user display name
- optional email: string user email
Example: https://mypleroma.org/api/v1/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
Response:

{
  "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,
      "confirmation_pending": bool,
      "approval_pending": bool,
      "registration_reason": string,
    },
    ...
  ]
}

DEPRECATED `DELETE /api/v1/pleroma/admin/users`

Remove a user

Params:
- nickname
Response: User’s nickname

`DELETE /api/v1/pleroma/admin/users`

Remove a user

Params:
- nicknames
Response: Array of user nicknames

Create a user

Method: POST
Params: users: [ { nickname, email, password } ]
Response: User’s nickname

`POST /api/v1/pleroma/admin/users/follow`

Make a user follow another user

Params:
- follower: The nickname of the follower
- followed: The nickname of the followed
Response:
- "ok"

`POST /api/v1/pleroma/admin/users/unfollow`

Make a user unfollow another user

Params:
- follower: The nickname of the follower
- followed: The nickname of the followed
Response:
- "ok"

`PATCH /api/v1/pleroma/admin/users/:nickname/toggle_activation`

Toggle user activation

Params:
- nickname
Response: User’s object

{
  "deactivated": bool,
  "id": integer,
  "nickname": string
}

`PUT /api/v1/pleroma/admin/users/tag`

Tag a list of users

Params:
- nicknames (array)
- tags (array)

`DELETE /api/v1/pleroma/admin/users/tag`

Untag a list of users

Params:
- nicknames (array)
- tags (array)

`GET /api/v1/pleroma/admin/users/:nickname/permission_group`

Get user user permission groups membership

Params: none
Response:

{
  "is_moderator": bool,
  "is_admin": bool
}

`GET /api/v1/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.

Get user user permission groups membership per permission group

Params: none
Response:

{
  "is_moderator": bool,
  "is_admin": bool
}

DEPRECATED `POST /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group`

Add user to permission group

Params: none
Response:
- On failure: {"error": "…"}
- On success: JSON of the user

`POST /api/v1/pleroma/admin/users/permission_group/:permission_group`

Add users to permission group

Params:
- nicknames: nicknames array
Response:
- On failure: {"error": "…"}
- On success: JSON of the user

DEPRECATED `DELETE /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group`

`DELETE /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group`

Remove user from permission group

Params: none
Response:
- On failure: {"error": "…"}
- On success: JSON of the user
Note: An admin cannot revoke their own admin status.

`DELETE /api/v1/pleroma/admin/users/permission_group/:permission_group`

Remove users from permission group

Params:
- nicknames: nicknames array
Response:
- On failure: {"error": "…"}
- On success: JSON of the user
Note: An admin cannot revoke their own admin status.

`PATCH /api/v1/pleroma/admin/users/activate`

Activate user

Params:
- nicknames: nicknames array
Response:

{
  users: [
    {
      // user object
    }
  ]
}

`PATCH /api/v1/pleroma/admin/users/deactivate`

Deactivate user

Params:
- nicknames: nicknames array
Response:

{
  users: [
    {
      // user object
    }
  ]
}

`PATCH /api/v1/pleroma/admin/users/approve`

Approve user

Params:
- nicknames: nicknames array
Response:

{
  users: [
    {
      // user object
    }
  ]
}

`PATCH /api/v1/pleroma/admin/users/suggest`

Suggest a user

Adds the user(s) to follower recommendations.

Params:
- nicknames: nicknames array
Response:

{
  users: [
    {
      // user object
    }
  ]
}

`PATCH /api/v1/pleroma/admin/users/unsuggest`

Unsuggest a user

Removes the user(s) from follower recommendations.

Params:
- nicknames: nicknames array
Response:

{
  users: [
    {
      // user object
    }
  ]
}

`GET /api/v1/pleroma/admin/users/:nickname_or_id`

Retrieve the details of a user

Params:
- nickname or id
Response:
- On failure: Not found
- On success: JSON of the user

`GET /api/v1/pleroma/admin/users/:nickname_or_id/statuses`

Retrieve user's latest statuses

Params:
- nickname or id
- optional page_size: number of statuses to return (default is 20)
- optional godmode: true/false – allows to see private statuses
- optional with_reblogs: true/false – allows to see reblogs (default is false)
Response:
- On failure: Not found
On success: JSON, where:
- total: total count of the statuses for the user
- activities: list of the statuses for the user

{
  "total" : 1,
  "activities": [
    // activities list
  ]
}

`GET /api/v1/pleroma/admin/instances/:instance/statuses`

Retrieve instance's latest statuses

Params:
- instance: instance name
- optional page_size: number of statuses to return (default is 20)
- optional godmode: true/false – allows to see private statuses
- optional with_reblogs: true/false – allows to see reblogs (default is false)
Response:
- On failure: Not found
- On success: JSON, where:
  - total: total count of the statuses for the instance
  - activities: list of the statuses for the instance

{
  "total" : 1,
  "activities": [
    // activities list
  ]
}

`DELETE /api/v1/pleroma/admin/instances/:instance`

Delete all users and activities from a remote instance

Note: this will trigger a job to remove instance content in the background. It may take some time.

Params:
- instance: remote instance host
Response:
- The instance name as a string

"lain.com"

`GET /api/v1/pleroma/admin/statuses`

Retrieves all latest statuses

Params:
- optional page_size: number of statuses to return (default is 20)
- optional local_only: excludes remote statuses
- optional godmode: true/false – allows to see private statuses
- optional with_reblogs: true/false – allows to see reblogs (default is false)
Response:
- On failure: Not found
- On success: JSON array of user's latest statuses

`GET /api/v1/pleroma/admin/relay`

List Relays

Params: none Response:

On success: JSON array of relays

[
  {"actor": "https://example.com/relay", "followed_back": true},
  {"actor": "https://example2.com/relay", "followed_back": false}
]

`POST /api/v1/pleroma/admin/relay`

Follow a Relay

Params:

relay_url

Response:

On success: relay json object

{"actor": "https://example.com/relay", "followed_back": true}

`DELETE /api/v1/pleroma/admin/relay`

Unfollow a Relay

Params:
- relay_url
- optional force: forcefully unfollow a relay even when the relay is not available. (default is false)

Response:

On success: URL of the unfollowed relay

"https://example.com/relay"

`POST /api/v1/pleroma/admin/users/invite_token`

Create an account registration invite token

Params:
- optional max_use (integer)
- optional expires_at (date string e.g. "2019-04-07")
Response:

{
  "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/v1/pleroma/admin/users/invites`

Get a list of generated invites

Params: none
Response:

{

  "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/v1/pleroma/admin/users/revoke_invite`

Revoke invite by token

Params:
- token
Response:

{
  "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/v1/pleroma/admin/users/email_invite`

Sends registration invite via email

Params:
- email
- name, optional

Response:

On success: 204, empty response

On failure:

400 Bad Request, JSON:

  [
    {
      "error": "Appropriate error message here"
    }
  ]

`GET /api/v1/pleroma/admin/users/:nickname/password_reset`

Get a password reset token for a given nickname

Params: none
Response:

{
  "token": "base64 reset token",
  "link": "https://pleroma.social/api/v1/pleroma/password_reset/url-encoded-base64-token"
}

`PATCH /api/v1/pleroma/admin/users/force_password_reset`

Force password reset for a user with a given nickname

Params:
- nicknames
Response: none (code 204)

PUT `/api/v1/pleroma/admin/users/disable_mfa`

Disable mfa for user's account.

Params:
- nickname
Response: User’s nickname

`GET /api/v1/pleroma/admin/users/:nickname/credentials`

Params:
- nickname
Response:

{
  "actor_type": "Person",
  "allow_following_move": true,
  "avatar": "https://pleroma.social/media/7e8e7508fd545ef580549b6881d80ec0ff2c81ed9ad37b9bdbbdf0e0d030159d.jpg",
  "background": "https://pleroma.social/media/4de34c0bd10970d02cbdef8972bef0ebbf55f43cadc449554d4396156162fe9a.jpg",
  "banner": "https://pleroma.social/media/8d92ba2bd244b613520abf557dd448adcd30f5587022813ee9dd068945986946.jpg",
  "bio": "bio",
  "default_scope": "public",
  "discoverable": false,
  "email": "user@example.com",
  "fields": [
    {
      "name": "example",
      "value": "<a href=\"https://example.com\" rel=\"ugc\">https://example.com</a>"
    }
  ],
  "hide_favorites": false,
  "hide_followers": false,
  "hide_followers_count": false,
  "hide_follows": false,
  "hide_follows_count": false,
  "id": "9oouHaEEUR54hls968",
  "locked": true,
  "name": "user",
  "no_rich_text": true,
  "pleroma_settings_store": {},
  "raw_fields": [
    {
      "id": 1,
      "name": "example",
      "value": "https://example.com"
    },
  ],
  "show_role": true,
  "skip_thread_containment": false
}

`PATCH /api/v1/pleroma/admin/users/:nickname/credentials`

Params:
- email
- password
- name
- bio
- avatar
- locked
- no_rich_text
- default_scope
- banner
- hide_follows
- hide_followers
- hide_followers_count
- hide_follows_count
- hide_favorites
- allow_following_move
- background
- show_role
- skip_thread_containment
- fields
- is_discoverable
- actor_type
Responses:

Status: 200

{"status": "success"}

Status: 400

{"errors":
  {"actor_type": "is invalid"},
  {"email": "has invalid format"},
  ...
 }

Status: 404

{"error": "Not found"}

`GET /api/v1/pleroma/admin/reports`

Get a list of reports

Params:
- optional state: string the state of reports. Valid values are open, closed and resolved
- optional limit: integer the number of records to retrieve
- optional page: integer page number
- optional page_size: integer number of log entries per page (default is 50)
Response:
- On failure: 403 Forbidden error {"error": "error_msg"} when requested by anonymous or non-admin
- On success: JSON, returns a list of reports, where:
  - account: the user who has been reported
  - actor: the user who has sent the report
  - statuses: list of statuses that have been included to the report

{
  "total" : 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/v1/pleroma/admin/grouped_reports`

Get a list of reports, grouped by status

Params: none
On success: JSON, returns a list of reports, where:
- date: date of the latest report
- account: the user who has been reported (see /api/v1/pleroma/admin/reports for reference)
- status: reported status (see /api/v1/pleroma/admin/reports for reference)
- actors: users who had reported this status (see /api/v1/pleroma/admin/reports for reference)
- reports: reports (see /api/v1/pleroma/admin/reports for reference)

  "reports": [
    {
      "date": "2019-10-07T12:31:39.615149Z",
      "account": { ... },
      "status": { ... },
      "actors": [{ ... }, { ... }],
      "reports": [{ ... }]
    }
  ]

`GET /api/v1/pleroma/admin/reports/:id`

Get an individual report

Params:
- id
Response:
- On failure:
  - 403 Forbidden {"error": "error_msg"}
  - 404 Not Found "Not found"
- On success: JSON, Report object (see above)

`PATCH /api/v1/pleroma/admin/reports`

Change the state of one or multiple reports

Params:

  `reports`: [
    {
      `id`, // required, report id
      `state` // required, the new state. Valid values are `open`, `closed` and `resolved`
    },
    ...
  ]

Response:

On failure:

400 Bad Request, JSON:

  [
    {
      `id`, // report id
      `error` // error message
    }
  ]

On success: 204, empty response

`POST /api/v1/pleroma/admin/reports/:id/notes`

Create report note

Params:
- id: required, report id
- content: required, the message
Response:
- On failure:
  - 400 Bad Request "Invalid parameters" when status is missing
- On success: 204, empty response

`DELETE /api/v1/pleroma/admin/reports/:report_id/notes/:id`

Delete report note

Params:
- report_id: required, report id
- id: required, note id
Response:
- On failure:
  - 400 Bad Request "Invalid parameters" when status is missing
- On success: 204, empty response

`GET /api/v1/pleroma/admin/statuses/:id`

Show status by id

Params:
- id: required, status id
Response:
- On failure:
  - 404 Not Found "Not Found"
- On success: JSON, Mastodon Status entity

`PUT /api/v1/pleroma/admin/statuses/:id`

Change the scope of an individual reported status

Params:
- id
- sensitive: optional, valid values are true or false
- visibility: optional, valid values are public, private and unlisted
Response:
- On failure:
  - 400 Bad Request "Unsupported visibility"
  - 403 Forbidden {"error": "error_msg"}
  - 404 Not Found "Not found"
- On success: JSON, Mastodon Status entity

`DELETE /api/v1/pleroma/admin/statuses/:id`

Delete an individual reported status

Params:
- id
Response:
- On failure:
  - 403 Forbidden {"error": "error_msg"}
  - 404 Not Found "Not found"
- On success: 200 OK {}

`GET /api/v1/pleroma/admin/restart`

Restarts pleroma application

Only works when configuration from database is enabled.

Params: none
Response:
- On failure:
  - 400 Bad Request "To use this endpoint you need to enable configuration from database."

{}

`GET /api/v1/pleroma/admin/need_reboot`

Returns the flag whether the pleroma should be restarted

Params: none
Response:
- need_reboot - boolean

{
  "need_reboot": false
}

`GET /api/v1/pleroma/admin/config`

Get list of merged default settings with saved in database.

If need_reboot is true, instance must be restarted, so reboot time settings can take effect.

Only works when configuration from database is enabled.

Params:
- only_db: true (optional, get only saved in database settings)
Response:
- On failure:
  - 400 Bad Request "To use this endpoint you need to enable configuration from database."

{
  "configs": [
    {
      "group": ":pleroma",
      "key": "Pleroma.Upload",
      "value": []
     }
  ],
  "need_reboot": true
}

`POST /api/v1/pleroma/admin/config`

Update config settings

If need_reboot is true, 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:

strings which start with Pleroma., Phoenix., Tesla. or strings like Oban, Ueberauth will be converted to modules;

"Pleroma.Upload" -> Pleroma.Upload
"Oban" -> Oban

strings starting with : will be converted to atoms;

":pleroma" -> :pleroma

objects with tuple key and array value will be converted to tuples;

{"tuple": ["string", "Pleroma.Upload", []]} -> {"string", Pleroma.Upload, []}

arrays with tuple objects will be converted to keywords;

[{"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 objects
- config object params:
  - group - 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},
    {: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 sent in separate config object params.

config :foo,
  bar: :baz,
  meta: [:data],
  ...

{
  "configs": [
    {"group": ":foo", "key": ":bar", "value": ":baz"},
    {"group": ":foo", "key": ":meta", "value": [":data"]},
    ...
  ]
}

Request:

{
  "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", []]
        }]}
      ]
    }
  ]
}

Response:
- On failure:
  - 400 Bad Request "To use this endpoint you need to enable configuration from database."

{
  "configs": [
    {
      "group": ":pleroma",
      "key": "Pleroma.Upload",
      "value": [...]
     }
  ],
  "need_reboot": true
}

`GET /api/v1/pleroma/admin/config/descriptions`

Get JSON with config descriptions.

Loads json generated from config/descriptions.exs.

Params: none
Response:

[{
    "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/v1/pleroma/admin/moderation_log`

Get moderation log

Params:
- optional page: integer page number
- optional page_size: integer number of log entries per page (default is 50)
- optional 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
- optional 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:42
- optional user_id: integer filter logs by actor's id
- optional search: string search logs by the log message
Response:

{
  "items": [
    {
      "id": 1234,
      "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
    }
  ],
  "total": 1
}

`POST /api/v1/pleroma/admin/reload_emoji`

Reload the instance's custom emoji

Authentication: required
Params: None
Response: JSON, "ok" and 200 status

`PATCH /api/v1/pleroma/admin/users/confirm_email`

Confirm users' emails

Params:
- nicknames
Response: Array of user nicknames

`PATCH /api/v1/pleroma/admin/users/resend_confirmation_email`

Resend confirmation email

Params:
- nicknames
Response: Array of user nicknames

`GET /api/v1/pleroma/admin/stats`

Stats

Query Params:
- optional instance: string instance hostname (without protocol) to get stats for
Example: https://mypleroma.org/api/v1/pleroma/admin/stats?instance=lain.com
Response:

{
  "status_visibility": {
    "direct": 739,
    "private": 9,
    "public": 17,
    "unlisted": 14
  }
}

`GET /api/v1/pleroma/admin/oauth_app`

List OAuth app

Params:
- optional name
- optional client_id
- optional page
- optional page_size
- optional trusted
Response:

{
  "apps": [
    {
      "id": 1,
      "name": "App name",
      "client_id": "yHoDSiWYp5mPV6AfsaVOWjdOyt5PhWRiafi6MRd1lSk",
      "client_secret": "nLmis486Vqrv2o65eM9mLQx_m_4gH-Q6PcDpGIMl6FY",
      "redirect_uri": "https://example.com/oauth-callback",
      "website": "https://example.com",
      "trusted": true
    }
  ],
  "count": 17,
  "page_size": 50
}

`POST /api/v1/pleroma/admin/oauth_app`

Create OAuth App

Params:
- name
- redirect_uris
- scopes
- optional website
- optional trusted
Response:

{
  "id": 1,
  "name": "App name",
  "client_id": "yHoDSiWYp5mPV6AfsaVOWjdOyt5PhWRiafi6MRd1lSk",
  "client_secret": "nLmis486Vqrv2o65eM9mLQx_m_4gH-Q6PcDpGIMl6FY",
  "redirect_uri": "https://example.com/oauth-callback",
  "website": "https://example.com",
  "trusted": true
}

On failure:

{
  "redirect_uris": "can't be blank",
  "name": "can't be blank"
}

`PATCH /api/v1/pleroma/admin/oauth_app/:id`

Update OAuth App

Params:
- optional name
- optional redirect_uris
- optional scopes
- optional website
- optional trusted
Response:

{
  "id": 1,
  "name": "App name",
  "client_id": "yHoDSiWYp5mPV6AfsaVOWjdOyt5PhWRiafi6MRd1lSk",
  "client_secret": "nLmis486Vqrv2o65eM9mLQx_m_4gH-Q6PcDpGIMl6FY",
  "redirect_uri": "https://example.com/oauth-callback",
  "website": "https://example.com",
  "trusted": true
}

`DELETE /api/v1/pleroma/admin/oauth_app/:id`

Delete OAuth App

Params: None
Response:
- On success: 204, empty response
- On failure:
  - 400 Bad Request "Invalid parameters" when status is missing

`GET /api/v1/pleroma/admin/media_proxy_caches`

Get a list of all banned MediaProxy URLs in Cachex

Authentication: required
Params:
optional page: integer page number
optional page_size: integer number of log entries per page (default is 50)
optional query: string search term
Response:

{
  "page_size": integer,
  "count": integer,
  "urls": [
    "http://example.com/media/a688346.jpg",
    "http://example.com/media/fb1f4d.jpg"
  ]
}

`POST /api/v1/pleroma/admin/media_proxy_caches/delete`

Remove a banned MediaProxy URL from Cachex

Authentication: required
Params:
- urls (array)
Response:

{ }

`POST /api/v1/pleroma/admin/media_proxy_caches/purge`

Purge a MediaProxy URL

Authentication: required
Params:
- urls (array)
- ban (boolean)
Response:

{ }

GET /api/v1/pleroma/admin/users/:nickname/chats

List a user's chats

Params: None
Response:

[
   {
      "sender": {
        "id": "someflakeid",
        "username": "somenick",
        ...
      },
      "receiver": {
        "id": "someflakeid",
        "username": "somenick",
        ...
      },
      "id" : "1",
      "unread" : 2,
      "last_message" : {...}, // The last message in that chat
      "updated_at": "2020-04-21T15:11:46.000Z"
   }
]

GET /api/v1/pleroma/admin/chats/:chat_id

View a single chat

Params: None
Response:

{
  "sender": {
    "id": "someflakeid",
    "username": "somenick",
    ...
  },
  "receiver": {
    "id": "someflakeid",
    "username": "somenick",
    ...
  },
  "id" : "1",
  "unread" : 2,
  "last_message" : {...}, // The last message in that chat
  "updated_at": "2020-04-21T15:11:46.000Z"
}

GET /api/v1/pleroma/admin/chats/:chat_id/messages

List the messages in a chat

Params: max_id, min_id
Response:

[
  {
    "account_id": "someflakeid",
    "chat_id": "1",
    "content": "Check this out :firefox:",
    "created_at": "2020-04-21T15:11:46.000Z",
    "emojis": [
      {
        "shortcode": "firefox",
        "static_url": "https://dontbulling.me/emoji/Firefox.gif",
        "url": "https://dontbulling.me/emoji/Firefox.gif",
        "visible_in_picker": false
      }
    ],
    "id": "13",
    "unread": true
  },
  {
    "account_id": "someflakeid",
    "chat_id": "1",
    "content": "Whats' up?",
    "created_at": "2020-04-21T15:06:45.000Z",
    "emojis": [],
    "id": "12",
    "unread": false
  }
]

DELETE /api/v1/pleroma/admin/chats/:chat_id/messages/:message_id

Delete a single message

Params: None
Response:

{
  "account_id": "someflakeid",
  "chat_id": "1",
  "content": "Check this out :firefox:",
  "created_at": "2020-04-21T15:11:46.000Z",
  "emojis": [
    {
      "shortcode": "firefox",
      "static_url": "https://dontbulling.me/emoji/Firefox.gif",
      "url": "https://dontbulling.me/emoji/Firefox.gif",
      "visible_in_picker": false
    }
  ],
  "id": "13",
  "unread": false
}

`GET /api/v1/pleroma/admin/instance_document/:document_name`

Get an instance document

Authentication: required
Response:

Returns the content of the document

<h1>Instance panel</h1>

`PATCH /api/v1/pleroma/admin/instance_document/:document_name`

Params:
- file (the file to be uploaded, using multipart form data.)

Update an instance document

Authentication: required
Response:

{
  "url": "https://example.com/instance/panel.html"
}

`DELETE /api/v1/pleroma/admin/instance_document/:document_name`

Delete an instance document

Response:

{
  "url": "https://example.com/instance/panel.html"
}

`GET /api/v1/pleroma/admin/frontends

List available frontends

Response:

[
   {
    "build_url": "https://git.pleroma.social/pleroma/fedi-fe/-/jobs/artifacts/${ref}/download?job=build",
    "git": "https://git.pleroma.social/pleroma/fedi-fe",
    "installed": true,
    "installed_refs": ["master"],
    "name": "fedi-fe",
    "ref": "master"
  },
  {
    "build_url": "https://git.pleroma.social/lambadalambda/kenoma/-/jobs/artifacts/${ref}/download?job=build",
    "git": "https://git.pleroma.social/lambadalambda/kenoma",
    "installed": false,
    "installed_refs": [],
    "name": "kenoma",
    "ref": "master"
  }
]

`POST /api/v1/pleroma/admin/frontends/install`

Install a frontend

Params:
- name: frontend name, required
- ref: frontend ref
- file: path to a frontend zip file
- build_url: build URL
- build_dir: build directory
Response:

[
   {
    "build_url": "https://git.pleroma.social/pleroma/fedi-fe/-/jobs/artifacts/${ref}/download?job=build",
    "git": "https://git.pleroma.social/pleroma/fedi-fe",
    "installed": true,
    "name": "fedi-fe",
    "ref": "master"
  },
  {
    "build_url": "https://git.pleroma.social/lambadalambda/kenoma/-/jobs/artifacts/${ref}/download?job=build",
    "git": "https://git.pleroma.social/lambadalambda/kenoma",
    "installed": false,
    "name": "kenoma",
    "ref": "master"
  }
]

{
  "error": "Could not install frontend"
}

`GET /api/v1/pleroma/admin/announcements`

List announcements

Params: offset, limit
Response: JSON, list of announcements

[
  {
    "id": "AHDp0GBdRn1EPN5HN2",
    "content": "some content",
    "starts_at": null,
    "ends_at": null,
    "all_day": false,
    "published_at": "2022-03-09T02:13:05",
    "reactions": [],
    "statuses": [],
    "tags": [],
    "emojis": [],
    "updated_at": "2022-03-09T02:13:05"
  }
]

Note that this differs from the Mastodon API variant: Mastodon API only returns active announcements, while this returns all.

`GET /api/v1/pleroma/admin/announcements/:id`

Display one announcement

Response: JSON, one announcement

{
  "id": "AHDp0GBdRn1EPN5HN2",
  "content": "some content",
  "starts_at": null,
  "ends_at": null,
  "all_day": false,
  "published_at": "2022-03-09T02:13:05",
  "reactions": [],
  "statuses": [],
  "tags": [],
  "emojis": [],
  "updated_at": "2022-03-09T02:13:05"
}

`POST /api/v1/pleroma/admin/announcements`

Create an announcement

Params:
- content: string, required, announcement content
- starts_at: datetime, optional, default to null, the time when the announcement will become active (displayed to users); if it is null, the announcement will be active immediately
- ends_at: datetime, optional, default to null, the time when the announcement will become inactive (no longer displayed to users); if it is null, the announcement will be active until an admin deletes it
- all_day: boolean, optional, default to false, tells the client whether to only display dates for starts_at and ends_at
Response: JSON, created announcement

{
  "id": "AHDp0GBdRn1EPN5HN2",
  "content": "some content",
  "starts_at": null,
  "ends_at": null,
  "all_day": false,
  "published_at": "2022-03-09T02:13:05",
  "reactions": [],
  "statuses": [],
  "tags": [],
  "emojis": [],
  "updated_at": "2022-03-09T02:13:05"
}

`PATCH /api/v1/pleroma/admin/announcements/:id`

Change an announcement

Params: same as POST /api/v1/pleroma/admin/announcements, except no param is required.
Updates the announcement according to params. Missing params are kept as-is.
Response: JSON, updated announcement

{
  "id": "AHDp0GBdRn1EPN5HN2",
  "content": "some content",
  "starts_at": null,
  "ends_at": null,
  "all_day": false,
  "published_at": "2022-03-09T02:13:05",
  "reactions": [],
  "statuses": [],
  "tags": [],
  "emojis": [],
  "updated_at": "2022-03-09T02:13:05"
}

`DELETE /api/v1/pleroma/admin/announcements/:id`

Delete an announcement

Response: JSON, empty object

{}

`GET /api/v1/pleroma/admin/rules`

List rules

Response: JSON, list of rules

[
  {
    "id": "1",
    "priority": 1,
    "text": "There are no rules",
    "hint": null
  }
]

`POST /api/v1/pleroma/admin/rules`

Create a rule

Params:
- text: string, required, rule content
- hint: string, optional, rule description
- priority: integer, optional, rule ordering priority
Response: JSON, a single rule

`PATCH /api/v1/pleroma/admin/rules/:id`

Update a rule

Params:
- text: string, optional, rule content
- hint: string, optional, rule description
- priority: integer, optional, rule ordering priority
Response: JSON, a single rule

`DELETE /api/v1/pleroma/admin/rules/:id`

Delete a rule

Response: JSON, empty object

{}

39 KiB Raw Permalink Blame History Unescape Escape

Admin API

GET /api/v1/pleroma/admin/users

List users

DEPRECATED DELETE /api/v1/pleroma/admin/users

Remove a user

DELETE /api/v1/pleroma/admin/users

Remove a user

Create a user

POST /api/v1/pleroma/admin/users/follow

Make a user follow another user

POST /api/v1/pleroma/admin/users/unfollow

Make a user unfollow another user

PATCH /api/v1/pleroma/admin/users/:nickname/toggle_activation

Toggle user activation

PUT /api/v1/pleroma/admin/users/tag

Tag a list of users

DELETE /api/v1/pleroma/admin/users/tag

Untag a list of users

GET /api/v1/pleroma/admin/users/:nickname/permission_group

Get user user permission groups membership

GET /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group

Get user user permission groups membership per permission group

DEPRECATED POST /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group

Add user to permission group

POST /api/v1/pleroma/admin/users/permission_group/:permission_group

Add users to permission group

DEPRECATED DELETE /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group

DELETE /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group

Remove user from permission group

DELETE /api/v1/pleroma/admin/users/permission_group/:permission_group

Remove users from permission group

PATCH /api/v1/pleroma/admin/users/activate

Activate user

PATCH /api/v1/pleroma/admin/users/deactivate

Deactivate user

PATCH /api/v1/pleroma/admin/users/approve

Approve user

PATCH /api/v1/pleroma/admin/users/suggest

Suggest a user

PATCH /api/v1/pleroma/admin/users/unsuggest

Unsuggest a user

GET /api/v1/pleroma/admin/users/:nickname_or_id

Retrieve the details of a user

GET /api/v1/pleroma/admin/users/:nickname_or_id/statuses

Retrieve user's latest statuses

GET /api/v1/pleroma/admin/instances/:instance/statuses

Retrieve instance's latest statuses

DELETE /api/v1/pleroma/admin/instances/:instance

Delete all users and activities from a remote instance

GET /api/v1/pleroma/admin/statuses

Retrieves all latest statuses

GET /api/v1/pleroma/admin/relay

List Relays

POST /api/v1/pleroma/admin/relay

Follow a Relay

DELETE /api/v1/pleroma/admin/relay

Unfollow a Relay

POST /api/v1/pleroma/admin/users/invite_token

Create an account registration invite token

GET /api/v1/pleroma/admin/users/invites

Get a list of generated invites

POST /api/v1/pleroma/admin/users/revoke_invite

Revoke invite by token

POST /api/v1/pleroma/admin/users/email_invite

Sends registration invite via email

GET /api/v1/pleroma/admin/users/:nickname/password_reset

Get a password reset token for a given nickname

PATCH /api/v1/pleroma/admin/users/force_password_reset

Force password reset for a user with a given nickname

PUT /api/v1/pleroma/admin/users/disable_mfa

Disable mfa for user's account.

GET /api/v1/pleroma/admin/users/:nickname/credentials

Get the user's email, password, display and settings-related fields

PATCH /api/v1/pleroma/admin/users/:nickname/credentials

Change the user's email, password, display and settings-related fields

GET /api/v1/pleroma/admin/reports

Get a list of reports

GET /api/v1/pleroma/admin/grouped_reports

Get a list of reports, grouped by status

39 KiB

Raw Permalink Blame History

`GET /api/v1/pleroma/admin/users`

DEPRECATED `DELETE /api/v1/pleroma/admin/users`

`DELETE /api/v1/pleroma/admin/users`

`POST /api/v1/pleroma/admin/users/follow`

`POST /api/v1/pleroma/admin/users/unfollow`

`PATCH /api/v1/pleroma/admin/users/:nickname/toggle_activation`

`PUT /api/v1/pleroma/admin/users/tag`

`DELETE /api/v1/pleroma/admin/users/tag`

`GET /api/v1/pleroma/admin/users/:nickname/permission_group`

`GET /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group`

DEPRECATED `POST /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group`

`POST /api/v1/pleroma/admin/users/permission_group/:permission_group`

DEPRECATED `DELETE /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group`

`DELETE /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group`

`DELETE /api/v1/pleroma/admin/users/permission_group/:permission_group`

`PATCH /api/v1/pleroma/admin/users/activate`

`PATCH /api/v1/pleroma/admin/users/deactivate`

`PATCH /api/v1/pleroma/admin/users/approve`

`PATCH /api/v1/pleroma/admin/users/suggest`

`PATCH /api/v1/pleroma/admin/users/unsuggest`

`GET /api/v1/pleroma/admin/users/:nickname_or_id`

`GET /api/v1/pleroma/admin/users/:nickname_or_id/statuses`

`GET /api/v1/pleroma/admin/instances/:instance/statuses`

`DELETE /api/v1/pleroma/admin/instances/:instance`

`GET /api/v1/pleroma/admin/statuses`

`GET /api/v1/pleroma/admin/relay`

`POST /api/v1/pleroma/admin/relay`

`DELETE /api/v1/pleroma/admin/relay`

`POST /api/v1/pleroma/admin/users/invite_token`

`GET /api/v1/pleroma/admin/users/invites`

`POST /api/v1/pleroma/admin/users/revoke_invite`

`POST /api/v1/pleroma/admin/users/email_invite`

`GET /api/v1/pleroma/admin/users/:nickname/password_reset`

`PATCH /api/v1/pleroma/admin/users/force_password_reset`

PUT `/api/v1/pleroma/admin/users/disable_mfa`

`GET /api/v1/pleroma/admin/users/:nickname/credentials`

`PATCH /api/v1/pleroma/admin/users/:nickname/credentials`

`GET /api/v1/pleroma/admin/reports`

`GET /api/v1/pleroma/admin/grouped_reports`

`GET /api/v1/pleroma/admin/reports/:id`

`PATCH /api/v1/pleroma/admin/reports`

`POST /api/v1/pleroma/admin/reports/:id/notes`

`DELETE /api/v1/pleroma/admin/reports/:report_id/notes/:id`

`GET /api/v1/pleroma/admin/statuses/:id`

`PUT /api/v1/pleroma/admin/statuses/:id`

`DELETE /api/v1/pleroma/admin/statuses/:id`

`GET /api/v1/pleroma/admin/restart`

`GET /api/v1/pleroma/admin/need_reboot`

`GET /api/v1/pleroma/admin/config`

`POST /api/v1/pleroma/admin/config`

`GET /api/v1/pleroma/admin/config/descriptions`

`GET /api/v1/pleroma/admin/moderation_log`

`POST /api/v1/pleroma/admin/reload_emoji`

`PATCH /api/v1/pleroma/admin/users/confirm_email`

`PATCH /api/v1/pleroma/admin/users/resend_confirmation_email`

`GET /api/v1/pleroma/admin/stats`

`GET /api/v1/pleroma/admin/oauth_app`

`POST /api/v1/pleroma/admin/oauth_app`

`PATCH /api/v1/pleroma/admin/oauth_app/:id`

`DELETE /api/v1/pleroma/admin/oauth_app/:id`

`GET /api/v1/pleroma/admin/media_proxy_caches`

`POST /api/v1/pleroma/admin/media_proxy_caches/delete`

`POST /api/v1/pleroma/admin/media_proxy_caches/purge`

`GET /api/v1/pleroma/admin/instance_document/:document_name`

`PATCH /api/v1/pleroma/admin/instance_document/:document_name`

`DELETE /api/v1/pleroma/admin/instance_document/:document_name`

`POST /api/v1/pleroma/admin/frontends/install`

`GET /api/v1/pleroma/admin/announcements`

`GET /api/v1/pleroma/admin/announcements/:id`