Descoberta de Admin

A descoberta de Admin é o lado de revisão do diretório público de guildas. Um Admin decide o aplicativo que um gerente de guilda envia, lê e edita a listagem aprovada, move-a entre categorias e remove a guilda do diretório. Uma guilda tem no máximo um aplicativo, e o recurso público Discovery conduz o mesmo ciclo de vida do lado da guilda.

Todas as operações, exceto Remover listagem de descoberta, exigem discovery:review, que cobre as leituras, Revisar aplicativo de descoberta, Mover listagens de descoberta para uma categoria e Atualizar listagem de descoberta. Remover listagem de descoberta exige discovery:remove em vez disso. Nenhum dos dois implica no outro.

Toda operação aqui registra uma entrada de auditoria de Admin com o motivo de auditoria de X-Audit-Log-Reason quando é bem-sucedida. Uma operação que armazena um motivo no aplicativo o recebe em seu corpo de solicitação, e esse motivo não é registrado na entrada.

Objeto de aplicativo pendente de Admin

O aplicativo enviado de uma guilda, juntamente com os detalhes da guilda que o Decoding Chat resolve no momento da solicitação.

Estrutura

Campo	Tipo	Descrição
guild_id	snowflake	Guilda que se inscreveu na descoberta
guild_name¹	string	Nome atual da guilda
guild_icon¹	?string	Hash atual do ícone da guilda, ou nulo quando a guilda não tem nenhum
guild_owner_id¹	snowflake	Proprietário atual da guilda
guild_owner_username²	?string	Nome de usuário do proprietário
guild_owner_global_name²	?string	Nome de exibição do proprietário, ou nulo quando não definido
guild_owner_discriminator² ³	?string	Discriminador do proprietário
guild_member_count¹ ⁴	integer	A contagem de membros no registro da guilda
guild_nsfw_level¹	?integer	O Nível NSFW atual da guilda
guild_features¹ ⁵	array[string]	Recursos de guilda atuais
description	string	Descrição da listagem de 10 a 300 caracteres
category_type⁶	integer	Categoria de descoberta em que a listagem está arquivada
primary_language⁷	?string	Código do idioma principal suportado
custom_tags⁶ ⁸	array[string]	Tags personalizadas normalizadas da listagem
applied_at	ISO8601 timestamp	Hora em que a guilda se inscreveu

¹ Resolvido a partir da guilda no momento da solicitação. Uma guilda que o Decoding Chat falha em carregar produz o nome literal (unknown guild), um ícone nulo, o ID do proprietário 0, uma contagem de membros de 0, um nível NSFW nulo, uma matriz de recursos vazia e nulo para todos os campos de nome do proprietário

² Lido da conta do proprietário, portanto, é nulo quando a guilda for resolvida, mas a conta do proprietário não

³ Renderizado como quatro dígitos com zeros à esquerda

⁴ A contagem armazenada no registro da guilda, por isso é aproximada

⁵ Um aplicativo aprovado tem o recurso discoverable aqui

⁶ Um nulo armazenado é lido como 0 para a categoria e como uma matriz vazia para as tags

⁷ Um nulo armazenado é lido como en-US, portanto, essa leitura não produz nulo

⁸ Armazenado já cortado, em minúsculas e com espaços em branco recolhidos, então uma tag não faz a viagem de volta na caixa com a qual foi enviada

Exemplo

{
  "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"
}

Objeto de listagem de descoberta de Admin

Uma listagem aprovada. Possui todos os campos do Objeto de aplicativo pendente de Admin com o mesmo significado, mais o campo abaixo.

Estrutura

Campo	Tipo	Descrição
approved_at¹	?ISO8601 timestamp	Hora em que o aplicativo foi aprovado

¹ O tempo de revisão do aplicativo, de modo que uma guilda aprovada automaticamente no envio tem seu tempo de envio aqui

Objeto de aplicativo de descoberta

Este é o objeto de aplicativo de descoberta do recurso de descoberta pública. Cada gravação nesta página responde com ele, portanto, um cliente que precisa do nome, ícone, proprietário, contagem de membros, nível NSFW ou recursos da guilda relê a listagem após uma gravação. Nenhuma resposta nesta página expõe o Admin que aprovou, rejeitou ou removeu o aplicativo.

