Host Control REST Routes

This page is the table-oriented route catalog for the Host Control REST API. For usage guidance, start with Host Control REST API Guide.

The product-facing API is available only under the stable /api/v1 prefix. Unprefixed routes were retired before the 1.0 release and return HTTP 404.

Health And Readiness

Method	Stable path	Role	Purpose
GET	/api/v1/health	public or authenticated by policy	Lightweight process health and shared-memory manager connectivity
GET	/api/v1/ready	public or authenticated by policy	Runtime readiness with HTTP 200 when accepted and 503 when not ready

These health routes may be unauthenticated when security.health.unauthenticated=true. Network admission still applies.

Security

Method	Stable path	Role	Purpose	Request body
POST	/api/v1/auth/login	public through admission policy	Create a Web Console session	admin password login payload
GET	/api/v1/auth/session	viewer	Read current browser/session identity	none
POST	/api/v1/auth/logout	viewer	Clear browser/session identity	none
GET	/api/v1/control/security	admin	Read security configuration and API key metadata	none
POST	/api/v1/control/security/admin-password	admin	Change the managed admin password	current/new password payload
POST	/api/v1/control/security/api-keys	admin	Create an API key	key name and role payload
DELETE	/api/v1/control/security/api-keys/{key_name}	admin	Revoke an API key	none

API key secret values are returned once at creation time and hidden afterwards.

Runtime Status And Bindings

Method	Stable path	Role	Purpose	Request body
GET	/api/v1/control/status	viewer	Full host runtime snapshot, including live lease-to-package instance ownership	none
GET	/api/v1/control/capabilities	viewer	Product/API capability snapshot including frontend mode and security policy	none
GET	/api/v1/control/specs	viewer	Installed spec dictionary used by the Web Console	none
GET	/api/v1/control/federation/hello	viewer	Federation bootstrap/status payload for peer discovery	none
GET	/api/v1/control/bindings	viewer	Runtime binding override and effective binding inventory	optional query by subsystem
POST	/api/v1/control/bindings	operator	Set a runtime binding override	source and target binding references
DELETE	/api/v1/control/bindings/{source}	operator	Remove one runtime binding override	none
GET	/api/v1/publishers	viewer	Event publisher/subscriber inventory and shared-memory state	none
GET	/api/v1/shm_manager	viewer	Shared-memory manager connectivity snapshot	none

The source path segment for binding deletion is a binding reference such as component.gripper.digital_io.

Subsystem Runtime Control

Method	Stable path	Role	Purpose	Request body
POST	/api/v1/control/subsystems/{subsystem}/lifecycle	operator	Request a subsystem lifecycle transition	transition, optional reason, optional session_id
POST	/api/v1/control/subsystems/{subsystem}/process	operator	Terminate or kill a managed subsystem process	action, optional session_id

Lifecycle transitions are start, pause, resume, stop, reset, fault, and degrade. Process actions are terminate and kill.

Configuration And Runtime Apply

Method	Stable path	Role	Purpose	Request body
GET	/api/v1/control/config	admin	Read effective, base, and override runtime config	none
POST	/api/v1/control/config	admin	Save raw YAML override	raw YAML override payload
POST	/api/v1/control/config/fields	admin	Save structured config field updates	dotted-key field update payload
POST	/api/v1/control/config/validate	admin	Validate raw YAML override without applying it	raw YAML override payload
POST	/api/v1/control/runtime/apply	admin	Apply managed runtime changes	none or apply options
POST	/api/v1/control/restart	admin	Request control-service restart when available	none

Prefer /api/v1/control/config/fields for ordinary UI or automation changes.

Managed Packages

Method	Stable path	Role	Purpose	Request body
GET	/api/v1/control/packages	viewer	List installed managed packages and active runtime instances	none
POST	/api/v1/control/packages/install	admin	Install a package archive	filename, content_base64, replace
DELETE	/api/v1/control/packages/{package_id}	admin	Uninstall a managed package	optional force query
POST	/api/v1/control/packages/{package_id}/start	operator	Start one package runtime instance through the launcher	optional instance_id, params, runtime_dir
POST	/api/v1/control/packages/{package_id}/stop	operator	Stop one package runtime instance	optional instance_id
POST	/api/v1/control/packages/{package_id}/restart	operator	Restart one package runtime instance	optional instance_id, params, runtime_dir
GET	/api/v1/control/packages/{package_id}/instances/{instance_id}/context	viewer	Return frontend runtime context for one package instance	none

Installation registers one package record by package name. Starting with a new instance_id creates another managed runtime instance, subject to resource-policy conflicts. Stopped, terminated, and killed instances are removed from the active instance registry rather than retained as package history.

Package Frontend Assets And Proxies

Method	Stable path	Role	Purpose
GET	/api/v1/packages/{package_id}/ui	viewer	Serve a managed package frontend entrypoint
GET	/api/v1/packages/{package_id}/ui/	viewer	Serve a managed package frontend entrypoint
GET	/api/v1/packages/{package_id}/ui/{path}	viewer	Serve static package frontend assets with SPA fallback
GET	/api/v1/packages/{package_id}/instances/{instance_id}/context	viewer	Return frontend runtime context for one package instance
ANY	/api/v1/packages/{package_id}/instances/{instance_id}/api	viewer or operator by package policy	Proxy same-origin REST calls to package instance GUI endpoint
ANY	/api/v1/packages/{package_id}/instances/{instance_id}/api/	viewer or operator by package policy	Proxy same-origin REST calls to package instance GUI endpoint
ANY	/api/v1/packages/{package_id}/instances/{instance_id}/api/{path}	viewer or operator by package policy	Proxy same-origin REST calls to package instance GUI endpoint
GET	/api/v1/packages/{package_id}/instances/{instance_id}/ws	viewer or operator by package policy	Proxy same-origin WebSocket calls to package instance GUI endpoint
GET	/api/v1/packages/{package_id}/instances/{instance_id}/ws/	viewer or operator by package policy	Proxy same-origin WebSocket calls to package instance GUI endpoint
GET	/api/v1/packages/{package_id}/instances/{instance_id}/ws/{path}	viewer or operator by package policy	Proxy same-origin WebSocket calls to package instance GUI endpoint

The proxy paths are not native subsystem transport. They are same-origin browser routes for package-owned frontend backends declared in package.yaml.

WebSocket Upgrade Routes

Method	Stable path	Role	Purpose
GET	/api/v1/ws/events	viewer	WebSocket upgrade for Event observation
GET	/api/v1/ws/control	operator	WebSocket upgrade for Procedure and Operation requests

For message kinds and fields, see Host Control WebSocket Messages.

System Frontend Fallback

Method	Path	Role	Purpose
GET	/	public or viewer by policy	Serve configured system frontend entrypoint
GET	/{path}	public or viewer by policy	Serve configured system frontend assets or SPA fallback

The system frontend can be the bundled Console, a custom static product frontend, or disabled.