Admin actions

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

admin_app_surfaces_get

Get instance app surface settings.

Route	GET /api/v1/admin/apps/surfaces
Tool name	calternal_api_admin_app_surfaces_get
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	read only
Encoding	request none, response json

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

admin_app_surfaces_put

Update instance app surface settings. Body fields: enabled, surface. Requires a recent account confirmation..

Route	PUT /api/v1/admin/apps/surfaces
Tool name	calternal_api_admin_app_surfaces_put
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
enabled	boolean	yes
surface	"notes" | "api" | "cli" | "mcp" | "mcp_events" | "webmcp"	yes	These gates protect external automation credentials. Browser sessions remain usable so a User can always restore their own access in Settings.

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

admin_check_search_integrity

Check admin search integrity Requires a recent account confirmation..

Route	POST /api/v1/admin/search/integrity/check
Tool name	calternal_api_admin_check_search_integrity
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request none, response json

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

admin_clear_failed_jobs

Clear failed jobs Requires a recent account confirmation..

Route	DELETE /api/v1/admin/jobs/{kind}/failed
Tool name	calternal_api_admin_clear_failed_jobs
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request none, response json

path

Field	Type	Required	Description
kind	string	yes

calternal action run admin_clear_failed_jobs --input '{"path":{"kind":"<kind>"}}' --confirm --json

admin_delete_user

Delete a User Requires a recent account confirmation..

Route	DELETE /api/v1/admin/users/{id}
Tool name	calternal_api_admin_delete_user
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request json, response json

path

Field	Type	Required	Description
id	string, uuid	yes

body: object or object or object

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

admin_get_codec_manifest

Get the media codec list.

Route	GET /api/v1/admin/system/codecs
Tool name	calternal_api_admin_get_codec_manifest
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	read only
Encoding	request none, response json

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

admin_get_dedup_scrub_status

Get the deduplication check status.

Route	GET /api/v1/admin/dedup/scrub
Tool name	calternal_api_admin_get_dedup_scrub_status
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	read only
Encoding	request none, response json

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

admin_get_job

Get a job.

Route	GET /api/v1/admin/jobs/{id}/detail
Tool name	calternal_api_admin_get_job
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	read only
Encoding	request none, response json

path

Field	Type	Required	Description
id	string, uuid	yes

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

admin_get_media_health

Read thumbnail service health.

Route	GET /api/v1/admin/system/media-health
Tool name	calternal_api_admin_get_media_health
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	read only
Encoding	request none, response json

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

admin_get_search_integrity

Get admin search integrity.

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

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

admin_get_unsplash_key_status

Get the background image key status.

Route	GET /api/v1/admin/appearance/unsplash-key
Tool name	calternal_api_admin_get_unsplash_key_status
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	read only
Encoding	request none, response json

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

admin_groups_add_member

Only a real Instance User can join; repeated additions are idempotent. Requires a recent account confirmation..

Route	PUT /api/v1/admin/groups/{id}/members/{user_id}
Tool name	calternal_api_admin_groups_add_member
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request none, response json

path

Field	Type	Required	Description
id	string, uuid	yes
user_id	string, uuid	yes

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

admin_groups_create

Create an empty Group; membership is a separate explicit authority change.. Body fields: name. Requires a recent account confirmation..

Route	POST /api/v1/admin/groups
Tool name	calternal_api_admin_groups_create
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
name	string	yes

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

admin_groups_delete

