Download File

Endpoint

GET /v2/files/{file_id}

Authentication

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

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

curl -X GET "https://platform.chamelio.ai/v2/files/document_789" \
  -H "Authorization: Bearer your_access_token"

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

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

There is no user_email query parameter here. The download is attributed to the access token’s user automatically.

Response

Success Response

Status Code: 200 OK

{
  "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.

{
  "detail": "Invalid file ID format. Expected document_{id} or attachment_{id}"
}

{
  "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.

{
  "detail": "Invalid access token"
}

403 Forbidden

Returned when the token does not carry the required scope.

{
  "detail": "Insufficient scope; this endpoint requires: files:read"
}

404 Not Found

Returned when the file does not exist.

{
  "detail": "Not found"
}

429 Too Many Requests

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

{
  "detail": "Rate limit exceeded"
}

500 Internal Server Error

Returned when the request fails due to a server error.

{
  "detail": "Failed to download file"
}

Notes

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.

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.

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.

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

Overview

API Key Access

OAuth App Access

Webhooks

Endpoint

Authentication

Path Parameters

Request Example

Response

Success Response

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Too Many Requests

500 Internal Server Error

Notes

Common MIME Types

Use Cases

​Endpoint

​Authentication

​Path Parameters

​Request Example

​Response

​Success Response

​Response Fields

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​429 Too Many Requests

​500 Internal Server Error

​Notes

​Common MIME Types

​Use Cases

Endpoint

Authentication

Path Parameters

Request Example

Response

Success Response

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Too Many Requests

500 Internal Server Error

Notes

Common MIME Types

Use Cases