# Initiate a file upload (inferred from BRC-26 status note)

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

**POST** `/upload`

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

Request an upload slot for a file.  The server responds with a
pre-signed upload URL (or equivalent mechanism) and the UHRP URL
that will address the content once the upload is complete.

The client then issues a PUT request to the returned `uploadURL` with
the raw file bytes.

## Authorization

- x-bsv-auth (apiKey in header)

## Body

Content type: `application/json`

- `fileSize` (integer, required)
  Exact byte length of the file to be uploaded.
- `sha256` (string, required)
  SHA-256 hash of the file content (hex, 64 characters).
- `mimeType` (string)
  Optional MIME type of the file.
- `retentionDays` (integer)
  Requested number of days the advertisement token should remain
  valid.  The server may cap this value.

Example:

```json
{
  "fileSize": 204800,
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "mimeType": "image/png",
  "retentionDays": 30
}
```

## Responses

### 200

Upload slot allocated.

- `uhrpUrl` (string, required)
  The UHRP URL that will address this content.  Encoded as
  Base58Check with prefix `ce00` over the SHA-256 hash.
- `uploadUrl` (string<uri>, required)
  Pre-signed HTTPS URL.  The client MUST issue a PUT request with
  the raw file bytes to this URL to complete the upload.
- `expiresAt` (integer)
  UNIX timestamp (seconds) when the upload URL expires.

Example:

```json
{
  "uhrpUrl": "uhrp://XYZ123abc...",
  "uploadUrl": "https://storage.example.com/put/abc123?sig=...",
  "expiresAt": 1714010000
}
```

### 400

Bad request — invalid input.

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

### 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"
}
```