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

# Files

> Send artwork and audio as URLs we download, or upload them yourself.

Release artwork and each track's audio take one of two forms.

**From a URL**

```json theme={"dark"}
"audio": {
  "url": "https://your-bucket.s3.amazonaws.com/nova/night-drive.wav",
  "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}
```

We download the file in the background, usually within a minute. `sha256` is optional; when you send it, a file that doesn't match is refused, so an incomplete download can't slip through.

**Upload it yourself**

```json theme={"dark"}
"audio": { "upload": true }
```

This reserves the slot. You then request a signed upload URL and send the file to it (below).

## Accepted hosts

URLs must use HTTPS and come from one of these hosts:

* Amazon S3 and CloudFront
* Google Cloud Storage
* Cloudflare R2
* Azure Blob Storage
* DigitalOcean Spaces
* Backblaze B2
* Wasabi
* Dropbox

Signed URLs work; make them valid for at least a day so retries can still reach the file. To download from your own domain, ask your AMM Distro representative to add it to your key. A URL on any other host is refused when you send the release.

## Uploading yourself

**1. Find the file ID**

After the `PUT`, the release shows the slot waiting for its file:

```json theme={"dark"}
"audio": { "present": false, "file": { "id": "3b11db77-…", "source": "upload", "status": "awaiting_upload" } }
```

**2. Request an upload URL**

```bash theme={"dark"}
curl -s -X POST "$BASE/delivery/releases/NOVA-004/files/3b11db77-…/upload-url" \
  -H "Authorization: Bearer $AMMD_API_KEY" -H "Content-Type: application/json" \
  -d '{ "contentType": "audio/wav", "sizeBytes": 52428800, "filename": "night-drive.wav" }'
```

`contentType` is `image/jpeg` or `image/png` for artwork, `audio/wav` or `audio/flac` for audio. `sizeBytes` is the exact size of the file.

**3. Upload the file**

Send the file with `PUT` to the returned `uploadUrl`, with the returned `headers`, within 6 hours:

```bash theme={"dark"}
curl -s -X PUT "$UPLOAD_URL" -H "Content-Type: audio/wav" --data-binary @night-drive.wav
```

The upload is refused if the file's size doesn't match `sizeBytes`.

**4. Complete the upload**

```bash theme={"dark"}
curl -s -X POST "$BASE/delivery/releases/NOVA-004/files/3b11db77-…/complete" \
  -H "Authorization: Bearer $AMMD_API_KEY"
```

The file is then checked the same way as a downloaded one.

## File status

Each file appears in the release with its status:

| Status | Meaning |
| - | - |
| `awaiting_upload` | Waiting for you to upload it. |
| `pending` | Being downloaded or checked. |
| `ready` | In use on the release. |
| `failed` | Can't be used. `error` says why. |

A file that breaks a requirement fails straight away with the reason, for example *"The artwork file is 1200×1200; artwork must be at least 1400×1400"*. A download that fails for network reasons is retried four more times over about an hour and a half before it's marked `failed`.

To fix a failed file, send the release again with a corrected file. Sending the same URL again retries it.

The requirements for each file type are in [File requirements](/reference/file-requirements.md).

## Replacing and keeping files

* Leave `artwork` or `audio` out of a later `PUT` and the current file stays.
* Send a different URL, or `upload: true` again, to replace it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.