pepepper/fluxer
1
0 Fork 0
mirror of https://github.com/fluxerapp/fluxer synced 2026-10-18 05:25:40 +09:00
Code Issues Packages Projects Releases Wiki Activity
Files
7a5b9a0deda0bbbb5fa745e3977109a91c7ec6a3
fluxer/fluxer_docs/src/content/docs/http-api/invites.mdx
T

433 lines
29 KiB
Plaintext
Raw Blame History

---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Invites
description: Invite objects, invite metadata, custom invite URLs, and the invite operations.
---
import RouteHeader from '@/components/RouteHeader.astro';
An invite is a code that admits an account into a guild or a group direct message.
[Get invite](#get-invite) is the only route here that needs no credential. [Modify guild custom invite URL](/http-api/guilds/#modify-guild-custom-invite-url) configures a guild's custom invite URL, and [Discovery](/http-api/discovery/) defines joining an approved public guild with no invite.
## Invite object
An invite object describes one code and the target it admits into. The `type` selects the representation.
### Structure
| Field | Type | Description |
| --- | --- | --- |
| code | string | The unique code that identifies the invite |
| type | integer | [Invite type](#invite-types) |
| guild?<sup>1</sup> | [partial guild](/http-api/guilds/#partial-guild-object) object | The guild the invite admits into |
| channel?<sup>2</sup> | [partial invite channel](#partial-invite-channel-object) object | The guild channel or group direct message the invite targets |
| inviter<sup>3</sup> | ?[partial user](/http-api/users/#partial-user-object) object | The account that created the invite, or null |
| member_count?<sup>4</sup> | integer | The member count of the guild, or the exact recipient count of the group direct message |
| presence_count?<sup>4</sup> | integer | The online member count of the guild |
| expires_at<sup>5</sup> | ?ISO8601 timestamp | The time at which the invite stops resolving, or null when it never expires |
| temporary<sup>6</sup> | boolean | Whether admission through this invite grants temporary membership |
<sup>1</sup> Present only when `type` is `0`, and it applies the same feature-gated asset stripping as the full [guild object](/http-api/guilds/#guild-object)
<sup>2</sup> Present when `type` is `0` or `1`. A guild invite with no stored target channel resolves the first guild text channel the default role can view
<sup>3</sup> Null when the record stores no creator, which is always the case for a custom invite URL
<sup>4</sup> Guild counts are `0` when unavailable
<sup>5</sup> Computed from the creation time plus the stored lifetime, and null whenever that lifetime is `0`
<sup>6</sup> Has no effect on a group direct message invite
:::note[Branch on `type` to know which fields arrive]
A guild invite always has `guild`, `channel`, `member_count`, and `presence_count`. A group direct message invite has `channel` and `member_count` only.
:::
### Example
```json
{
"code": "aB3dEf7h",
"type": 0,
"guild": {"id": "1489002177550843904", "name": "Example guild"},
"channel": {"id": "1489002177550843905", "name": "general", "type": 0},
"inviter": {"id": "1501314428688998182", "username": "example"},
"member_count": 412,
"presence_count": 87,
"expires_at": null,
"temporary": false
}
```
## Invite types
| Value | Name | Description |
| --- | --- | --- |
| 0 | GUILD | An invite that admits an account into a guild |
| 1 | GROUP_DM | An invite that admits an account into a group direct message |
## Invite metadata object
The metadata object extends the [invite](#invite-object) with its creation and usage state. [Create channel invite](#create-channel-invite), [List channel invites](#list-channel-invites), and [List guild invites](#list-guild-invites) return it. [Get invite](#get-invite) never does.
### Structure
| Field | Type | Description |
| --- | --- | --- |
| created_at | ISO8601 timestamp | The time at which the invite record was created |
| uses<sup>1</sup> | integer | The number of admissions completed through the invite |
| max_uses<sup>2</sup> | integer | The maximum admissions the invite permits, where `0` is unlimited |
| max_age?<sup>3</sup> | integer | The stored lifetime in seconds, where `0` never expires |
<sup>1</sup> The counter advances only when the admission adds the account, so accepting an invite for a target the account already belongs to leaves it unchanged
<sup>2</sup> The value is `0` for every custom invite URL and for any invite created without an explicit maximum
<sup>3</sup> Present only when `type` is `0`, because a group direct message invite reports its expiry only through `expires_at`
### Example
```json
{
"code": "aB3dEf7h",
"type": 0,
"created_at": "2026-08-04T11:22:19.000Z",
"uses": 3,
"max_uses": 25,
"max_age": 86400,
"temporary": false
}
```
## Partial invite channel object
The partial channel has only enough identity to describe the target before admission.
### Structure
| Field | Type | Description |
| --- | --- | --- |
| id | snowflake | The ID of the channel |
| name<sup>1</sup> | ?string | The name of the channel, or null |
| type | integer | [Channel type](/http-api/channels/#channel-types) |
| recipients?<sup>2</sup> | array[[partial invite recipient](#partial-invite-recipient-object) object] | The accounts in the group direct message |
<sup>1</sup> A guild channel always stores a name, and a group direct message that stores no name reports null
<sup>2</sup> Present only on a group direct message invite, and it lists every current recipient including the invite creator
## Partial invite recipient object
A partial recipient has only the username.
### Structure
| Field | Type | Description |
| --- | --- | --- |
| username | string | The username of the recipient |
### Example
```json
{
"username": "example"
}
```
## Custom invite URLs
[Modify guild custom invite URL](/http-api/guilds/#modify-guild-custom-invite-url) creates or replaces a custom invite code. It has type `0`, null `inviter` and `expires_at`, and `max_uses` and `max_age` of `0`. Its channel is the first guild text channel in channel order that the default role can view.
Custom invite codes are case-insensitive. Clearing or replacing a code makes the old link stop resolving immediately.
[Accept invite](#accept-invite) records the join as a custom invite URL admission and attributes no inviter and no source invite code. [List channel invites](#list-channel-invites) and [List guild invites](#list-guild-invites) exclude custom invite URLs, and [Delete invite](#delete-invite) refuses them.
## Get invite
<RouteHeader method="GET" path="/v1/invites/{invite_code}" unauthenticated />
Reads one invite. Returns an [invite object](#invite-object) on success.
An `Authorization` header that cannot be resolved is ignored, and the route returns the same representation to every caller. The read consumes no use.
Codes from [Create channel invite](#create-channel-invite) are case-sensitive. Custom invite codes are case-insensitive.
:::note[Every admission gate runs at accept time]
A 200 response means the invite code exists and none of the 404 conditions in the response table below applies. [Accept invite](#accept-invite) checks bans, the guild's invites-disabled feature, exhausted uses, the active presence a temporary invite requires, and whether the target is full.
:::
:::note[Lookup does not guarantee admission]
Expired invites no longer resolve. An exhausted invite may still resolve until an acceptance attempt removes it.
:::
### Path parameters
| Field | Type | Description |
| --- | --- | --- |
| invite_code<sup>1</sup> | string | The invite code to resolve (1 through 256 characters) |
<sup>1</sup> Normalised before lookup by removing form feed and right-to-left override characters and trimming, and a value empty or above 256 characters afterwards returns the field code `STRING_LENGTH_INVALID`
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [invite](#invite-object) object | Invite resolved |
| 404 | [error response](/http-api/#error-response) | No record has the code, a guild invite names no guild, a group direct message invite names no channel or unresolvable recipient, or a guild invite with no stored target channel exposes no viewable channel, each returning `UNKNOWN_INVITE` |
| 404 | [error response](/http-api/#error-response) | The stored target channel no longer exists and the request returns `UNKNOWN_CHANNEL` |
| 404 | [error response](/http-api/#error-response) | The named guild no longer exists and the request returns `UNKNOWN_GUILD` |
### Rate limit
100 requests per 10 seconds for each identity and invite code, on the `invite:read::invite_code` bucket. The identity is the authenticated account when a credential resolves, and otherwise the derived key for the client IP address.
## Accept invite
<RouteHeader method="POST" path="/v1/invites/{invite_code}" />
Accepts an invite and admits the authenticated account into its target. Returns an [invite object](#invite-object) on success.
A guild admission emits [Guild Create](/gateway/events/#guild-create), [Guild Member Add](/gateway/events/#guild-member-add), [User Settings Update](/gateway/events/#user-settings-update), [User Guild Settings Update](/gateway/events/#user-guild-settings-update), and [Message Create](/gateway/events/#message-create) Gateway events. A group direct message admission emits [Channel Create](/gateway/events/#channel-create), [Channel Recipient Add](/gateway/events/#channel-recipient-add), and [Message Create](/gateway/events/#message-create) Gateway events.
### Limitations
- User-only, so a bot token is rejected with 403 `ACCESS_DENIED`.
- The caller needs no permission.
:::caution[Exhausted invites stop working]
Accepting an exhausted invite returns 404 `UNKNOWN_INVITE` and makes the code stop resolving. Custom invite URLs have no use limit.
:::
### Path parameters
| Field | Type | Description |
| --- | --- | --- |
| invite_code | string | The invite code to accept (1 through 256 characters) |
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [invite](#invite-object) object | Account was admitted, or was already a member of the target |
| 400 | [error response](/http-api/#error-response) | A temporary guild invite is accepted without an active presence and the request returns `TEMPORARY_INVITE_REQUIRES_PRESENCE` |
| 400 | [error response](/http-api/#error-response) | An unclaimed account accepts a group direct message invite and the request returns `UNCLAIMED_ACCOUNT_CANNOT_JOIN_GROUP_DMS` |
| 400 | [error response](/http-api/#error-response) | A type `1` invite names a private channel that is not a group direct message and the caller is not already a recipient and the request returns `INVALID_CHANNEL_TYPE` |
| 400 | [error response](/http-api/#error-response) | The caller already holds the maximum number of guilds and the request returns `MAX_GUILDS` |
| 400 | [error response](/http-api/#error-response) | The target is full and the request returns `MAX_GUILD_MEMBERS` or `MAX_GROUP_DM_RECIPIENTS` |
| 403 | [error response](/http-api/#error-response) | Caller is a bot or presents a bearer credential and the request returns `ACCESS_DENIED` |
| 403 | [error response](/http-api/#error-response) | The guild has the invites-disabled feature and the request returns `INVITES_DISABLED` |
| 403 | [error response](/http-api/#error-response) | Instant invites are temporarily disabled for the guild and the request returns `FEATURE_TEMPORARILY_DISABLED` |
| 403 | [error response](/http-api/#error-response) | The caller is banned by account or email address and the request returns `USER_BANNED_FROM_GUILD` |
| 403 | [error response](/http-api/#error-response) | The caller is banned by network address and the request returns `USER_IP_BANNED_FROM_GUILD` |
| 403 | [error response](/http-api/#error-response) | The account is [limited](/http-api/users/#account-limitation) and not already a member or recipient, and the request returns `ACCOUNT_LIMITED` |
| 404 | [error response](/http-api/#error-response) | The named guild no longer exists and the request returns `UNKNOWN_GUILD` |
| 404 | [error response](/http-api/#error-response) | The target channel no longer exists and the request returns `UNKNOWN_CHANNEL` |
| 404 | [error response](/http-api/#error-response) | The code resolves to no record, the record is exhausted, a guild invite names no guild, or a group direct message invite names no channel or a channel that no longer exists, each returning `UNKNOWN_INVITE` |
### Side effects
When the account is already in the target, the route returns 200 with the invite object. It consumes no use and emits no Dispatch. A new admission consumes one use and removes the invite when its limit is reached. A failed admission consumes no use. If the invite's channel has been deleted, the account can still join and consume a use even though the response is 404 `UNKNOWN_CHANNEL`.
A guild admission creates the membership, records whether the join used a custom invite URL or an instant invite, and adds the guild to the caller's settings and folder layout. A temporary invite marks the membership temporary.
The joining account receives [Guild Create](/gateway/events/#guild-create). [Guild Member Add](/gateway/events/#guild-member-add) is guild-wide and reaches every session connected to the guild, subject to the [event filtering](/gateway/event-filtering/) gates, which withhold it from a passive user session in a guild with more than 250 members. The joining account receives [User Settings Update](/gateway/events/#user-settings-update) when the join changes its stored settings, and [User Guild Settings Update](/gateway/events/#user-guild-settings-update) when its `default_hide_muted_channels` setting is enabled. Unless the guild's `system_channel_flags` has [SUPPRESS_JOIN_NOTIFICATIONS](/http-api/guilds/#system-channel-flags) or the guild has no system channel, the operation creates a join system message and delivers [Message Create](/gateway/events/#message-create).
A group direct message admission adds the caller as a recipient and creates a recipient addition system message. The joining account receives [Channel Create](/gateway/events/#channel-create), the recipients the group already held receive [Channel Recipient Add](/gateway/events/#channel-recipient-add), and every recipient receives [Message Create](/gateway/events/#message-create).
No admission path records a guild audit entry.
### Rate limit
10 requests per 10 seconds for each authenticated user, on the `invite:accept` bucket, which is not partitioned by invite code.
## Delete invite
<RouteHeader method="DELETE" path="/v1/invites/{invite_code}" bot auditReason mfa />
Deletes an invite permanently and returns 204 with an empty body. Emits an [Invite Delete](/gateway/events/#invite-delete) Gateway event.
### Limitations
- A guild invite requires guild membership.
- The invite creator deletes it without holding [MANAGE_GUILD](/http-api/permissions/), and any other member needs that permission.
- A group direct message invite requires the caller to be a current recipient and the owner of the group.
`MANAGE_GUILD` is an [elevated permission](/http-api/permissions/#elevated-permissions), so a caller who is neither the guild owner nor enrolled in multi-factor authentication receives 400 [`TWO_FACTOR_REQUIRED`](/http-api/errors/) in a guild whose [MFA level](/http-api/guilds/#mfa-levels) is elevated.
:::note[Non-membership and missing permission return the same 403]
A non-member and a member without the permission both receive 403 `MISSING_PERMISSIONS`. A guild that no longer exists returns 404 `UNKNOWN_GUILD`.
:::
:::caution[Deletion is immediate and unrecoverable]
The invite code can be allocated again later, and every outstanding link with that code stops resolving immediately.
:::
### Path parameters
| Field | Type | Description |
| --- | --- | --- |
| invite_code | string | The invite code to delete (1 through 256 characters) |
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | Invite was deleted |
| 400 | [error response](/http-api/#error-response) | The caller is not the creator and the guild requires elevated multi-factor authentication that the caller lacks, and the request returns `TWO_FACTOR_REQUIRED` |
| 403 | [error response](/http-api/#error-response) | Caller presents a bearer credential and the request returns `ACCESS_DENIED`, or the caller is not a guild member, is neither the creator nor a [MANAGE_GUILD](/http-api/permissions/) holder, or does not own the group direct message, each returning `MISSING_PERMISSIONS` |
| 404 | [error response](/http-api/#error-response) | The named guild no longer exists and the request returns `UNKNOWN_GUILD` |
| 404 | [error response](/http-api/#error-response) | No record has the code, the record is the guild's current custom invite URL, or a guild invite names no target, each returning `UNKNOWN_INVITE` |
| 404 | [error response](/http-api/#error-response) | The group direct message no longer exists or the caller is not one of its recipients and the request returns `UNKNOWN_CHANNEL` |
### Side effects
A guild invite records an [INVITE_DELETE audit action](/http-api/guild-audit-logs/#audit-actions) targeting the invite code, with the channel, creator, maximum uses, lifetime, and temporary flag as metadata, the removed record as the change set, and the supplied reason. Fluxer logs a failure to write that entry and still completes the request. The `X-Audit-Log-Reason` header is read but never recorded for a group direct message invite.
Sessions holding `VIEW_AUDIT_LOG` receive [Guild Audit Log Entry Create](/gateway/events/#guild-audit-log-entry-create). [Invite Delete](/gateway/events/#invite-delete) has only `code`, `channel_id`, and `guild_id`. The guild delivers it to the sessions holding `MANAGE_CHANNELS` on the channel named by `channel_id`, as [event filtering](/gateway/event-filtering/) states. A passive session in a guild with more than 250 members is suppressed after that filter. A group direct message invite creates no audit entry and delivers Invite Delete to every current recipient's sessions, where no passive gate applies.
### Rate limit
20 requests per 10 seconds for each authenticated user and invite code, on the `invite:delete::invite_code` bucket.
## Create channel invite
<RouteHeader method="POST" path="/v1/channels/{channel_id}/invites" bot auditReason />
Creates an invite for a channel, or returns an existing equivalent invite. Returns an [invite metadata object](#invite-metadata-object) on success. Emits an [Invite Create](/gateway/events/#invite-create) Gateway event when a new record is created.
### Limitations
- A guild channel requires guild membership, [VIEW_CHANNEL](/http-api/permissions/), and [CREATE_INSTANT_INVITE](/http-api/permissions/) in that exact channel.
- An age-restricted guild channel also requires an age-verified account.
- A private channel requires the caller to be a current recipient, and no ownership is required.
- A [thread](/http-api/threads/), a [forum channel, or a media channel](/http-api/forums/) creates no invite. A caller who can view the channel receives 400 `INVALID_CHANNEL_TYPE`. A user request without the [`channel_threads` client capability](/http-api/threads/#client-capability) receives 404 `UNKNOWN_CHANNEL`. A caller who lacks `VIEW_CHANNEL` in the parent of a thread, or cannot view a private thread, receives 403 `MISSING_ACCESS`.
This operation does not require elevated multi-factor authentication.
:::note[Guild affiliation determines the invite type]
A channel that belongs to a guild creates a guild invite. Any other channel the caller can resolve creates a type `1` invite, including a direct message and the personal notes channel. Of these type `1` invites, only one whose channel is a group direct message admits an account through [Accept invite](#accept-invite).
:::
### Path parameters
| Field | Type | Description |
| --- | --- | --- |
| channel_id | snowflake | The ID of the guild channel or private channel |
### JSON body
Every field is optional and nullable, and an omitted or null value takes the stated default.
| Field | Type | Description |
| --- | --- | --- |
| max_uses?<sup>1</sup> | ?integer | The maximum number of admissions (0-100, default 0, where 0 is unlimited) |
| max_age?<sup>1</sup> | ?integer | The lifetime in seconds (0-604800, default 0, where 0 never expires) |
| unique?<sup>2</sup> | ?boolean | Whether to create a new invite even when an equivalent one already exists (default false) |
| temporary?<sup>3</sup> | ?boolean | Whether admission grants temporary membership (default false) |
<sup>1</sup> A negative value, a `max_uses` above 100, or a `max_age` above 604,800 seconds is rejected with 400 `INVALID_FORM_BODY` on that field
<sup>2</sup> When false or omitted the operation returns an existing invite whose creator, target channel, maximum uses, lifetime, and temporary flag all match the request exactly. A custom invite URL never matches
<sup>3</sup> Has no effect on a private channel invite
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [invite metadata](#invite-metadata-object) object | Invite was created, or an equivalent existing invite was returned |
| 400 | [error response](/http-api/#error-response) | The guild already holds its maximum number of invites and the request returns `MAX_INVITES` |
| 400 | [error response](/http-api/#error-response) | Channel is a thread, a forum channel, or a media channel the caller can view and the request returns `INVALID_CHANNEL_TYPE` |
| 403 | [error response](/http-api/#error-response) | Caller presents a bearer credential and the request returns `ACCESS_DENIED` |
| 403 | [error response](/http-api/#error-response) | The guild is unavailable to the caller and the request returns `MISSING_ACCESS` |
| 403 | [error response](/http-api/#error-response) | Caller lacks `VIEW_CHANNEL` in the parent of a thread, or cannot view a private thread, each returning `MISSING_ACCESS` |
| 403 | [error response](/http-api/#error-response) | Instant invites are temporarily disabled for the guild and the request returns `FEATURE_TEMPORARILY_DISABLED` |
| 403 | [error response](/http-api/#error-response) | The caller is not a guild member or lacks [VIEW_CHANNEL](/http-api/permissions/) or [CREATE_INSTANT_INVITE](/http-api/permissions/) and the request returns `MISSING_PERMISSIONS` |
| 403 | [error response](/http-api/#error-response) | The channel is age restricted and the account is not age verified and the request returns `NSFW_CONTENT_AGE_RESTRICTED` |
| 404 | [error response](/http-api/#error-response) | Channel does not exist, is pending deletion, or the caller is not a recipient of the private channel, each returning `UNKNOWN_CHANNEL`, or the channel's guild no longer exists and the request returns `UNKNOWN_GUILD` |
| 404 | [error response](/http-api/#error-response) | Channel is a thread, a forum channel, or a media channel and the caller is neither a bot nor a user session that declares the `channel_threads` client capability, returning `UNKNOWN_CHANNEL` |
### Side effects
Returning an existing equivalent invite changes nothing, records no audit entry, and emits no Dispatch.
Creating an invite allocates a random eight-character code drawn from the mixed-case alphanumeric alphabet. A guild invite records an [INVITE_CREATE audit action](/http-api/guild-audit-logs/#audit-actions) targeting the invite code, with the channel, creator, maximum uses, lifetime, and temporary flag as metadata and the supplied reason, then delivers [Guild Audit Log Entry Create](/gateway/events/#guild-audit-log-entry-create) to sessions holding `VIEW_AUDIT_LOG`. Fluxer logs a failure to write that entry and still completes the request. The `X-Audit-Log-Reason` header is read but never recorded for a private channel.
The guild delivers [Invite Create](/gateway/events/#invite-create) to sessions holding `MANAGE_CHANNELS` on the invite's channel, subject to [event filtering](/gateway/event-filtering/). A private channel invite records no audit entry and delivers the event to every current recipient's sessions.
The guild invite ceiling is its configured `max_guild_invites` limit, which defaults to 1,000. It includes invites across all channels and the custom invite URL.
### Rate limit
20 requests per minute for each authenticated user and channel ID, on the `invite:create::channel_id` bucket.
## List channel invites
<RouteHeader method="GET" path="/v1/channels/{channel_id}/invites" bot mfa />
Returns the standard invites of one channel as an array of [invite metadata objects](#invite-metadata-object), ordered by descending creation time.
### Limitations
- A guild channel requires guild membership, [VIEW_CHANNEL](/http-api/permissions/) in that channel, and [MANAGE_CHANNELS](/http-api/permissions/) in the guild.
- An age-restricted guild channel also requires an age-verified account.
- A group direct message requires the caller to be a current recipient and its owner.
`MANAGE_CHANNELS` is an [elevated permission](/http-api/permissions/#elevated-permissions), so a caller who is neither the guild owner nor enrolled in multi-factor authentication receives 400 [`TWO_FACTOR_REQUIRED`](/http-api/errors/) in a guild whose [MFA level](/http-api/guilds/#mfa-levels) is elevated.
The operation is not paginated. Every matching record is returned in one response, bounded by the guild invite ceiling described by [Create channel invite](#create-channel-invite). The response excludes the custom invite URL record.
### Path parameters
| Field | Type | Description |
| --- | --- | --- |
| channel_id | snowflake | The ID of the guild channel or group direct message |
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | array[[invite metadata](#invite-metadata-object) object] | Invites were returned, and the array is empty when the channel holds none |
| 400 | [error response](/http-api/#error-response) | The guild requires elevated multi-factor authentication that the caller lacks and the request returns `TWO_FACTOR_REQUIRED` |
| 403 | [error response](/http-api/#error-response) | Caller presents a bearer credential and the request returns `ACCESS_DENIED` |
| 403 | [error response](/http-api/#error-response) | The guild is unavailable to the caller and the request returns `MISSING_ACCESS` |
| 403 | [error response](/http-api/#error-response) | The caller is not a guild member, lacks [VIEW_CHANNEL](/http-api/permissions/) or [MANAGE_CHANNELS](/http-api/permissions/), or does not own the group direct message and the request returns `MISSING_PERMISSIONS` |
| 403 | [error response](/http-api/#error-response) | The channel is age restricted and the account is not age verified and the request returns `NSFW_CONTENT_AGE_RESTRICTED` |
| 404 | [error response](/http-api/#error-response) | Channel does not exist, is pending deletion, the caller is not a recipient of the private channel, or the private channel is not a group direct message, each returning `UNKNOWN_CHANNEL`, or the channel's guild no longer exists and the request returns `UNKNOWN_GUILD` |
### Rate limit
40 requests per 10 seconds for each authenticated user and channel ID, on the `invite:list::channel_id` bucket.
## List guild invites
<RouteHeader method="GET" path="/v1/guilds/{guild_id}/invites" bot mfa />
Returns the standard invites of one guild across all of its channels as an array of [invite metadata objects](#invite-metadata-object), ordered by descending creation time. Requires guild membership and [MANAGE_GUILD](/http-api/permissions/).
`MANAGE_GUILD` is an [elevated permission](/http-api/permissions/#elevated-permissions), so a caller who is neither the guild owner nor enrolled in multi-factor authentication receives 400 [`TWO_FACTOR_REQUIRED`](/http-api/errors/) in a guild whose [MFA level](/http-api/guilds/#mfa-levels) is elevated.
The operation is not paginated. Every matching record is returned in one response, bounded by the guild invite ceiling described by [Create channel invite](#create-channel-invite). The response excludes the custom invite URL record, so a client reads the current custom invite code through [Get guild custom invite URL](/http-api/guilds/#get-guild-custom-invite-url).
### Path parameters
| Field | Type | Description |
| --- | --- | --- |
| guild_id | snowflake | The ID of the guild |
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | array[[invite metadata](#invite-metadata-object) object] | Invites were returned, and the array is empty when the guild holds none |
| 400 | [error response](/http-api/#error-response) | The guild requires elevated multi-factor authentication that the caller lacks and the request returns `TWO_FACTOR_REQUIRED` |
| 403 | [error response](/http-api/#error-response) | Caller presents a bearer credential and the request returns `ACCESS_DENIED` |
| 403 | [error response](/http-api/#error-response) | The guild is unavailable to the caller and the request returns `MISSING_ACCESS` |
| 403 | [error response](/http-api/#error-response) | The caller is not a member of the guild or lacks [MANAGE_GUILD](/http-api/permissions/) and the request returns `MISSING_PERMISSIONS` |
| 404 | [error response](/http-api/#error-response) | Guild does not exist and the request returns `UNKNOWN_GUILD` |
### Rate limit
40 requests per 10 seconds for each authenticated user and guild ID, on the `invite:list::guild_id` bucket.
Reference in new issue View Git Blame Copy Permalink