> ## 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 /files/{file_id}
```

## Authentication

This endpoint requires authentication via API key. Include your API key in the `X-API-Key` header:

```bash theme={null}
X-API-Key: ca_your_api_key_here
```

## Path Parameters

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

## Query Parameters

| Parameter    | Type   | Required | Description                                                         |
| ------------ | ------ | -------- | ------------------------------------------------------------------- |
| `user_email` | string | No       | Email address of the user downloading the file (for audit purposes) |

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://platform.chamelio.ai/files/document_789?user_email=john@example.com" \
    -H "X-API-Key: ca_your_api_key_here"
  ```

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

  file_id = "document_789"
  user_email = "john@example.com"

  url = f"https://platform.chamelio.ai/files/{file_id}"
  headers = {
      "X-API-Key": "ca_your_api_key_here"
  }
  params = {
      "user_email": user_email
  }

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

  ```javascript JavaScript theme={null}
  const fileId = 'document_789';
  const userEmail = 'john@example.com';

  const response = await fetch(
    `https://platform.chamelio.ai/files/${fileId}?user_email=${encodeURIComponent(userEmail)}`,
    {
      method: 'GET',
      headers: {
        'X-API-Key': 'ca_your_api_key_here'
      }
    }
  );

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

## 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.

```json theme={null}
{
  "detail": "Invalid file ID format: invalid_id"
}
```

### 401 Unauthorized

Returned when authentication fails. See the [authentication errors](/api-reference/introduction#authentication-errors) section for details.

```json theme={null}
{
  "detail": "Invalid API key"
}
```

### 404 Not Found

Returned when the file doesn't exist or you don't have access to it.

```json theme={null}
{
  "detail": "File not found"
}
```

### 500 Internal Server Error

Returned when the request fails due to a server error.

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

## Notes

<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>

<Tip>
  Provide the `user_email` parameter for audit tracking. This helps maintain a record of who downloaded which files and when.
</Tip>

## 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
* **Integration** - Connect file storage with other business systems