API Parameter Reference

This document maps parameter and response field names across all ORB interfaces: CQRS (internal), SDK, CLI, REST, and MCP.

Naming Conventions

Interface	Convention	Example
CQRS / Domain	snake_case	requested_count, template_id
SDK	snake_case; CLI aliases accepted	count maps to requested_count
CLI	snake_case arguments	--template-id, --machine-count
REST (request body)	camelCase or snake_case (both accepted)	templateId or template_id
REST (response body)	camelCase	requestId, templateId
MCP	snake_case (mirrors SDK/CQRS)	template_id, requested_count

The REST layer uses a to_camel alias generator (BaseRequestModel) so both forms are accepted on input. Responses are always camelCase.

The SDK ParameterMapper applies two alias mappings globally before constructing any CQRS object:

SDK alias	CQRS field
count	requested_count
provider	provider_name

---

Operations

Request Machines

Create a new machine provisioning request.

CQRS command: CreateRequestCommand

Interface	Parameter	CQRS field	Notes
CQRS	template_id	—	required
CQRS	requested_count	—	required
CQRS	request_id	—	optional; pre-generated by CLI handler
CQRS	timeout	—	optional, default 3600
CQRS	tags	—	optional
SDK	template_id	template_id	required
SDK	count	requested_count	alias via ParameterMapper
SDK	requested_count	requested_count	direct name also accepted
CLI	template_id / --template-id	template_id	positional or flag
CLI	machine_count / --machine-count	requested_count	positional or flag
REST body	template_id or templateId	template_id
REST body	count, machine_count, or machineCount	requested_count	all three aliases accepted (AliasChoices)
REST body	additional_data	passed through	optional
MCP	template_id	template_id
MCP	requested_count	requested_count

REST endpoint: POST /api/v1/machines/request

Response fields:

Interface	Field	Description
REST	requestId	ID of the created request
REST	message	Human-readable status message
SDK (command output)	created_request_id	Populated on command object after execution
CLI	scheduler-formatted response	Delegated to SchedulerPort.format_request_response()

---

Return Machines

Create a return request for one or more machines.

CQRS command: CreateReturnRequestCommand

Interface	Parameter	CQRS field	Notes
CQRS	machine_ids	—	required; list of machine ID strings
CQRS	force_return	—	optional, default false
CQRS	timeout	—	optional, default 3600
SDK	machine_ids	machine_ids
SDK	force_return	force_return
CLI	machine_ids	machine_ids	positional args
CLI	--all + --force	triggers list query then machine_ids	destructive; requires --force
CLI	-f <file> (input_data)	machines[].machineId or machines[].machine_id	JSON file input
REST body	machine_ids or machineIds	machine_ids
MCP	machine_ids	machine_ids

REST endpoint: POST /api/v1/machines/return

SDK command output fields (populated on command object after execution):

Field	Description
created_request_ids	List of created return request IDs
processed_machines	Machine IDs that were successfully queued
skipped_machines	List of {machine_id, reason} dicts for skipped machines

---

Get Request Status

Retrieve the current status of a provisioning or return request.

CQRS query: GetRequestQuery

Interface	Parameter	CQRS field	Notes
CQRS	request_id	—	required
CQRS	long	—	optional, default false
CQRS	lightweight	—	optional, default false
CQRS	provider_name	—	optional
SDK	request_id	request_id
SDK	long	long
CLI	request_id / --request-id	request_id	positional or flag
CLI	-f <file> (input_data)	requests[].request_id	JSON file input
REST path	request_id	request_id	URL path parameter
REST query	long	long	default true in REST
MCP	request_id	request_id

REST endpoint: GET /api/v1/requests/{request_id}/status

---

List Active Requests

List all active provisioning requests.

CQRS query: ListActiveRequestsQuery

Interface	Parameter	CQRS field	Notes
CQRS	all_resources	—	optional, default false
CQRS	limit	—	optional, default 50
CQRS	offset	—	optional, default 0
CQRS	provider_name	—	optional
CQRS	filter_expressions	—	optional list of filter strings
CLI	--all	all_resources=True
REST query	status	passed to ListRequestsQuery.status	filter by status string
REST query	limit	limit

REST endpoint: GET /api/v1/requests

