# List all files currently advertised by this host (inferred)

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

**GET** `/list`

Base URL: `https://{host}`

Returns a paginated list of UHRP advertisement records that this
storage server is currently hosting (i.e. its active UTXO tokens
on the `tm_uhrp` overlay topic).

## Authorization

- x-bsv-auth (apiKey in header)

## Query parameters

- `offset` (integer)
  Pagination offset (number of records to skip).
- `limit` (integer)
  Maximum number of records to return.

## Responses

### 200

List of hosted file records.

- `files` (object[], required)
  - `uhrpUrl` (string, required)
    UHRP URL for this file.
  - `downloadUrl` (string<uri>, required)
    HTTPS URL where this server serves the file.
  - `expiresAt` (integer, required)
    UNIX timestamp of the advertisement UTXO expiry.
  - `contentLength` (integer, required)
    Byte length of the advertised file.
  - `txid` (string)
    Transaction ID of the active advertisement UTXO.
- `total` (integer, required)
  Total number of files currently hosted by this server.
- `offset` (integer)
  Echoed from the query parameter.
- `limit` (integer)
  Echoed from the query parameter.

Example:

```json
{
  "files": [
    {
      "uhrpUrl": "uhrp://XYZ123abc...",
      "downloadUrl": "https://storage.example.com/files/abc123",
      "expiresAt": 1714100000,
      "contentLength": 204800,
      "txid": "a1b2c3d4..."
    }
  ],
  "total": 42,
  "offset": 0,
  "limit": 100
}
```

### 401

Missing or invalid BRC-103 authentication.

- `error` (string, required)
  Human-readable error description.
- `code` (string)
  Machine-readable error code (see specs/errors.md).

Example:

```json
{
  "error": "invalid UHRP URL",
  "code": "ERR_INVALID_PARAMETER"
}
```

### 500

Internal server error.

- `error` (string, required)
  Human-readable error description.
- `code` (string)
  Machine-readable error code (see specs/errors.md).

Example:

```json
{
  "error": "invalid UHRP URL",
  "code": "ERR_INVALID_PARAMETER"
}
```