Deletion hides authority immediately and retains Security state for Undo (#1028). Requires a recent account confirmation..

Route	DELETE /api/v1/admin/groups/{id}
Tool name	calternal_api_admin_groups_delete
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request none, response json

path

Field	Type	Required	Description
id	string, uuid	yes

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

admin_groups_list

List one row per Group, including empty Groups, on Admin → People..

Route	GET /api/v1/admin/groups
Tool name	calternal_api_admin_groups_list
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	read only
Encoding	request none, response json

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

admin_groups_remove_member

Remove live membership; collaboration rechecks use the same Index view. Requires a recent account confirmation..

Route	DELETE /api/v1/admin/groups/{id}/members/{user_id}
Tool name	calternal_api_admin_groups_remove_member
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request none, response json

path

Field	Type	Required	Description
id	string, uuid	yes
user_id	string, uuid	yes

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

admin_groups_rename

Rename preserves the Group ID and all grants. Refresh current Share labels.. Body fields: name. Requires a recent account confirmation..

Route	PUT /api/v1/admin/groups/{id}
Tool name	calternal_api_admin_groups_rename
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request json, response json

path

Field	Type	Required	Description
id	string, uuid	yes

body

Field	Type	Required	Description
name	string	yes

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

admin_groups_restore

Undo an admin deletion with the original ID and grants; normal guards apply. Requires a recent account confirmation..

Route	POST /api/v1/admin/groups/{id}/restore
Tool name	calternal_api_admin_groups_restore
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request none, response json

path

Field	Type	Required	Description
id	string, uuid	yes

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

admin_job_events

Stream admin job 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/admin/jobs/events
Tool name	calternal_api_admin_job_events
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	read only
Encoding	request none, response sse

headers

Field	Type	Required	Description
Last-Event-ID	string	no

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

admin_list_jobs

List jobs.

Route	GET /api/v1/admin/jobs
Tool name	calternal_api_admin_list_jobs
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	read only
Encoding	request none, response json

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

admin_list_user_archives

List User archives.

Route	GET /api/v1/admin/user-archives
Tool name	calternal_api_admin_list_user_archives
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	read only
Encoding	request none, response json

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

admin_list_users

List Users.

Route	GET /api/v1/admin/users
Tool name	calternal_api_admin_list_users
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	read only
Encoding	request none, response json

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

admin_pause_job_kind

Pause jobs of one type. Body fields: reason. Requires a recent account confirmation..

Route	POST /api/v1/admin/jobs/{kind}/pause
Tool name	calternal_api_admin_pause_job_kind
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request json, response json

path

Field	Type	Required	Description
kind	string	yes

body

Field	Type	Required	Description
reason	string	yes

calternal action run admin_pause_job_kind --input '{"path":{"kind":"<kind>"}}' --confirm --json

admin_put_dedup_scrub_schedule

Set the deduplication check schedule. Body fields: day, frequency, time. Requires a recent account confirmation..

Route	PUT /api/v1/admin/dedup/scrub/schedule
Tool name	calternal_api_admin_put_dedup_scrub_schedule
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
day	"monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday" or null	no
frequency	"weekly" | "daily" | "off"	yes	The small schedule vocabulary exposed to the admin UI. Cron remains a server-side storage detail; this type is the editable representation.
time	string	yes

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

admin_put_unsplash_key

Set the background image key. Body fields: access_key. Requires a recent account confirmation..

Route	PUT /api/v1/admin/appearance/unsplash-key
Tool name	calternal_api_admin_put_unsplash_key
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
access_key	string	yes

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

admin_rebuild_search_index

Rebuild the search index Requires a recent account confirmation..

Route	POST /api/v1/admin/search/rebuild
Tool name	calternal_api_admin_rebuild_search_index
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request none, response json

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

admin_resume_job_kind

Resume jobs of one type Requires a recent account confirmation..

Route	POST /api/v1/admin/jobs/{kind}/resume
Tool name	calternal_api_admin_resume_job_kind
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request none, response json

path

Field	Type	Required	Description
kind	string	yes

calternal action run admin_resume_job_kind --input '{"path":{"kind":"<kind>"}}' --confirm --json

admin_retry_failed_jobs

Retry failed jobs Requires a recent account confirmation..

Route	POST /api/v1/admin/jobs/{kind}/retry-failed
Tool name	calternal_api_admin_retry_failed_jobs
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request none, response json

path

Field	Type	Required	Description
kind	string	yes

calternal action run admin_retry_failed_jobs --input '{"path":{"kind":"<kind>"}}' --confirm --json

admin_run_job_kind_now

Run one job now Requires a recent account confirmation..

Route	POST /api/v1/admin/jobs/{kind}/run-now
Tool name	calternal_api_admin_run_job_kind_now
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request none, response json

path

Field	Type	Required	Description
kind	string	yes

calternal action run admin_run_job_kind_now --input '{"path":{"kind":"<kind>"}}' --confirm --json

admin_stop_job

Stop a job Requires a recent account confirmation..

Route	DELETE /api/v1/admin/jobs/{id}
Tool name	calternal_api_admin_stop_job
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request none, response json

path

Field	Type	Required	Description
id	string, uuid	yes

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

admin_trigger_dedup_scrub

Start a deduplication check Requires a recent account confirmation..

Route	POST /api/v1/admin/dedup/scrub/trigger
Tool name	calternal_api_admin_trigger_dedup_scrub
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request none, response json

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

get_config

Get instance configuration.

Route	GET /api/v1/admin/config
Tool name	calternal_api_get_config
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	read only
Encoding	request none, response json

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

get_config_toml

Get instance configuration as TOML.

Route	GET /api/v1/admin/config/toml
Tool name	calternal_api_get_config_toml
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	read only
Encoding	request none, response text

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

list_backups

List instance Backups.

Route	GET /api/v1/admin/backups
Tool name	calternal_api_list_backups
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	read only
Encoding	request none, response json

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

put_config

Update instance configuration. Body fields: apple_app_ids, backup_retention, backup_schedule, dedup_scrub_schedule, default_quota, instance_name, oidc_providers, open_signup, profile_signing, user_deletion_archive_days, version, video_cache_max_bytes. Requires a recent account confirmation..

Route	PUT /api/v1/admin/config
Tool name	calternal_api_put_config
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
apple_app_ids	array of string	no
backup_retention	integer (0–)	yes
backup_schedule	string	yes
dedup_scrub_schedule	string	no	Six-field wall-clock cron expression for the low-priority file check. The server evaluates it in the Instance time zone. An empty string means the scheduled check is off.
default_quota	integer, int64 (0–)	no
instance_name	string	yes
oidc_providers	array of object	no
open_signup	boolean	yes
profile_signing	object or null	no
user_deletion_archive_days	integer, int32 (0–)	no
version	integer, int32 (0–)	yes
video_cache_max_bytes	integer, int64 (0–)	no	Maximum bytes used by completed cached video renditions.

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

put_config_toml

Update instance configuration from TOML Requires a recent account confirmation..

Route	PUT /api/v1/admin/config/toml
Tool name	calternal_api_put_config_toml
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request text, response json

body: string. Raw UTF-8 text

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

set_instance_plugin

Set an instance Plugin. Body fields: cascade, enabled. Requires a recent account confirmation..

Route	PUT /api/v1/admin/plugins/{id}
Tool name	calternal_api_set_instance_plugin
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request json, response json

path

Field	Type	Required	Description
id	string	yes

body

Field	Type	Required	Description
cascade	boolean	no	Disable enabled dependents in the same operation.
enabled	boolean	yes	Whether to enable this plugin for the Instance.

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

trigger_backup

Start an instance Backup.

Route	POST /api/v1/admin/backups/trigger
Tool name	calternal_api_trigger_backup
Surfaces	cli, mcp, webmcp
Scopes	admin
Effect	destructive, needs --confirm
Encoding	request none, response text

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