logo

pleroma

My custom branche(s) on git.pleroma.social/pleroma/pleroma git clone https://anongit.hacktivis.me/git/pleroma.git/

admin_api.md (40284B)

    

  1. # Admin API
  3. Authentication is required and the user must be an admin.
  5. The `/api/v1/pleroma/admin/*` path is backwards compatible with `/api/pleroma/admin/*` (`/api/pleroma/admin/*` will be deprecated in the future).
  7. ## `GET /api/v1/pleroma/admin/users`
  9. ### List users
  11. - Query Params:
  12.   - *optional* `query`: **string** search term (e.g. nickname, domain, nickname@domain)
  13.   - *optional* `filters`: **string** comma-separated string of filters:
  14.     - `local`: only local users
  15.     - `external`: only external users
  16.     - `active`: only active users
  17.     - `need_approval`: only unapproved users
  18.     - `unconfirmed`: only unconfirmed users
  19.     - `deactivated`: only deactivated users
  20.     - `is_admin`: users with admin role
  21.     - `is_moderator`: users with moderator role
  22.   - *optional* `page`: **integer** page number
  23.   - *optional* `page_size`: **integer** number of users per page (default is `50`)
  24.   - *optional* `tags`: **[string]** tags list
  25.   - *optional* `actor_types`: **[string]** actor type list (`Person`, `Service`, `Application`)
  26.   - *optional* `name`: **string** user display name
  27.   - *optional* `email`: **string** user email
  28. - 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`
  29. - Response:
  31. ```json
  32. {
  33.   "page_size": integer,
  34.   "count": integer,
  35.   "users": [
  36.     {
  37.       "deactivated": bool,
  38.       "id": integer,
  39.       "nickname": string,
  40.       "roles": {
  41.         "admin": bool,
  42.         "moderator": bool
  43.       },
  44.       "local": bool,
  45.       "tags": array,
  46.       "avatar": string,
  47.       "display_name": string,
  48.       "confirmation_pending": bool,
  49.       "approval_pending": bool,
  50.       "registration_reason": string,
  51.     },
  52.     ...
  53.   ]
  54. }
  55. ```
  57. ## DEPRECATED `DELETE /api/v1/pleroma/admin/users`
  59. ### Remove a user
  61. - Params:
  62.   - `nickname`
  63. - Response: User’s nickname
  65. ## `DELETE /api/v1/pleroma/admin/users`
  67. ### Remove a user
  69. - Params:
  70.   - `nicknames`
  71. - Response: Array of user nicknames
  73. ## `POST /api/v1/pleroma/admin/users`
  75. ### Create a user
  77. - Method: `POST`
  78. - Params:
  79.   `users`: [
  80.     {
  81.       `nickname`,
  82.       `email`,
  83.       `password`
  84.     }
  85.   ]
  86. - Response: Array of user objects
  88. ## `POST /api/v1/pleroma/admin/users/follow`
  90. ### Make a user follow another user
  92. - Params:
  93.   - `follower`: The nickname of the follower
  94.   - `followed`: The nickname of the followed
  95. - Response:
  96.   - "ok"
  98. ## `POST /api/v1/pleroma/admin/users/unfollow`
  100. ### Make a user unfollow another user
  102. - Params:
  103.   - `follower`: The nickname of the follower
  104.   - `followed`: The nickname of the followed
  105. - Response:
  106.   - "ok"
  108. ## `PATCH /api/v1/pleroma/admin/users/:nickname/toggle_activation`
  110. ### Toggle user activation
  112. - Params:
  113.   - `nickname`
  114. - Response: User’s object
  116. ```json
  117. {
  118.   "deactivated": bool,
  119.   "id": integer,
  120.   "nickname": string
  121. }
  122. ```
  124. ## `PUT /api/v1/pleroma/admin/users/tag`
  126. ### Tag a list of users
  128. - Params:
  129.   - `nicknames` (array)
  130.   - `tags` (array)
  132. ## `DELETE /api/v1/pleroma/admin/users/tag`
  134. ### Untag a list of users
  136. - Params:
  137.   - `nicknames` (array)
  138.   - `tags` (array)
  140. ## `GET /api/v1/pleroma/admin/users/:nickname/permission_group`
  142. ### Get user user permission groups membership
  144. - Params: none
  145. - Response:
  147. ```json
  148. {
  149.   "is_moderator": bool,
  150.   "is_admin": bool
  151. }
  152. ```
  154. ## `GET /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group`
  156. Note: Available `:permission_group` is currently moderator and admin. 404 is returned when the permission group doesn’t exist.
  158. ### Get user user permission groups membership per permission group
  160. - Params: none
  161. - Response:
  163. ```json
  164. {
  165.   "is_moderator": bool,
  166.   "is_admin": bool
  167. }
  168. ```
  170. ## DEPRECATED `POST /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group`
  172. ### Add user to permission group
  174. - Params: none
  175. - Response:
  176.   - On failure: `{"error": "…"}`
  177.   - On success: JSON of the user
  179. ## `POST /api/v1/pleroma/admin/users/permission_group/:permission_group`
  181. ### Add users to permission group
  183. - Params:
  184.   - `nicknames`: nicknames array
  185. - Response:
  186.   - On failure: `{"error": "…"}`
  187.   - On success: JSON of the user
  189. ## DEPRECATED `DELETE /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group`
  191. ## `DELETE /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group`
  193. ### Remove user from permission group
  195. - Params: none
  196. - Response:
  197.   - On failure: `{"error": "…"}`
  198.   - On success: JSON of the user
  199. - Note: An admin cannot revoke their own admin status.
  201. ## `DELETE /api/v1/pleroma/admin/users/permission_group/:permission_group`
  203. ### Remove users from permission group
  205. - Params:
  206.   - `nicknames`: nicknames array
  207. - Response:
  208.   - On failure: `{"error": "…"}`
  209.   - On success: JSON of the user
  210. - Note: An admin cannot revoke their own admin status.
  212. ## `PATCH /api/v1/pleroma/admin/users/activate`
  214. ### Activate user
  216. - Params:
  217.   - `nicknames`: nicknames array
  218. - Response:
  220. ```json
  221. {
  222.   users: [
  223.     {
  224.       // user object
  225.     }
  226.   ]
  227. }
  228. ```
  230. ## `PATCH /api/v1/pleroma/admin/users/deactivate`
  232. ### Deactivate user
  234. - Params:
  235.   - `nicknames`: nicknames array
  236. - Response:
  238. ```json
  239. {
  240.   users: [
  241.     {
  242.       // user object
  243.     }
  244.   ]
  245. }
  246. ```
  248. ## `PATCH /api/v1/pleroma/admin/users/approve`
  250. ### Approve user
  252. - Params:
  253.   - `nicknames`: nicknames array
  254. - Response:
  256. ```json
  257. {
  258.   users: [
  259.     {
  260.       // user object
  261.     }
  262.   ]
  263. }
  264. ```
  266. ## `PATCH /api/v1/pleroma/admin/users/suggest`
  268. ### Suggest a user
  270. Adds the user(s) to follower recommendations.
  272. - Params:
  273.   - `nicknames`: nicknames array
  274. - Response:
  276. ```json
  277. {
  278.   users: [
  279.     {
  280.       // user object
  281.     }
  282.   ]
  283. }
  284. ```
  286. ## `PATCH /api/v1/pleroma/admin/users/unsuggest`
  288. ### Unsuggest a user
  290. Removes the user(s) from follower recommendations.
  292. - Params:
  293.   - `nicknames`: nicknames array
  294. - Response:
  296. ```json
  297. {
  298.   users: [
  299.     {
  300.       // user object
  301.     }
  302.   ]
  303. }
  304. ```
  306. ## `GET /api/v1/pleroma/admin/users/:nickname_or_id`
  308. ### Retrieve the details of a user
  310. - Params:
  311.   - `nickname` or `id`
  312. - Response:
  313.   - On failure: `Not found`
  314.   - On success: JSON of the user
  316. ## `GET /api/v1/pleroma/admin/users/:nickname_or_id/statuses`
  318. ### Retrieve user's latest statuses
  320. - Params:
  321.   - `nickname` or `id`
  322.   - *optional* `page_size`: number of statuses to return (default is `20`)
  323.   - *optional* `godmode`: `true`/`false` – allows to see private statuses
  324.   - *optional* `with_reblogs`: `true`/`false` – allows to see reblogs (default is false)
  325. - Response:
  326.   - On failure: `Not found`
  327.  - On success: JSON, where:
  328.     - `total`: total count of the statuses for the user
  329.     - `activities`: list of the statuses for the user
  331. ```json
  332. {
  333.   "total" : 1,
  334.   "activities": [
  335.     // activities list
  336.   ]
  337. }
  338. ```
  340. ## `GET /api/v1/pleroma/admin/instances/:instance/statuses`
  342. ### Retrieve instance's latest statuses
  344. - Params:
  345.   - `instance`: instance name
  346.   - *optional* `page_size`: number of statuses to return (default is `20`)
  347.   - *optional* `godmode`: `true`/`false` – allows to see private statuses
  348.   - *optional* `with_reblogs`: `true`/`false` – allows to see reblogs (default is false)
  349. - Response:
  350.   - On failure: `Not found`
  351.   - On success: JSON, where:
  352.     - `total`: total count of the statuses for the instance
  353.     - `activities`: list of the statuses for the instance
  355. ```json
  356. {
  357.   "total" : 1,
  358.   "activities": [
  359.     // activities list
  360.   ]
  361. }
  362. ```
  364. ## `DELETE /api/v1/pleroma/admin/instances/:instance`
  366. ### Delete all users and activities from a remote instance
  368. Note: this will trigger a job to remove instance content in the background.
  369. It may take some time.
  371. - Params:
  372.   - `instance`: remote instance host
  373. - Response:
  374.   - The `instance` name as a string
  376. ```json
  377. "lain.com"
  378. ```
  380. ## `GET /api/v1/pleroma/admin/statuses`
  382. ### Retrieves all latest statuses
  384. - Params:
  385.   - *optional* `page_size`: number of statuses to return (default is `20`)
  386.   - *optional* `local_only`: excludes remote statuses
  387.   - *optional* `godmode`: `true`/`false` – allows to see private statuses
  388.   - *optional* `with_reblogs`: `true`/`false` – allows to see reblogs (default is false)
  389. - Response:
  390.   - On failure: `Not found`
  391.   - On success: JSON array of user's latest statuses
  393. ## `GET /api/v1/pleroma/admin/relay`
  395. ### List Relays
  397. Params: none
  398. Response:
  400. * On success: JSON array of relays
  402. ```json
  403. [
  404.   {"actor": "https://example.com/relay", "followed_back": true},
  405.   {"actor": "https://example2.com/relay", "followed_back": false}
  406. ]
  407. ```
  409. ## `POST /api/v1/pleroma/admin/relay`
  411. ### Follow a Relay
  413. Params:
  415. * `relay_url`
  417. Response:
  419. * On success: relay json object
  421. ```json
  422. {"actor": "https://example.com/relay", "followed_back": true}
  423. ```
  425. ## `DELETE /api/v1/pleroma/admin/relay`
  427. ### Unfollow a Relay
  429. - Params:
  430.   - `relay_url`
  431.   - *optional* `force`: forcefully unfollow a relay even when the relay is not available. (default is `false`)
  433. Response:
  435. * On success: URL of the unfollowed relay
  437. ```json
  438. "https://example.com/relay"
  439. ```
  441. ## `POST /api/v1/pleroma/admin/users/invite_token`
  443. ### Create an account registration invite token
  445. - Params:
  446.   - *optional* `max_use` (integer)
  447.   - *optional* `expires_at` (date string e.g. "2019-04-07")
  448. - Response:
  450. ```json
  451. {
  452.   "id": integer,
  453.   "token": string,
  454.   "used": boolean,
  455.   "expires_at": date,
  456.   "uses": integer,
  457.   "max_use": integer,
  458.   "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
  459. }
  460. ```
  462. ## `GET /api/v1/pleroma/admin/users/invites`
  464. ### Get a list of generated invites
  466. - Params: none
  467. - Response:
  469. ```json
  470. {
  472.   "invites": [
  473.     {
  474.       "id": integer,
  475.       "token": string,
  476.       "used": boolean,
  477.       "expires_at": date,
  478.       "uses": integer,
  479.       "max_use": integer,
  480.       "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
  481.     },
  482.     ...
  483.   ]
  484. }
  485. ```
  487. ## `POST /api/v1/pleroma/admin/users/revoke_invite`
  489. ### Revoke invite by token
  491. - Params:
  492.   - `token`
  493. - Response:
  495. ```json
  496. {
  497.   "id": integer,
  498.   "token": string,
  499.   "used": boolean,
  500.   "expires_at": date,
  501.   "uses": integer,
  502.   "max_use": integer,
  503.   "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
  505. }
  506. ```
  508. ## `POST /api/v1/pleroma/admin/users/email_invite`
  510. ### Sends registration invite via email
  512. - Params:
  513.   - `email`
  514.   - `name`, optional
  516. - Response:
  517.   - On success: `204`, empty response
  518.   - On failure:
  519.     - 400 Bad Request, JSON:
  521.     ```json
  522.       [
  523.         {
  524.           "error": "Appropriate error message here"
  525.         }
  526.       ]
  527.     ```
  529. ## `GET /api/v1/pleroma/admin/users/:nickname/password_reset`
  531. ### Get a password reset token for a given nickname
  534. - Params: none
  535. - Response:
  537. ```json
  538. {
  539.   "token": "base64 reset token",
  540.   "link": "https://pleroma.social/api/v1/pleroma/password_reset/url-encoded-base64-token"
  541. }
  542. ```
  544. ## `PATCH /api/v1/pleroma/admin/users/force_password_reset`
  546. ### Force password reset for a user with a given nickname
  548. - Params:
  549.   - `nicknames`
  550. - Response: none (code `204`)
  552. ## PUT `/api/v1/pleroma/admin/users/disable_mfa`
  554. ### Disable mfa for user's account.
  556. - Params:
  557.   - `nickname`
  558. - Response: User’s nickname
  560. ## `GET /api/v1/pleroma/admin/users/:nickname/credentials`
  562. ### Get the user's email, password, display and settings-related fields
  564. - Params:
  565.   - `nickname`
  567. - Response:
  569. ```json
  570. {
  571.   "actor_type": "Person",
  572.   "allow_following_move": true,
  573.   "avatar": "https://pleroma.social/media/7e8e7508fd545ef580549b6881d80ec0ff2c81ed9ad37b9bdbbdf0e0d030159d.jpg",
  574.   "background": "https://pleroma.social/media/4de34c0bd10970d02cbdef8972bef0ebbf55f43cadc449554d4396156162fe9a.jpg",
  575.   "banner": "https://pleroma.social/media/8d92ba2bd244b613520abf557dd448adcd30f5587022813ee9dd068945986946.jpg",
  576.   "bio": "bio",
  577.   "default_scope": "public",
  578.   "discoverable": false,
  579.   "email": "user@example.com",
  580.   "fields": [
  581.     {
  582.       "name": "example",
  583.       "value": "<a href=\"https://example.com\" rel=\"ugc\">https://example.com</a>"
  584.     }
  585.   ],
  586.   "hide_favorites": false,
  587.   "hide_followers": false,
  588.   "hide_followers_count": false,
  589.   "hide_follows": false,
  590.   "hide_follows_count": false,
  591.   "id": "9oouHaEEUR54hls968",
  592.   "locked": true,
  593.   "name": "user",
  594.   "no_rich_text": true,
  595.   "pleroma_settings_store": {},
  596.   "raw_fields": [
  597.     {
  598.       "id": 1,
  599.       "name": "example",
  600.       "value": "https://example.com"
  601.     },
  602.   ],
  603.   "show_role": true,
  604.   "skip_thread_containment": false
  605. }
  606. ```
  608. ## `PATCH /api/v1/pleroma/admin/users/:nickname/credentials`
  610. ### Change the user's email, password, display and settings-related fields
  612. * Params:
  613.   * `email`
  614.   * `password`
  615.   * `name`
  616.   * `bio`
  617.   * `avatar`
  618.   * `locked`
  619.   * `no_rich_text`
  620.   * `default_scope`
  621.   * `banner`
  622.   * `hide_follows`
  623.   * `hide_followers`
  624.   * `hide_followers_count`
  625.   * `hide_follows_count`
  626.   * `hide_favorites`
  627.   * `allow_following_move`
  628.   * `background`
  629.   * `show_role`
  630.   * `skip_thread_containment`
  631.   * `fields`
  632.   * `is_discoverable`
  633.   * `actor_type`
  635. * Responses:
  637. Status: 200
  639. ```json
  640. {"status": "success"}
  641. ```
  643. Status: 400
  645. ```json
  646. {"errors":
  647.   {"actor_type": "is invalid"},
  648.   {"email": "has invalid format"},
  649.   ...
  650.  }
  651. ```
  653. Status: 404
  655. ```json
  656. {"error": "Not found"}
  657. ```
  659. ## `GET /api/v1/pleroma/admin/reports`
  661. ### Get a list of reports
  663. - Params:
  664.   - *optional* `state`: **string** the state of reports. Valid values are `open`, `closed` and `resolved`
  665.   - *optional* `limit`: **integer** the number of records to retrieve
  666.   - *optional* `page`: **integer** page number
  667.   - *optional* `page_size`: **integer** number of log entries per page (default is `50`)
  668. - Response:
  669.   - On failure: 403 Forbidden error `{"error": "error_msg"}` when requested by anonymous or non-admin
  670.   - On success: JSON, returns a list of reports, where:
  671.     - `account`: the user who has been reported
  672.     - `actor`: the user who has sent the report
  673.     - `statuses`: list of statuses that have been included to the report
  675. ```json
  676. {
  677.   "total" : 1,
  678.   "reports": [
  679.     {
  680.       "account": {
  681.         "acct": "user",
  682.         "avatar": "https://pleroma.example.org/images/avi.png",
  683.         "avatar_static": "https://pleroma.example.org/images/avi.png",
  684.         "bot": false,
  685.         "created_at": "2019-04-23T17:32:04.000Z",
  686.         "display_name": "User",
  687.         "emojis": [],
  688.         "fields": [],
  689.         "followers_count": 1,
  690.         "following_count": 1,
  691.         "header": "https://pleroma.example.org/images/banner.png",
  692.         "header_static": "https://pleroma.example.org/images/banner.png",
  693.         "id": "9i6dAJqSGSKMzLG2Lo",
  694.         "locked": false,
  695.         "note": "",
  696.         "pleroma": {
  697.           "confirmation_pending": false,
  698.           "hide_favorites": true,
  699.           "hide_followers": false,
  700.           "hide_follows": false,
  701.           "is_admin": false,
  702.           "is_moderator": false,
  703.           "relationship": {},
  704.           "tags": []
  705.         },
  706.         "source": {
  707.           "note": "",
  708.           "pleroma": {},
  709.           "sensitive": false
  710.         },
  711.         "tags": ["force_unlisted"],
  712.         "statuses_count": 3,
  713.         "url": "https://pleroma.example.org/users/user",
  714.         "username": "user"
  715.       },
  716.       "actor": {
  717.         "acct": "lain",
  718.         "avatar": "https://pleroma.example.org/images/avi.png",
  719.         "avatar_static": "https://pleroma.example.org/images/avi.png",
  720.         "bot": false,
  721.         "created_at": "2019-03-28T17:36:03.000Z",
  722.         "display_name": "Roger Braun",
  723.         "emojis": [],
  724.         "fields": [],
  725.         "followers_count": 1,
  726.         "following_count": 1,
  727.         "header": "https://pleroma.example.org/images/banner.png",
  728.         "header_static": "https://pleroma.example.org/images/banner.png",
  729.         "id": "9hEkA5JsvAdlSrocam",
  730.         "locked": false,
  731.         "note": "",
  732.         "pleroma": {
  733.           "confirmation_pending": false,
  734.           "hide_favorites": false,
  735.           "hide_followers": false,
  736.           "hide_follows": false,
  737.           "is_admin": false,
  738.           "is_moderator": false,
  739.           "relationship": {},
  740.           "tags": []
  741.         },
  742.         "source": {
  743.           "note": "",
  744.           "pleroma": {},
  745.           "sensitive": false
  746.         },
  747.         "tags": ["force_unlisted"],
  748.         "statuses_count": 1,
  749.         "url": "https://pleroma.example.org/users/lain",
  750.         "username": "lain"
  751.       },
  752.       "content": "Please delete it",
  753.       "created_at": "2019-04-29T19:48:15.000Z",
  754.       "id": "9iJGOv1j8hxuw19bcm",
  755.       "state": "open",
  756.       "statuses": [
  757.         {
  758.           "account": { ... },
  759.           "application": {
  760.             "name": "Web",
  761.             "website": null
  762.           },
  763.           "bookmarked": false,
  764.           "card": null,
  765.           "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>",
  766.           "created_at": "2019-04-23T19:15:47.000Z",
  767.           "emojis": [],
  768.           "favourited": false,
  769.           "favourites_count": 0,
  770.           "id": "9i6mQ9uVrrOmOime8m",
  771.           "in_reply_to_account_id": null,
  772.           "in_reply_to_id": null,
  773.           "language": null,
  774.           "media_attachments": [],
  775.           "mentions": [
  776.             {
  777.               "acct": "lain",
  778.               "id": "9hEkA5JsvAdlSrocam",
  779.               "url": "https://pleroma.example.org/users/lain",
  780.               "username": "lain"
  781.             },
  782.             {
  783.               "acct": "user",
  784.               "id": "9i6dAJqSGSKMzLG2Lo",
  785.               "url": "https://pleroma.example.org/users/user",
  786.               "username": "user"
  787.             }
  788.           ],
  789.           "muted": false,
  790.           "pinned": false,
  791.           "pleroma": {
  792.             "content": {
  793.               "text/plain": "@lain click on my link https://www.google.com/"
  794.             },
  795.             "conversation_id": 28,
  796.             "in_reply_to_account_acct": null,
  797.             "local": true,
  798.             "spoiler_text": {
  799.               "text/plain": ""
  800.             }
  801.           },
  802.           "reblog": null,
  803.           "reblogged": false,
  804.           "reblogs_count": 0,
  805.           "replies_count": 0,
  806.           "sensitive": false,
  807.           "spoiler_text": "",
  808.           "tags": [],
  809.           "uri": "https://pleroma.example.org/objects/8717b90f-8e09-4b58-97b0-e3305472b396",
  810.           "url": "https://pleroma.example.org/notice/9i6mQ9uVrrOmOime8m",
  811.           "visibility": "direct"
  812.         }
  813.       ]
  814.     }
  815.   ]
  816. }
  817. ```
  819. ## `GET /api/v1/pleroma/admin/grouped_reports`
  821. ### Get a list of reports, grouped by status
  823. - Params: none
  824. - On success: JSON, returns a list of reports, where:
  825.   - `date`: date of the latest report
  826.   - `account`: the user who has been reported (see `/api/v1/pleroma/admin/reports` for reference)
  827.   - `status`: reported status (see `/api/v1/pleroma/admin/reports` for reference)
  828.   - `actors`: users who had reported this status (see `/api/v1/pleroma/admin/reports` for reference)
  829.   - `reports`: reports (see `/api/v1/pleroma/admin/reports` for reference)
  831. ```json
  832.   "reports": [
  833.     {
  834.       "date": "2019-10-07T12:31:39.615149Z",
  835.       "account": { ... },
  836.       "status": { ... },
  837.       "actors": [{ ... }, { ... }],
  838.       "reports": [{ ... }]
  839.     }
  840.   ]
  841. ```
  843. ## `GET /api/v1/pleroma/admin/reports/:id`
  845. ### Get an individual report
  847. - Params:
  848.   - `id`
  849. - Response:
  850.   - On failure:
  851.     - 403 Forbidden `{"error": "error_msg"}`
  852.     - 404 Not Found `"Not found"`
  853.   - On success: JSON, Report object (see above)
  855. ## `PATCH /api/v1/pleroma/admin/reports`
  857. ### Change the state of one or multiple reports
  859. - Params:
  861. ```json
  862.   `reports`: [
  863.     {
  864.       `id`, // required, report id
  865.       `state` // required, the new state. Valid values are `open`, `closed` and `resolved`
  866.     },
  867.     ...
  868.   ]
  869. ```
  871. - Response:
  872.   - On failure:
  873.     - 400 Bad Request, JSON:
  875.     ```json
  876.       [
  877.         {
  878.           `id`, // report id
  879.           `error` // error message
  880.         }
  881.       ]
  882.     ```
  884.   - On success: `204`, empty response
  886. ## `POST /api/v1/pleroma/admin/reports/:id/notes`
  888. ### Create report note
  890. - Params:
  891.   - `id`: required, report id
  892.   - `content`: required, the message
  893. - Response:
  894.   - On failure:
  895.     - 400 Bad Request `"Invalid parameters"` when `status` is missing
  896.   - On success: `204`, empty response
  898. ## `DELETE /api/v1/pleroma/admin/reports/:report_id/notes/:id`
  900. ### Delete report note
  902. - Params:
  903.   - `report_id`: required, report id
  904.   - `id`: required, note id
  905. - Response:
  906.   - On failure:
  907.     - 400 Bad Request `"Invalid parameters"` when `status` is missing
  908.   - On success: `204`, empty response
  910. ## `GET /api/v1/pleroma/admin/statuses/:id`
  912. ### Show status by id
  914. - Params:
  915.   - `id`: required, status id
  916. - Response:
  917.   - On failure:
  918.     - 404 Not Found `"Not Found"`
  919.   - On success: JSON, Mastodon Status entity
  921. ## `PUT /api/v1/pleroma/admin/statuses/:id`
  923. ### Change the scope of an individual reported status
  925. - Params:
  926.   - `id`
  927.   - `sensitive`: optional, valid values are `true` or `false`
  928.   - `visibility`: optional, valid values are `public`, `private` and `unlisted`
  929. - Response:
  930.   - On failure:
  931.     - 400 Bad Request `"Unsupported visibility"`
  932.     - 403 Forbidden `{"error": "error_msg"}`
  933.     - 404 Not Found `"Not found"`
  934.   - On success: JSON, Mastodon Status entity
  936. ## `DELETE /api/v1/pleroma/admin/statuses/:id`
  938. ### Delete an individual reported status
  940. - Params:
  941.   - `id`
  942. - Response:
  943.   - On failure:
  944.     - 403 Forbidden `{"error": "error_msg"}`
  945.     - 404 Not Found `"Not found"`
  946.   - On success: 200 OK `{}`
  948. ## `GET /api/v1/pleroma/admin/restart`
  950. ### Restarts pleroma application
  952. **Only works when configuration from database is enabled.**
  954. - Params: none
  955. - Response:
  956.   - On failure:
  957.     - 400 Bad Request `"To use this endpoint you need to enable configuration from database."`
  959. ```json
  960. {}
  961. ```
  963. ## `GET /api/v1/pleroma/admin/need_reboot`
  965. ### Returns the flag whether the pleroma should be restarted
  967. - Params: none
  968. - Response:
  969.   - `need_reboot` - boolean
  970. ```json
  971. {
  972.   "need_reboot": false
  973. }
  974. ```
  976. ## `GET /api/v1/pleroma/admin/config`
  978. ### Get list of merged default settings with saved in database.
  980. *If `need_reboot` is `true`, instance must be restarted, so reboot time settings can take effect.*
  982. **Only works when configuration from database is enabled.**
  984. - Params:
  985.   - `only_db`: true (*optional*, get only saved in database settings)
  986. - Response:
  987.   - On failure:
  988.     - 400 Bad Request `"To use this endpoint you need to enable configuration from database."`
  990. ```json
  991. {
  992.   "configs": [
  993.     {
  994.       "group": ":pleroma",
  995.       "key": "Pleroma.Upload",
  996.       "value": []
  997.      }
  998.   ],
  999.   "need_reboot": true
  1000. }
  1001. ```
  1003. ## `POST /api/v1/pleroma/admin/config`
  1005. ### Update config settings
  1007. *If `need_reboot` is `true`, instance must be restarted, so reboot time settings can take effect.*
  1009. **Only works when configuration from database is enabled.**
  1011. Some modifications are necessary to save the config settings correctly:
  1013. - strings which start with `Pleroma.`, `Phoenix.`, `Tesla.` or strings like `Oban`, `Ueberauth` will be converted to modules;
  1014. ```
  1015. "Pleroma.Upload" -> Pleroma.Upload
  1016. "Oban" -> Oban
  1017. ```
  1018. - strings starting with `:` will be converted to atoms;
  1019. ```
  1020. ":pleroma" -> :pleroma
  1021. ```
  1022. - objects with `tuple` key and array value will be converted to tuples;
  1023. ```
  1024. {"tuple": ["string", "Pleroma.Upload", []]} -> {"string", Pleroma.Upload, []}
  1025. ```
  1026. - arrays with *tuple objects* will be converted to keywords;
  1027. ```
  1028. [{"tuple": [":key1", "value"]}, {"tuple": [":key2", "value"]}] -> [key1: "value", key2: "value"]
  1029. ```
  1031. 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:
  1032. - all settings inside these keys:
  1033.   - `:hackney_pools`
  1034.   - `:connections_pool`
  1035.   - `:pools`
  1036.   - `:chat`
  1037. - partially settings inside these keys:
  1038.   - `:seconds_valid` in `Pleroma.Captcha`
  1039.   - `:proxy_remote` in `Pleroma.Upload`
  1040.   - `:upload_limit` in `:instance`
  1042. - Params:
  1043.   - `configs` - array of config objects
  1044.   - config object params:
  1045.     - `group` - string (**required**)
  1046.     - `key` - string (**required**)
  1047.     - `value` - string, [], {} or {"tuple": []} (**required**)
  1048.     - `delete` - true (*optional*, if setting must be deleted)
  1049.     - `subkeys` - array of strings (*optional*, only works when `delete=true` parameter is passed, otherwise will be ignored)
  1051. *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.*
  1052. ```
  1053. [subkey: val1, subkey2: val2, subkey3: val3] \\ initial value
  1054. {"group": ":pleroma", "key": "some_key", "delete": true, "subkeys": [":subkey", ":subkey3"]} \\ passing json for deletion
  1055. [subkey2: val2] \\ value after deletion
  1056. ```
  1058. *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.*
  1060. Example of setting without keyword in value:
  1061. ```elixir
  1062. config :tesla, :adapter, Tesla.Adapter.Hackney
  1063. ```
  1065. List of settings which support only full update by key:
  1066. ```elixir
  1067. @full_key_update [
  1068.     {:pleroma, :ecto_repos},
  1069.     {:mime, :types},
  1070.     {:cors_plug, [:max_age, :methods, :expose, :headers]},
  1071.     {:auto_linker, :opts},
  1072.     {:swarm, :node_blacklist},
  1073.     {:logger, :backends}
  1074.   ]
  1075. ```
  1077. List of settings which support only full update by subkey:
  1078. ```elixir
  1079. @full_subkey_update [
  1080.     {:pleroma, :assets, :mascots},
  1081.     {:pleroma, :emoji, :groups},
  1082.     {:pleroma, :workers, :retries},
  1083.     {:pleroma, :mrf_subchain, :match_actor},
  1084.     {:pleroma, :mrf_keyword, :replace}
  1085.   ]
  1086. ```
  1088. *Settings without explicit key must be sent in separate config object params.*
  1089. ```elixir
  1090. config :foo,
  1091.   bar: :baz,
  1092.   meta: [:data],
  1093.   ...
  1094. ```
  1095. ```json
  1096. {
  1097.   "configs": [
  1098.     {"group": ":foo", "key": ":bar", "value": ":baz"},
  1099.     {"group": ":foo", "key": ":meta", "value": [":data"]},
  1100.     ...
  1101.   ]
  1102. }
  1103. ```
  1104. - Request:
  1106. ```json
  1107. {
  1108.   "configs": [
  1109.     {
  1110.       "group": ":pleroma",
  1111.       "key": "Pleroma.Upload",
  1112.       "value": [
  1113.         {"tuple": [":uploader", "Pleroma.Uploaders.Local"]},
  1114.         {"tuple": [":filters", ["Pleroma.Upload.Filter.Dedupe"]]},
  1115.         {"tuple": [":link_name", true]},
  1116.         {"tuple": [":proxy_remote", false]},
  1117.         {"tuple": [":proxy_opts", [
  1118.           {"tuple": [":redirect_on_failure", false]},
  1119.           {"tuple": [":max_body_length", 1048576]},
  1120.           {"tuple": [":http", [
  1121.             {"tuple": [":follow_redirect", true]},
  1122.             {"tuple": [":pool", ":upload"]},
  1123.           ]]}
  1124.         ]
  1125.         ]},
  1126.         {"tuple": [":dispatch", {
  1127.           "tuple": ["/api/v1/streaming", "Pleroma.Web.MastodonAPI.WebsocketHandler", []]
  1128.         }]}
  1129.       ]
  1130.     }
  1131.   ]
  1132. }
  1133. ```
  1135. - Response:
  1136.   - On failure:
  1137.     - 400 Bad Request `"To use this endpoint you need to enable configuration from database."`
  1138. ```json
  1139. {
  1140.   "configs": [
  1141.     {
  1142.       "group": ":pleroma",
  1143.       "key": "Pleroma.Upload",
  1144.       "value": [...]
  1145.      }
  1146.   ],
  1147.   "need_reboot": true
  1148. }
  1149. ```
  1151. ## ` GET /api/v1/pleroma/admin/config/descriptions`
  1153. ### Get JSON with config descriptions.
  1154. Loads json generated from `config/descriptions.exs`.
  1156. - Params: none
  1157. - Response:
  1159. ```json
  1160. [{
  1161.     "group": ":pleroma", // string
  1162.     "key": "ModuleName", // string
  1163.     "type": "group", // string or list with possible values,
  1164.     "description": "Upload general settings", // string
  1165.     "children": [
  1166.       {
  1167.         "key": ":uploader", // string or module name `Pleroma.Upload`
  1168.         "type": "module",
  1169.         "description": "Module which will be used for uploads",
  1170.         "suggestions": ["module1", "module2"]
  1171.       },
  1172.       {
  1173.         "key": ":filters",
  1174.         "type": ["list", "module"],
  1175.         "description": "List of filter modules for uploads",
  1176.         "suggestions": [
  1177.           "module1", "module2", "module3"
  1178.         ]
  1179.       }
  1180.     ]
  1181. }]
  1182. ```
  1184. ## `GET /api/v1/pleroma/admin/moderation_log`
  1186. ### Get moderation log
  1188. - Params:
  1189.   - *optional* `page`: **integer** page number
  1190.   - *optional* `page_size`: **integer** number of log entries per page (default is `50`)
  1191.   - *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`
  1192.   - *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
  1193.   - *optional* `user_id`: **integer** filter logs by actor's id
  1194.   - *optional* `search`: **string** search logs by the log message
  1195. - Response:
  1197. ```json
  1198. {
  1199.   "items": [
  1200.     {
  1201.       "id": 1234,
  1202.       "data": {
  1203.         "actor": {
  1204.           "id": 1,
  1205.           "nickname": "lain"
  1206.         },
  1207.         "action": "relay_follow"
  1208.       },
  1209.       "time": 1502812026, // timestamp
  1210.       "message": "[2017-08-15 15:47:06] @nick0 followed relay: https://example.org/relay" // log message
  1211.     }
  1212.   ],
  1213.   "total": 1
  1214. }
  1215. ```
  1217. ## `POST /api/v1/pleroma/admin/reload_emoji`
  1219. ### Reload the instance's custom emoji
  1221. - Authentication: required
  1222. - Params: None
  1223. - Response: JSON, "ok" and 200 status
  1225. ## `PATCH /api/v1/pleroma/admin/users/confirm_email`
  1227. ### Confirm users' emails
  1229. - Params:
  1230.   - `nicknames`
  1231. - Response: Array of user nicknames
  1233. ## `PATCH /api/v1/pleroma/admin/users/resend_confirmation_email`
  1235. ### Resend confirmation email
  1237. - Params:
  1238.   - `nicknames`
  1239. - Response: Array of user nicknames
  1241. ## `GET /api/v1/pleroma/admin/stats`
  1243. ### Stats
  1245. - Query Params:
  1246.   - *optional* `instance`: **string** instance hostname (without protocol) to get stats for
  1247. - Example: `https://mypleroma.org/api/v1/pleroma/admin/stats?instance=lain.com`
  1249. - Response:
  1251. ```json
  1252. {
  1253.   "status_visibility": {
  1254.     "direct": 739,
  1255.     "private": 9,
  1256.     "public": 17,
  1257.     "unlisted": 14
  1258.   }
  1259. }
  1260. ```
  1262. ## `GET /api/v1/pleroma/admin/oauth_app`
  1264. ### List OAuth app
  1266. - Params:
  1267.   - *optional* `name`
  1268.   - *optional* `client_id`
  1269.   - *optional* `page`
  1270.   - *optional* `page_size`
  1271.   - *optional* `trusted`
  1273. - Response:
  1275. ```json
  1276. {
  1277.   "apps": [
  1278.     {
  1279.       "id": 1,
  1280.       "name": "App name",
  1281.       "client_id": "yHoDSiWYp5mPV6AfsaVOWjdOyt5PhWRiafi6MRd1lSk",
  1282.       "client_secret": "nLmis486Vqrv2o65eM9mLQx_m_4gH-Q6PcDpGIMl6FY",
  1283.       "redirect_uri": "https://example.com/oauth-callback",
  1284.       "website": "https://example.com",
  1285.       "trusted": true
  1286.     }
  1287.   ],
  1288.   "count": 17,
  1289.   "page_size": 50
  1290. }
  1291. ```
  1294. ## `POST /api/v1/pleroma/admin/oauth_app`
  1296. ### Create OAuth App
  1298. - Params:
  1299.   - `name`
  1300.   - `redirect_uris`
  1301.   - `scopes`
  1302.   - *optional* `website`
  1303.   - *optional* `trusted`
  1305. - Response:
  1307. ```json
  1308. {
  1309.   "id": 1,
  1310.   "name": "App name",
  1311.   "client_id": "yHoDSiWYp5mPV6AfsaVOWjdOyt5PhWRiafi6MRd1lSk",
  1312.   "client_secret": "nLmis486Vqrv2o65eM9mLQx_m_4gH-Q6PcDpGIMl6FY",
  1313.   "redirect_uri": "https://example.com/oauth-callback",
  1314.   "website": "https://example.com",
  1315.   "trusted": true
  1316. }
  1317. ```
  1319. - On failure:
  1320. ```json
  1321. {
  1322.   "redirect_uris": "can't be blank",
  1323.   "name": "can't be blank"
  1324. }
  1325. ```
  1327. ## `PATCH /api/v1/pleroma/admin/oauth_app/:id`
  1329. ### Update OAuth App
  1331. - Params:
  1332.   -  *optional* `name`
  1333.   -  *optional* `redirect_uris`
  1334.   -  *optional* `scopes`
  1335.   -  *optional* `website`
  1336.   -  *optional* `trusted`
  1338. - Response:
  1340. ```json
  1341. {
  1342.   "id": 1,
  1343.   "name": "App name",
  1344.   "client_id": "yHoDSiWYp5mPV6AfsaVOWjdOyt5PhWRiafi6MRd1lSk",
  1345.   "client_secret": "nLmis486Vqrv2o65eM9mLQx_m_4gH-Q6PcDpGIMl6FY",
  1346.   "redirect_uri": "https://example.com/oauth-callback",
  1347.   "website": "https://example.com",
  1348.   "trusted": true
  1349. }
  1350. ```
  1352. ## `DELETE /api/v1/pleroma/admin/oauth_app/:id`
  1354. ### Delete OAuth App
  1356. - Params: None
  1358. - Response:
  1359.   - On success: `204`, empty response
  1360.   - On failure:
  1361.     - 400 Bad Request `"Invalid parameters"` when `status` is missing
  1363. ## `GET /api/v1/pleroma/admin/media_proxy_caches`
  1365. ### Get a list of all banned MediaProxy URLs in Cachex
  1367. - Authentication: required
  1368. - Params:
  1369. - *optional* `page`: **integer** page number
  1370. - *optional* `page_size`: **integer** number of log entries per page (default is `50`)
  1371. - *optional* `query`: **string** search term
  1373. - Response:
  1375. ``` json
  1376. {
  1377.   "page_size": integer,
  1378.   "count": integer,
  1379.   "urls": [
  1380.     "http://example.com/media/a688346.jpg",
  1381.     "http://example.com/media/fb1f4d.jpg"
  1382.   ]
  1383. }
  1385. ```
  1387. ## `POST /api/v1/pleroma/admin/media_proxy_caches/delete`
  1389. ### Remove a banned MediaProxy URL from Cachex
  1391. - Authentication: required
  1392. - Params:
  1393.   - `urls` (array)
  1395. - Response:
  1397. ``` json
  1398. { }
  1400. ```
  1402. ## `POST /api/v1/pleroma/admin/media_proxy_caches/purge`
  1404. ### Purge a MediaProxy URL
  1406. - Authentication: required
  1407. - Params:
  1408.   - `urls` (array)
  1409.   - `ban` (boolean)
  1411. - Response:
  1413. ``` json
  1414. { }
  1416. ```
  1418. ## GET /api/v1/pleroma/admin/users/:nickname/chats
  1420. ### List a user's chats
  1422. - Params: None
  1424. - Response:
  1426. ```json
  1427. [
  1428.    {
  1429.       "sender": {
  1430.         "id": "someflakeid",
  1431.         "username": "somenick",
  1432.         ...
  1433.       },
  1434.       "receiver": {
  1435.         "id": "someflakeid",
  1436.         "username": "somenick",
  1437.         ...
  1438.       },
  1439.       "id" : "1",
  1440.       "unread" : 2,
  1441.       "last_message" : {...}, // The last message in that chat
  1442.       "updated_at": "2020-04-21T15:11:46.000Z"
  1443.    }
  1444. ]
  1445. ```
  1447. ## GET /api/v1/pleroma/admin/chats/:chat_id
  1449. ### View a single chat
  1451. - Params: None
  1453. - Response:
  1455. ```json
  1456. {
  1457.   "sender": {
  1458.     "id": "someflakeid",
  1459.     "username": "somenick",
  1460.     ...
  1461.   },
  1462.   "receiver": {
  1463.     "id": "someflakeid",
  1464.     "username": "somenick",
  1465.     ...
  1466.   },
  1467.   "id" : "1",
  1468.   "unread" : 2,
  1469.   "last_message" : {...}, // The last message in that chat
  1470.   "updated_at": "2020-04-21T15:11:46.000Z"
  1471. }
  1472. ```
  1474. ## GET /api/v1/pleroma/admin/chats/:chat_id/messages
  1476. ### List the messages in a chat
  1478. - Params: `max_id`, `min_id`
  1480. - Response:
  1482. ```json
  1483. [
  1484.   {
  1485.     "account_id": "someflakeid",
  1486.     "chat_id": "1",
  1487.     "content": "Check this out :firefox:",
  1488.     "created_at": "2020-04-21T15:11:46.000Z",
  1489.     "emojis": [
  1490.       {
  1491.         "shortcode": "firefox",
  1492.         "static_url": "https://dontbulling.me/emoji/Firefox.gif",
  1493.         "url": "https://dontbulling.me/emoji/Firefox.gif",
  1494.         "visible_in_picker": false
  1495.       }
  1496.     ],
  1497.     "id": "13",
  1498.     "unread": true
  1499.   },
  1500.   {
  1501.     "account_id": "someflakeid",
  1502.     "chat_id": "1",
  1503.     "content": "Whats' up?",
  1504.     "created_at": "2020-04-21T15:06:45.000Z",
  1505.     "emojis": [],
  1506.     "id": "12",
  1507.     "unread": false
  1508.   }
  1509. ]
  1510. ```
  1512. ## DELETE /api/v1/pleroma/admin/chats/:chat_id/messages/:message_id
  1514. ### Delete a single message
  1516. - Params: None
  1518. - Response:
  1520. ```json
  1521. {
  1522.   "account_id": "someflakeid",
  1523.   "chat_id": "1",
  1524.   "content": "Check this out :firefox:",
  1525.   "created_at": "2020-04-21T15:11:46.000Z",
  1526.   "emojis": [
  1527.     {
  1528.       "shortcode": "firefox",
  1529.       "static_url": "https://dontbulling.me/emoji/Firefox.gif",
  1530.       "url": "https://dontbulling.me/emoji/Firefox.gif",
  1531.       "visible_in_picker": false
  1532.     }
  1533.   ],
  1534.   "id": "13",
  1535.   "unread": false
  1536. }
  1537. ```
  1539. ## `GET /api/v1/pleroma/admin/instance_document/:document_name`
  1541. ### Get an instance document
  1543. - Authentication: required
  1545. - Response:
  1547. Returns the content of the document
  1549. ```html
  1550. <h1>Instance panel</h1>
  1551. ```
  1553. ## `PATCH /api/v1/pleroma/admin/instance_document/:document_name`
  1554. - Params:
  1555.   - `file` (the file to be uploaded, using multipart form data.)
  1557. ### Update an instance document
  1559. - Authentication: required
  1561. - Response:
  1563. ``` json
  1564. {
  1565.   "url": "https://example.com/instance/panel.html"
  1566. }
  1567. ```
  1569. ## `DELETE /api/v1/pleroma/admin/instance_document/:document_name`
  1571. ### Delete an instance document
  1573. - Response:
  1575. ``` json
  1576. {
  1577.   "url": "https://example.com/instance/panel.html"
  1578. }
  1579. ```
  1581. ## `GET /api/v1/pleroma/admin/frontends
  1583. ### List available frontends
  1585. - Response:
  1587. ```json
  1588. [
  1589.    {
  1590.     "build_url": "https://git.pleroma.social/pleroma/fedi-fe/-/jobs/artifacts/${ref}/download?job=build",
  1591.     "git": "https://git.pleroma.social/pleroma/fedi-fe",
  1592.     "installed": true,
  1593.     "installed_refs": ["master"],
  1594.     "name": "fedi-fe",
  1595.     "ref": "master"
  1596.   },
  1597.   {
  1598.     "build_url": "https://git.pleroma.social/lambadalambda/kenoma/-/jobs/artifacts/${ref}/download?job=build",
  1599.     "git": "https://git.pleroma.social/lambadalambda/kenoma",
  1600.     "installed": false,
  1601.     "installed_refs": [],
  1602.     "name": "kenoma",
  1603.     "ref": "master"
  1604.   }
  1605. ]
  1606. ```
  1608. ## `POST /api/v1/pleroma/admin/frontends/install`
  1610. ### Install a frontend
  1612. - Params:
  1613.   - `name`: frontend name, required
  1614.   - `ref`: frontend ref
  1615.   - `file`: path to a frontend zip file
  1616.   - `build_url`: build URL
  1617.   - `build_dir`: build directory
  1619. - Response:
  1621. ```json
  1622. [
  1623.    {
  1624.     "build_url": "https://git.pleroma.social/pleroma/fedi-fe/-/jobs/artifacts/${ref}/download?job=build",
  1625.     "git": "https://git.pleroma.social/pleroma/fedi-fe",
  1626.     "installed": true,
  1627.     "name": "fedi-fe",
  1628.     "ref": "master"
  1629.   },
  1630.   {
  1631.     "build_url": "https://git.pleroma.social/lambadalambda/kenoma/-/jobs/artifacts/${ref}/download?job=build",
  1632.     "git": "https://git.pleroma.social/lambadalambda/kenoma",
  1633.     "installed": false,
  1634.     "name": "kenoma",
  1635.     "ref": "master"
  1636.   }
  1637. ]
  1638. ```
  1640. ```json
  1641. {
  1642.   "error": "Could not install frontend"
  1643. }
  1644. ```
  1646. ## `GET /api/v1/pleroma/admin/announcements`
  1648. ### List announcements
  1650. - Params: `offset`, `limit`
  1652. - Response: JSON, list of announcements
  1654. ```json
  1655. [
  1656.   {
  1657.     "id": "AHDp0GBdRn1EPN5HN2",
  1658.     "content": "some content",
  1659.     "starts_at": null,
  1660.     "ends_at": null,
  1661.     "all_day": false,
  1662.     "published_at": "2022-03-09T02:13:05",
  1663.     "reactions": [],
  1664.     "statuses": [],
  1665.     "tags": [],
  1666.     "emojis": [],
  1667.     "updated_at": "2022-03-09T02:13:05"
  1668.   }
  1669. ]
  1670. ```
  1672. Note that this differs from the Mastodon API variant: Mastodon API only returns *active* announcements, while this returns all.
  1674. ## `GET /api/v1/pleroma/admin/announcements/:id`
  1676. ### Display one announcement
  1678. - Response: JSON, one announcement
  1680. ```json
  1681. {
  1682.   "id": "AHDp0GBdRn1EPN5HN2",
  1683.   "content": "some content",
  1684.   "starts_at": null,
  1685.   "ends_at": null,
  1686.   "all_day": false,
  1687.   "published_at": "2022-03-09T02:13:05",
  1688.   "reactions": [],
  1689.   "statuses": [],
  1690.   "tags": [],
  1691.   "emojis": [],
  1692.   "updated_at": "2022-03-09T02:13:05"
  1693. }
  1694. ```
  1696. ## `POST /api/v1/pleroma/admin/announcements`
  1698. ### Create an announcement
  1700. - Params:
  1701.   - `content`: string, required, announcement content
  1702.   - `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
  1703.   - `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
  1704.   - `all_day`: boolean, optional, default to false, tells the client whether to only display dates for `starts_at` and `ends_at`
  1706. - Response: JSON, created announcement
  1708. ```json
  1709. {
  1710.   "id": "AHDp0GBdRn1EPN5HN2",
  1711.   "content": "some content",
  1712.   "starts_at": null,
  1713.   "ends_at": null,
  1714.   "all_day": false,
  1715.   "published_at": "2022-03-09T02:13:05",
  1716.   "reactions": [],
  1717.   "statuses": [],
  1718.   "tags": [],
  1719.   "emojis": [],
  1720.   "updated_at": "2022-03-09T02:13:05"
  1721. }
  1722. ```
  1724. ## `PATCH /api/v1/pleroma/admin/announcements/:id`
  1726. ### Change an announcement
  1728. - Params: same as `POST /api/v1/pleroma/admin/announcements`, except no param is required.
  1730. - Updates the announcement according to params. Missing params are kept as-is.
  1732. - Response: JSON, updated announcement
  1734. ```json
  1735. {
  1736.   "id": "AHDp0GBdRn1EPN5HN2",
  1737.   "content": "some content",
  1738.   "starts_at": null,
  1739.   "ends_at": null,
  1740.   "all_day": false,
  1741.   "published_at": "2022-03-09T02:13:05",
  1742.   "reactions": [],
  1743.   "statuses": [],
  1744.   "tags": [],
  1745.   "emojis": [],
  1746.   "updated_at": "2022-03-09T02:13:05"
  1747. }
  1748. ```
  1750. ## `DELETE /api/v1/pleroma/admin/announcements/:id`
  1752. ### Delete an announcement
  1754. - Response: JSON, empty object
  1756. ```json
  1757. {}
  1758. ```
  1761. ## `GET /api/v1/pleroma/admin/rules`
  1763. ### List rules
  1765. - Response: JSON, list of rules
  1767. ```json
  1768. [
  1769.   {
  1770.     "id": "1",
  1771.     "priority": 1,
  1772.     "text": "There are no rules",
  1773.     "hint": null
  1774.   }
  1775. ]
  1776. ```
  1778. ## `POST /api/v1/pleroma/admin/rules`
  1780. ### Create a rule
  1782. - Params:
  1783.   - `text`: string, required, rule content
  1784.   - `hint`: string, optional, rule description
  1785.   - `priority`: integer, optional, rule ordering priority
  1787. - Response: JSON, a single rule
  1789. ## `PATCH /api/v1/pleroma/admin/rules/:id`
  1791. ### Update a rule
  1793. - Params:
  1794.   - `text`: string, optional, rule content
  1795.   - `hint`: string, optional, rule description
  1796.   - `priority`: integer, optional, rule ordering priority
  1798. - Response: JSON, a single rule
  1800. ## `DELETE /api/v1/pleroma/admin/rules/:id`
  1802. ### Delete a rule
  1804. - Response: JSON, empty object
  1806. ```json
  1807. {}
  1808. ```