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

# Download File

> Download a file by its unique file ID

## Endpoint

```
GET /v2/files/{file_id}
```

## Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

```bash theme={null}
Authorization: Bearer your_access_token
```

**Required scope:** `files:read`

## Path Parameters

| Parameter | Type   | Required | Description                                                           |
| --------- | ------ | -------- | --------------------------------------------------------------------- |
| `file_id` | string | Yes      | Unique file identifier (format: `document_{id}` or `attachment_{id}`) |

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://platform.chamelio.ai/v2/files/document_789" \
    -H "Authorization: Bearer your_access_token"
  ```

  ```python Python theme={null}
  import requests

  file_id = "document_789"

  url = f"https://platform.chamelio.ai/v2/files/{file_id}"
  headers = {
      "Authorization": "Bearer your_access_token"
  }

  response = requests.get(url, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const fileId = 'document_789';

  const response = await fetch(
    `https://platform.chamelio.ai/v2/files/${fileId}`,
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer your_access_token'
      }
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

<Info>
  There is no `user_email` query parameter here. The download is attributed to the access token's user
  automatically.
</Info>

## Response

### Success Response

**Status Code:** `200 OK`

```json theme={null}
{
  "file_id": "document_789",
  "file_name": "acme_contract.pdf",
  "content_type": "application/pdf",
  "download_url": "https://s3.amazonaws.com/chamelio-files/...",
  "expires_at": "2025-01-20T12:00:00Z"
}
```

### Response Fields

| Field          | Type   | Description                                                                                                                |
| -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
| `file_id`      | string | The file identifier that was requested                                                                                     |
| `file_name`    | string | Name of the file                                                                                                           |
| `content_type` | string | MIME type of the file (e.g., `application/pdf`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`) |
| `download_url` | string | Presigned URL to download the file                                                                                         |
| `expires_at`   | string | ISO 8601 timestamp when the download URL expires                                                                           |

## Error Responses

### 400 Bad Request

Returned when the file ID format is invalid, or when the access token has no user behind it.
`client_credentials` tokens act as the admin who created the application, so this applies only to
tokens issued before application creators were recorded.

```json theme={null}
{
  "detail": "Invalid file ID format. Expected document_{id} or attachment_{id}"
}
```

```json theme={null}
{
  "detail": "client_credentials tokens are not associated with a user"
}
```

### 401 Unauthorized

Returned when the access token is missing, unknown, revoked, or expired, or when an `X-API-Key` was
sent instead of a bearer token. See [OAuth error responses](/api-reference/oauth-apps#error-responses).

```json theme={null}
{
  "detail": "Invalid access token"
}
```

### 403 Forbidden

Returned when the token does not carry the required scope.

```json theme={null}
{
  "detail": "Insufficient scope; this endpoint requires: files:read"
}
```

### 404 Not Found

Returned when the file does not exist.

```json theme={null}
{
  "detail": "Not found"
}
```

### 429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

```json theme={null}
{
  "detail": "Rate limit exceeded"
}
```

### 500 Internal Server Error

Returned when the request fails due to a server error.

```json theme={null}
{
  "detail": "Failed to download file"
}
```

## Notes

<Warning>
  The access token's user is validated against the organization, but the file itself is authorized at the
  **organization** level. Any file in the organization can be downloaded with a valid `files:read` token,
  regardless of whether that user could open the file in the web application. Treat `files:read` as
  organization-wide file access and grant it deliberately.
</Warning>

<Info>
  File IDs follow a specific format: `document_{id}` for documents and `attachment_{id}` for attachments.
  Use the complete file ID as returned from other endpoints.
</Info>

<Warning>
  The presigned download URL expires after a certain time (indicated by `expires_at`). Download the file
  before the URL expires or request a new URL.
</Warning>

## Common MIME Types

| Extension       | MIME Type                                                                 |
| --------------- | ------------------------------------------------------------------------- |
| `.pdf`          | `application/pdf`                                                         |
| `.docx`         | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
| `.doc`          | `application/msword`                                                      |
| `.xlsx`         | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`       |
| `.txt`          | `text/plain`                                                              |
| `.png`          | `image/png`                                                               |
| `.jpg`, `.jpeg` | `image/jpeg`                                                              |

## Use Cases

This endpoint is useful for:

* **File retrieval** - Download files uploaded to or generated by workflows
* **Document export** - Export documents to external systems
* **Archival** - Save files to long-term storage
* **User downloads** - Allow end users to download files through custom interfaces