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.

Definitions

A guild is considered discoverable by the API if it has the DISCOVERABLE guild feature. Additionally, any guilds within a directory channel the user has access to (guilds that have the HAS_DIRECTORY_ENTRY guild feature), like in a student hub, are also considered discoverable relative to the user.

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

Discoverable Guild Object

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

Discoverable Guild Structure

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

² Only included when fetched from the Get Discovery Slug endpoint.

³ Only included 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

¹ 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

Discovery Health Score Structure

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

Discovery Reason Structure

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

Example Discovery Category

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

Guild Profile Object

Guild Profile Structure

¹ This is not a complete list of all the features the guild has, and is limited to community features (MEMBER_VERIFICATION_GATE_ENABLED, COMMUNITY, MEMBER_VERIFICATION_MANUAL_APPROVAL, DISCOVERABLE, PARTNERED, VERIFIED).

Game Activity Structure

Guild Trait Structure

Guild Badge Type

Guild Visibility

Example Guild Profile

{
  "id": "1241115476021481582",
  "name": "Fehlerjäger",
  "icon_hash": "b47f6747d7d6548b6f3eaf8c8e8af20c",
  "member_count": 131,
  "online_count": 53,
  "description": "Do you enjoy finding those creepy crawlies? 🐛 We seek those with a keen eye and ability for uncovering hidden gems 🔎",
  "brand_color_primary": "#7cf895",
  "banner_hash": "1468ceeb0f9c384826b982b7eddbfa6f",
  "game_application_ids": ["356869127241072640"],
  "game_activity": {
    "356869127241072640": {
      "activity_level": 1,
      "activity_score": 45
    }
  },
  "tag": "BUG",
  "badge": 6,
  "badge_color_primary": "#32a070",
  "badge_color_secondary": "#57b59e",
  "badge_hash": "6082c2553b03b47ccaea5203567df3cf",
  "traits": [
    {
      "emoji_id": null,
      "emoji_name": null,
      "emoji_animated": false,
      "label": "Bug Hunting",
      "position": 0
    }
  ],
  "features": ["MEMBER_VERIFICATION_MANUAL_APPROVAL", "COMMUNITY", "MEMBER_VERIFICATION_GATE_ENABLED"],
  "visibility": 1,
  "custom_banner_hash": null,
  "premium_subscription_count": 13,
  "premium_tier": 2
}

Endpoints

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

Query String Params

¹ 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

Returns a list of discoverable guild objects that match the query.

Query String Params

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 Params

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

Monetization Store Page Structure

Store Page Guild Structure

Store Page Role Subscription Structure

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

Query String Params

Checks if a discovery search term is allowed.

Query String Params

Response Body

Example Response

{ "valid": true }

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

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

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

JSON Params

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

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

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 PUBLIC or PUBLIC_WITH_RECRUITMENT visibility.

Modifies the guild profile for the given guild ID. Requires the MANAGE_GUILD permission. Returns the updated guild profile object on success.

JSON Params

¹ Requires the GUILD_TAGS guild feature.