Arquivos (Archives)

Um arquivo (archive) é um snapshot de uma conta de usuário ou de uma guilda, gerado em segundo plano e baixado como um arquivo de computador. Create user archive e Create guild archive solicitam um. As operações aqui leem o estado do arquivo e emitem URLs de download com limite de tempo.

Enquanto o Decoding Chat compila um arquivo, ele ignora qualquer arquivo armazenado que esteja faltando no armazenamento. Qualquer outra falha de leitura ou gravação faz com que essa tentativa de compilação falhe e defina failed_at.

Todas as operações necessitam de uma ACL que abranja o tipo de assunto que ela afeta.

Um arquivo de usuário necessita de archive:view_all ou archive:trigger:user.
Um arquivo de guilda necessita de archive:view_all ou archive:trigger:guild.
A leitura de ambos os tipos de uma vez necessita de archive:view_all, ou archive:trigger:user e archive:trigger:guild simultaneamente.

Objeto Archive

Um arquivo está em um desses estados de ciclo de vida. Ele está em compilação enquanto completed_at e failed_at são ambos nulos, concluído quando completed_at é definido e falho quando failed_at é definido. Quando o Decoding Chat inicia uma nova tentativa em um arquivo que falhou, ele limpa failed_at e error_message, então o arquivo é reportado como em compilação novamente enquanto a tentativa for executada.

Estrutura

Campo	Tipo	Descrição
archive_id	snowflake	O ID do arquivo, usado com seu assunto para endereçar o registro
subject_type	string	O tipo de assunto do arquivo em que o registro está armazenado
subject_id	snowflake	O usuário ou a guilda de que o arquivo foi tirado
requested_by	snowflake	A conta de administrador que solicitou o arquivo
requested_at	ISO8601 timestamp	O momento em que o registro do arquivo foi criado
started_at	?ISO8601 timestamp	O momento em que a compilação começou ou nulo enquanto a tarefa não começou
completed_at	?ISO8601 timestamp	O momento em que a compilação foi concluída ou nulo quando não foi concluída
failed_at	?ISO8601 timestamp	O momento em que a compilação falhou ou nulo quando não falhou
file_size¹	?string	O tamanho do objeto de arquivo armazenado em bytes ou nulo antes da conclusão
progress_percent²	number	O progresso da compilação de 0 a 100
progress_step²	?string	A etapa que a tarefa de compilação relatou por último
error_message	?string	O texto da falha que a tarefa de compilação relatou ou nulo quando não falhou
download_url_expires_at³	?ISO8601 timestamp	A expiração do cache carimbada no objeto de arquivo armazenado na conclusão ou nulo antes da conclusão
expires_at⁴	?ISO8601 timestamp	O momento em que o arquivo deixa de poder ser lido

¹ O tamanho é uma string decimal

² Um novo arquivo começa em 0 com a etapa Queued, e a conclusão define 100 e Completed. A falha deixa progress_percent onde estava e define a etapa para Failed

³ Gravado na conclusão usando o expires_at fixo do arquivo. Create archive download retorna uma URL com sua própria expiração

⁴ O valor é 365 dias após requested_at

Exemplo

{
  "archive_id": "1501314428688998182",
  "subject_type": "user",
  "subject_id": "1478812292088791040",
  "requested_by": "1478812292088791041",
  "requested_at": "2026-08-14T11:02:03.000Z",
  "completed_at": "2026-08-14T11:06:41.000Z",
  "file_size": "48211904",
  "progress_percent": 100,
  "progress_step": "Completed",
  "expires_at": "2027-08-14T11:02:03.000Z"
}

Tipos de assunto do arquivo

Valor	Descrição
user	O arquivo captura uma conta de usuário
guild	O arquivo captura uma guilda

List archives também aceita all como um valor de filtro, e é o padrão lá. Nenhum segmento de caminho aceita ele.

Objeto Archive download

Este objeto usa nomes de campos camelCase, diferentemente de todos os outros corpos de resposta Admin.

Estrutura

Campo	Tipo	Descrição
downloadUrl¹	string	O URL por tempo limitado no qual o arquivo é obtido
expiresAt²	ISO8601 timestamp	O momento em que o URL para de funcionar

¹ O URL é um link de armazenamento de objeto pré-assinado sem credencial de administrador, de modo que possuí-lo concede acesso até expirar

² O valor é de sete dias após a concessão ser emitida, independentemente do próprio expires_at do arquivo

Exemplo

{
  "downloadUrl": "https://storage.example.com/harvests/1501314428688998182.zip?signature=abc123",
  "expiresAt": "2026-09-07T11:06:41.000Z"
}

List archives

GET/v1/admin/archives

Audit reason

Retorna objetos archive correspondentes aos filtros fornecidos, do mais recente para o mais antigo. Requer uma ACL cobrindo o subject_type solicitado.

Parâmetros de consulta

Campo	Tipo	Descrição
subject_type?¹	string	`user`, `guild` ou `all` (padrão `all`)
subject_id?²	snowflake	O assunto exato cujos arquivos são retornados
requested_by?³	snowflake	A conta do administrador que solicitou os arquivos retornados
limit?⁴	integer	O número máximo de arquivos a retornar (1-200, padrão 50)
include_expired?⁵	boolean	Se deve incluir arquivos que passaram de seus `expires_at` (padrão false)

