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

# Files

> API reference for Essal Office file storage — upload, download, list, and delete files.

## List Files

`GET /v1/office/files`

Returns a paginated list of uploaded files in the workspace.

**Query Parameters**

| Parameter     | Type    | Description                                  |
| ------------- | ------- | -------------------------------------------- |
| `uploader_id` | string  | Filter by uploader user ID                   |
| `mime_type`   | string  | Filter by MIME type (e.g. `application/pdf`) |
| `limit`       | integer | Results per page (default: 20, max: 100)     |

***

## Upload a File

`POST /v1/office/files`

Multipart form upload:

```bash theme={null}
curl -X POST https://api.essal.cloud/v1/office/files \
  -H "X-API-Key: esk_live_xxxxxxxxxxxxxxxxxxxx" \
  -F "file=@/path/to/report.pdf" \
  -F "name=Q3 Report.pdf"
```

**Response** — `201 Created`

```json theme={null}
{
  "id": "fil_01HXYZFIL1",
  "name": "Q3 Report.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 204800,
  "uploaded_by": "usr_01HXYZ1234",
  "created_at": "2026-07-10T10:00:00Z"
}
```

***

## Get a Download URL

`GET /v1/office/files/{id}/download`

Returns a pre-signed download URL valid for 1 hour:

```json theme={null}
{
  "url": "https://cdn.essal.cloud/files/fil_01HXYZFIL1?token=...",
  "expires_at": "2026-07-10T11:00:00Z"
}
```

***

## Chunked Upload

For files larger than 100 MB, use the chunked upload endpoint:

`POST /v1/office/files/upload/chunked`

Initiate a chunked upload session, then upload each part sequentially with `PUT /v1/office/files/upload/chunked/{session_id}/parts/{part_number}`. Complete with `POST /v1/office/files/upload/chunked/{session_id}/complete`.

***

## Delete a File

`DELETE /v1/office/files/{id}`

**Response** — `204 No Content`

<Warning>
  Deleting a file permanently removes it from storage. Any documents with this file as an attachment will show a broken reference. This action cannot be undone.
</Warning>