StoreFront Store Services API

Machine control service

September 26, 2025

Contributed by:

The Machine Control APIs are a set of APIs for managing VDA machines. Using the APIs the client has the ability to:

List machines associated with given resources
Shutdown a specific machine
Power Off a specific machine
Suspend/Hibernate a specific machine

Endpoints Summary

URL	Method	Request content-type	Response content-type	Description
/machinecontrol/list	POST	Resource Ids	Machine list operation result	List machines associated with the given resources
/machinecontrol/poweroff	POST	Machine Id	Machine control operation result	Poweroff the requested machine
/machinecontrol/shutdown	POST	Machine Id	Machine control operation result	Shutdown the requested machine
/machinecontrol/suspend	POST	Machine Id	Machine control operation result	Suspend the requested machine

Machine List API

The machine list API is called using a list of Resource Ids from a prior resource enumeration. Resources with the property canquerymachinestate=true may result in machines being returned in the machine list response, but it is not guaranteed - the resource needs to be an assigned desktop with an underlying power-managed machine.

Details in the machine list response can be used to determine the state of machines, or as input to call other machine control APIs. The power state of machines returned via this API is cached on the server, so may be several minutes out of date.

Request

URL	Method	Request content-type	Response content-type	Description
/machinecontrol/list	POST	application/vnd.citrix.machinecontrolstatusparams+xml	application/vnd.citrix.machinecontrolstatusresult+xml	Returns the machine data (if any) for machines associated with the given Resource Ids

Request Parameters

XML Node / attribute	Type	Description
machinecontrolstatusparams	Top level node	Root document node
machinecontrolstatusparams/resourceids	Array of strings with element name resourceId	The resource identifiers to fetch machine data for.

Note that a maximum of 200 resource Ids can be provided per request.

Example Request

POST http://www.example.com/Citrix/store/machinecontrol/list HTTP/1.1
Accept: application/vnd.citrix.machinecontrolstatusresult+xml
Content-Type: application/vnd.citrix.machinecontrolstatusparams+xml
Authorization: CitrixAuth H4sIAAAA.....
Citrix-TransactionId: d7f9bf67-1fdf-4e88-897d-3f30a259bd4b
Host: www.example.com
Content-Length: 400
<?xml version="1.0" encoding="utf-8"?>
<machinecontrolstatusparams xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://citrix.com/delivery-services/1-0/machinecontrolstatusparams">
  <resourceids>
    <resourceid>Controller.Desktop 1</resourceid>
    <resourceid>Controller.Desktop 2</resourceid>
  </resourceids>
</machinecontrolstatusparams>
<!--NeedCopy-->

Response

Response code	Response Format	Content-Type header	Description
200	XML Machine control status response	application/vnd.citrix.machinecontrolstatusresult+xml	Success
401			Bad/Missing security token (see CitrixAuth Authentication Scheme document [3] )

The response XML is part of the http://citrix.com/delivery-services/2-0/machinecontrol namespace.

XML Node / attribute	Type	Description
machinecontrolstatusresult	Top level node	Root document node
machinecontrolstatusresult: status	string	Overall result of the operation - success or failure
machinecontrolstatusresult/errorid	string	Only set when the overall result of the operation is failure
machinecontrolstatusresult/machinestatus	Array of status elements	Holds information about a machine.
status/machineid	string	Identifier for machine used with other APIs.
status/resourceid	string	Identifier for resource used in the request machinecontrolstatusparams.
status/maxLastUpdatedTime	string	Timestamp indicating the time when the power state could have last been updated.
status/machinedata	machinedata	Element holding data describing the machine’s current state.
status/machinedata/lastUpdatedTime	string	The timestamp of the time when the data was last updated.
status/machinedata/machineId	string	This is the ID used with the machine control APIs
status/machinedata/machineName	string	The hostname of the machine
status/machinedata/registrationState	string	The VDA registration status. “Registered”, “Unregistered”,”Initializing”, “AgentError”
status/machinedata/powerState	string	The power state of the machine. Typically “Unmanaged” or “On” unless transitioning from VM hibernation. Possible values are “Unmanaged”,”Unknown”,”Unavailable”,”Off”,”On”,”Suspended”,”TurningOn”,”TurningOff”,”Suspending”,”Resuming”,”NotSupported”,”VirtualMachineNotFound”
status/machinedata/sessionSupport	string	Whether the VDA is a “SingleSession” VDI worker or a “MultiSession” capable RDS server
status/machinedata/suspendSupported	string	Whether the machine supports hibernation. “true” or “false”
status/machinedata/shutDownSupported	string	Whether the client may shut down the host machine. “true” or “false”
status/machinedata/turnOffSupported	string	Whether the client may power off the host machine. “true” or “false”
status/machinedata:poweractioninprogress	string	Whether a power action is in progress on the machine. “true” or “false”

