Skip to content

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

TypeScript fluxerfluxerapp
7.5 KB
Raw Blame
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Archives
description: Reading user and guild archives and getting download links for them.
---

import RouteHeader from '@/components/RouteHeader.astro';

An archive is a snapshot of one user account or one guild, built in the background. [Create user archive](/admin-api/users/#create-user-archive) and [Create guild archive](/admin-api/guilds/#create-guild-archive) start one, and the routes below look it up and give you a download link.

The Admin API routes on this page need `archive:view_all`, or `archive:trigger:user` for user archives and `archive:trigger:guild` for guild archives. See [ACL evaluation](/admin-api/#acl-evaluation).

## Archive object

An archive is building while `completed_at` and `failed_at` are both null. It is complete once `completed_at` is set and failed once `failed_at` is set. A retry clears `failed_at` and `error_message`, so a failed archive can read as building again. An archive is deleted at `expires_at`, 365 days after it was requested.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| archive_id | snowflake | The ID of the archive |
| subject_type | string | The [archive subject type](#archive-subject-types) |
| subject_id | snowflake | The user or guild the archive was taken of |
| requested_by | snowflake | The admin account that requested the archive |
| requested_at | ISO8601 timestamp | The time the archive was requested |
| started_at | ?ISO8601 timestamp | The time construction began |
| completed_at | ?ISO8601 timestamp | The time construction completed |
| failed_at | ?ISO8601 timestamp | The time construction failed |
| file_size | ?string | The size of the archive in bytes, as a decimal string |
| progress_percent | number | The construction progress from 0 to 100 |
| progress_step | ?string | The step the build last reported |
| error_message | ?string | The failure text, if the build failed |
| download_url_expires_at | ?ISO8601 timestamp | Set when the build completes, to the same time as `expires_at` |
| expires_at | ?ISO8601 timestamp | The time the archive is deleted |

### Example

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

## Archive subject types

| Value | Description |
| --- | --- |
| user | The archive captures one user account |
| guild | The archive captures one guild |

## Archive download object

This object uses camelCase field names.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| downloadUrl | string | The time-limited URL the archive file is fetched from |
| expiresAt | ISO8601 timestamp | The time the URL stops working, seven days after it was issued |

### Example

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

## List archives

<RouteHeader method="GET" path="/v1/admin/archives" auditReason />

Returns [archive](#archive-object) objects, newest first, with no pagination. Use a narrower filter to find older archives. Without `requested_by`, the API narrows `all` to the subject types your ACLs cover. With it, you get that account's archives of both subject types, whatever `subject_type` says.

### Query parameters

| Field | Type | Description |
| --- | --- | --- |
| subject_type? | string | `user`, `guild` or `all` (default `all`) |
| subject_id? | snowflake | The subject whose archives are returned, with `subject_type` set to `user` or `guild` |
| requested_by? | snowflake | The admin account that requested the archives, ignored when `subject_id` is set |
| limit? | integer | The maximum number of archives to return (1-200, default 50) |
| include_expired? | boolean | Whether to include archives past their `expires_at` (default false) |

### Response body

| Field | Type | Description |
| --- | --- | --- |
| archives | array[[archive](#archive-object) object] | The archives matching the filters |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | response body | The archives were returned |
| 400 | [error response](/admin-api/#error-response) | `INVALID_FORM_BODY` when `subject_id` is set while `subject_type` is `all` |
| 403 | [error response](/admin-api/#error-response) | `MISSING_ACL` when you don't have an ACL for this subject type |

The rate limit is 200 requests per minute, on the `admin:lookup` bucket.

## Get archive

<RouteHeader method="GET" path="/v1/admin/archives/{subject_type}/{subject_id}/{archive_id}" auditReason />

Returns one [archive](#archive-object) object, or null `archive` when nothing matches or the archive has expired.

### Response body

| Field | Type | Description |
| --- | --- | --- |
| archive | ?[archive](#archive-object) object | The archive, or null when it was not found |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | response body | The lookup ran, whether or not it found the archive |
| 403 | [error response](/admin-api/#error-response) | `MISSING_ACL` when you don't have an ACL for this subject type |

The rate limit is 200 requests per minute, on the `admin:lookup` bucket.

## Get archive download link

<RouteHeader method="GET" path="/v1/admin/archives/{subject_type}/{subject_id}/{archive_id}/download" auditReason />

Returns an [archive download](#archive-download-object) object for a completed archive. The URL points to [Download signed file](#download-signed-file) unless the instance uses presigned storage links.

:::caution[The link needs no credentials]
Anyone with the URL can download the archive for seven days, and nothing revokes it.
:::

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | [archive download](#archive-download-object) object | The link was issued |
| 400 | [error response](/admin-api/#error-response) | `HARVEST_NOT_READY`, `HARVEST_FAILED` or `HARVEST_EXPIRED` when the archive is not downloadable |
| 403 | [error response](/admin-api/#error-response) | `MISSING_ACL` when you don't have an ACL for this subject type |
| 404 | [error response](/admin-api/#error-response) | `UNKNOWN_HARVEST` when nothing matches or the archive has expired |

The rate limit is 200 requests per minute, on the `admin:lookup` bucket.

## Download signed file

<RouteHeader method="GET" path="/v1/signed-downloads/{filename}" unauthenticated />

Streams an archive or a [report](/admin-api/reports/) file from a link the Admin API gave out. The `token` expires after seven days for an archive and five minutes for a report file. On an instance that uses presigned storage links, this route always returns 404.

### Query parameters

| Field | Type | Description |
| --- | --- | --- |
| token | string | Signed download token from the link (1-2,048 characters) |

### Request headers

| Field | Type | Description |
| --- | --- | --- |
| Range? | string | A byte range to fetch part of the file |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | file bytes | The complete file was streamed |
| 206 | file bytes | The requested byte range was streamed |
| 404 | `Not Found` | The token is missing, invalid or expired, or the file is gone |
| 416 | `Range Not Satisfiable` | The range lies outside the file |

The rate limit is 60 requests per minute, on the `user:harvest:download_file` bucket.