Search actions

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

parse_search

Parse a search query.

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

query

Field	Type	Required	Description
q	string	yes

calternal action run parse_search --input '{"query":{"q":"<q>"}}' --json

record_search_opened

Record a search selection. Body fields: plugin_id, result_id..

Route	POST /api/v1/search/opened
Tool name	calternal_api_record_search_opened
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
plugin_id	string	yes	Plugin that owns the opened result.
result_id	string	yes	Stable result identifier returned by the search API.

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

search

Search Notes, Files, Calendar and other enabled data providers. Continuation: Reduce limit or use the route’s declared filters. Do not invent a cursor..

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

query

Field	Type	Required	Description
limit	integer, int32 (1–200)	no
q	string	yes
semantic	boolean	no
show_hidden	boolean	no

calternal action run search --input '{"query":{"q":"<q>"}}' --json

search_saved_create

Create a saved search. Body fields: name, pinned, query..

Route	POST /api/v1/search/saved
Tool name	calternal_api_search_saved_create
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
name	string	yes	Display name (1 to 120 characters).
pinned	boolean	no	Show the search in the sidebar. Default: false.
query	string	yes	Raw query with operators (1 to 512 characters, valid search grammar).

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

search_saved_delete

Delete a saved search.

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

path

Field	Type	Required	Description
id	string	yes

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

search_saved_get

Get a saved search.

Route	GET /api/v1/search/saved/{id}
Tool name	calternal_api_search_saved_get
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 search_saved_get --input '{"path":{"id":"<id>"}}' --json

search_saved_list

List saved searches.

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

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

search_saved_trash

Move a saved search to the Trash and return its journal identity for Undo..

Route	POST /api/v1/search/saved/{id}/trash
Tool name	calternal_api_search_saved_trash
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

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

search_saved_trash_undo

Restore only the exact saved-search file still held under its Trash receipt.. Body fields: expected_hash, trash_name..

Route	POST /api/v1/search/saved/{id}/trash/undo
Tool name	calternal_api_search_saved_trash_undo
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

path

Field	Type	Required	Description
id	string	yes

body

Field	Type	Required	Description
expected_hash	string	yes
trash_name	string	yes

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

search_saved_unpin

Unpin a saved search and return the exact previous Files Version for Undo..

Route	POST /api/v1/search/saved/{id}/unpin
Tool name	calternal_api_search_saved_unpin
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

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

search_saved_unpin_undo

Restore the previous saved-search bytes only while the unpinned file is unchanged.. Body fields: expected_hash, version_name..

Route	POST /api/v1/search/saved/{id}/unpin/undo
Tool name	calternal_api_search_saved_unpin_undo
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

path

Field	Type	Required	Description
id	string	yes

body

Field	Type	Required	Description
expected_hash	string	yes
version_name	string	yes

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

search_saved_update

Update a saved search. Body fields: name, pinned, query..

Route	PATCH /api/v1/search/saved/{id}
Tool name	calternal_api_search_saved_update
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

path

Field	Type	Required	Description
id	string	yes

body

Field	Type	Required	Description
name	string | null	no	New display name.
pinned	boolean | null	no	New sidebar state.
query	string | null	no	New raw query.

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