Discovery

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.

Searching Discovery

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.

Algolia Credentials

These credentials are for production only.

Application ID: NKTZZ4AIZU
API Key: aca0d7082e4e63af5ba5917d5e96bed0

Discoverable Guild Object

A partial guild object returned from discovery, Get Emoji Guild, and Get Sticker Guild endpoints.

Discoverable Guild Structure

Field	Type	Description
id	snowflake	The ID of the guild
name	string	The name of the guild (2-100 characters)
icon	?string	The guild's icon hash
description	?string	The description for the guild
banner	?string	The guild's banner hash
splash	?string	The guild's splash hash
discovery_splash	?string	The guild's discovery splash hash
features	array[string]	Enabled guild features
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
emojis? ¹	array[emoji object]	Custom guild emojis; limited to 30 entries
emoji_count? ¹	integer	Total number of custom guild emojis
stickers? ¹	array[sticker object]	Custom guild stickers; limited to 30 entries
sticker_count? ¹	integer	Total number of custom guild stickers
auto_removed	boolean	Whether the guild has automatically been removed from discovery for not hitting required targets
primary_category_id	integer	The ID of the primary discovery category set for the guild
primary_category? ³	discovery category	The primary discovery category set for the guild
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? ²	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)
category_ids? ²	array[snowflake]	The IDs of discovery subcategories set for the guild (max 5)
categories? ³	array[discovery category]	The discovery categories set for the guild (max 5)
created_at? ²	ISO8601 timestamp	When the guild was created

¹ 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.

² These fields are only returned when using the Get Discovery Slug endpoint.

³ These fields are only returned when searching discovery.

Example Discoverable Guild

{
  "id": "752630786561409076",
  "name": "Elite Creative",
  "description": "The largest Fortnite Creative server across the globe. Join a Creative community offering events, 1v1s. and more!",
  "icon": "278da1c7740e394657c1179f4782aef1",
  "splash": "2b4ae5cdd71038b4880b1b57a6e5dacb",
  "banner": "57e939e67aebaf232d28205603020b55",
  "approximate_presence_count": 21125,
  "approximate_member_count": 155455,
  "premium_subscription_count": 17,
  "preferred_locale": "en-US",
  "auto_removed": false,
  "discovery_splash": "9d7ec672b89b320ef7a51e5b6ae453b8",
  "primary_category_id": 1,
  "vanity_url_code": "creative",
  "is_published": true,
  "keywords": [
    "Fortnite",
    "Creative",
    "Fortnite Creative",
    "Boxfights",
    "Zonewars",
    "Buildfights",
    "1v1",
    "EU",
    "NA",
    "Creator"
  ],
  "features": [
    "ANIMATED_BANNER",
    "ANIMATED_ICON",
    "AUTO_MODERATION",
    "BANNER",
    "COMMUNITY",
    "DISCOVERABLE",
    "ENABLED_DISCOVERABLE_BEFORE",
    "GUILD_ONBOARDING_EVER_ENABLED",
    "GUILD_WEB_PAGE_VANITY_URL",
    "INVITE_SPLASH",
    "NEWS",
    "PREVIEW_ENABLED",
    "RAID_ALERTS_ENABLED",
    "ROLE_ICONS",
    "VANITY_URL",
    "WELCOME_SCREEN_ENABLED"
  ],
  "emojis": [],
  "emoji_count": 339
}

Discovery Requirements Object

A guild's progress on meeting the requirements of joining discovery.

Discovery Requirements Structure

Field	Type	Description
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
protected?	boolean	Whether the guild has the MFA requirement for moderation actions enabled
sufficient ¹	boolean	Whether the guild meets the requirements to be in Discovery
sufficient_without_grace_period ¹	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)
health_score?	discovery health score object	The guild's activity metrics
minimum_size?	?integer	The minimum guild member count requirement
grace_period_end_date?	ISO8601 timestamp	When the guild's grace period ends

¹ 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 sufficient and sufficient_without_grace_period.

Discovery NSFW Properties Structure

Field	Type	Description
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

Field	Type	Description
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

{
  "guild_id": "1046920999469330512",
  "safe_environment": true,
  "healthy": true,
  "health_score_pending": false,
  "size": true,
  "nsfw_properties": {
    "channels": ["1060703057651978261"],
    "channels_banned_keywords": {
      "1060703057651978261": ["risque"]
    },
    "name": "Alien Network",
    "name_banned_keywords": ["alien"],
    "description": "Where the 👽s 👽 and sometimes very 👽 things happen 😨.",
    "description_banned_keywords": ["👽"]
  },
  "protected": true,
  "sufficient": false,
  "sufficient_without_grace_period": true,
  "valid_rules_channel": true,
  "retention_healthy": true,
  "engagement_healthy": true,
  "age": true,
  "minimum_age": 56,
  "health_score": {
    "avg_nonnew_participators": "1738",
    "avg_nonnew_communicators": "348",
    "num_intentful_joiners": "834",
    "perc_ret_w1_intentful": 0.37651924871356596
  },
  "minimum_size": 1000,
  "grace_period_end_date": "2037-07-01T17:47:49.974000+00:00"
}

Discovery Metadata Object

A guild's discovery settings.

Discovery Metadata Structure

Field	Type	Description
guild_id	snowflake	The ID of the guild
primary_category_id	integer	The ID of the primary discovery category set for 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 emojis and stickers
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)
category_ids	array[snowflake]	The IDs of discovery subcategories set for the guild (max 5)

