logo

pleroma

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

admin_api.md (39373B)

    

  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.   {
  1198.     "id": 1234,
  1199.     "data": {
  1200.       "actor": {
  1201.         "id": 1,
  1202.         "nickname": "lain"
  1203.       },
  1204.       "action": "relay_follow"
  1205.     },
  1206.     "time": 1502812026, // timestamp
  1207.     "message": "[2017-08-15 15:47:06] @nick0 followed relay: https://example.org/relay" // log message
  1208.   }
  1209. ]
  1210. ```
  1212. ## `POST /api/v1/pleroma/admin/reload_emoji`
  1214. ### Reload the instance's custom emoji
  1216. - Authentication: required
  1217. - Params: None
  1218. - Response: JSON, "ok" and 200 status
  1220. ## `PATCH /api/v1/pleroma/admin/users/confirm_email`
  1222. ### Confirm users' emails
  1224. - Params:
  1225.   - `nicknames`
  1226. - Response: Array of user nicknames
  1228. ## `PATCH /api/v1/pleroma/admin/users/resend_confirmation_email`
  1230. ### Resend confirmation email
  1232. - Params:
  1233.   - `nicknames`
  1234. - Response: Array of user nicknames
  1236. ## `GET /api/v1/pleroma/admin/stats`
  1238. ### Stats
  1240. - Query Params:
  1241.   - *optional* `instance`: **string** instance hostname (without protocol) to get stats for
  1242. - Example: `https://mypleroma.org/api/v1/pleroma/admin/stats?instance=lain.com`
  1244. - Response:
  1246. ```json
  1247. {
  1248.   "status_visibility": {
  1249.     "direct": 739,
  1250.     "private": 9,
  1251.     "public": 17,
  1252.     "unlisted": 14
  1253.   }
  1254. }
  1255. ```
  1257. ## `GET /api/v1/pleroma/admin/oauth_app`
  1259. ### List OAuth app
  1261. - Params:
  1262.   - *optional* `name`
  1263.   - *optional* `client_id`
  1264.   - *optional* `page`
  1265.   - *optional* `page_size`
  1266.   - *optional* `trusted`
  1268. - Response:
  1270. ```json
  1271. {
  1272.   "apps": [
  1273.     {
  1274.       "id": 1,
  1275.       "name": "App name",
  1276.       "client_id": "yHoDSiWYp5mPV6AfsaVOWjdOyt5PhWRiafi6MRd1lSk",
  1277.       "client_secret": "nLmis486Vqrv2o65eM9mLQx_m_4gH-Q6PcDpGIMl6FY",
  1278.       "redirect_uri": "https://example.com/oauth-callback",
  1279.       "website": "https://example.com",
  1280.       "trusted": true
  1281.     }
  1282.   ],
  1283.   "count": 17,
  1284.   "page_size": 50
  1285. }
  1286. ```
  1289. ## `POST /api/v1/pleroma/admin/oauth_app`
  1291. ### Create OAuth App
  1293. - Params:
  1294.   - `name`
  1295.   - `redirect_uris`
  1296.   - `scopes`
  1297.   - *optional* `website`
  1298.   - *optional* `trusted`
  1300. - Response:
  1302. ```json
  1303. {
  1304.   "id": 1,
  1305.   "name": "App name",
  1306.   "client_id": "yHoDSiWYp5mPV6AfsaVOWjdOyt5PhWRiafi6MRd1lSk",
  1307.   "client_secret": "nLmis486Vqrv2o65eM9mLQx_m_4gH-Q6PcDpGIMl6FY",
  1308.   "redirect_uri": "https://example.com/oauth-callback",
  1309.   "website": "https://example.com",
  1310.   "trusted": true
  1311. }
  1312. ```
  1314. - On failure:
  1315. ```json
  1316. {
  1317.   "redirect_uris": "can't be blank",
  1318.   "name": "can't be blank"
  1319. }
  1320. ```
  1322. ## `PATCH /api/v1/pleroma/admin/oauth_app/:id`
  1324. ### Update OAuth App
  1326. - Params:
  1327.   -  *optional* `name`
  1328.   -  *optional* `redirect_uris`
  1329.   -  *optional* `scopes`
  1330.   -  *optional* `website`
  1331.   -  *optional* `trusted`
  1333. - Response:
  1335. ```json
  1336. {
  1337.   "id": 1,
  1338.   "name": "App name",
  1339.   "client_id": "yHoDSiWYp5mPV6AfsaVOWjdOyt5PhWRiafi6MRd1lSk",
  1340.   "client_secret": "nLmis486Vqrv2o65eM9mLQx_m_4gH-Q6PcDpGIMl6FY",
  1341.   "redirect_uri": "https://example.com/oauth-callback",
  1342.   "website": "https://example.com",
  1343.   "trusted": true
  1344. }
  1345. ```
  1347. ## `DELETE /api/v1/pleroma/admin/oauth_app/:id`
  1349. ### Delete OAuth App
  1351. - Params: None
  1353. - Response:
  1354.   - On success: `204`, empty response
  1355.   - On failure:
  1356.     - 400 Bad Request `"Invalid parameters"` when `status` is missing
  1358. ## `GET /api/v1/pleroma/admin/media_proxy_caches`
  1360. ### Get a list of all banned MediaProxy URLs in Cachex
  1362. - Authentication: required
  1363. - Params:
  1364. - *optional* `page`: **integer** page number
  1365. - *optional* `page_size`: **integer** number of log entries per page (default is `50`)
  1366. - *optional* `query`: **string** search term
  1368. - Response:
  1370. ``` json
  1371. {
  1372.   "page_size": integer,
  1373.   "count": integer,
  1374.   "urls": [
  1375.     "http://example.com/media/a688346.jpg",
  1376.     "http://example.com/media/fb1f4d.jpg"
  1377.   ]
  1378. }
  1380. ```
  1382. ## `POST /api/v1/pleroma/admin/media_proxy_caches/delete`
  1384. ### Remove a banned MediaProxy URL from Cachex
  1386. - Authentication: required
  1387. - Params:
  1388.   - `urls` (array)
  1390. - Response:
  1392. ``` json
  1393. { }
  1395. ```
  1397. ## `POST /api/v1/pleroma/admin/media_proxy_caches/purge`
  1399. ### Purge a MediaProxy URL
  1401. - Authentication: required
  1402. - Params:
  1403.   - `urls` (array)
  1404.   - `ban` (boolean)
  1406. - Response:
  1408. ``` json
  1409. { }
  1411. ```
  1413. ## GET /api/v1/pleroma/admin/users/:nickname/chats
  1415. ### List a user's chats
  1417. - Params: None
  1419. - Response:
  1421. ```json
  1422. [
  1423.    {
  1424.       "sender": {
  1425.         "id": "someflakeid",
  1426.         "username": "somenick",
  1427.         ...
  1428.       },
  1429.       "receiver": {
  1430.         "id": "someflakeid",
  1431.         "username": "somenick",
  1432.         ...
  1433.       },
  1434.       "id" : "1",
  1435.       "unread" : 2,
  1436.       "last_message" : {...}, // The last message in that chat
  1437.       "updated_at": "2020-04-21T15:11:46.000Z"
  1438.    }
  1439. ]
  1440. ```
  1442. ## GET /api/v1/pleroma/admin/chats/:chat_id
  1444. ### View a single chat
  1446. - Params: None
  1448. - Response:
  1450. ```json
  1451. {
  1452.   "sender": {
  1453.     "id": "someflakeid",
  1454.     "username": "somenick",
  1455.     ...
  1456.   },
  1457.   "receiver": {
  1458.     "id": "someflakeid",
  1459.     "username": "somenick",
  1460.     ...
  1461.   },
  1462.   "id" : "1",
  1463.   "unread" : 2,
  1464.   "last_message" : {...}, // The last message in that chat
  1465.   "updated_at": "2020-04-21T15:11:46.000Z"
  1466. }
  1467. ```
  1469. ## GET /api/v1/pleroma/admin/chats/:chat_id/messages
  1471. ### List the messages in a chat
  1473. - Params: `max_id`, `min_id`
  1475. - Response:
  1477. ```json
  1478. [
  1479.   {
  1480.     "account_id": "someflakeid",
  1481.     "chat_id": "1",
  1482.     "content": "Check this out :firefox:",
  1483.     "created_at": "2020-04-21T15:11:46.000Z",
  1484.     "emojis": [
  1485.       {
  1486.         "shortcode": "firefox",
  1487.         "static_url": "https://dontbulling.me/emoji/Firefox.gif",
  1488.         "url": "https://dontbulling.me/emoji/Firefox.gif",
  1489.         "visible_in_picker": false
  1490.       }
  1491.     ],
  1492.     "id": "13",
  1493.     "unread": true
  1494.   },
  1495.   {
  1496.     "account_id": "someflakeid",
  1497.     "chat_id": "1",
  1498.     "content": "Whats' up?",
  1499.     "created_at": "2020-04-21T15:06:45.000Z",
  1500.     "emojis": [],
  1501.     "id": "12",
  1502.     "unread": false
  1503.   }
  1504. ]
  1505. ```
  1507. ## DELETE /api/v1/pleroma/admin/chats/:chat_id/messages/:message_id
  1509. ### Delete a single message
  1511. - Params: None
  1513. - Response:
  1515. ```json
  1516. {
  1517.   "account_id": "someflakeid",
  1518.   "chat_id": "1",
  1519.   "content": "Check this out :firefox:",
  1520.   "created_at": "2020-04-21T15:11:46.000Z",
  1521.   "emojis": [
  1522.     {
  1523.       "shortcode": "firefox",
  1524.       "static_url": "https://dontbulling.me/emoji/Firefox.gif",
  1525.       "url": "https://dontbulling.me/emoji/Firefox.gif",
  1526.       "visible_in_picker": false
  1527.     }
  1528.   ],
  1529.   "id": "13",
  1530.   "unread": false
  1531. }
  1532. ```
  1534. ## `GET /api/v1/pleroma/admin/instance_document/:document_name`
  1536. ### Get an instance document
  1538. - Authentication: required
  1540. - Response:
  1542. Returns the content of the document
  1544. ```html
  1545. <h1>Instance panel</h1>
  1546. ```
  1548. ## `PATCH /api/v1/pleroma/admin/instance_document/:document_name`
  1549. - Params:
  1550.   - `file` (the file to be uploaded, using multipart form data.)
  1552. ### Update an instance document
  1554. - Authentication: required
  1556. - Response:
  1558. ``` json
  1559. {
  1560.   "url": "https://example.com/instance/panel.html"
  1561. }
  1562. ```
  1564. ## `DELETE /api/v1/pleroma/admin/instance_document/:document_name`
  1566. ### Delete an instance document
  1568. - Response:
  1570. ``` json
  1571. {
  1572.   "url": "https://example.com/instance/panel.html"
  1573. }
  1574. ```
  1576. ## `GET /api/v1/pleroma/admin/frontends
  1578. ### List available frontends
  1580. - Response:
  1582. ```json
  1583. [
  1584.    {
  1585.     "build_url": "https://git.pleroma.social/pleroma/fedi-fe/-/jobs/artifacts/${ref}/download?job=build",
  1586.     "git": "https://git.pleroma.social/pleroma/fedi-fe",
  1587.     "installed": true,
  1588.     "installed_refs": ["master"],
  1589.     "name": "fedi-fe",
  1590.     "ref": "master"
  1591.   },
  1592.   {
  1593.     "build_url": "https://git.pleroma.social/lambadalambda/kenoma/-/jobs/artifacts/${ref}/download?job=build",
  1594.     "git": "https://git.pleroma.social/lambadalambda/kenoma",
  1595.     "installed": false,
  1596.     "installed_refs": [],
  1597.     "name": "kenoma",
  1598.     "ref": "master"
  1599.   }
  1600. ]
  1601. ```
  1603. ## `POST /api/v1/pleroma/admin/frontends/install`
  1605. ### Install a frontend
  1607. - Params:
  1608.   - `name`: frontend name, required
  1609.   - `ref`: frontend ref
  1610.   - `file`: path to a frontend zip file
  1611.   - `build_url`: build URL
  1612.   - `build_dir`: build directory
  1614. - Response:
  1616. ```json
  1617. [
  1618.    {
  1619.     "build_url": "https://git.pleroma.social/pleroma/fedi-fe/-/jobs/artifacts/${ref}/download?job=build",
  1620.     "git": "https://git.pleroma.social/pleroma/fedi-fe",
  1621.     "installed": true,
  1622.     "name": "fedi-fe",
  1623.     "ref": "master"
  1624.   },
  1625.   {
  1626.     "build_url": "https://git.pleroma.social/lambadalambda/kenoma/-/jobs/artifacts/${ref}/download?job=build",
  1627.     "git": "https://git.pleroma.social/lambadalambda/kenoma",
  1628.     "installed": false,
  1629.     "name": "kenoma",
  1630.     "ref": "master"
  1631.   }
  1632. ]
  1633. ```
  1635. ```json
  1636. {
  1637.   "error": "Could not install frontend"
  1638. }
  1639. ```
  1641. ## `GET /api/v1/pleroma/admin/announcements`
  1643. ### List announcements
  1645. - Params: `offset`, `limit`
  1647. - Response: JSON, list of announcements
  1649. ```json
  1650. [
  1651.   {
  1652.     "id": "AHDp0GBdRn1EPN5HN2",
  1653.     "content": "some content",
  1654.     "starts_at": null,
  1655.     "ends_at": null,
  1656.     "all_day": false,
  1657.     "published_at": "2022-03-09T02:13:05",
  1658.     "reactions": [],
  1659.     "statuses": [],
  1660.     "tags": [],
  1661.     "emojis": [],
  1662.     "updated_at": "2022-03-09T02:13:05"
  1663.   }
  1664. ]
  1665. ```
  1667. Note that this differs from the Mastodon API variant: Mastodon API only returns *active* announcements, while this returns all.
  1669. ## `GET /api/v1/pleroma/admin/announcements/:id`
  1671. ### Display one announcement
  1673. - Response: JSON, one announcement
  1675. ```json
  1676. {
  1677.   "id": "AHDp0GBdRn1EPN5HN2",
  1678.   "content": "some content",
  1679.   "starts_at": null,
  1680.   "ends_at": null,
  1681.   "all_day": false,
  1682.   "published_at": "2022-03-09T02:13:05",
  1683.   "reactions": [],
  1684.   "statuses": [],
  1685.   "tags": [],
  1686.   "emojis": [],
  1687.   "updated_at": "2022-03-09T02:13:05"
  1688. }
  1689. ```
  1691. ## `POST /api/v1/pleroma/admin/announcements`
  1693. ### Create an announcement
  1695. - Params:
  1696.   - `content`: string, required, announcement content
  1697.   - `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
  1698.   - `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
  1699.   - `all_day`: boolean, optional, default to false, tells the client whether to only display dates for `starts_at` and `ends_at`
  1701. - Response: JSON, created announcement
  1703. ```json
  1704. {
  1705.   "id": "AHDp0GBdRn1EPN5HN2",
  1706.   "content": "some content",
  1707.   "starts_at": null,
  1708.   "ends_at": null,
  1709.   "all_day": false,
  1710.   "published_at": "2022-03-09T02:13:05",
  1711.   "reactions": [],
  1712.   "statuses": [],
  1713.   "tags": [],
  1714.   "emojis": [],
  1715.   "updated_at": "2022-03-09T02:13:05"
  1716. }
  1717. ```
  1719. ## `PATCH /api/v1/pleroma/admin/announcements/:id`
  1721. ### Change an announcement
  1723. - Params: same as `POST /api/v1/pleroma/admin/announcements`, except no param is required.
  1725. - Updates the announcement according to params. Missing params are kept as-is.
  1727. - Response: JSON, updated announcement
  1729. ```json
  1730. {
  1731.   "id": "AHDp0GBdRn1EPN5HN2",
  1732.   "content": "some content",
  1733.   "starts_at": null,
  1734.   "ends_at": null,
  1735.   "all_day": false,
  1736.   "published_at": "2022-03-09T02:13:05",
  1737.   "reactions": [],
  1738.   "statuses": [],
  1739.   "tags": [],
  1740.   "emojis": [],
  1741.   "updated_at": "2022-03-09T02:13:05"
  1742. }
  1743. ```
  1745. ## `DELETE /api/v1/pleroma/admin/announcements/:id`
  1747. ### Delete an announcement
  1749. - Response: JSON, empty object
  1751. ```json
  1752. {}
  1753. ```