Invites

An invite is a code that admits an account into a guild or a group direct message.

Get invite is the only route here that needs no credential. Modify guild custom invite URL configures a guild’s custom invite URL, and 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. A guild invite has the guild it admits into and that guild’s online count. A group direct message invite exposes the group’s current recipients through its partial channel.

Structure

Field	Type	Description
code	string	The unique code that identifies the invite
type	integer	Invite type
guild?1	partial guild object	The guild the invite admits into
channel?2	partial invite channel object	The guild channel or group direct message the invite targets
inviter3	?partial user object	The account that created the invite, or null
member_count?4	integer	The member count of the guild, or the exact recipient count of the group direct message
presence_count?4	integer	The online member count of the guild
expires_at5	?ISO8601 timestamp	The time at which the invite stops resolving, or null when it never expires
temporary6	boolean	Whether admission through this invite grants temporary membership

¹ Present only when type is 0, and it applies the same feature-gated asset stripping as the full guild object

² 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

³ Null when the record stores no creator, which is always the case for a custom invite URL

⁴ A guild invite reports the counts the main Gateway currently holds, and both are 0 when it holds none

⁵ Computed from the creation time plus the stored lifetime, and null whenever that lifetime is 0

⁶ Enforced only for a guild invite. A group direct message invite stores and reports the flag without ever reading it

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

