Storage Files API Reference

Storage is the Cosmos document management system (DMS). Files and folders are both items; every item has an owner, an access level, and optional per-user ACL entries. For architecture and configuration, see Storage Service.

Every endpoint except health checks requires Authorization: Bearer YOUR_TOKEN and X-Org-Id: YOUR_ORG_ID. A missing token returns 401; a missing or invalid X-Org-Id returns 400. X-Project-Id is optional and attributes the action to a project in Recent Activity. Errors use {"error": "BadRequest", "status": 400, "message": "..."}. See API Conventions.

Local base URL: http://localhost:8107. All paths below are under /api/v1/.

Endpoint Summary

Item Object

Uploads

Direct upload

POST /api/v1/items/upload/
Content-Type: multipart/form-data

Returns 201 with the item and a version object that includes a signed_url.

.m4a files are stored as audio/mp4. Storage checks that file content matches the declared type and rejects mismatches.

Resumable upload sessions

Large files upload directly to cloud storage, then Storage verifies and promotes them in the background.

1. Start — POST /api/v1/items/upload-session/start

   json

   {
     "filename": "recording.mp4",
     "content_type": "video/mp4",
     "declared_size": 2147483648,
     "parent_path": "/Recordings",
     "force_create_path": true,
     "access_level": "private"
   }
   

   Optional fields: kind (normal or redaction), name, parent_id, force_upload_new_version, description, owner_id, redaction, and target_item_id. declared_size can be up to 6 GiB.

   Returns 201:

   json

   {
     "session_id": "SESSION_UUID",
     "session_token": "YOUR_SESSION_TOKEN",
     "status": "initiated",
     "kind": "normal",
     "upload_url": "https://...",
     "method": "PUT",
     "headers": {"...": "..."},
     "protocol": "azure_block",
     "expires_at": "2026-11-03T12:00:00Z",
     "chunk_size": 8388608
   }
   

   protocol is azure_block, gcs_resumable, or local_put depending on the backend.

2. Upload — send the bytes to upload_url using method and headers. Call POST .../upload-session/{id}/uploading when you begin, and POST .../upload-session/{id}/refresh-url if the URL expires.

3. Complete — POST /api/v1/items/upload-session/{id}/complete, optionally with {"checksum": "<sha256 hex>"}. Returns 202; the checksum is verified asynchronously.

4. Poll — GET /api/v1/items/upload-session/{id} until status is completed (or failed, aborted, expired). Statuses move through initiated, uploading, and completing. POST .../upload-session/{id}/abort cancels it.

Import from URL

POST /api/v1/items/import-url/ with source_url and the same destination fields as a direct upload.

Versions and Downloads

Browse and Search

GET /api/v1/items/?parent_id=FOLDER_UUID&search=report&file_type=pdf&sort_by=updated_at&sort_order=desc&page_size=20

{"results": [{"id": "ITEM_UUID", "name": "Q3 report.pdf", "is_directory": false, "...": "..."}], "next_cursor": "...", "page_size": 20}

Results only include items the caller can view.

Item Operations

Bulk Operations

Bulk fetch. GET /api/v1/items/bulk-fetch/?item=UUID&item=UUID:2 returns items with signed URLs; append :version to pin a version. GET /api/v1/items/bulk-fetch-by-path/?item=/Reports/q3.pdf does the same by path. Items the caller cannot view are skipped. Administrators can set signed_url_expiry_minutes.

Bulk access level.

POST /api/v1/items/bulk-access-level/

{"items": [{"item_id": "ITEM_UUID", "access_level": "public_read", "update_children": true}]}

Up to 1,000 items. Returns {"updated_count": 1, "failed_items": []}.

Permission check.

POST /api/v1/items/check-permissions/

{"item_ids": ["ITEM_UUID_1", "ITEM_UUID_2"]}

Up to 100 IDs. Returns one permission object per item (view, update, delete, manage ACL). The frontend uses this to decide which actions to show; results are cached for 5 minutes.

Access Control

Each ACL entry grants or denies one user specific actions on an item. A user has at most one allow and one deny entry per item. allow is evaluated before deny, and RBAC *_all permissions bypass deny entries.

PUT /api/v1/items/{id}/acl/

{
  "acls": [
    {
      "user_id": "USER_UUID",
      "effect": "allow",
      "can_view": true,
      "can_update": true,
      "can_delete": false,
      "can_manage_acl": false,
      "applies_to_children": true
    }
  ]
}

PUT replaces the item's entries and returns {"success": true, "message": "...", "affected_count": 1, "acls": [...]}. GET returns the current entries; DELETE removes them.

ZIP and Unzip

POST /api/v1/items/{id}/zip/ archives a folder and POST /api/v1/items/{id}/unzip/ extracts a ZIP file. Both return 202 Accepted and run in the background. Only items the caller can view are included, and the archive type is validated before extraction.

Upload-Time Redaction

Storage can remove PII from documents and images as they are uploaded.

Large uploads can also be redacted through an upload session with "kind": "redaction".

Metrics

GET /api/v1/metrics/

{"org_id": "YOUR_ORG_ID", "total_files": 1280, "total_folders": 96, "total_size": 73400320}

Limits

Testing

curl -s -X POST http://localhost:8107/api/v1/items/upload/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Org-Id: YOUR_ORG_ID" \
  -F "file=@./report.pdf" \
  -F "parent_path=/Reports" \
  -F "force_create_path=true"

curl -s "http://localhost:8107/api/v1/items/?search=report" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Org-Id: YOUR_ORG_ID"