mirror of
https://github.com/fluxerapp/fluxer
synced 2026-10-18 21:45:31 +09:00
docs(api): tidy up the reference prose (#2628)
This commit is contained in:
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
|
||||
|
||||
|
||||
Reference in new issue
Block a user