Estrutura

Campo	Tipo	Descrição
guild_id	snowflake	Guilda à qual o aplicativo pertence
guild_nsfw_level?¹	?integer	Nível NSFW da guilda
status	string	Status do aplicativo de descoberta
description	string	A descrição exibida na listagem
category_type	integer	Categoria de descoberta em que a listagem está arquivada
primary_language	?string	Código do idioma principal suportado
custom_tags	array[string]	Tags personalizadas normalizadas da listagem
applied_at	ISO8601 timestamp	Hora em que a guilda se inscreveu
reviewed_at²	?ISO8601 timestamp	Hora em que o aplicativo foi aprovado ou rejeitado, ou nulo enquanto estiver pendente
review_reason³	?string	Motivo registrado com a aprovação ou rejeição, ou nulo
removed_at⁴	?ISO8601 timestamp	Hora em que uma listagem aprovada foi removida, ou nulo
removal_reason⁴	?string	Motivo registrado com a remoção, ou nulo

¹ Nenhuma rota nesta página o preenche. Leia o nível do Objeto de aplicativo pendente de Admin ou do objeto guilda em vez disso

² Um aplicativo aprovado automaticamente no envio tem seu tempo de envio aqui

³ Nulo para uma aprovação que não forneceu motivo e para uma aprovação automática. Uma rejeição sempre tem um

⁴ Ambos os campos são definidos apenas por Remover listagem de descoberta

Exemplo

{
  "guild_id": "1478812292088791040",
  "status": "approved",
  "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",
  "reviewed_at": "2026-08-20T09:11:02.000Z",
  "review_reason": null,
  "removed_at": null,
  "removal_reason": null
}

Categorias de descoberta

Cada versão é fornecida com um conjunto de categorias fixo, e nenhuma operação do Admin o altera. Consulte as categorias de descoberta para o conjunto.

Todo category_type e category_id aqui é um número inteiro de 0 a 8. Um valor fora desse intervalo falha no caminho, consulta ou validação do corpo.

Listar aplicativos de descoberta

GET/v1/admin/discovery/applications

Audit reason

Retorna todos os aplicativos pendentes como uma matriz de objetos de aplicativo pendente de Admin. Requer discovery:review.

A resposta é uma matriz simples sem ordem garantida, cursor ou limite. Ordene localmente se uma ordem estável for necessária.

Uma guilda aprovada automaticamente no momento do envio nunca aparece aqui. Um aplicativo cujo registro armazenado não pode mais ser lido é retirado da matriz. O pedido ainda é bem-sucedido.

Resposta

Status	Corpo	Condição
200	array[objeto aplicativo pendente de Admin]	Os aplicativos pendentes foram retornados

Efeitos colaterais

A operação registra uma entrada de auditoria de Admin com ação list_discovery_applications, tipo de alvo guild, ID de alvo 0 e chave de metadados result_count.

Limite de taxa

30 solicitações por 10 segundos para cada usuário autenticado, no bucket discovery:admin:list.

Revisar aplicativo de descoberta

PATCH/v1/admin/discovery/applications/{guild_id}

Audit reason

Aprova ou rejeita um aplicativo pendente e retorna o objeto de aplicativo de descoberta atualizado. Requer discovery:review.

Parâmetros de caminho

Campo	Tipo	Descrição
guild_id	snowflake	Guilda que se inscreveu na descoberta

Corpo JSON

status é a decisão, e a restrição em reason depende de qual for.

Campo	Tipo	Descrição
status¹	approved \| rejected	Decisão a aplicar
reason² ³	string	Motivo armazenado no aplicativo como `review_reason` (no máximo 500 caracteres)

¹ Um valor fora dos dois listados falha na validação do corpo. Nem removed nem pending são aceitos

² Opcional quando status é approved, e omiti-lo armazena nulo. Uma string vazia falha na validação do corpo com 400 INVALID_FORM_BODY

