Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
9.5 KB
Raw Blame
---
# 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.