docs(api): tidy up the reference prose (#2628)

This commit is contained in:
Hampus authored and GitHub committed 2026-09-09 02:11:38 +02:00
1 parent 184eeb0846
commit bfa9bf221d
88 files changed
+1084 -1156

No files matched your search

@@ -189,7 +189,7 @@ The slowmode state combines the channel's configured interval with the authentic
## RTC region object
An RTC region names one voice routing target the deployment operates. Its identifier is the value a guild voice channel stores in `rtc_region`, and the name and emoji exist only for presentation.
An RTC region names one voice routing target the deployment operates. Its identifier is the value a guild voice channel stores in `rtc_region`, and the name and emoji exist only for display.
### Structure
@@ -217,8 +217,7 @@ Returns the [channel object](#channel-object) visible to the authenticated user.
### Limitations
- A guild channel requires [VIEW_CHANNEL](/http-api/permissions/).
- A guild channel that resolves to an age restriction also requires a satisfied age verification.
- A guild channel requires [VIEW_CHANNEL](/http-api/permissions/), and a satisfied age verification when it resolves to an age restriction.
- A private channel requires current recipient access.
- The personal notes channel requires ownership.
@@ -241,12 +240,12 @@ Fluxer enforces age verification only for a guild text, voice, or link channel.
| 404 | [error response](/http-api/#error-response) | Channel does not exist, or the caller is not a recipient of the private channel, each returning `UNKNOWN_CHANNEL`, or the guild that owns the channel does not exist and the request returns `UNKNOWN_GUILD` |
:::note[The guild resolves after the channel]
A channel whose guild is gone fails with `UNKNOWN_GUILD` rather than `UNKNOWN_CHANNEL`.
A channel whose guild is gone fails with `UNKNOWN_GUILD`, not `UNKNOWN_CHANNEL`.
:::
### Side effects
Requesting the personal notes channel of the authenticated user creates that channel when it does not already exist, and returns it directly without a [Channel Create](/gateway/events/#channel-create) Dispatch.
Requesting the personal notes channel of the authenticated user creates it when it does not already exist, and returns it with no [Channel Create](/gateway/events/#channel-create) Dispatch.
### Rate limit
@@ -276,7 +275,7 @@ Returns the authenticated user's [channel slowmode state object](#channel-slowmo
### Side effects
The read does not advance the caller's slowmode countdown. Requesting the personal notes channel of the authenticated user creates that channel when it does not already exist, with no [Channel Create](/gateway/events/#channel-create) Dispatch.
The read does not advance the caller's slowmode countdown. Requesting the personal notes channel of the authenticated user creates it when it does not already exist, with no [Channel Create](/gateway/events/#channel-create) Dispatch.
### Rate limit
@@ -341,7 +340,7 @@ Modifies a guild channel or a group direct message and returns the updated [chan
The submitted array becomes the complete overwrite collection of the channel.
:::
[Set channel permission overwrite](#set-channel-permission-overwrite) and [Delete channel permission overwrite](#delete-channel-permission-overwrite) each mutate one overwrite and leave the rest untouched.
[Set channel permission overwrite](#set-channel-permission-overwrite) and [Delete channel permission overwrite](#delete-channel-permission-overwrite) each change one overwrite and leave the rest untouched.
### Path parameters
@@ -454,7 +453,7 @@ Fluxer trims a stored nickname, and a value that is null or empty after trimming
### Side effects
A guild channel change emits [Channel Update](/gateway/events/#channel-update) to every session subscribed to the guild. Replacing a category's permission overwrites also replaces them on each child whose overwrites still exactly match the category's previous values, with one Dispatch per changed child. A child whose overwrites had diverged is left unchanged.
A guild channel change emits [Channel Update](/gateway/events/#channel-update) to every session subscribed to its guild. Replacing a category's permission overwrites also replaces them on each child whose overwrites still exactly match the category's previous values, with one Dispatch per changed child. A child whose overwrites had differed is left unchanged.
Changing `rate_limit_per_user` clears the channel's current slowmode state so the new interval applies immediately. Changing `rtc_region` on a guild voice channel moves its active voice connections to the selected region.
@@ -470,7 +469,7 @@ A group direct message change emits [Channel Update](/gateway/events/#channel-up
<RouteHeader method="DELETE" path="/v1/channels/{channel_id}" bot />
Deletes a guild channel, closes a direct message, or removes the caller from a group direct message, and returns 204 with an empty body. Emits a [Channel Delete](/gateway/events/#channel-delete) Gateway event.
Deletes a guild channel, closes a direct message, or removes the caller from a group direct message. Returns 204 with an empty body. Emits a [Channel Delete](/gateway/events/#channel-delete) Gateway event.
### Limitations
@@ -569,16 +568,15 @@ Adds a user to a group direct message and returns 204 with an empty body. Emits
### Limitations
- The caller must be a current recipient of the group.
- The caller and the target must be friends, including when the caller is a bot.
- The caller must be a current recipient of the group, and must be friends with the target, including when the caller is a bot.
- The target's group direct message admission policy must allow the caller.
- An instance with CAPTCHA enabled also requires a CAPTCHA proof.
Fluxer evaluates the target's admission policy in this order.
1. A target that has never stored settings admits every caller.
2. A nobody setting rejects every caller. An everyone setting admits every caller.
3. A friends-only setting admits only a caller the target has as a friend.
2. The nobody setting rejects every caller, and the everyone setting admits every caller.
3. The friends-only setting admits only a caller the target has as a friend.
4. Otherwise Fluxer admits the caller through an existing friendship, then through a mutual friend when the friends-of-friends setting is enabled, and then through a mutual guild when the guild-members setting is enabled.
### Path parameters
@@ -610,7 +608,7 @@ Fluxer evaluates the target's admission policy in this order.
| 403 | [error response](/http-api/#error-response) | Caller is not a recipient, or the target's admission policy rejects the caller, each returning `MISSING_ACCESS` |
| 404 | [error response](/http-api/#error-response) | Channel does not exist and the request returns `UNKNOWN_CHANNEL` |
The `MAX_GROUP_DM_RECIPIENTS` body has `max_recipients` reporting the exact ceiling that was reached. That ceiling is the deployment's [`max_group_dm_recipients`](/http-api/instance/#limit-keys) limit resolved for the caller, and it defaults to 50.
The `MAX_GROUP_DM_RECIPIENTS` body has `max_recipients`, the exact ceiling that was reached. That ceiling is the deployment's [`max_group_dm_recipients`](/http-api/instance/#limit-keys) limit resolved for the caller, and it defaults to 50.
### Side effects
@@ -629,7 +627,7 @@ Removes a user from a group direct message and returns 204 with an empty body. E
### Limitations
- The caller must be a current recipient.
- A caller may remove themself regardless of ownership.
- A caller may remove themselves regardless of ownership.
- Removing another recipient requires ownership of the group.
- Setting `delete_messages` takes effect only when `user_id` is the caller, and it then requires sudo verification on the same terms as [Delete or leave channel](#delete-or-leave-channel).
@@ -696,7 +694,7 @@ Creates or replaces one permission overwrite on a guild channel and returns 204
The operation does not require `VIEW_CHANNEL` and never returns `TWO_FACTOR_REQUIRED` or `NSFW_CONTENT_AGE_RESTRICTED`.
:::note[The identifier alone keys the overwrite]
:::note[The identifier alone selects the overwrite]
`type` records whether the identifier names a role or a member, and does not change which entry is written. An overwrite can be stored for an identifier that names nothing, and [Delete channel permission overwrite](#delete-channel-permission-overwrite) removes it.
:::
@@ -757,7 +755,7 @@ Deletes one permission overwrite from a guild channel and returns 204 with an em
- A caller without [ADMINISTRATOR](/http-api/permissions/) must already hold every permission bit the removed overwrite denied.
The operation is idempotent. It does not require `VIEW_CHANNEL` and never returns `TWO_FACTOR_REQUIRED` or `NSFW_CONTENT_AGE_RESTRICTED`.
The operation is idempotent, does not require `VIEW_CHANNEL`, and never returns `TWO_FACTOR_REQUIRED` or `NSFW_CONTENT_AGE_RESTRICTED`.
### Path parameters
@@ -766,7 +764,7 @@ The operation is idempotent. It does not require `VIEW_CHANNEL` and never return
| channel_id | snowflake | The ID of the guild channel |
| overwrite_id<sup>1</sup> | snowflake | The ID of the role or member the overwrite represents |
<sup>1</sup> The identifier alone selects the overwrite. The request has no overwrite type
<sup>1</sup> The identifier alone selects the overwrite, and the request has no overwrite type
### Response