Note: the REST handler uses ListRequestsQuery (from orb.application.request.queries), not ListActiveRequestsQuery. The CLI --all path uses ListActiveRequestsQuery.

---

List Return Requests

List requests pending machine return.

CQRS query: ListReturnRequestsQuery

Interface	Parameter	CQRS field	Notes
CQRS	machine_names	—	optional list; filters by machine name
CQRS	status	—	optional
CQRS	limit	—	optional, default 50
CQRS	offset	—	optional, default 0
CQRS	provider_name	—	optional
CLI	-f <file> (input_data)	machines[].name or machines[].machineId	JSON file input
REST	(no parameters)	—	returns all pending return requests
MCP	machine_names	machine_names

REST endpoint: GET /api/v1/requests/return

---

Cancel Request

Cancel an in-progress request.

CQRS command: CancelRequestCommand

Interface	Parameter	CQRS field	Notes
CQRS	request_id	—	required
CQRS	reason	—	required (pass "" if none)
CLI	request_id / --request-id	request_id	positional or flag
CLI	--reason	reason	optional

No REST endpoint exists for cancel. No MCP tool is auto-generated unless a handler is registered.

---

List Templates

List available machine templates.

CQRS query: ListTemplatesQuery

Interface	Parameter	CQRS field	Notes
CQRS	provider_api	—	optional; filter by provider API string
CQRS	active_only	—	optional, default true
CQRS	limit	—	optional, default 50
CQRS	offset	—	optional, default 0
CQRS	provider_name	—	optional
SDK	provider_api	provider_api
SDK	active_only	active_only
CLI	--provider-api	provider_api
CLI	-f <file> (input_data)	provider_api, active_only	JSON file input
REST query	provider_api	provider_api
MCP	provider_api	provider_api

REST endpoint: GET /api/v1/templates

---

Get Template

Retrieve a single template by ID.

CQRS query: GetTemplateQuery

Interface	Parameter	CQRS field	Notes
CQRS	template_id	—	required
CQRS	provider_name	—	optional
SDK	template_id	template_id
CLI	template_id / --template-id	template_id	positional or flag
REST path	template_id	template_id	URL path parameter
MCP	template_id	template_id

REST endpoint: GET /api/v1/templates/{template_id}

---

Create Template

Register a new template.

CQRS command: CreateTemplateCommand

Interface	Parameter	CQRS field	Notes
CQRS	template_id	—	required
CQRS	image_id	—	required
CQRS	provider_api	—	required
CQRS	name	—	optional
CQRS	description	—	optional
CQRS	instance_type	—	optional
CQRS	tags	—	optional dict
CQRS	configuration	—	full config dict
CLI	--file	reads JSON; accepts template_id/templateId, image_id/imageId, provider_api/providerApi, instance_type/instanceType	snake_case or camelCase both accepted in file
REST body	template_id or templateId	template_id
REST body	image_id or imageId	image_id
REST body	provider_api or providerApi	provider_api	default "aws"
REST body	instance_type or instanceType	instance_type
REST body	name	name
REST body	key_name or keyName	key_name
REST body	security_group_ids or securityGroupIds	security_group_ids
REST body	subnet_ids or subnetIds	subnet_ids
REST body	user_data or userData	user_data
REST body	tags	tags
REST body	version	version	default "1.0"

REST endpoint: POST /api/v1/templates

Response fields:

Interface	Field	Description
REST	templateId	ID of the created template
REST	message	Human-readable confirmation
REST	timestamp	ISO 8601 timestamp
CLI	template_id	ID of the created template
CLI	success	boolean

---

Update Template

Update an existing template.

CQRS command: UpdateTemplateCommand

Interface	Parameter	CQRS field	Notes
CQRS	template_id	—	required
CQRS	name	—	optional
CQRS	description	—	optional
CQRS	configuration	—	optional dict
CLI	template_id / --template-id	template_id	positional or flag
CLI	--name	name
CLI	--description	description
REST path	template_id	template_id	URL path parameter
REST body	same fields as Create (all optional)

REST endpoint: PUT /api/v1/templates/{template_id}

---

Delete Template

Remove a template.

CQRS command: DeleteTemplateCommand

