Photos actions

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

photos_create_upload

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

Route	POST /api/v1/photos/uploads
Tool name	calternal_api_photos_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 photos_create_upload --input '{"headers":{"Tus-Resumable":"<Tus-Resumable>","Upload-Length":"<Upload-Length>","Upload-Metadata":"<Upload-Metadata>"}}' --confirm --json

photos_get_item

Get a Photo item.

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

path

Field	Type	Required	Description
item_id	string	yes

calternal action run photos_get_item --input '{"path":{"item_id":"<item_id>"}}' --json

photos_get_library_roots

Get Photos library folders.

Route	GET /api/v1/photos/library-roots
Tool name	calternal_api_photos_get_library_roots
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

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

photos_get_preferences

Get Photos preferences.

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

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

photos_get_stack

Get a Photo stack.

Route	GET /api/v1/photos/stacks/{group_id}
Tool name	calternal_api_photos_get_stack
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

path

Field	Type	Required	Description
group_id	string	yes

calternal action run photos_get_stack --input '{"path":{"group_id":"<group_id>"}}' --json

photos_put_library_roots

Set Photos library folders. Body fields: library_roots..

Route	PUT /api/v1/photos/library-roots
Tool name	calternal_api_photos_put_library_roots
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
library_roots	array of string	yes

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

photos_put_preferences

Set Photos preferences. Body fields: screenshot_destination..

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

body

Field	Type	Required	Description
screenshot_destination	"photos" | "documents"	yes

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

photos_search

Search Photos Continuation: Reduce limit or use the route’s declared filters. Do not invent a cursor..

Route	GET /api/v1/photos/search
Tool name	calternal_api_photos_search
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

query

Field	Type	Required	Description
aperture	number, double	no
camera	string	no
date	string	no
iso	integer, int64	no
lens	string	no
limit	integer (0–)	no
place	string	no
q	string	no

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

photos_set_key_photo

Set the key Photo in a burst. Body fields: item_id..

Route	PUT /api/v1/photos/stacks/{group_id}/key-photo
Tool name	calternal_api_photos_set_key_photo
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

path

Field	Type	Required	Description
group_id	string	yes

body

Field	Type	Required	Description
item_id	string	yes

calternal action run photos_set_key_photo --input '{"path":{"group_id":"<group_id>"}}' --confirm --json

photos_timeline

Get the Photos timeline Continuation: Pass next_before unchanged. Use the day route for more tiles, or reduce days and tiles_per_day..

Route	GET /api/v1/photos/timeline
Tool name	calternal_api_photos_timeline
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

query

Field	Type	Required	Description
before	string	no
days	integer (0–)	no
filter	"all" | "videos" | "stacks"	no	Which timeline groups a read returns. videos keeps groups whose display item is a video; stacks keeps RAW+JPEG pairs, Live Photos and bursts.
tiles_per_day	integer (0–)	no

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

photos_timeline_buckets

Get Photos day counts.

Route	GET /api/v1/photos/timeline/buckets
Tool name	calternal_api_photos_timeline_buckets
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

query

Field	Type	Required	Description
filter	"all" | "videos" | "stacks"	no	Which timeline groups a read returns. videos keeps groups whose display item is a video; stacks keeps RAW+JPEG pairs, Live Photos and bursts.

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

photos_timeline_day

Get Photos for a day Continuation: Increase offset by the number of returned tiles until count is reached. Reduce limit after an overflow..

Route	GET /api/v1/photos/timeline/days/{day}
Tool name	calternal_api_photos_timeline_day
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

path

Field	Type	Required	Description
day	string	yes

query

Field	Type	Required	Description
filter	"all" | "videos" | "stacks"	no	Which timeline groups a read returns. videos keeps groups whose display item is a video; stacks keeps RAW+JPEG pairs, Live Photos and bursts.
limit	integer (0–)	no
offset	integer (0–)	no

calternal action run photos_timeline_day --input '{"path":{"day":"<day>"}}' --json

photos_undo_key_photo

Restore the prior burst key only while every Sidecar still has its captured revision (#775).. Body fields: previous_item_id, sidecars..

Route	POST /api/v1/photos/stacks/{group_id}/key-photo/undo
Tool name	calternal_api_photos_undo_key_photo
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

path

Field	Type	Required	Description
group_id	string	yes

body

Field	Type	Required	Description
previous_item_id	string | null	no	Explicit prior key, or None to remove all Calternal key markers.
sidecars	array of object	yes	Sidecar revisions returned by the forward update.

calternal action run photos_undo_key_photo --input '{"path":{"group_id":"<group_id>"}}' --confirm --json