From 98ebbf06157e0af24e7f82c8da31f0c4812a73f7 Mon Sep 17 00:00:00 2001
From: sam <sam@sleepycat.moe>
Date: Thu, 28 Dec 2023 17:08:21 +0100
Subject: [PATCH] docs: add new admin endpoints to documentation

---
 docs/api/endpoints/v2/admin.md | 72 ++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 docs/api/endpoints/v2/admin.md

diff --git a/docs/api/endpoints/v2/admin.md b/docs/api/endpoints/v2/admin.md
new file mode 100644
index 0000000..4681c86
--- /dev/null
+++ b/docs/api/endpoints/v2/admin.md
@@ -0,0 +1,72 @@
+# Admin endpoints (v2)
+
+## Audit log object
+
+| Field              | Type                | Description                                                                         |
+| ------------------ | ------------------- | ----------------------------------------------------------------------------------- |
+| id                 | snowflake           | This action's ID                                                                    |
+| target_user_id     | snowflake           | The target user of this action. This may not be a valid user.                       |
+| target_member_id   | snowflake?          | The target member of this action. This may not be a valid member, even if not null. |
+| moderator_id       | snowflake           | The moderator that took this action. This may not be a valid user.                  |
+| report_id          | int?                | The report closed by this action                                                    |
+| reason             | string              | The reason this action was taken                                                    |
+| action_taken       | string              | The type of action taken. May be 'ignore', 'warn', or 'suspend'.                    |
+| cleared_data       | cleared data object | Any user/member data cleared by this action                                         |
+| target_name        | string?             | The target user's username                                                          |
+| target_member_name | string?             | The target member's name                                                            |
+| moderator_name     | string?             | The moderator's name                                                                |
+
+### Cleared data object
+
+| Field              | Type                                          | Description                                                 |
+| ------------------ | --------------------------------------------- | ----------------------------------------------------------- |
+| display_name       | ?string                                       | The previously set display name                             |
+| bio                | ?string                                       | The previously set bio                                      |
+| links              | ?string[]                                     | The previously set links                                    |
+| names              | ?[field_entry](../#field-entry)[]             | The previously set names                                    |
+| pronouns           | ?[pronoun_entry](../#pronoun-entry)[]         | The previously set pronouns                                 |
+| fields             | ?[field](../#field)[]                         | The previously set fields                                   |
+| custom_preferences | ?[custom_preference](../#custom-preference)[] | The previously set custom preferences _(user actions only)_ |
+
+## Endpoints
+
+### Get audit logs
+
+#### `GET /admin/audit-log`
+
+**Requires authentication.** Gets a list of audit log entries. By default, returns the latest 100 entries;
+to page through results, use the `before` query parameter.
+Returns an array of [audit log objects](./admin#audit-log-object) on success.
+
+#### Query parameters
+
+| Name   | Type      | Description                                  |
+| ------ | --------- | -------------------------------------------- |
+| before | snowflake | Only get entries with IDs lower than this ID |
+
+### Take action on a user
+
+#### `POST /admin/users/{id}/actions`
+
+**Requires authentication.** Take moderation actions on the given user.
+
+#### Request body parameters
+
+| Field                    | Type    | Description                                                                     |
+| ------------------------ | ------- | ------------------------------------------------------------------------------- |
+| type                     | string  | The type of action to take. Can be 'ignore', 'warn', 'suspend'.                 |
+| report_id                | ?int    | The report this action will close. Required if type is 'ignore'.                |
+| reason                   | ?string | The reason for this action. Required if type is not 'ignore'.                   |
+| clear.display_name       | bool    | Whether to clear the user's display name                                        |
+| clear.bio                | bool    | Whether to clear the user's bio                                                 |
+| clear.links              | bool    | Whether to clear the user's profile links                                       |
+| clear.names              | int[]   | Array of indexes of the user's names to clear. Must not have any duplicates.    |
+| clear.pronouns           | int[]   | Array of indexes of the user's pronouns to clear. Must not have any duplicates. |
+| clear.fields             | int[]   | Array of indexes of the user's fields to clear. Must not have any duplicates.   |
+| clear.custom_preferences | uuid[]  | Array of custom preference IDs to clear. Must not have any duplicates.          |
+
+#### Response body
+
+| Field        | Type      | Description                        |
+| ------------ | --------- | ---------------------------------- |
+| audit_log_id | snowflake | The ID of the newly created action |