API Reference

infrastrActure exposes a REST API on port 7500 and a built-in MCP endpoint on /mcp.

Surface Map

Surface	Auth	Notes
`/health`	none	Liveness only
`/api/auth/callback`	none	OAuth return path
most `/api/*` routes	API key	`Authorization: Bearer <key>` or `X-API-Key`
`/mcp`	API key	key tier controls what tools are exposed
`/api/infra/ssh/*`	admin API key only	also requires `X-User-Id`

Authorization: Bearer <api-key>
Content-Type: application/json
X-User-Id: <user-id>
X-Request-Id: <optional-request-id>

Method	Path	Purpose
`GET`	`/health`	simple liveness check
`GET`	`/status`	service, Docker, DB, storage status

Method	Path	Purpose
`POST`	`/api/auth/keys/generate`	mint API key
`GET`	`/api/auth/keys`	list keys
`DELETE`	`/api/auth/keys/:id`	revoke key
`GET`	`/api/auth/callback`	complete shared-tool OAuth flow

Method	Path	Purpose
`GET`	`/api/marketplace/tools`	search catalog
`GET`	`/api/marketplace/tools/:id`	get tool details
`POST`	`/api/marketplace/tools/:id/install`	initiate install flow
`GET`	`/api/registry`	list registry-backed tool definitions
`GET`	`/api/registry/:id`	get one registry tool
`POST`	`/api/marketplace/refresh`	refresh catalog

Method	Path	Purpose
`GET`	`/api/installations`	list tenant/user installations
`GET`	`/api/installations/:id`	inspect installation
`PATCH`	`/api/installations/:id`	mutate installation config
`DELETE`	`/api/installations/:id`	remove installation
`GET`	`/api/installations/:id/tools`	list tools exposed by one installation
`POST`	`/api/installations/:id/tools/call`	call a tool
`POST`	`/api/installations/:id/files`	upload file payloads
`GET`	`/api/containers`	list managed containers
`POST`	`/api/containers/:id/:action`	start / stop / restart / remove

Method	Path	Purpose
`POST`	`/api/shared-tools/:toolId/oauth/state`	create per-user OAuth state
`GET`	`/api/shared-tools/:toolId/oauth/status`	get per-user auth status
`GET`	`/api/shared-tools/:toolId/oauth/user-email`	read linked email

Method	Path	Purpose
`GET`	`/api/sandboxes`	list sandboxes
`POST`	`/api/sandboxes`	create sandbox
`GET`	`/api/sandboxes/:id`	inspect sandbox
`PATCH`	`/api/sandboxes/:id`	update sandbox
`DELETE`	`/api/sandboxes/:id`	destroy sandbox
`POST`	`/api/sandboxes/:id/:action`	lifecycle action
`GET`	`/api/runtime/config/:sandboxId`	sandbox runtime config
`GET`	`/api/runtime/proxy-auth/:sandboxId`	runtime proxy auth payload
`ALL`	`/api/runtime/proxy/:sandboxId/*`	proxy to sandbox runtime

See Infra SSH for the dedicated operational model and security notes.

The canonical surface is /api/integrations/client. A small number of named-instance aliases exist for convenience and historical reasons.

Method	Path	Purpose
`GET`	`/api/integrations/client`	canonical MCP config for clients
`POST`	`/api/integrations/client/sync`	sync notification
`GET`	`/api/integrations/tessaract`	named alias for the TessarAct instance
`POST`	`/api/integrations/tessaract/sync`	sync trigger for the TessarAct instance

New clients should use /api/integrations/client with the appropriate instanceId query parameter rather than registering a new named alias.

The built-in MCP server currently exposes 27 tools in these families:

Family	Count	Examples
containers	3	`list_containers`, `container_action`
marketplace	2	`search_marketplace`, `get_tool_details`
installations	3	`list_installations`, `install_tool`
shared tools	1	`list_shared_tools`
sandboxes	4	`create_sandbox`, `sandbox_action`
service	1	`service_status`
infra SSH	13	`infra_ssh_list_hosts`, `infra_ssh_open_forward`

Most REST failures return:

{
  "success": false,
  "error": "Human-readable message"
}

Infra SSH errors also distinguish:

That distinction is preserved in audit records.