³ Obrigatório e com pelo menos um caractere quando status for rejected, então uma rejeição sem um motivo falha na validação do corpo

Resposta

Status	Corpo	Condição
200	objeto aplicativo de descoberta	A decisão foi aplicada
404	resposta de erro	A guilda não contém nenhum aplicativo, retornado como `DISCOVERY_APPLICATION_NOT_FOUND`
409	resposta de erro	O aplicativo não está pendente, retornado como `DISCOVERY_APPLICATION_ALREADY_REVIEWED`

Efeitos colaterais

Uma aprovação move o aplicativo para approved e registra o tempo de revisão, o Admin revisor e o motivo fornecido. Ele adiciona o recurso discoverable à guilda e indexa a listagem, para que a guilda apareça em Pesquisar guildas de descoberta. Guild Update é disparado para todas as sessões que podem observar a guilda. A indexação é ignorada em uma instância sem back-end de pesquisa configurado, e a aprovação ainda é bem-sucedida.

Uma rejeição move o aplicativo para rejected e registra o tempo de revisão, o Admin revisor e o motivo necessário. Ele deixa todos os campos de guilda como estão e não emite Dispatch de Gateway.

Uma aprovação cuja guilda não possa mais ser resolvida ainda é bem-sucedida. O Decoding Chat ignora a concessão de recursos e o Dispatch.

A operação registra uma entrada de auditoria de Admin com ação approve_discovery_application ou reject_discovery_application, tipo de alvo guild, ID da guilda como ID de alvo e chave de metadados status.

Limite de taxa

20 solicitações por 10 segundos para cada usuário autenticado, no bucket discovery:admin:action.

Listar categorias de descoberta

GET/v1/admin/discovery/categories

Audit reason

Retorna o conjunto fixo de categoria de descoberta como uma matriz de objetos de categoria de descoberta, em ordem crescente de ID. Requer discovery:review.

Ele relata o mesmo conjunto em todas as instâncias executando a mesma versão e não tem contagem de listagem. Os nomes são os nomes de exibição da versão e não são localizados.

Resposta

Status	Corpo	Condição
200	array[objeto categoria de descoberta]	Categorias foram retornadas

Efeitos colaterais

A operação registra uma entrada de auditoria de Admin com ação list_discovery_categories, tipo de alvo discovery_category, ID de alvo 0 e chave de metadados result_count.

Limite de taxa

30 solicitações por 10 segundos para cada usuário autenticado, no bucket discovery:admin:list.

Listar guildas em uma categoria de descoberta

GET/v1/admin/discovery/categories/{category_id}/listings

Audit reason

Retorna uma página de compensação das listagens aprovadas arquivadas em uma categoria, a maioria dos membros primeiro, como uma matriz de objetos de listagem de descoberta de Admin. Requer discovery:review.

Parâmetros de caminho

Campo	Tipo	Descrição
category_id	integer	Categoria de descoberta de 0 a 8

Parâmetros de consulta

Campo	Tipo	Descrição
limit?	integer	Listagens para retornar (1-100, padrão 50)
offset?¹	integer	Listagens para pular (0-10000, padrão 0)

¹ Aplicado após o filtro de categoria e a classificação de membros, então aumente-o para paginar uma categoria

Uma reconstrução do índice de pesquisa de descoberta não altera o que esta operação responde. Ele não relata nenhum total, portanto, uma página menor que limit é o único sinal de fim de categoria. Uma listagem cuja guilda não pôde ser resolvida classifica como se não tivesse membros e chega ao fim.

Resposta

Status	Corpo	Condição
200	array[objeto listagem de descoberta de Admin]	A página foi retornada

Efeitos colaterais

A operação registra uma entrada de auditoria de Admin com ação list_discovery_category_listings, tipo de alvo discovery_category, ID de alvo 0 e chaves de metadados category_id, limit, offset, result_count para as listagens nesta página, e total para cada listagem aprovada na categoria.

Limite de taxa

30 solicitações por 10 segundos para cada usuário autenticado, no bucket discovery:admin:list.

Listar listagens de descoberta

GET/v1/admin/discovery/listings

Audit reason

