## Download object

`GET /v1/storage/objects/:key`

Returns the object's content or a temporary download link. The behavior is determined by the query parameters: by default — a redirect, `?inline=true` — content in the response body.

## Parameters

**Path**

| Parameter | Type | Description |
|----------|-----|---------|
| `key` | string | Object key. The `/` characters in the key must be encoded: `users%2F42%2Favatar.png` |

**Query**

| Parameter | Type | Default | Description |
|----------|-----|-----------|---------|
| `inline` | boolean | `false` | `true` or `1` — return the content directly in the response body (HTTP 200) instead of a redirect |
| `inline_render` | boolean | `false` | Only together with `?inline=true`. `true` or `1` — removes the `Content-Disposition` header, the browser displays the file instead of downloading it |
| `download` | string | — | File name. When following the link, the browser will prompt to save the file with the given name |

## Examples

### curl — personal key

```bash
curl -L "https://vibecode.bitrix24.com/v1/storage/objects/reports%2F2024%2Fannual.pdf" \
  -H "X-Api-Key: YOUR_API_KEY" \
  --output annual.pdf
```

### curl — OAuth app

```bash
curl -L "https://vibecode.bitrix24.com/v1/storage/objects/reports%2F2024%2Fannual.pdf" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  --output annual.pdf
```

### JavaScript — personal key

```javascript
// Get a temporary link (without following the redirect)
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/storage/objects/reports%2F2024%2Fannual.pdf',
  {
    redirect: 'manual',
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  }
)
const url = res.headers.get('location') // temporary link, valid for 10 minutes
```

### JavaScript — OAuth app

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/storage/objects/reports%2F2024%2Fannual.pdf',
  {
    redirect: 'manual',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
const url = res.headers.get('location')
```

## Response

The response format depends on the query parameters.

**Default — redirect**

Returns `302 Found` with a temporary link in the `Location` header. The link is valid for 10 minutes. Browsers follow the redirect automatically; in server-side code use `redirect: 'manual'` and read `response.headers.get('location')`.

```
HTTP/1.1 302 Found
Location: <temporary link>
Cache-Control: no-store
```

**`?inline=true` — content in the response body**

Returns `200 OK` with the object's content directly in the response body. By default the browser saves the file (the `Content-Disposition: attachment` header). To have the browser display the file instead of downloading it, add `&inline_render=true`.

```
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 204800
ETag: "e3b0c44298fc1c149afbf4c8996fb92"
X-Content-Type-Options: nosniff
Content-Disposition: attachment; filename="annual.pdf"

<object content>
```

**`?download=<name>` — download with a given name**

Returns `302 Found`. When following the link from the `Location` header, storage serves the file with the `Content-Disposition: attachment; filename="<name>"` header, so the browser will prompt to save it with the given name.

```
HTTP/1.1 302 Found
Location: <temporary link with the given file name>
Cache-Control: no-store
```

## Error response example

404 — object not found:

```json
{
  "success": false,
  "error": {
    "code": "STORAGE_OBJECT_NOT_FOUND",
    "message": "Object reports/2024/annual.pdf not found"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 401 | `MISSING_API_KEY` | API key not passed |
| 403 | `STORAGE_SCOPE_REQUIRED` | The API key has no `vibe:storage` scope |
| 404 | `STORAGE_OBJECT_NOT_FOUND` | An object with the given key is not found |
| 410 | `STORAGE_OBJECT_DELETED` | The object was deleted |
| 502 | `STORAGE_OBJECT_STREAM_FAILED` | Error while transferring the object's content (only for `?inline=true` mode) |

The full list of general errors — [Errors](/docs/errors).

## See also

- [Objects](/docs/storage/objects)
- [List objects](/docs/storage/objects/list)
- [Object metadata](/docs/storage/objects/head)
- [Upload](/docs/storage/upload)