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 |