{
  "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 with its creation and usage state. Creation and listing operations return it when the caller has management access to the target, and Get invite never does.

Structure

Field	Type	Description
created_at	ISO8601 timestamp	The time at which the invite record was created
uses1	integer	The number of admissions completed through the invite
max_uses2	integer	The maximum admissions the invite permits, where 0 is unlimited
max_age?3	integer	The stored lifetime in seconds, where 0 never expires

¹ The counter advances only when the admission actually adds the account, so accepting an invite for a target the account already belongs to leaves it unchanged

² The value is 0 for every custom invite URL and for any invite created without an explicit maximum

³ Present only when type is 0, because a group direct message invite reports its expiry solely through expires_at

Example

{
  "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
name1	?string	The name of the channel, or null
type	integer	Channel type
recipients?2	array[partial invite recipient object]	The accounts currently in the group direct message

¹ A guild channel always stores a name, and a group direct message that stores no name reports null

² 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

{
  "username": "example"
}

Custom invite URLs

Modify guild custom invite URL creates and replaces a custom invite code and stores it as a guild invite record of type 0. It has no fixed target channel, creator, maximum uses, or lifetime, so a resolved custom invite URL reports a null inviter, a null expires_at, max_uses of 0, and max_age of 0. Its channel is the first guild text channel in channel order that the default role can view.

A custom invite code is stored lowercased, so Get invite and Accept invite resolve it in any case through their lowercase retry. Clearing or replacing the code deletes the invite record outright, and a released code stops resolving immediately.

Accept invite records the join as a custom invite URL admission and attributes no inviter and no source invite code. List channel invites and List guild invites exclude custom invite URLs, and Delete invite refuses them.

Get invite

GET/v1/invites/{invite_code}Unauthenticated

Reads one invite. Returns an 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.

Fluxer retries a lookup that misses once against the lowercase form of the supplied code. A code allocated by Create channel invite is drawn from a mixed-case alphanumeric alphabet and is matched exactly.

Every admission gate runs at accept time

Resolving an invite proves that the record exists and that its target is describable. Accept invite evaluates bans, disabled invites, exhausted uses, missing presence, and target capacity.

Expiry removes the record from storage

A record’s storage lifetime equals max_age. An exhausted record survives until an acceptance attempt or an explicit deletion removes it.

Path parameters

Field	Type	Description
invite_code1	string	The invite code to resolve (1 through 256 characters)

¹ 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 object	Invite resolved
404	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	The stored target channel no longer exists and the request returns UNKNOWN_CHANNEL
404	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, where the identity is the authenticated account when a credential resolves and otherwise the derived key for the client IP address.

Accept invite

POST/v1/invites/{invite_code}

Accepts an invite and admits the authenticated account into its target. Returns an invite object on success.

A guild admission emits Guild Create, Guild Member Add, User Settings Update, User Guild Settings Update, and Message Create Gateway events. A group direct message admission emits Channel Create, Channel Recipient Add, and Message Create Gateway events.

Limitations

• User-only, so a bot token is rejected with 403 ACCESS_DENIED.
• The caller needs no permission.

Exhausting an invite deletes it

An acceptance attempt against an invite whose maximum uses are already spent deletes the record before the request fails with 404 UNKNOWN_INVITE, so the failing caller removes it. A custom invite URL is never deleted this way.

Path parameters

Field	Type	Description
invite_code	string	The invite code to accept (1 through 256 characters)

Response

Status	Body	Condition
200	invite object	Account was admitted, or was already a member of the target
400	error response	A temporary guild invite is accepted without an active presence and the request returns TEMPORARY_INVITE_REQUIRES_PRESENCE
400	error response	An unclaimed account accepts a group direct message invite and the request returns UNCLAIMED_ACCOUNT_CANNOT_JOIN_GROUP_DMS
400	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	The caller already holds the maximum number of guilds and the request returns MAX_GUILDS
400	error response	The target is full and the request returns MAX_GUILD_MEMBERS or MAX_GROUP_DM_RECIPIENTS
403	error response	Caller is a bot or presents a bearer credential and the request returns ACCESS_DENIED
403	error response	The guild has the invites-disabled feature and the request returns INVITES_DISABLED
403	error response	Instant invites are temporarily disabled for the guild and the request returns FEATURE_TEMPORARILY_DISABLED
403	error response	The caller is banned by account or email address and the request returns USER_BANNED_FROM_GUILD
403	error response	The caller is banned by network address and the request returns USER_IP_BANNED_FROM_GUILD
403	error response	A deferred phone verification requirement becomes due and the request returns ACCOUNT_SUSPICIOUS_ACTIVITY
404	error response	The named guild no longer exists and the request returns UNKNOWN_GUILD
404	error response	The target channel no longer exists and the request returns UNKNOWN_CHANNEL
404	error response	The code resolves to no record, the record is exhausted, or the invite names no reachable target, each returning UNKNOWN_INVITE

Side effects

An account already in the target receives the invite unchanged without consuming a use or emitting a Dispatch. Otherwise uses advances exactly once after admission completes, and the record is deleted when that advance spends its last use. A failed admission consumes no use. Fluxer builds the response body after the admission has committed, through the same target resolution Get invite performs. A guild invite whose stored target channel has since been deleted therefore admits the account and advances uses before the request returns 404 UNKNOWN_CHANNEL.

A guild admission creates the membership, records whether the join used a custom invite URL or an instant invite, adds the guild to the caller’s settings and folder layout, and marks the membership temporary when the invite is temporary.

The joining account receives Guild Create. Guild Member Add is guild-wide and reaches every session connected to the guild, subject to the event filtering gates, which suppress it for a passive session in a large guild. The joining account receives User Settings Update when the join changes its stored settings, and User Guild Settings Update when its default_hide_muted_channels setting is enabled. Unless join notifications are suppressed or no system channel exists, the operation creates a join system message and delivers 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, the recipients the group already held receive Channel Recipient Add, and every recipient receives 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

DELETE/v1/invites/{invite_code}BotAudit reasonMFA

Deletes an invite permanently and returns 204 with an empty body. Emits an Invite Delete Gateway event.

Limitations

• A guild invite requires guild membership.
• The invite creator deletes it without holding MANAGE_GUILD, 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, so a caller who is neither the guild owner nor enrolled in multi-factor authentication receives 400 TWO_FACTOR_REQUIRED in a guild whose MFA level is elevated.

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.

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	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	Caller presents a bearer credential and the request returns ACCESS_DENIED, or the caller is not a member of the guild, is neither the creator nor a holder of MANAGE_GUILD, or does not own the group direct message, each returning MISSING_PERMISSIONS
404	error response	The named guild no longer exists and the request returns UNKNOWN_GUILD
404	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	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 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. 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 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

POST/v1/channels/{channel_id}/invitesBotAudit reason

Creates an invite for a channel, or returns an existing equivalent invite. Returns an invite metadata object on success. Emits an Invite Create Gateway event when a new record is created.

Limitations

• A guild channel requires guild membership, VIEW_CHANNEL, and CREATE_INSTANT_INVITE in that exact channel.
• An age-restricted guild channel additionally requires an age-verified account.
• A private channel requires the caller to be a current recipient, and no ownership is required.

CREATE_INSTANT_INVITE is read directly from the main Gateway, so this operation never requires elevated multi-factor authentication.

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. Only a group direct message admits an account afterwards.

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?1	?integer	The maximum number of admissions (0-100, default 0, where 0 is unlimited)
max_age?1	?integer	The lifetime in seconds (0-604800, default 0, where 0 never expires)
unique?2	?boolean	Whether to create a new invite even when an equivalent one already exists (default false)
temporary?3	?boolean	Whether admission grants temporary membership (default false)

¹ 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

² 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

³ Stored and never enforced on a private channel invite

Response

Status	Body	Condition
200	invite metadata object	Invite was created, or an equivalent existing invite was returned
400	error response	The guild already holds its maximum number of invites and the request returns MAX_INVITES
403	error response	Caller presents a bearer credential and the request returns ACCESS_DENIED
403	error response	The guild is unavailable to the caller and the request returns MISSING_ACCESS
403	error response	Instant invites are temporarily disabled for the guild and the request returns FEATURE_TEMPORARILY_DISABLED
403	error response	The caller is not a guild member or lacks VIEW_CHANNEL or CREATE_INSTANT_INVITE and the request returns MISSING_PERMISSIONS
403	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	Channel does not exist, is pending deletion, or the caller is not a recipient of the private channel, each returning UNKNOWN_CHANNEL, or the guild the channel belongs to no longer exists and the request returns UNKNOWN_GUILD

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 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 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 to the sessions holding MANAGE_CHANNELS on the invite’s channel, as event filtering states. The payload has no channel_id member, so that filter reads the channel from the nested channel.id. A passive session in a guild with more than 250 members is suppressed after that filter. A private channel invite records no audit entry and delivers Invite Create to every current recipient’s sessions.

The guild invite ceiling is the configured max_guild_invites value for the guild’s feature set, which defaults to 1,000. It counts every guild invite across all channels, including the custom invite URL record, and Fluxer compares it before writing a new record.

Rate limit

20 requests per minute for each authenticated user and channel ID, on the invite:create::channel_id bucket.

List channel invites

GET/v1/channels/{channel_id}/invitesBotMFA

Returns the standard invites of one channel as an array of invite metadata objects, ordered by descending creation time.

Limitations

• A guild channel requires guild membership, VIEW_CHANNEL in that channel, and MANAGE_CHANNELS in the guild.
• An age-restricted guild channel additionally 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, so a caller who is neither the guild owner nor enrolled in multi-factor authentication receives 400 TWO_FACTOR_REQUIRED in a guild whose MFA level 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. 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 object]	Invites were returned, and the array is empty when the channel holds none
400	error response	The guild requires elevated multi-factor authentication that the caller lacks and the request returns TWO_FACTOR_REQUIRED
403	error response	Caller presents a bearer credential and the request returns ACCESS_DENIED
403	error response	The guild is unavailable to the caller and the request returns MISSING_ACCESS
403	error response	The caller is not a guild member, lacks VIEW_CHANNEL or MANAGE_CHANNELS, or does not own the group direct message and the request returns MISSING_PERMISSIONS
403	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	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 guild the channel belongs to 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

GET/v1/guilds/{guild_id}/invitesBotMFA

Returns the standard invites of one guild across all of its channels as an array of invite metadata objects, ordered by descending creation time. Requires guild membership and MANAGE_GUILD.

MANAGE_GUILD is an elevated permission, so a caller who is neither the guild owner nor enrolled in multi-factor authentication receives 400 TWO_FACTOR_REQUIRED in a guild whose MFA level 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. The response excludes the custom invite URL record, so a client reads the current custom invite code through 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 object]	Invites were returned, and the array is empty when the guild holds none
400	error response	The guild requires elevated multi-factor authentication that the caller lacks and the request returns TWO_FACTOR_REQUIRED
403	error response	Caller presents a bearer credential and the request returns ACCESS_DENIED
403	error response	The guild is unavailable to the caller and the request returns MISSING_ACCESS
403	error response	The caller is not a member of the guild or lacks MANAGE_GUILD and the request returns MISSING_PERMISSIONS
404	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.