A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Admin discovery
description: Review discovery applications, edit and move listings, and remove guilds from the directory.
---
import RouteHeader from '@/components/RouteHeader.astro';
Admins review the guild applications that guild managers submit through the public [Discovery](/http-api/discovery/) resource. Every endpoint here needs `discovery:review` except [Remove discovery listing](#remove-discovery-listing), which needs `discovery:remove`. Each one records an [Admin audit entry](/admin-api/#admin-audit-entry-object).
## Admin pending application object
A pending application and details about its guild.
### Structure
| Field | Type | Description |
| --- | --- | --- |
| guild_id | snowflake | The ID of the guild that applied |
| guild_name | string | The name of the guild |
| guild_icon | ?string | The icon hash of the guild |
| guild_owner_id | snowflake | The ID of the guild owner |
| guild_owner_username | ?string | The username of the owner |
| guild_owner_global_name | ?string | The display name of the owner |
| guild_owner_discriminator | ?string | The discriminator of the owner |
| guild_member_count | integer | The approximate member count |
| guild_nsfw_level | ?integer | The [NSFW level](/http-api/guilds/#nsfw-levels) of the guild |
| guild_features | array[string] | The [guild features](/http-api/guilds/#guild-features) |
| description | string | The listing description (10-300 characters) |
| category_type | integer | The [discovery category](/http-api/discovery/#discovery-categories) of the listing |
| primary_language | ?string | The [primary language](/http-api/discovery/#supported-primary-languages) code |
| custom_tags | array[string] | The [custom tags](/http-api/discovery/#custom-tags) of the listing |
| applied_at | ISO8601 timestamp | When the guild applied |
### Example
```json
{
"guild_id": "1478812292088791040",
"guild_name": "Example Guild",
"guild_icon": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
"guild_owner_id": "1478812292088791041",
"guild_owner_username": "example",
"guild_owner_global_name": "Example",
"guild_owner_discriminator": "0042",
"guild_member_count": 1204,
"guild_nsfw_level": 0,
"guild_features": ["COMMUNITY"],
"description": "A place to talk about building things.",
"category_type": 3,
"primary_language": "en-US",
"custom_tags": ["makers", "diy"],
"applied_at": "2026-08-19T14:03:55.000Z"
}
```
## Admin discovery listing object
An approved listing has every field of the [Admin pending application object](#admin-pending-application-object) plus `approved_at`.
### Structure
| Field | Type | Description |
| --- | --- | --- |
| approved_at | ?ISO8601 timestamp | When the application was approved |
## List discovery applications
<RouteHeader method="GET" path="/v1/admin/discovery/applications" auditReason />
Returns every pending application as an array of [Admin pending application](#admin-pending-application-object) objects.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | array[[Admin pending application](#admin-pending-application-object) object] | Pending applications were returned |
The rate limit is 30 requests per 10 seconds, on the `discovery:admin:list` bucket.
## Review discovery application
<RouteHeader method="PATCH" path="/v1/admin/discovery/applications/{guild_id}" auditReason />
Approves or rejects a pending application and returns the [discovery application](/http-api/discovery/#discovery-application-object). An approval adds the `DISCOVERABLE` and `VISITS_ENABLED` [guild features](/http-api/guilds/#guild-features) and sends [Guild Update](/gateway/events/#guild-update).
### JSON body
| Field | Type | Description |
| --- | --- | --- |
| status | approved \| rejected | The decision |
| reason? | string | The review reason, at most 500 characters. Required for `rejected`, where it must be at least 1 character |
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [discovery application](/http-api/discovery/#discovery-application-object) object | The decision was applied |
| 404 | [error response](/admin-api/#error-response) | `DISCOVERY_APPLICATION_NOT_FOUND` when the guild has no application |
| 409 | [error response](/admin-api/#error-response) | `DISCOVERY_APPLICATION_ALREADY_REVIEWED` when the application is not pending |
The rate limit is 20 requests per 10 seconds, on the `discovery:admin:action` bucket.
## List discovery categories
<RouteHeader method="GET" path="/v1/admin/discovery/categories" auditReason />
Returns the [discovery categories](/http-api/discovery/#discovery-categories) as an array of [discovery category](/http-api/discovery/#discovery-category-object) objects.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | array[[discovery category](/http-api/discovery/#discovery-category-object) object] | Categories were returned |
The rate limit is 30 requests per 10 seconds, on the `discovery:admin:list` bucket.
## List guilds in a discovery category
<RouteHeader method="GET" path="/v1/admin/discovery/categories/{category_id}/listings" auditReason />
Returns approved listings in a category as an array of [Admin discovery listing](#admin-discovery-listing-object) objects, most members first. `category_id` is an integer from 0 to 8.
### Query parameters
| Field | Type | Description |
| --- | --- | --- |
| limit? | integer | The number of listings to return (1-100, default 50) |
| offset? | integer | The number of listings to skip (0-10000, default 0) |
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | array[[Admin discovery listing](#admin-discovery-listing-object) object] | The page was returned |
The rate limit is 30 requests per 10 seconds, on the `discovery:admin:list` bucket.
## List discovery listings
<RouteHeader method="GET" path="/v1/admin/discovery/listings" auditReason />
Returns every approved listing as an array of [Admin discovery listing](#admin-discovery-listing-object) objects.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | array[[Admin discovery listing](#admin-discovery-listing-object) object] | Approved listings were returned |
The rate limit is 30 requests per 10 seconds, on the `discovery:admin:list` bucket.
## Move discovery listings to a category
<RouteHeader method="PATCH" path="/v1/admin/discovery/listings" auditReason />
Moves the guilds in `guild_ids` to one [discovery category](/http-api/discovery/#discovery-categories). The request returns 200 even when some guilds don't move, and `failed_guild_ids` lists them.
### JSON body
| Field | Type | Description |
| --- | --- | --- |
| guild_ids | array[snowflake] | The guilds to move (1-100) |
| category_type | integer | The category to move them to (0-8) |
### Response body
| Field | Type | Description |
| --- | --- | --- |
| updated | integer | The number of guilds that moved |
| failed_guild_ids | array[snowflake] | The guilds that did not move |
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | response body | The batch ran |
The rate limit is 20 requests per 10 seconds, on the `discovery:admin:action` bucket.
## Update discovery listing
<RouteHeader method="PATCH" path="/v1/admin/discovery/listings/{guild_id}" auditReason />
Updates the listing of an approved or pending application and returns the [discovery application](/http-api/discovery/#discovery-application-object). An approved listing stays approved.
### JSON body
| Field | Type | Description |
| --- | --- | --- |
| description? | string | The listing description (10-300 characters) |
| category_type? | integer | The category (0-8) |
| primary_language? | string | A [primary language](/http-api/discovery/#supported-primary-languages) code |
| custom_tags? | array[string] | Up to 10 [custom tags](/http-api/discovery/#custom-tags) that replace the current ones |
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [discovery application](/http-api/discovery/#discovery-application-object) object | The listing was updated |
| 403 | [error response](/admin-api/#error-response) | `CONTENT_BLOCKED` when the description matches a content blocklist |
| 404 | [error response](/admin-api/#error-response) | `DISCOVERY_APPLICATION_NOT_FOUND` when the guild has no application |
| 409 | [error response](/admin-api/#error-response) | `DISCOVERY_APPLICATION_ALREADY_REVIEWED` when the application is rejected or removed |
The rate limit is 20 requests per 10 seconds, on the `discovery:admin:action` bucket.
## Remove discovery listing
<RouteHeader method="DELETE" path="/v1/admin/discovery/listings/{guild_id}" auditReason />
Removes an approved listing and returns the [discovery application](/http-api/discovery/#discovery-application-object). Fluxer removes the `DISCOVERABLE` feature from the guild, keeps `VISITS_ENABLED` and sends [Guild Update](/gateway/events/#guild-update). The guild has to apply again to be listed.
### JSON body
| Field | Type | Description |
| --- | --- | --- |
| reason | string | The removal reason (1-500 characters) |
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [discovery application](/http-api/discovery/#discovery-application-object) object | The listing was removed |
| 400 | [error response](/admin-api/#error-response) | `DISCOVERY_NOT_DISCOVERABLE` when the application is not approved |
| 404 | [error response](/admin-api/#error-response) | `DISCOVERY_APPLICATION_NOT_FOUND` when the guild has no application |
The rate limit is 20 requests per 10 seconds, on the `discovery:admin:action` bucket.