> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/karanhudia/borg-ui/llms.txt
> Use this file to discover all available pages before exploring further.

# Archives

> List, inspect, and manage backup archives

## Overview

Archive endpoints allow you to list archives in a repository, view detailed information, browse contents, delete archives, and extract files.

## List Archives

List all archives in a repository.

**Endpoint:** `GET /api/archives/list`

<ParamField query="repository" type="string" required>
  Repository path
</ParamField>

**Example Request:**

```bash theme={null}
curl "http://localhost:5000/api/archives/list?repository=/local/backups/my-repo" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Response:**

```json theme={null}
{
  "archives": {
    "archives": [
      {
        "name": "backup-2024-01-15T10:30:00",
        "id": "abc123def456",
        "start": "2024-01-15T10:30:00",
        "time": "2024-01-15T10:30:00"
      },
      {
        "name": "backup-2024-01-14T02:00:00",
        "id": "def456ghi789",
        "start": "2024-01-14T02:00:00",
        "time": "2024-01-14T02:00:00"
      }
    ]
  }
}
```

## Get Archive Info

Get detailed information about a specific archive.

**Endpoint:** `GET /api/archives/{archive_id}/info`

<ParamField query="repository" type="string" required>
  Repository path
</ParamField>

<ParamField query="include_files" type="boolean" default={false}>
  Include file listing in response
</ParamField>

<ParamField query="file_limit" type="integer" default={1000}>
  Maximum number of files to return if include\_files is true
</ParamField>

**Example Request:**

```bash theme={null}
curl "http://localhost:5000/api/archives/backup-2024-01-15T10:30:00/info?repository=/local/backups/my-repo&include_files=true&file_limit=100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Response:**

```json theme={null}
{
  "info": {
    "name": "backup-2024-01-15T10:30:00",
    "id": "abc123def456",
    "start": "2024-01-15T10:30:00",
    "end": "2024-01-15T10:45:30",
    "duration": 930.5,
    "stats": {
      "original_size": 10737418240,
      "compressed_size": 8589934592,
      "deduplicated_size": 2147483648,
      "nfiles": 15420
    },
    "command_line": [
      "borg",
      "create",
      "--stats",
      "--json",
      "--compression",
      "lz4"
    ],
    "hostname": "server01",
    "username": "root",
    "chunker_params": "19,23,21,4095",
    "limits": {
      "max_archive_size": 0
    },
    "comment": "",
    "repository": {
      "id": "repo123",
      "location": "/local/backups/my-repo"
    },
    "encryption": {
      "mode": "repokey-blake2"
    },
    "cache": {
      "path": "/root/.cache/borg/abc123",
      "stats": {
        "total_chunks": 52341,
        "total_csize": 8589934592,
        "unique_chunks": 12456,
        "unique_csize": 2147483648
      }
    },
    "files": [
      {
        "path": "/data/file1.txt",
        "type": "file",
        "mode": "rw-r--r--",
        "user": "root",
        "group": "root",
        "size": 4096,
        "mtime": "2024-01-15T09:00:00",
        "healthy": true
      }
    ],
    "file_count": 100
  }
}
```

<ResponseField name="info.stats.original_size" type="integer">
  Original size in bytes before compression
</ResponseField>

<ResponseField name="info.stats.compressed_size" type="integer">
  Size after compression in bytes
</ResponseField>

<ResponseField name="info.stats.deduplicated_size" type="integer">
  Actual storage used after deduplication in bytes
</ResponseField>

<ResponseField name="info.stats.nfiles" type="integer">
  Number of files in the archive
</ResponseField>

<ResponseField name="info.command_line" type="array">
  Command used to create the archive
</ResponseField>

<ResponseField name="info.hostname" type="string">
  Hostname where backup was created
</ResponseField>

<ResponseField name="info.files" type="array">
  Array of file objects (only if include\_files=true)
</ResponseField>

## Get Archive Contents

List files and directories in an archive.

**Endpoint:** `GET /api/archives/{archive_id}/contents`

<ParamField query="repository" type="string" required>
  Repository path
</ParamField>

<ParamField query="path" type="string" default="">
  Subdirectory path to list (empty for root)
</ParamField>

**Example Request:**

```bash theme={null}
curl "http://localhost:5000/api/archives/backup-2024-01-15T10:30:00/contents?repository=/local/backups/my-repo&path=/data" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Response:**

```json theme={null}
{
  "contents": [
    {
      "path": "/data/file1.txt",
      "type": "file",
      "mode": "rw-r--r--",
      "user": "root",
      "group": "root",
      "size": 4096,
      "mtime": "2024-01-15T09:00:00"
    },
    {
      "path": "/data/subdir",
      "type": "directory",
      "mode": "rwxr-xr-x",
      "user": "root",
      "group": "root",
      "size": 0,
      "mtime": "2024-01-15T09:00:00"
    }
  ]
}
```

## Delete Archive

Delete an archive from the repository (runs in background).

**Endpoint:** `DELETE /api/archives/{archive_id}`

**Admin Only:** Yes

<ParamField query="repository" type="string" required>
  Repository path
</ParamField>

**Example Request:**

```bash theme={null}
curl -X DELETE "http://localhost:5000/api/archives/backup-2024-01-15T10:30:00?repository=/local/backups/my-repo" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Response:**

```json theme={null}
{
  "job_id": 456,
  "status": "pending",
  "message": "Archive deletion started in background"
}
```

<ResponseField name="job_id" type="integer">
  ID of the delete job for status monitoring
</ResponseField>

## Get Delete Job Status

Monitor the status of an archive deletion.

**Endpoint:** `GET /api/archives/delete-jobs/{job_id}`

**Example Request:**

```bash theme={null}
curl http://localhost:5000/api/archives/delete-jobs/456 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Response:**

```json theme={null}
{
  "id": 456,
  "repository_id": 1,
  "archive_name": "backup-2024-01-15T10:30:00",
  "status": "completed",
  "started_at": "2024-01-15T11:00:00Z",
  "completed_at": "2024-01-15T11:05:30Z",
  "progress": 100,
  "progress_message": "Archive deleted successfully",
  "error_message": null,
  "logs": null,
  "has_logs": false
}
```

## Cancel Delete Job

Cancel a running archive deletion.

**Endpoint:** `POST /api/archives/delete-jobs/{job_id}/cancel`

**Admin Only:** Yes

**Example Request:**

```bash theme={null}
curl -X POST http://localhost:5000/api/archives/delete-jobs/456/cancel \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Response:**

```json theme={null}
{
  "message": "Delete job cancelled successfully"
}
```

## Download File from Archive

Extract and download a specific file from an archive.

**Endpoint:** `GET /api/archives/download`

<ParamField query="repository" type="string" required>
  Repository path
</ParamField>

<ParamField query="archive" type="string" required>
  Archive name
</ParamField>

<ParamField query="file_path" type="string" required>
  Path to file within archive
</ParamField>

<ParamField query="token" type="string" required>
  Access token (passed as query parameter for download links)
</ParamField>

**Example Request:**

```bash theme={null}
curl "http://localhost:5000/api/archives/download?repository=/local/backups/my-repo&archive=backup-2024-01-15T10:30:00&file_path=/data/file1.txt&token=YOUR_ACCESS_TOKEN" \
  -o file1.txt
```

**Response:** Binary file content with appropriate Content-Type header

## Archive Status Values

Delete jobs can have the following statuses:

* `pending` - Job created, waiting to start
* `running` - Deletion in progress
* `completed` - Deletion completed successfully
* `failed` - Deletion failed with errors
* `cancelled` - Deletion was cancelled