¹ all retorna os arquivos limit mais recentes em ambos os tipos de assunto, de modo que um tipo de assunto muito ativo pode ofuscar o outro

² subject_type também deve nomear user ou guild

³ Ignorado quando subject_id é fornecido. Quando requested_by se aplica, o Decoding Chat ignora subject_type e retorna os arquivos daquela conta de ambos os tipos de assunto

⁴ A listagem não é paginada e não retorna cursor. Apenas um filtro mais estreito alcança registros mais antigos

⁵ O valor conta como verdadeiro apenas para true, True ou 1. Excluir arquivos expirados pode deixar menos resultados do que o limit

Corpo da resposta

Campo	Tipo	Descrição
archives	array[objeto archive]	Os arquivos correspondentes aos filtros, primeiro o mais recente

Resposta

Status	Corpo	Condição
200	corpo da resposta	Os arquivos foram retornados
400	resposta de erro	`subject_id` é fornecido enquanto `subject_type` é `all`. `INVALID_FORM_BODY` possui `INVALID_FORMAT` em `subject_type`
403	resposta de erro	`MISSING_ACL` sem uma ACL cobrindo o tipo de assunto solicitado

Efeitos colaterais

A operação registra uma entrada de auditoria Admin com a ação list_archives, o tipo de alvo archive, o ID do alvo 0 e as chaves de metadados subject_type, limit, include_expired e result_count. subject_type é o valor após o Decoding Chat reduzir all para as ACLs da conta. A entrada também tem subject_user_id ou subject_guild_id quando subject_id for fornecido e requested_by_user_id quando requested_by for fornecido.

Limite de taxa

200 solicitações por minuto para cada usuário autenticado, no bucket admin:lookup.

Get archive

GET/v1/admin/archives/{subject_type}/{subject_id}/{archive_id}

Audit reason

Retorna um objeto archive. Requer uma ACL cobrindo o tipo de assunto.

Parâmetros de caminho

Campo	Tipo	Descrição
subject_type	string	O tipo de assunto de arquivo, `user` ou `guild`
subject_id	snowflake	O usuário ou a guilda de que o arquivo foi tirado
archive_id	snowflake	O ID do arquivo

Corpo da resposta

Campo	Tipo	Descrição
archive¹	?objeto archive	O arquivo ou nulo quando o assunto e o identificador não resolverem em nada

¹ Um arquivo faltante responde 200 com um arquivo nulo, que também é a resposta quando o identificador pertence a um assunto diferente e quando o arquivo passou do seu expires_at

Resposta

Status	Corpo	Condição
200	corpo da resposta	A busca foi realizada, quer tenha sido resolvida ou não
403	resposta de erro	`MISSING_ACL` sem uma ACL cobrindo o tipo de assunto

Efeitos colaterais

A leitura não emite permissão de download.

A operação registra uma entrada de auditoria Admin com a ação get_archive, o tipo de alvo igual a subject_type, o ID do alvo igual a subject_id e as chaves de metadados archive_id e found. found é false quando a resposta tiver um arquivo nulo.

Limite de taxa

200 solicitações por minuto para cada usuário autenticado, no bucket admin:lookup.

Create archive download

GET/v1/admin/archives/{subject_type}/{subject_id}/{archive_id}/download

Audit reason

Emite um URL de download temporário para um arquivo concluído. Retorna um objeto archive download em caso de sucesso. Requer uma ACL cobrindo o tipo de assunto.

Parâmetros de caminho

Campo	Tipo	Descrição
subject_type	string	O tipo de assunto de arquivo, `user` ou `guild`
subject_id	snowflake	O usuário ou a guilda de que o arquivo foi tirado
archive_id	snowflake	O ID de um arquivo concluído

Resposta

Status	Corpo	Condição
200	objeto archive download	A concessão foi emitida
400¹	resposta de erro	O arquivo não pode ser baixado, retornado como `HARVEST_NOT_READY`, `HARVEST_FAILED` ou `HARVEST_EXPIRED`
403	resposta de erro	`MISSING_ACL` sem uma ACL cobrindo o tipo de assunto
404²	resposta de erro	O assunto e o identificador não resolvem em nada, retornado como `UNKNOWN_HARVEST`

¹ HARVEST_FAILED enquanto failed_at está definido, HARVEST_NOT_READY enquanto o arquivo não tem tempo de conclusão ou nenhum objeto armazenado, e HARVEST_EXPIRED assim que expires_at passou, testados nessa ordem

² O registro do arquivo deixa de poder ser lido em expires_at, de modo que um arquivo após a sua expiração responde com UNKNOWN_HARVEST, não HARVEST_EXPIRED

Efeitos colaterais

A operação cria um URL de download pré-assinado válido por sete dias e não altera nenhum campo do arquivo, incluindo download_url_expires_at.

A operação registra uma entrada de auditoria Admin com a ação get_archive_download_url, tipo de alvo igual a subject_type, ID do alvo igual a subject_id e a chave de metadados archive_id. A entrada não possui URL. Uma solicitação que retorna 400 ou 404 não registra nenhuma entrada.

Limite de taxa

200 solicitações por minuto para cada usuário autenticado, no bucket admin:lookup.