# Media links: Scarleta API reference

Page: https://www.scarleta.ai/docs/reference/media-links
Base URL: https://api.scarleta.ai. Authentication: `Authorization: Bearer $SCARLETA_API_KEY`.
Operations: 1.

## POST /v1/media/refresh-url

Operation id: `refresh_media_url`

**Get a fresh link for a media file**

Media links that Scarleta returns can carry a signature that expires. Send a link you hold (`url`, an absolute address of at most 2048 characters, expired or not) and the route returns a freshly signed link for the same file, so a player can carry on. Only a file of your own account on Scarleta is signed. For anything else the answer is still 200 with `url` set to null: another account's file, an address on another site, or a link that cannot be signed right now. A null `url` means "no fresh link"; the link you already hold is not echoed back.

A missing, empty, over-long or relative `url`, and a body that is not valid JSON, are all 400 `invalid_url`. On success this route answers `{ data }` without `meta`.

Access: API key required; free and paid accounts. Cost: no token cost.

### Request body

| Field | Type | Description |
| --- | --- | --- |
| `url` | string | The link to refresh, an absolute address of at most 2048 characters. Allowed: 1 to 2048 characters. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `url` | string \| null | The freshly signed link, or null when the link is not a file of yours that can be signed. |

### Responses

200: A fresh link, or `url: null`.

```json
{
  "data": {
    "url": "https://api.scarleta.ai/v1/audio/media/9b2c7d1e-5a40-4f83-b6c9-0d1e2f3a4b5c.wav?exp=1791337470&sig=example-signature"
  }
}
```

400: The body is not valid JSON, or `url` is missing, empty, too long or not an absolute address.

```json
{
  "error": {
    "code": "invalid_url",
    "message": "url must be a non-empty string",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_url"
  }
}
```

401: Missing, malformed, unknown or revoked API key.

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_key"
  }
}
```

429: Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#rate_limit_exceeded"
  }
}
```

503: Temporary platform condition; retry shortly.

```json
{
  "error": {
    "code": "auth_unavailable",
    "message": "Authentication service temporarily unavailable",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#auth_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`invalid_url`](https://www.scarleta.ai/docs/errors#invalid_url), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`rate_limit_exceeded`](https://www.scarleta.ai/docs/errors#rate_limit_exceeded), [`rate_limit_unavailable`](https://www.scarleta.ai/docs/errors#rate_limit_unavailable), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

```bash
curl -X POST "https://api.scarleta.ai/v1/media/refresh-url" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.scarleta.ai/v1/audio/media/9b2c7d1e-5a40-4f83-b6c9-0d1e2f3a4b5c.wav"
  }'
```