Example Response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Pragma: no-cache
Content-Type: application/vnd.citrix.machinecontrolstatusresult+xml
Expires: -1
Server: Microsoft-IIS/10.0
Date: Thu, 23 Nov 2023 16:50:14 GMT
Content-Length: 1131
<?xml version="1.0" encoding="utf-8"?>
<machinecontrolstatusresult status="success" xmlns="http://citrix.com/delivery-services/1-0/machinecontrolstatusresult">
  <machinestatus>
    <status>
      <machineid>Controller.S-1-5-21-3729792978-2641905665-2579007459-1105</machineid>
      <resourceid>Controller.Desktop 1</resourceid>
      <maxLastUpdatedTime>2025-09-24T09:25:07.9586903Z</maxLastUpdatedTime>
      <machinedata>
        <lastUpdatedTime>2025-09-24T09:25:54.2998305Z</lastUpdatedTime>
        <machinename>CVAD-01</machinename>
        <machineid>Controller.S-1-5-21-3729792978-2641905665-2579007459-1105</machineid>
        <registrationstate>Registered</registrationstate>
        <powerstate>On</powerstate>
        <sessionsupport>SingleSession</sessionsupport>
        <shutdownsupported>true</shutdownsupported>
        <turnoffsupported>true</turnoffsupported>
        <suspendsupported>true</suspendsupported>
        <poweractioninprogress>false</poweractioninprogress>
      </machinedata>
    </status>
  </machinestatus>
</machinecontrolstatusresult>
<!--NeedCopy-->

Machine Shutdown, PowerOff And Suspend APIs

The machine shutdown, power off and suspend APIs use a similar API protocol that only differs by endpoint URL path.

The shutdown API is called for the single machine with a machineId returned from a prior machinecontrol/list or usersessions/list request. Note that shutting down a machine may take a long time to finish as it is dependent on the underlying operating system completing the shutdown request.

The PowerOff API uses a similar protocol to the shutdown API but will cause the machine to be powered off without a graceful OS shutdown.

The Suspend API uses a similar protocol to the shutdown API but will cause the machine to be placed in stand-by.

If the response contains a continuationToken then the API should be polled with the token so the caller can tell when the operation has completed.

Request

URL	Method	Request content-type	Response content-type	Description
/machinecontrol/shutdown	POST	application/vnd.citrix.machinecontroloperationparams+xml	application/vnd.citrix.machinecontroloperation+xml	Shutdown the requested machine
/machinecontrol/poweroff	POST	application/vnd.citrix.machinecontroloperationparams+xml	application/vnd.citrix.machinecontroloperation+xml	Poweroff the requested machine
/machinecontrol/suspend	POST	application/vnd.citrix.machinecontroloperationparams+xml	application/vnd.citrix.machinecontroloperation+xml	Suspend the requested machine

Request Parameters

XML Node / attribute	Type	Description
machinecontroloperationparams	Top level node	Root document node
machinecontroloperationparams/machineid	string	The machine identifier to perform the operation on
machinecontroloperationparams/continuationToken	string	The continuation token returned as the continuationid in a prior API response.

Note that machineid and continuationToken are mutually exclusive options.

Example Request

POST http://www.example.com/Citrix/store/machinecontrol/shutdown HTTP/1.1
Accept: application/vnd.citrix.machinecontroloperation+xml
Content-Type: application/vnd.citrix.machinecontroloperationparams+xml
Authorization: CitrixAuth H4sIAAAA.....
Citrix-TransactionId: d7f9bf67-1fdf-4e88-897d-3f30a259bd4b
Host: www.example.com
Content-Length: 489
<!--NeedCopy-->

Machine identifier request payload

<?xml version="1.0" encoding="utf-8"?>
<machinecontroloperationparams xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://citrix.com/delivery-services/1-0/machinecontroloperationparams">
  <machineid>Controller.S-1-5-21-3729792978-2641905665-2579007459-1105</machineid>
</machinecontroloperationparams>
<!--NeedCopy-->

Continuation request payload