Retorna todas as listagens aprovadas como uma matriz de objetos de listagem de descoberta de Admin. Requer discovery:review.

A resposta é uma matriz simples sem ordem garantida, cursor ou limite. Aplicativos pendentes, rejeitados e removidos são excluídos.

Resposta

Status	Corpo	Condição
200	array[objeto listagem de descoberta de Admin]	Listagens aprovadas foram retornadas

Efeitos colaterais

A operação registra uma entrada de auditoria de Admin com ação list_discovery_listings, tipo de alvo guild, ID de alvo 0 e chave de metadados result_count.

Limite de taxa

30 solicitações por 10 segundos para cada usuário autenticado, no bucket discovery:admin:list.

Mover listagens de descoberta para uma categoria

PATCH/v1/admin/discovery/listings

Audit reason

Arquiva cada guilda nomeada em uma categoria de descoberta e relata quantas foram movidas. Requer discovery:review.

Corpo JSON

Campo	Tipo	Descrição
guild_ids¹	array[snowflake]	Guildas para mover, 1 a 100 entradas
category_type	integer	Categoria de descoberta de 0 a 8 para arquivar todas as guildas nomeadas

¹ Entradas duplicadas são recolhidas antes da movimentação, de modo que uma guilda nomeada duas vezes é tentada uma vez e contada uma vez

Corpo da resposta

Campo	Tipo	Descrição
updated	integer	Número de guildas distintas que foram movidas
failed_guild_ids¹	array[snowflake]	Guildas distintas que não foram movidas

¹ Uma guilda chega aqui quando não possui nenhum aplicativo, quando seu aplicativo é rejeitado ou removido ou quando a gravação falhou. A resposta não diz qual. Tente novamente a guilda através de Atualizar listagem de descoberta para ler o erro

Resposta

Status	Corpo	Condição
200	corpo da resposta	O lote foi executado, quer cada guilda tenha sido movida ou não

Repetir a solicitação é seguro. A operação move um aplicativo pendente da mesma forma que move um aprovado, de modo que essa operação pode rearquivar uma guilda que ainda aguarda revisão.

Efeitos colaterais

Um movimento substitui category_type do aplicativo e preserva sua descrição, idioma, tags, status e timestamps. Uma listagem movida que já foi aprovada aparece na nova categoria na próxima pesquisa pública. Nenhum campo de guilda é alterado e nenhum Dispatch de Gateway é emitido.

A operação registra uma entrada de auditoria de Admin com ação update_discovery_categories, tipo de alvo guild, ID de alvo 0 e chaves de metadados category_type, guild_count, updated e failed. Ele registra a entrada quando todas as guildas falham também. Os IDs de guilda não são registrados.

Limite de taxa

20 solicitações por 10 segundos para cada usuário autenticado, no bucket discovery:admin:action.

Atualizar listagem de descoberta

PATCH/v1/admin/discovery/listings/{guild_id}

Audit reason

Atualiza a listagem armazenada de uma guilda e retorna o objeto de aplicativo de descoberta atualizado. Requer discovery:review.

Parâmetros de caminho

Campo	Tipo	Descrição
guild_id¹	snowflake	Guilda cujo aplicativo é editado

¹ Apesar do caminho da rota, um aplicativo pendente é aceito, bem como uma listagem aprovada, o que permite que um Admin corrija o texto antes de aprová-lo

Corpo JSON

Todo membro é opcional. Um membro omitido preserva o valor armazenado, e um objeto vazio é aceito e não altera nada.

Campo	Tipo	Descrição
description?¹	string	Descrição da listagem de 10 a 300 caracteres
category_type?	integer	Categoria de descoberta de 0 a 8
primary_language?²	string	Código de idioma principal suportado
custom_tags?³ ⁴	array[string]	Até 10 tags personalizadas

¹ Um valor fornecido é verificado em relação às listas de bloqueio de conteúdo da instância antes que o aplicativo armazenado seja lido, portanto, uma correspondência retorna 403 CONTENT_BLOCKED mesmo quando a guilda não contém nenhum aplicativo. A verificação cobre frases banidas e URLs e domínios banidos encontrados no texto