Discovery Reason Structure

Field	Type	Description
reason	string	The reason to join the guild
emoji_id	?snowflake	The ID of a guild's custom emoji
emoji_name	?string	The unicode character of the emoji

Example Discovery Metadata

{
  "guild_id": "1046920999469330512",
  "primary_category_id": 49,
  "keywords": ["test"],
  "emoji_discoverability_enabled": true,
  "partner_actioned_timestamp": null,
  "partner_application_timestamp": null,
  "is_published": false,
  "reasons_to_join": [
    { "reason": "Alien", "emoji_id": null, "emoji_name": "👽" },
    { "reason": "Alien", "emoji_id": null, "emoji_name": "👽" },
    { "reason": "Alien", "emoji_id": null, "emoji_name": "👽" },
    { "reason": "Alien", "emoji_id": null, "emoji_name": "👽" }
  ],
  "social_links": ["https://twitter.com/alien"],
  "about": "Alien\nAlien\nAlien\nAlien\nAlien\nAlien",
  "category_ids": [48]
}

Discovery Category Object

Discovery Category Structure

Field	Type	Description
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

Example Discovery Category

{
  "id": 1,
  "name": "Gaming",
  "is_primary": true
}

Endpoints

Get Discoverable Guilds

GET/discoverable-guilds

Returns a list of discoverable guild objects representing the guilds that are available for the current user to discover.

Query String Params

Field	Type	Description
guild_ids? ¹	array[snowflake]	The IDs of the discoverable guilds to return (max 48)
application_ids? ¹	array[snowflake]	The IDs of the applications to return matching discoverable guilds for (max 48)
categories? ¹	array[integer]	The IDs of the discovery categories to filter results by
limit? ²	integer	The maximum number of guilds to return (max 48, default 48)
offset? ²	integer	Number of guilds to skip before returning guilds (default 0)

¹ Only one of guild_ids, application_ids, or categories may be specified. If both are specified, only guild_ids or application_ids is respected.

² Pagination parameters are ignored if guild_ids or application_ids are specified.

Response Body

Field	Type	Description
guilds	array[discoverable guild object]	The guilds that match the query
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

Search Discoverable Guilds

GET/discovery/search

Unauthenticated

Returns a list of discoverable guild objects representing the guilds that match the query. This endpoint is a proxy for searching using the Algolia API. See the Algolia Search documentation for more information.

Query String Params

Field	Type	Description
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 (default 0)

Get Discovery Slug

GET/discovery/{guild.id}

Unauthenticated

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 CREATOR_STORE_PAGE guild feature.

Response Body

Field	Type	Description
slug	string	The guild's discovery slug; can be appended to `https://discord.com/servers/` to get the guild's discovery page
guild?	discoverable guild object	The guild information, if the guild is discoverable
store_page?	monetization store page object	The guild's monetization store page, if enabled

Monetization Store Page Structure

Field	Type	Description
guild	store page guild object	The guild information
role_subscription	store page role subscription object	The guild's role subscription information

Store Page Guild Structure

Field	Type	Description
id	snowflake	The ID of the guild
name	string	The name of the guild (2-100 characters)
icon_hash	?string	The guild's icon hash
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
invite	?partial invite object	A special `CREATOR_PAGE` invite for the guild

Store Page Role Subscription Structure

Field	Type	Description
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
benefit_channels	array[partial channel object]	The channels that are unlocked by role subscriptions
benefit_emojis	array[emoji object]	The emojis that are unlocked by role subscriptions
purchase_page_invite	?partial invite object	A special `ROLE_SUBSCRIPTIONS` invite for the guild

Get Discovery Categories

GET/discovery/categories

Returns a list of discovery category objects representing the available discovery categories.

Query String Params

Field	Type	Description
locale?	string	The language to return category names in (default "en-US")
primary_only?	boolean	Whether to only return categories that can be set as a guild's primary category (default false)

Validate Discovery Search Term

GET/discovery/valid-term

Checks if a discovery search term is allowed.

Query String Params

Field	Type	Description
term	string	The search term to validate

Response Body

Field	Type	Description
valid	boolean	Whether the provided term is valid

Example Response

{ "valid": true }

Get Guild Discovery Requirements

GET/guilds/{guild.id}/discovery-requirements

Returns the discovery requirements object for the guild. Requires the MANAGE_GUILD permission.

Get Guild Discovery Metadata

GET/guilds/{guild.id}/discovery-metadata

Returns the discovery metadata object for the guild. Requires the MANAGE_GUILD permission.

Modify Guild Discovery Metadata

PATCH/guilds/{guild.id}/discovery-metadata

Replaces the discovery metadata for the guild. Requires the MANAGE_GUILD permission. Returns the updated discovery metadata object on success.

JSON Params

Field	Type	Description
primary_category_id?	?integer	The ID of the primary discovery category set for the guild (default 0)
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)

Add Guild Discovery Subcategory

PUT/guilds/{guild.id}/discovery-categories/{category.id}

Adds a discovery subcategory to the guild. Requires the MANAGE_GUILD permission. Returns a 204 empty response on success.

Remove Guild Discovery Subcategory

DELETE/guilds/{guild.id}/discovery-categories/{category.id}

Removes a discovery subcategory from the guild. Requires the MANAGE_GUILD permission. Returns a 204 empty response on success.