<?xml version="1.0" encoding="utf-8"?>
<machinecontroloperationparams xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://citrix.com/delivery-services/1-0/machinecontroloperationparams">
  <continuationToken>c4068ad9-e9f2-48c3-9c1e-d6ae87006e7e.3621</continuationToken>
</machinecontroloperationparams>
<!--NeedCopy-->

Response

The API calling pattern is an initial request or continuation request which results in a response with a payload containing:

isSuccess is true indicating success
isSuccess is empty and the continuationid not empty indicating a slow operation that needs to be polled with the continuation request variant.
isSuccess is empty and errorid is non empty indicating a failure.

Response Parameters

XML Node / attribute	Type	Description
machinecontroloperation	Top level node	Root document node
machinecontroloperation/status	string	“Success” or “Failure” at processing the request.
machinecontroloperation/actionstatus	string	This is the status of the possibly ongoing operation. One of “Pending”, “Started”, “Completed”, “Failed”, “Canceled”, “Deleted”, “Lost”
machinecontroloperation/isSuccess	string	If “true” the operation has completed and was successful. Otherwise empty or failure has occurred
machinecontroloperation/continuationid	string	If set then delay and re-poll the API with this continuationToken set in the request
machinecontroloperation/errorvalue	string	A description of the error
machinecontroloperation/errorid	string	The error ID
machinecontroloperation/retrydelayhint	int	This is obsolete. Use appropriate client logic for back off and retry polling to check the operation status

Example Response

HTTP/1.1 200 OK Cache-Control: no-cache, no-store Pragma: no-cache Content-Type: application/vnd.citrix.machinecontroloperation+xml Expires: -1 Server: Microsoft-IIS/10.0 Date: Thu, 23 Nov 2023 17:06:57 GMT Content-Length: 371

Successful operation completed response:

<?xml version="1.0" encoding="utf-8"?>
<machinecontroloperation xmlns="http://citrix.com/delivery-services/1-0/machinecontroloperation">
  <status>Success<status/>
  <actionstatus>Completed<actionstatus/>
  <isSuccess>true<isSuccess/>
  <continuationid><continuationid/>
  <errorvalue><errorvalue/>
  <retrydelayhint><retrydelayhint/>  
<machinecontroloperation/>
<!--NeedCopy-->

Operation in progress response:

<?xml version="1.0" encoding="utf-8"?>
<machinecontroloperation xmlns="http://citrix.com/delivery-services/1-0/machinecontroloperation">
  <status>Success<status/>
  <actionstatus>Pending<actionstatus/>
  <isSuccess><isSuccess/>
  <continuationid>c4068ad9-e9f2-48c3-9c1e-d6ae87006e7e.3621<continuationid/>
  <errorvalue><errorvalue/>
  <retrydelayhint>30<retrydelayhint/>  
<machinecontroloperation/>
<!--NeedCopy-->

Operation failed response:

<?xml version="1.0" encoding="utf-8"?>
<machinecontroloperation xmlns="http://citrix.com/delivery-services/1-0/machinecontroloperation">
  <status>Failure<status/>
  <actionstatus>Started<actionstatus/>
  <isSuccess><isSuccess/>
  <continuationid><continuationid/>
  <errorid>13<errorid/>
  <errorvalue><errorvalue/>
  <retrydelayhint><retrydelayhint/>  
<machinecontroloperation/>
<!--NeedCopy-->

An unknown machineid or continuationId was provided:

HTTP/1.1 404 OK
X-Citrix-Error-Reason: Machine not found with requested machineid or continuationId
Cache-Control: no-cache, no-store
Pragma: no-cache
Expires: -1
Server: Microsoft-IIS/10.0
Date: Thu, 23 Nov 2023 17:06:57 GMT
<!--NeedCopy-->

An invalid format machineid or continuationId was supplied:

HTTP/1.1 400 OK
X-Citrix-Error-Reason: Invalid machineId or continuationId supplied
Cache-Control: no-cache, no-store
Pragma: no-cache
Expires: -1
Server: Microsoft-IIS/10.0
Date: Thu, 23 Nov 2023 17:06:57 GMT
<!--NeedCopy-->

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Machine control service

September 26, 2025

Contributed by:

September 26, 2025

Contributed by:

Machine control service

Endpoints Summary

Machine List API

Request

Request Parameters

Example Request

Response

Example Response

Machine Shutdown, PowerOff And Suspend APIs

Request

Request Parameters

Example Request

Response

Response Parameters

Example Response

In this article