Files actions

45 actions. Each action calls the same API route with the same scopes on every surface.

change_head

Get the Files change cursor.

Route	GET /api/v1/files/changes/head
Tool name	calternal_api_change_head
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

calternal action run change_head --input '{}' --json

change_wakeups

Subscribe to Files change wakeups Continuation: Reduce poll_ms after an overflow. Read current data after reconnect; use Last-Event-ID only where the route replays events..

Route	GET /api/v1/files/changes/events
Tool name	calternal_api_change_wakeups
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response sse

headers

Field	Type	Required	Description
Last-Event-ID	string	no

calternal action run change_wakeups --input '{}' --json

changes

Read Files changes Continuation: Resume from the returned cursor. If it expired, read change_head and rebuild from Files listing..

Route	GET /api/v1/files/changes
Tool name	calternal_api_changes
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

query

Field	Type	Required	Description
cursor	integer, int64	no
limit	integer, int64	no

calternal action run changes --input '{}' --json

copy_paths

Copy Files items. Body fields: destination, paths, replace..

Route	POST /api/v1/files/copy
Tool name	calternal_api_copy_paths
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
destination	string	yes
paths	array of string	yes
replace	boolean	no

calternal action run copy_paths --input '{}' --confirm --json

download

Download a Files item Continuation: Use the declared Range header or the existing streaming transfer command..

Route	GET /api/v1/files/download
Tool name	calternal_api_download
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response base64

query

Field	Type	Required	Description
inline	boolean	no
path	string	yes

headers

Field	Type	Required	Description
If-None-Match	string | null	no
If-Range	string | null	no
Range	string | null	no

calternal action run download --input '{"query":{"path":"<path>"}}' --json

download_version

Read a saved Files Version in byte chunks up to 720 KiB; continue at the returned content-range..

Route	GET /api/v1/files/versions/download
Tool name	calternal_api_download_version
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response base64

query

Field	Type	Required	Description
path	string	yes
version	string	yes

headers

Field	Type	Required	Description
Range	string | null	no

calternal action run download_version --input '{"query":{"path":"<path>","version":"<version>"}}' --json

download_zip

Download a ZIP in bounded chunks. Start at body.offset zero; body.chunk_size can be up to 720 KiB. Copy headers.etag to body.revision on each continuation. Add returned byte counts to offset and stop when base64 is empty. On HTTP 409 discard all chunks and restart at zero; on body read errors discard the failed chunk and retry with the same revision. Continuations read the prefix again for checksums, then stop at the chunk boundary. Selections are limited to 10000 entries and 8 MiB of path text.. Body fields: chunk_size, offset, paths, revision..

Route	POST /api/v1/files/download/zip
Tool name	calternal_files_download_zip
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request json, response base64

body

Field	Type	Required	Description
chunk_size	integer | null, int32 (1–737280)	no	Maximum chunk size, up to 720 KiB. The next call uses offset plus bytes returned.
offset	integer | null, int64 (0–)	no	Byte offset from the start of the deterministic ZIP stream.
paths	array of string	yes	Home-relative item paths to include.
revision	string | null	no	Copy the first chunk’s ETag here on every continuation. Restart at zero after a 409.

calternal action run download_zip --input '{}' --json

empty_trash

Empty Trash.

Route	POST /api/v1/files/trash/empty
Tool name	calternal_api_empty_trash
Surfaces	cli, mcp, webmcp
Scopes	data, account
Effect	destructive, needs --confirm
Encoding	request none, response json

calternal action run empty_trash --input '{}' --confirm --json

events

Read Home file changes from a Last-Event-ID cursor. Continuation: Reduce poll_ms after an overflow. Read current data after reconnect; use Last-Event-ID only where the route replays events..

Route	GET /api/v1/files/events
Tool name	calternal_files_read_home_changes
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response sse

headers

Field	Type	Required	Description
Last-Event-ID	string	no

calternal action run events --input '{}' --json

files_create_invite_link

Create a seven-day, five-account invitation for an item the User owns (§54).. Body fields: access, path..

Route	POST /api/v1/files/invite-links
Tool name	calternal_api_files_create_invite_link
Surfaces	cli, mcp, webmcp
Scopes	account
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
access	string	yes
path	string	yes

calternal action run files_create_invite_link --input '{}' --confirm --json

files_create_public_link

