# Your first API download

Submit one URL, wait for completion, and retrieve every returned file.

This guide uses the hosted API from your backend. Ask [partner@mediafilez.online](mailto:partner@mediafilez.online) for access. You do not need to run Redis, a worker, or a Discord bot to use it.

## Set your key

Store your key in the calling service's private environment. Do not put it in browser JavaScript or a public repository.

```bash
export MEDIAFILEZ_API_KEY='YOUR_API_KEY'
```

On PowerShell:

```powershell
$env:MEDIAFILEZ_API_KEY = 'YOUR_API_KEY'
```

The base URL is `https://api.mediafilez.online/api/v1`. Test the key:

```bash
curl --fail-with-body 'https://api.mediafilez.online/api/v1/users/me' \
  -H "Authorization: ApiKey $MEDIAFILEZ_API_KEY"
```

## 1. Start a download

Replace the URL with a public media link you are allowed to download.

```bash
curl --fail-with-body 'https://api.mediafilez.online/api/v1/media/download' \
  -H "Authorization: ApiKey $MEDIAFILEZ_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-first-download-001' \
  -d '{
    "url": "https://example.com/video.mp4",
    "output": {
        "type": "auto",
        "format": "original",
        "quality": "best"
    }
}'
```

The response is `202`. A shortened example:

```json
{
    "job": {
        "id": "job_example",
        "status": "queued",
        "result": null
    }
}
```

Keep `job.id`. Keep the same idempotency key if you retry this same request after a connection failure. Use a new key for a new download.

## 2. Wait for the job

```bash
curl --fail-with-body 'https://api.mediafilez.online/api/v1/jobs/job_example' \
  -H "Authorization: ApiKey $MEDIAFILEZ_API_KEY"
```

Poll about every two seconds. Continue for `queued` or `processing`. Stop for `completed`, `failed`, `cancelled`, or `expired`.

When successful, a shortened response looks like:

```json
{
    "job": {
        "id": "job_example",
        "status": "completed",
        "result": {
            "fileId": "fil_example",
            "files": [
                {
                    "fileId": "fil_example"
                }
            ]
        }
    }
}
```

If `result.files` exists, use every entry. Otherwise use `result.fileId`. This matters for albums, which can produce several files. See [job results](/docs/en/reference/jobs).

## 3. Get a download URL

```bash
curl --fail-with-body 'https://api.mediafilez.online/api/v1/files/fil_example' \
  -H "Authorization: ApiKey $MEDIAFILEZ_API_KEY"
```

Read `file.url` from the JSON response. Fetch that URL to obtain the bytes. **Do not send your API key to the storage URL.**

Private download URLs expire, normally after 15 minutes. Ask `/files/:id` again for a fresh URL. Refreshing a URL does not restore a deleted or expired artifact.

## Next steps

Use the [complete Node.js and Python example](/docs/en/guides/nodejs), learn about [authentication](/docs/en/guides/authentication), or open the [API reference](/docs/en/reference/overview).

## Request examples

Choose a language. JavaScript and Node.js examples use a server environment, not a public browser key. Replace illustrative IDs with your own.

### Try a download request

```request
{
    "method": "POST",
    "path": "/media/download",
    "body": {
        "url": "https://example.com/video.mp4"
    }
}
```

### Read the job status

```request
{
    "method": "GET",
    "path": "/jobs/job_example"
}
```

### Get the file address

```request
{
    "method": "GET",
    "path": "/files/fil_example"
}
```