² Um código fora do conjunto suportado falha na validação do corpo. Um idioma é sempre armazenado, para que a listagem não possa retornar a não ter nenhum

³ Uma matriz fornecida substitui as tags armazenadas completamente, então uma matriz vazia limpa todas as tags

⁴ Cada entrada tem 2 a 30 caracteres, tanto conforme enviado quanto após a normalização. Uma entrada que falha nesse limite ou na regra de caractere falha na validação de corpo contra seu próprio índice, e valores normalizados duplicados entram em colapso para a primeira ocorrência

Resposta

Status	Corpo	Condição
200	objeto aplicativo de descoberta	A listagem foi atualizada ou os valores enviados já correspondiam aos valores armazenados
403	resposta de erro	A descrição corresponde a uma lista de bloqueio de conteúdo, retornada como `CONTENT_BLOCKED`
404	resposta de erro	A guilda não contém nenhum aplicativo, retornado como `DISCOVERY_APPLICATION_NOT_FOUND`
409	resposta de erro	O aplicativo armazenado é rejeitado ou removido, retornado como `DISCOVERY_APPLICATION_ALREADY_REVIEWED`

Efeitos colaterais

Os membros fornecidos atualizam o aplicativo enquanto preservam seu status, tempo de envio, tempo de revisão, motivo da revisão e campos de remoção. Editar uma listagem aprovada não a retorna para revisão. A nova descrição, categoria, idioma e tags aparecem na próxima pesquisa pública. Editar um aplicativo pendente não altera nada que um leitor público possa ver.

Nenhum campo de guilda é alterado, portanto, nenhum Guild Update é acionado.

A operação registra uma entrada de auditoria de Admin com a ação update_discovery_listing, tipo de alvo guild, o ID da guilda como ID de alvo e chave de metadados status com o status do aplicativo armazenado. fields nomeia os membros fornecidos unidos por vírgulas e está ausente para um corpo vazio. Um category_type ou primary_language fornecido adiciona uma chave do mesmo nome com seu valor. A descrição e as tags não são registradas.

Limite de taxa

20 solicitações por 10 segundos para cada usuário autenticado, no bucket discovery:admin:action.

Remover listagem de descoberta

DELETE/v1/admin/discovery/listings/{guild_id}

Audit reason

Remove uma listagem aprovada da descoberta, retira o recurso discoverable da guilda e retorna o objeto de aplicativo de descoberta atualizado. Requer discovery:remove.

Parâmetros de caminho

Campo	Tipo	Descrição
guild_id	snowflake	A guilda cuja listagem foi removida

Corpo JSON

O corpo é necessário mesmo que seja um DELETE, então uma solicitação sem ele falha na validação do corpo.

Campo	Tipo	Descrição
reason	string	Motivo armazenado no aplicativo como `removal_reason`, 1 a 500 caracteres

Resposta

Status	Corpo	Condição
200	objeto aplicativo de descoberta	A listagem foi removida
400¹	resposta de erro	O aplicativo não está aprovado, retornado como `DISCOVERY_NOT_DISCOVERABLE`
404	resposta de erro	A guilda não contém nenhum aplicativo, retornado como `DISCOVERY_APPLICATION_NOT_FOUND`

¹ Um aplicativo pendente é recusado dessa forma, então rejeitá-lo através de Revisar aplicativo de descoberta é a única maneira de fechá-lo

Efeitos colaterais

O aplicativo é movido para removed e registra o tempo de remoção, o Admin que o removeu e o motivo necessário. O recurso discoverable é removido da guilda, a guilda para de aparecer em Pesquisar guildas de descoberta e Guild Update é disparado para todas as sessões que podem observar a guilda.

Uma remoção cuja guilda não pode mais ser resolvida ainda é bem-sucedida. O Decoding Chat ignora a remoção do recurso e o Dispatch.

A operação registra uma entrada de auditoria de Admin com ação remove_discovery_listing, tipo de alvo guild, ID da guilda como ID de alvo e sem metadados.

Limite de taxa

20 solicitações por 10 segundos para cada usuário autenticado, no bucket discovery:admin:action.