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

# Overview

> Manage company-level folders and files via the API

The Company Files API lets you create a folder hierarchy, upload files, and
organize them into folders — all at the company level.

<Note>
  These endpoints manage **company-level** files and folders only. Entity-scoped
  file endpoints (attached to exposures, policies, events, etc.) are planned for
  a future release.
</Note>

## Key Concepts

* **Folder** — a named container that can hold files and other folders. Folders form a tree via `parentFolderId` (null = root).
* **File** — a binary object with metadata (name, MIME type, category). Files can optionally live inside a folder.
* **Folder contents** — the `GET /folders/{folderId}` endpoint returns a mixed list of files and subfolders, discriminated by the `contentType` field (`file` or `folder`).
* **Soft delete** — both file and folder deletes are soft (the record is marked as deleted). Deleting a folder recursively soft-deletes all contents.

## API Endpoints

### Folders

| Method | Endpoint                 | Description                               |
| ------ | ------------------------ | ----------------------------------------- |
| POST   | `/v1/folders`            | Create a folder                           |
| GET    | `/v1/folders`            | List all folders (flat, paginated)        |
| GET    | `/v1/folders/{folderId}` | List folder contents (files + subfolders) |
| PATCH  | `/v1/folders/{folderId}` | Rename or move a folder                   |
| DELETE | `/v1/folders/{folderId}` | Soft-delete folder (recursive)            |

### Files

| Method | Endpoint                     | Description                           |
| ------ | ---------------------------- | ------------------------------------- |
| POST   | `/v1/files`                  | Upload a file (multipart)             |
| GET    | `/v1/files/{fileId}`         | Get file metadata                     |
| GET    | `/v1/files/{fileId}/content` | Download file content (binary stream) |
| PATCH  | `/v1/files/{fileId}`         | Rename or move a file                 |
| DELETE | `/v1/files/{fileId}`         | Soft-delete a file                    |

## Permissions

| Operation                                                      | Permission            |
| -------------------------------------------------------------- | --------------------- |
| List folders, List folder contents, Get file, Download content | `company.file:read`   |
| Create folder, Upload file                                     | `company.file:create` |
| Rename/move folder, Rename/move file                           | `company.file:update` |
| Delete folder, Delete file                                     | `company.file:delete` |

## Workflow Example

A typical integration creates a folder structure, uploads files into it, then
retrieves them later.

**1. Create a folder**

```bash theme={null}
curl -X POST https://app.aiinsurance.io/api/v1/external/companies/{companyId}/folders \
  -H "Authorization: YOUR-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Claims Documents"}'
# → {"id": "folder-uuid"}
```

**2. Upload a file into the folder**

```bash theme={null}
curl -X POST https://app.aiinsurance.io/api/v1/external/companies/{companyId}/files \
  -H "Authorization: YOUR-API-KEY" \
  -F "file=@claim-report.pdf" \
  -F "fileName=claim-report.pdf" \
  -F "mimeType=application/pdf" \
  -F "folderId=folder-uuid"
# → {"id": "file-uuid", "name": "claim-report.pdf", ...}
```

**3. List folder contents**

```bash theme={null}
curl https://app.aiinsurance.io/api/v1/external/companies/{companyId}/folders/folder-uuid \
  -H "Authorization: YOUR-API-KEY"
# → {"items": [{"contentId": "file-uuid", "contentType": "file", ...}], "totalCount": 1}
```

**4. Download the file**

```bash theme={null}
curl https://app.aiinsurance.io/api/v1/external/companies/{companyId}/files/file-uuid/content \
  -H "Authorization: YOUR-API-KEY" \
  -o claim-report.pdf
```