Interface	Parameter	CQRS field	Notes
CQRS	template_id	—	required
CLI	template_id / --template-id	template_id	positional or flag
REST path	template_id	template_id	URL path parameter

REST endpoint: DELETE /api/v1/templates/{template_id}

---

Validate Template

Validate a template configuration without persisting it.

CQRS query: ValidateTemplateQuery

Interface	Parameter	CQRS field	Notes
CQRS	template_config	—	required dict
CQRS	template_id	—	optional
CLI	--file	template_config	JSON or YAML file
CLI	template_id	template_id	validate a loaded template by ID
CLI	--all	iterates all loaded templates
REST body	raw JSON dict	template_config

REST endpoint: POST /api/v1/templates/validate

Response fields:

Interface	Field	Description
REST	valid	boolean
REST	templateId	template ID
REST	validationErrors	list of error strings
REST	validationWarnings	list of warning strings
CLI	valid	boolean
CLI	validation_errors	list
CLI	validation_warnings	list

---

Cleanup Old Requests

Remove requests older than a given age.

CQRS command: CleanupOldRequestsCommand

Interface	Parameter	CQRS field	Notes
CQRS	older_than_days	—	optional, default 1
CQRS	statuses_to_cleanup	—	optional list of status strings
SDK	older_than_days	older_than_days

SDK command output fields:

Field	Description
requests_cleaned	Count of requests removed
request_ids_found	List of request IDs that were found for cleanup

---

Cleanup All Resources

Remove all stale requests and machines.

CQRS command: CleanupAllResourcesCommand

Interface	Parameter	CQRS field	Notes
CQRS	older_than_days	—	optional, default 1
CQRS	include_pending	—	optional, default false
SDK	older_than_days	older_than_days
SDK	include_pending	include_pending

SDK command output fields:

Field	Description
requests_cleaned	Count of requests removed
machines_cleaned	Count of machines removed
total_cleaned	Combined total

---

SDK Method Names

The SDK auto-discovers CQRS handlers and derives method names by stripping the Command or Query suffix and converting to snake_case.

CQRS class	SDK method name
CreateRequestCommand	create_request
CreateReturnRequestCommand	create_return_request
CancelRequestCommand	cancel_request
UpdateRequestStatusCommand	update_request_status
SyncRequestCommand	sync_request
CleanupOldRequestsCommand	cleanup_old_requests
CleanupAllResourcesCommand	cleanup_all_resources
CleanupTerminatedMachinesCommand	cleanup_terminated_machines
CompleteRequestCommand	complete_request
PopulateMachineIdsCommand	populate_machine_ids
CreateTemplateCommand	create_template
UpdateTemplateCommand	update_template
DeleteTemplateCommand	delete_template
GetRequestQuery	get_request
ListActiveRequestsQuery	list_active_requests
ListReturnRequestsQuery	list_return_requests
GetTemplateQuery	get_template
ListTemplatesQuery	list_templates
ValidateTemplateQuery	validate_template
GetMachineQuery	get_machine
ListMachinesQuery	list_machines
GetActiveMachineCountQuery	get_active_machine_count
GetConfigurationQuery	get_configuration
GetRequestSummaryQuery	get_request_summary
GetMachineHealthQuery	get_machine_health

---

MCP Tool Names

MCP tools mirror SDK method names exactly. Tool names are snake_case strings (e.g., create_request, list_templates). The inputSchema for each tool is generated from the CQRS command/query field definitions. See the SDK method names table above for the full list.

MCP tool calls return:

{ "success": true, "data": <sdk result>, "tool": "<tool_name>" }

On error:

{ "error": { "type": "<ExceptionClass>", "message": "...", "tool": "<tool_name>", "arguments": {} } }

---

REST Response Envelope

All REST responses use camelCase keys. Common envelope fields:

Field	Type	Present on
requestId	string	machine request, request status
templateId	string	template create/update/delete
message	string	all write operations
timestamp	ISO 8601 string	all responses
success	boolean	template operations
templates	array	list templates
total_count	integer	list templates
valid	boolean	validate template
validationErrors	array	validate template
validationWarnings	array	validate template

Request status responses are formatted by the active SchedulerPort strategy and their shape varies by scheduler type.