AI actions

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

cancel_turn

Cancel a turn.

Route	DELETE /api/v1/ai/turns/{id}
Tool name	calternal_api_cancel_turn
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 cancel_turn --input '{"path":{"id":"<id>"}}' --confirm --json

get_turn

Get a turn.

Route	GET /api/v1/ai/turns/{id}
Tool name	calternal_api_get_turn
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 get_turn --input '{"path":{"id":"<id>"}}' --json

list_credentials

List AI credentials.

Route	GET /api/v1/ai/credentials
Tool name	calternal_api_list_credentials
Surfaces	cli, mcp, webmcp
Scopes	account
Effect	read only
Encoding	request none, response json

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

list_turns

List AI turns Continuation: Reduce limit or use the route’s declared filters. Do not invent a cursor..

Route	GET /api/v1/ai/turns
Tool name	calternal_api_list_turns
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 list_turns --input '{}' --json

remove_credential

Remove an AI provider credential.

Route	DELETE /api/v1/ai/credentials/{provider}
Tool name	calternal_api_remove_credential
Surfaces	cli, mcp, webmcp
Scopes	account
Effect	destructive, needs --confirm
Encoding	request none, response json

path

Field	Type	Required	Description
provider	"claude" | "codex"	yes	The official coding Agent selected by a prompt mention.

calternal action run remove_credential --input '{"path":{"provider":"<provider>"}}' --confirm --json

save_credential

Save an AI provider credential. Body fields: credential..

Route	PUT /api/v1/ai/credentials/{provider}
Tool name	calternal_api_save_credential
Surfaces	cli, mcp, webmcp
Scopes	account
Effect	destructive, needs --confirm
Encoding	request json, response json

path

Field	Type	Required	Description
provider	"claude" | "codex"	yes	The official coding Agent selected by a prompt mention.

body

Field	Type	Required	Description
credential	string	yes	Provider subscription access token accepted by the official CLI.

calternal action run save_credential --input '{"path":{"provider":"<provider>"}}' --confirm --json

start_ask

Ask a question. Body fields: provider, question..

Route	POST /api/v1/ai/ask
Tool name	calternal_api_start_ask
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
provider	"claude" | "codex"	yes	Configured official Agent provider used for the read-only turn.
question	string	yes	Question to answer from data visible to this User.

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

start_turn

Start an agent turn. Body fields: context, prompt..

Route	POST /api/v1/ai/turns
Tool name	calternal_api_start_turn
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
context	string	no	Optional calternal context supplied by the calling editor.
prompt	string	yes	User request containing exactly one whole-token @claude or @codex mention.

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

stream_turn

Stream turn events 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/ai/turns/{id}/events
Tool name	calternal_api_stream_turn
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response sse

path

Field	Type	Required	Description
id	string	yes

headers

Field	Type	Required	Description
Last-Event-ID	string	no

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

undo_turn

Undo an agent turn.

Route	POST /api/v1/ai/turns/{id}/undo
Tool name	calternal_api_undo_turn
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

path

Field	Type	Required	Description
id	string	yes

body: object or null

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