logo

pleroma

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

admin_api.md (40241B)

    

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