# Upload document file

URL: /en/docs/api/v1/documents/id/file/put
Last Updated: 2026-07-30T21:15:30.510Z

## Description
No description available.

## Available Actions
- Execute PUT request
- View request parameters
- View response schema
- Get code examples
- Navigate to related topics
- View step-by-step instructions
- Get best practices

## Content
### PUT /api/v1/documents/{id}/file

**Upload document file**

Upload a file to associate with a document. Supports two upload methods:
1. Multipart form-data with file field
2. Binary stream with X-Original-Filename header

File validation includes size limits (10MB), MIME type checking, and
automatic type detection from file signatures.

**Authentication:** Bearer token (`Authorization: Bearer <token>`)

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string (uuid) | Yes | Document ID to upload file for |

**Header parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `X-Original-Filename` | string | No | Original filename (required for binary uploads) |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `locale` | enum: en \| de \| fr \| ja \| ko \| zh | No | Locale whose document file should be uploaded or removed. Base locale codes are resolved to Directus language codes such as ja-JP, ko-KR, and zh-CN. |

**Request body** (`multipart/form-data`) - required:

- `file` (string (binary), required): File to upload. Supports various document and image formats (e.g., PDF, DOCX, PNG, JPG).

**Request body** (`application/octet-stream`) - required:

**Responses:**

- `200` - File uploaded successfully
  - `success` (boolean)
  - `data` (object)
    - `fileId` (string (uuid)): Directus file ID
    - `url` (string): Public URL to access the file

  Example (Successful upload):
  
  ```json
  {
  "success": true,
  "data": {
    "fileId": "file-789",
    "url": "https://directus.example.com/assets/file-789"
  }
}
  ```
- `400` - Bad Request - validation failed
  - `error` (string)
  - `details` (string)

  Example (File too large):
  
  ```json
  {
  "error": "document_too_large",
  "details": "File size exceeds 10MB limit"
}
  ```

  Example (Invalid file type):
  
  ```json
  {
  "error": "document_invalid_type",
  "details": "File type not supported"
}
  ```

  Example (Empty file):
  
  ```json
  {
  "error": "file_cannot_be_empty",
  "details": "File cannot be empty"
}
  ```

  Example (No file provided):
  
  ```json
  {
  "error": "no_file_processed_from_form_data",
  "details": "No file found in request"
}
  ```
- `401` - Unauthorized
- `404` - Document not found
- `415` - Unsupported Media Type
  - `error` (string)
- `500` - Internal server error
  - `error` (string)

**Code samples:**

cURL:

```bash
curl -X PUT "https://app.orbiqhq.com/api/v1/documents/{id}/file" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```