Create a public link. Body fields: clear_password, expires_at, hide_filenames, max_downloads, password, path, permissions, presentation, slug..

Route	POST /api/v1/files/links
Tool name	calternal_api_files_create_public_link
Surfaces	cli, mcp, webmcp
Scopes	data, account
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
clear_password	boolean	no	On update: remove the password. password: null keeps the current one, so turning a password off needs this explicit flag.
expires_at	string | null	no
hide_filenames	boolean	yes
max_downloads	integer | null, int64 (0–)	no
password	string | null	no
path	string	yes
permissions	object	yes
presentation	string	yes
slug	string | null	no

calternal action run files_create_public_link --input '{}' --confirm --json

files_create_share

Share a Files item. Body fields: access, path, recipient_id, recipient_kind..

Route	POST /api/v1/files/shares
Tool name	calternal_api_files_create_share
Surfaces	cli, mcp, webmcp
Scopes	data, account
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
access	string	yes
path	string	yes
recipient_id	string	yes
recipient_kind	"user" | "group"	no	The default preserves existing User clients; Groups retain one grant (#1028).

calternal action run files_create_share --input '{}' --confirm --json

files_create_upload

Start a resumable upload. Required headers: Tus-Resumable, Upload-Length, Upload-Metadata..

Route	POST /api/v1/files/uploads
Tool name	calternal_api_files_create_upload
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request base64, response json

headers

Field	Type	Required	Description
Tus-Resumable	string	yes
Upload-Checksum	string | null	no
Upload-Conflict-Policy	string | null	no
Upload-Length	string	yes
Upload-Metadata	string	yes

body: string. Base64 encoded bytes; send large uploads in chunks

calternal action run files_create_upload --input '{"headers":{"Tus-Resumable":"<Tus-Resumable>","Upload-Length":"<Upload-Length>","Upload-Metadata":"<Upload-Metadata>"}}' --confirm --json

files_get_pins

Get pinned Files items.

Route	GET /api/v1/files/pins
Tool name	calternal_api_files_get_pins
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

calternal action run files_get_pins --input '{}' --json

files_get_preferences

Get Files preferences.

Route	GET /api/v1/files/preferences
Tool name	calternal_api_files_get_preferences
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

calternal action run files_get_preferences --input '{}' --json

files_item

Find a Files item by ID.

Route	GET /api/v1/files/items/{id}
Tool name	calternal_api_files_item
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

calternal action run files_item --input '{"path":{"id":"<id>"}}' --json

files_list_invite_links

List only the current owner’s invitations and joined people (#1035)..

Route	GET /api/v1/files/invite-links
Tool name	calternal_api_files_list_invite_links
Surfaces	cli, mcp, webmcp
Scopes	account
Effect	read only
Encoding	request none, response json

query

Field	Type	Required	Description
path	string	no

calternal action run files_list_invite_links --input '{}' --json

files_list_public_links

List public links.

Route	GET /api/v1/files/links
Tool name	calternal_api_files_list_public_links
Surfaces	cli, mcp, webmcp
Scopes	data, account
Effect	read only
Encoding	request none, response json

calternal action run files_list_public_links --input '{}' --json

files_people

List other Users.

Route	GET /api/v1/files/people
Tool name	calternal_api_files_people
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

calternal action run files_people --input '{}' --json

files_quota

Get Home quota.

Route	GET /api/v1/files/quota
Tool name	calternal_api_files_quota
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

calternal action run files_quota --input '{}' --json

files_recent

List recent Files items Continuation: Reduce limit or use the route’s declared filters. Do not invent a cursor..

Route	GET /api/v1/files/recent
Tool name	calternal_api_files_recent
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

query

Field	Type	Required	Description
limit	integer, int64	no

calternal action run files_recent --input '{}' --json

files_revoke_invite_link

Stop new joins without removing existing item grants (DESIGN §54)..

Route	DELETE /api/v1/files/invite-links/{id}
Tool name	calternal_api_files_revoke_invite_link
Surfaces	cli, mcp, webmcp
Scopes	account
Effect	destructive, needs --confirm
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

calternal action run files_revoke_invite_link --input '{"path":{"id":"<id>"}}' --confirm --json

files_revoke_public_link

Revoke a public link.

Route	DELETE /api/v1/files/links/{id}
Tool name	calternal_api_files_revoke_public_link
Surfaces	cli, mcp, webmcp
Scopes	data, account
Effect	destructive, needs --confirm
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

calternal action run files_revoke_public_link --input '{"path":{"id":"<id>"}}' --confirm --json

files_revoke_share

Revoke a Files share.

Route	DELETE /api/v1/files/shares/{id}
Tool name	calternal_api_files_revoke_share
Surfaces	cli, mcp, webmcp
Scopes	data, account
Effect	destructive, needs --confirm
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

calternal action run files_revoke_share --input '{"path":{"id":"<id>"}}' --confirm --json

files_set_pins

Set pinned Files items. Body fields: pins, revision..

Route	PUT /api/v1/files/pins
Tool name	calternal_api_files_set_pins
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
pins	array of object	yes
revision	integer, int64 (0–)	yes	Revision returned by the last GET or successful PUT.

calternal action run files_set_pins --input '{}' --confirm --json

files_set_preferences

Set Files preferences. Body fields: show_dot_files, show_sidecar_files..

Route	PUT /api/v1/files/preferences
Tool name	calternal_api_files_set_preferences
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
show_dot_files	boolean	yes	Show names that start with U+002E in the User’s Home.
show_sidecar_files	boolean	yes	Show paired XMP and Apple AAE sidecar files as separate entries.

calternal action run files_set_preferences --input '{}' --confirm --json

files_shared_note

Read a stable Note identity through a live grant. Guessing and revocation return the same 404 as a missing Note. Private references are redacted for read-only recipients before any Markdown reaches the browser (#1034, §54)..

Route	GET /api/v1/files/shared-notes/{id}
Tool name	calternal_api_files_shared_note
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

calternal action run files_shared_note --input '{"path":{"id":"<id>"}}' --json

files_shared_notes

Enumerate only grant candidates; verify live filesystem identities before exposing their titles. Group membership comes from files_shares (#1028)..

Route	GET /api/v1/files/shared-notes
Tool name	calternal_api_files_shared_notes
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

query

Field	Type	Required	Description
after	string	no

calternal action run files_shared_notes --input '{}' --json

files_update_invite_link

Existing people get the same access change; individual removal stays separate (§54).. Body fields: access, revoked..

Route	PATCH /api/v1/files/invite-links/{id}
Tool name	calternal_api_files_update_invite_link
Surfaces	cli, mcp, webmcp
Scopes	account
Effect	destructive, needs --confirm
Encoding	request json, response json

path

Field	Type	Required	Description
id	string	yes

body

Field	Type	Required	Description
access	string | null	no
revoked	boolean | null	no

calternal action run files_update_invite_link --input '{"path":{"id":"<id>"}}' --confirm --json

head

Read a Tus upload’s offset and length before sending more bytes.. Required headers: Tus-Resumable..

Route	HEAD /api/v1/files/uploads/{id}
Tool name	calternal_files_read_upload_status
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

headers

Field	Type	Required	Description
Tus-Resumable	string	yes

calternal action run head --input '{"path":{"id":"<id>"},"headers":{"Tus-Resumable":"<Tus-Resumable>"}}' --json

list

List Files entries in one Home folder, with a stable page cursor. Continuation: Pass next_cursor unchanged with the same filters. Reduce limit after an overflow..

Route	GET /api/v1/files/entries
Tool name	calternal_files_list_folder
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

query

Field	Type	Required	Description
cursor	string	no
limit	integer (0–)	no
notes_filter	boolean	no
path	string	no
show_hidden	boolean	no
show_sidecars	boolean	no
sort	string	no

calternal action run list --input '{}' --json

list_shares

List Files shares.

Route	GET /api/v1/files/shares
Tool name	calternal_api_list_shares
Surfaces	cli, mcp, webmcp
Scopes	data, account
Effect	read only
Encoding	request none, response json

calternal action run list_shares --input '{}' --json

mkdir

Create a folder in the current User’s Home and return its stable item ID.. Body fields: path..

Route	POST /api/v1/files/mkdir
Tool name	calternal_files_create_folder
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
path	string	yes

calternal action run mkdir --input '{}' --confirm --json

move_paths

Move Files items. Body fields: destination, paths, replace..

Route	POST /api/v1/files/move
Tool name	calternal_api_move_paths
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
destination	string	yes
paths	array of string	yes
replace	boolean	no

calternal action run move_paths --input '{}' --confirm --json

patch

Send bytes to a resumable upload. Required headers: Tus-Resumable, Upload-Offset..

Route	PATCH /api/v1/files/uploads/{id}
Tool name	calternal_api_patch
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request base64, response json

path

Field	Type	Required	Description
id	string	yes

headers

Field	Type	Required	Description
Tus-Resumable	string	yes
Upload-Checksum	string | null	no
Upload-Offset	string	yes

body: string. Base64 encoded bytes; send large uploads in chunks

calternal action run patch --input '{"path":{"id":"<id>"},"headers":{"Tus-Resumable":"<Tus-Resumable>","Upload-Offset":"<Upload-Offset>"}}' --confirm --json

rename

Rename a File or folder in the current User’s Home.. Body fields: name, path..

Route	POST /api/v1/files/rename
Tool name	calternal_files_rename_item
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
name	string	yes
path	string	yes

calternal action run rename --input '{}' --confirm --json

restore

Restore Files items from Trash. Body fields: name..

Route	POST /api/v1/files/restore
Tool name	calternal_api_restore
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
name	string	yes

calternal action run restore --input '{}' --confirm --json

restore_version

Restore a previous version. Body fields: expected_current_hash, path, version..

Route	POST /api/v1/files/versions/restore
Tool name	calternal_api_restore_version
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
expected_current_hash	string	no
path	string	yes
version	string	yes

calternal action run restore_version --input '{}' --confirm --json

serve

Serve the authorized indexed renderer with access-checked, private no-store thumbnail bytes..

Route	GET /api/v1/files/thumb/{hash}
Tool name	calternal_api_serve
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response base64

path

Field	Type	Required	Description
hash	string	yes

query

Field	Type	Required	Description
kind	"media" | "pdf" | "text-card"	no	Public names for the renderer families carried by Files thumbnail URLs.
s	integer, int32 (0–)	yes
v	integer, int32 (1–2)	no

calternal action run serve --input '{"path":{"hash":"<hash>"},"query":{"s":"<s>"}}' --json

stat

Read a File or folder’s size, type and stable item ID..

Route	GET /api/v1/files/stat
Tool name	calternal_files_read_item
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

query

Field	Type	Required	Description
inline	boolean	no
path	string	yes

calternal action run stat --input '{"query":{"path":"<path>"}}' --json

terminate

Cancel an unfinished Tus upload to Files.. Required headers: Tus-Resumable..

Route	DELETE /api/v1/files/uploads/{id}
Tool name	calternal_files_cancel_upload
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

headers

Field	Type	Required	Description
Tus-Resumable	string	yes

calternal action run terminate --input '{"path":{"id":"<id>"},"headers":{"Tus-Resumable":"<Tus-Resumable>"}}' --confirm --json

trash

Move Files items to Trash.

Route	POST /api/v1/files/trash
Tool name	calternal_api_trash
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

body: array of object

calternal action run trash --input '{}' --confirm --json

trash_entries

List Trash items.

Route	GET /api/v1/files/trash/entries
Tool name	calternal_api_trash_entries
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

calternal action run trash_entries --input '{}' --json

update

Update a Public link’s settings for its current Files item.. Body fields: clear_password, expires_at, hide_filenames, max_downloads, password, path, permissions, presentation, slug..

Route	PUT /api/v1/files/links/{id}
Tool name	calternal_files_update_public_link
Surfaces	cli, mcp, webmcp
Scopes	data, account
Effect	destructive, needs --confirm
Encoding	request json, response json

path

Field	Type	Required	Description
id	string	yes

body

Field	Type	Required	Description
clear_password	boolean	no	On update: remove the password. password: null keeps the current one, so turning a password off needs this explicit flag.
expires_at	string | null	no
hide_filenames	boolean	yes
max_downloads	integer | null, int64 (0–)	no
password	string | null	no
path	string	yes
permissions	object	yes
presentation	string	yes
slug	string | null	no

calternal action run update --input '{"path":{"id":"<id>"}}' --confirm --json

versions

List saved Versions for a File in Home..

Route	GET /api/v1/files/versions
Tool name	calternal_files_list_versions
Surfaces	cli, mcp, webmcp
Scopes	data, account
Effect	read only
Encoding	request none, response json

query

Field	Type	Required	Description
inline	boolean	no
path	string	yes

calternal action run versions --input '{"query":{"path":"<path>"}}' --json