Descubrimiento
Discovery is a feature that allows users to find and join new communities on Discord, open to all guilds that meet the requirements. Discovery happens within the client or the marketing page.
A guild is considered discoverable by the API if it has the guild feature. Additionally, any guilds within a directory channel the user has access to (guilds that have the guild feature), like in a student hub, are also considered discoverable relative to the user.
Discord utilizes Algolia to power search for discovery. You can search for guilds by name, description, keywords, and more. Reference the Algolia Search documentation for more information on how to search. A proxied version of the Algolia Search API is available, with limited parameter support.
These credentials are for production only.
Application ID: NKTZZ4AIZUAPI Key: <...>A partial guild object returned from discovery, Get Emoji Guild, Get Sticker Guild, and Get Soundboard Sound Guild.
id
snowflake
The ID of the guild
name
string
The name of the guild (2-100 characters)
description
?string
The description for the guild (max 300 characters)
vanity_url_code
?string
The guild's vanity invite code
preferred_locale
string
The preferred locale of the guild; used in discovery and notices from Discord (default "en-US")
premium_subscription_count
integer
The number of premium subscriptions (boosts) the guild currently has
approximate_member_count
integer
Approximate number of members in the guild
approximate_presence_count
integer
Approximate number of online members in the guild
emoji_count? 1
integer
Total number of custom guild emojis
sticker_count? 1
integer
Total number of custom guild stickers
auto_removed
boolean
Whether the guild has automatically been removed from discovery for not hitting required targets
keywords
?array[string]
The discovery search keywords for the guild (max 30 characters, max 10)
is_published
boolean
Whether the guild's landing web page is currently published
reasons_to_join? 2
array[discovery reason object]
The reasons to join the guild shown in the discovery web page (max 4)
social_links? 2
?array[string]
The guild's social media links shown in the discovery web page (max 256 characters, max 9)
about? 2
?string
The guild's long description shown in the discovery web page (max 2400 characters)
created_at? 2
ISO8601 timestamp
When the guild was created
1 The presence of these fields is dependent on the endpoint used to retrieve the guild. Get Emoji Guild will return emoji-related fields, and Get Sticker Guild will return sticker-related fields.
2 Only included when fetched from the Get Discovery Slug endpoint.
3 Only included when searching discovery.
A guild's progress on meeting the requirements of joining discovery.
Discovery Requirements Structure
guild_id?
snowflake
The ID of the guild
safe_environment?
boolean
Whether the guild has not been flagged by Trust & Safety
healthy?
boolean
Whether the guild meets activity requirements
health_score_pending?
boolean
Whether the guild's activity metrics have not yet been calculated
size?
boolean
Whether the guild meets the minimum member count requirement
nsfw_properties?
discovery NSFW properties object
Disallowed terms found in the guild's name, description, and channel names
sufficient 1
boolean
Whether the guild meets the requirements to be in Discovery
sufficient_without_grace_period 1
boolean
Whether the grace period can allow the guild to remain in Discovery
valid_rules_channel?
boolean
Whether the guild has a rules channel set
retention_healthy?
boolean
Whether the guild meets the new member retention requirement
engagement_healthy?
boolean
Whether the guild meets the weekly visitor and communicator requirements
age?
boolean
Whether the guild meets the minimum age requirement
minimum_age?
?integer
The minimum guild age requirement (in days)
minimum_size?
?integer
The minimum guild member count requirement
grace_period_end_date?
ISO8601 timestamp
When the guild's grace period ends
1 Certain guilds, such as those that are verified, are exempt from discovery requirements. These guilds will not have a fully populated discovery requirements object, and are guaranteed to receive only and .
Discovery NSFW Properties Structure
channels?
array[snowflake]
The IDs of the channels with names containing disallowed terms
channel_banned_keywords?
map[snowflake, array[string]]
The disallowed terms found in the given channel names
name?
string
The guild name, if it contains disallowed terms
name_banned_keywords?
array[string]
The disallowed terms found in the guild name
description?
string
The guild description, if it contains disallowed terms
description_banned_keywords?
array[string]
The disallowed terms found in the guild description
Discovery Health Score Structure
avg_nonnew_communicators
?string
Average weekly number of users who talk in the guild and have been on Discord for 8 weeks+
avg_nonnew_participators
?string
Average weekly number of users who view the guild and have been on Discord for 8 weeks+
num_intentful_joiners
?string
Average number of users who join the guild per week
perc_ret_w1_intentful
?float
Percentage of new members who remain in the guild for at least a week
Example Discovery Requirements
A guild's discovery settings.
guild_id
snowflake
The ID of the guild
keywords
?array[string]
The discovery search keywords for the guild (max 30 characters, max 10)
emoji_discoverability_enabled
boolean
Whether the guild is shown as a source through custom guild expressions
partner_actioned_timestamp
?ISO8601 timestamp
When the guild's partner application was actioned by an employee
partner_application_timestamp
?ISO8601 timestamp
When the guild applied for partnership
is_published
boolean
Whether the guild's landing web page is currently published
reasons_to_join
array[discovery reason object]
The reasons to join the guild shown in the discovery web page (max 4)
social_links
?array[string]
The guild's social media links shown in the discovery web page (max 256 characters, max 9)
about
?string
The guild's long description shown in the discovery web page (max 2400 characters)
reason
string
The reason to join the guild
emoji_name
?string
The unicode character of the emoji
id
integer
The ID of the category
name
string
The name of the category
is_primary
boolean
Whether the category can be used as a guild's primary category
id
snowflake
The ID of the guild
name
string
The name of the guild (2-100 characters)
member_count
integer
Approximate count of total members in the guild
online_count
integer
Approximate count of non-offline members in the guild
description
string
The description for the guild (max 300 characters)
brand_color_primary
string
The guild's accent color as a hexadecimal color string
game_application_ids
array[snowflake]
The IDs of the applications representing the games the guild plays (max 20)
tag
?string
The tag of the guild (2-4 characters)
badge_color_primary
string
The primary color of the badge as a hexadecimal color string
badge_color_secondary
string
The secondary color of the badge as a hexadecimal color string
premium_subscription_count
integer
The number of premium subscriptions (boosts) the guild currently has
1 This is not a complete list of all the features the guild has, and is limited to community features (, , , , , ).
activity_level
integer
The activity level of the guild in the game
activity_score
integer
The activity score of the guild in the game
emoji_id
?snowflake
ID of the emoji associated with the trait
emoji_name
?string
Name of the emoji associated with the trait
emoji_animated
boolean
Whether the associated emoji is animated
label
string
Name of the trait
position
integer
Position of the trait in the array for sorting
0
SWORD
1
WATER_DROP
2
SKULL
3
TOADSTOOL
4
MOON
5
LIGHTNING
6
LEAF
7
HEART
8
FIRE
9
COMPASS
10
CROSSHAIRS
11
FLOWER
12
FORCE
13
GEM
14
LAVA
15
PSYCHIC
16
SMOKE
17
SNOW
18
SOUND
19
SUN
20
WIND
1
PUBLIC
This guild is considered public and can be viewed by anyone
2
RESTRICTED
This guild is considered private but cannot be viewed and joining requires an invite
3
PUBLIC_WITH_RECRUITMENT
The guild is considered public, allowing anyone to view it and submit a join request
GET/discoverable-guilds
Returns a list of discoverable guild objects representing the guilds that are available for the current user to discover.
guild_ids? 1
array[snowflake]
The IDs of the discoverable guilds to return (max 48)
application_ids? 1
array[snowflake]
The IDs of the applications to return matching discoverable guilds for (max 48)
limit? 2
integer
The maximum number of guilds to return (max 48, default 48)
offset? 2
integer
Number of guilds to skip before returning guilds
1 Only one of , , or may be specified. If both are specified, only or is respected.
2 Pagination parameters are ignored if or are specified.
total
integer
The total number of guilds that match the query
limit
integer
The number of guilds returned in the response
offset
integer
The number of guilds skipped before returning guilds
GET/discoverable-guilds/search
Returns a list of discoverable guild objects that match the query.
query
string
The query to match (max 100 characters)
limit?
integer
The maximum number of guilds to return (max 48, default 24)
offset?
integer
Number of guilds to skip before returning guilds (max 2999)
GET/discovery/search
Returns a list of discoverable guild objects that have a landing web page and match the query. This endpoint is a proxy for searching using the Algolia API. See the Algolia Search documentation for more information.
query?
string
The query to match
limit?
integer
The maximum number of guilds to return (1-48, default 48)
offset?
integer
Number of guilds to skip before returning guilds (max 2999)
GET/discovery/{guild.id}
Returns information about a guild's landing web page or monetization store page. This endpoint requires the guild to either be discoverable and published or have the guild feature.
slug
string
The guild's discovery slug; can be appended to https://discord.com/servers/ to get the guild's discovery page
Monetization Store Page Structure
id
snowflake
The ID of the guild
name
string
The name of the guild (2-100 characters)
approximate_member_count
integer
Approximate number of members in the guild
approximate_presence_count
integer
Approximate number of online members in the guild
locked_server
boolean
Whether the entire guild is locked behind a role subscription
Store Page Role Subscription Structure
settings
role subscription settings object
The guild's role subscription settings
group_listings
array[role subscription group listing object]
The guild's role subscription group listings
trials
array[role subscription trial object]
The guild's role subscription trials
subscriber_count
?integer
The number of subscribers to the guild's role subscriptions, if public
GET/discovery/categories
Returns a list of discovery category objects representing the available discovery categories.
primary_only?
boolean
Whether to only return categories that can be set as a guild's primary category (default false)
GET/discovery/valid-term
Checks if a discovery search term is allowed.
term
string
The search term to validate
valid
boolean
Whether the provided term is valid
GET/guilds/{guild.id}/discovery-requirements
Returns the discovery requirements object for the guild. Requires the permission.
GET/guilds/{guild.id}/discovery-metadata
Returns the discovery metadata object for the guild. Requires the permission.
PATCH/guilds/{guild.id}/discovery-metadata
Replaces the discovery metadata for the guild. Requires the permission. Returns the updated discovery metadata object on success.
keywords?
?array[string]
The discovery search keywords for the guild (max 10)
emoji_discoverability_enabled?
?boolean
Whether the guild is shown as a source through custom emojis and stickers (default true)
is_published?
?boolean
Whether the guild's landing web page is currently published (default false)
reasons_to_join?
?array[discovery reason object]
The reasons to join the guild shown in the discovery web page (max 4)
social_links?
?array[string]
The guild's social media links shown in the discovery web page (max 256 characters, max 9)
about?
?string
The guild's long description shown in the discovery web page (max 2400 characters)
PUT/guilds/{guild.id}/discovery-categories/{category.id}
Adds a discovery subcategory to the guild. Requires the permission. Returns a 204 empty response on success.
DELETE/guilds/{guild.id}/discovery-categories/{category.id}
Removes a discovery subcategory from the guild. Requires the permission. Returns a 204 empty response on success.
GET/guilds/{guild.id}/profile
Returns a guild profile object for the given guild ID. User must be a member of the guild or the guild must be discoverable or have a or visibility.
PATCH/guilds/{guild.id}/profile
Modifies the guild profile for the given guild ID. Requires the permission. Returns the updated guild profile object on success.
name?
string
The name of the guild (2-100 characters)
icon?
The guild's icon; animated icons are only shown when the guild has the ANIMATED_ICON feature
description?
?string
The description for the guild (max 300 characters)
brand_color_primary?
string
The guild's accent color as a hexadecimal color string
game_application_ids?
array[snowflake]
The IDs of the applications representing the games the guild plays (max 20)
tag? 1
?string
The tag of the guild (2-4 characters)
badge_color_primary 1
?string
The primary color of the badge as a hexadecimal color string
badge_color_secondary 1
?string
The secondary color of the badge as a hexadecimal color string
1 Requires the guild feature.