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.

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.

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

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

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

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

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