BSV blockchainBSV blockchain

List all files currently advertised by this host (inferred)

GET/list

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).

Query Parameters

offsetinteger

Pagination offset (number of records to skip).

limitinteger

Maximum number of records to return.

Response

List of hosted file records.

filesobject[]
Show files properties
uhrpUrlstring

UHRP URL for this file.

downloadUrlstring<uri>

HTTPS URL where this server serves the file.

expiresAtinteger

UNIX timestamp of the advertisement UTXO expiry.

contentLengthinteger

Byte length of the advertised file.

txidstring

Transaction ID of the active advertisement UTXO.

totalinteger

Total number of files currently hosted by this server.

offsetinteger

Echoed from the query parameter.

limitinteger

Echoed from the query parameter.

Missing or invalid BRC-103 authentication.

errorstring

Human-readable error description.

codestring

Machine-readable error code (see specs/errors.md).

Internal server error.

errorstring

Human-readable error description.

codestring

Machine-readable error code (see specs/errors.md).

Request
curl -X GET "https://{host}/list?offset=<offset>&limit=<limit>" \
  -H "x-bsv-auth: <x-bsv-auth>"
Response
{
  "files": [
    {
      "uhrpUrl": "uhrp://XYZ123abc...",
      "downloadUrl": "https://storage.example.com/files/abc123",
      "expiresAt": 1714100000,
      "contentLength": 204800,
      "txid": "a1b2c3d4..."
    }
  ],
  "total": 42,
  "offset": 0,
  "limit": 100
}