File Explorer

The File Explorer API operates inside a record-specific storage root and provides the complete file workflow.

Scopes and paths

The base URL is /api/v1/file-explorer/{scope}/{record}. Supported scopes are addresses, devices, and tickets (singular forms are normalized too). {record} accepts the record key resolved by that scope. Paths are relative to the scoped root; never send filesystem paths or .. traversal segments.

Read operations require files:read; mutations and archive creation require files:write. Record authorization is checked in addition to the OAuth scope.

List or inspect

With an omitted path or a directory path, returns a directory listing. With a file path, returns that entry's metadata. The same wildcard route intentionally supports both behaviors.

Search

Search from the path with a JSON body. Fields are search, type (file or directory), extension, mime_type, recursive (default true), sort_by (name, size, modified_at, or type), sort_direction, per_page (1–200), and page.

{
  "search": "invoice",
  "extension": "pdf",
  "recursive": true,
  "sort_by": "modified_at",
  "sort_direction": "desc",
  "per_page": 50,
  "page": 1
}

Upload files

Send multipart/form-data with one or more files[]. Each file may be at most 50 MiB. Returns 201 with uploaded entries and the refreshed listing.

Create a directory

Send { "name": "Documents" }. Names are limited to 255 characters and sanitized within the target directory. Returns the new directory entry with status 201.

Move or rename

Send the complete new relative path. Changing the basename renames the entry; changing its parent moves it. Both can happen in one request.

{ "path": "archive/invoice-2026.pdf" }

Delete an entry

Deletes the file or directory and returns 204 No Content.

Create an archive

Send a non-empty paths array and optional archive name (maximum 255 characters). The response is a temporary downloaded archive; the server removes its temporary file after sending it.

{ "paths": ["reports", "invoice.pdf"], "name": "support-files" }

Download

Downloads a file. If path is a directory, the server creates and downloads an archive.

Stream

Streams a file inline with its detected content type and a private five-minute cache header. Directories cannot be streamed.