About XML API

The XML API protocol was designed to support interaction between Plesk and third-party software remotely. To perform an operation through XML API, you should send a specifically-structured HTTP message to a particular Plesk endpoint (https://<your-host-or-IP>:8443/enterprise/control/agent.php). Plesk receives the message, transforms the message into operation instructions, attempts to perform the operations, and returns operation statuses and details. For more information about packets structure and messages transport, see Client-Server Model and XML API Packets.

API errors are generally returned in the language that is selected as default in Plesk. However, not all error messages were translated, so some messages may be returned in English.

Note: The XML API protocol is OS-agnostic. You are free to use it on Plesk for Windows servers and for Linux servers.

Who Can Use XML API

At the moment, the use of the XML API protocol is allowed to Administrator, resellers and customers. These users are provided with programmatic means of managing various Plesk objects they own.

• Administrator is allowed to perform all operations of whatever version of all available protocol versions.
• Resellers have access to a limited number of operations within each particular version of XML API. When using a reseller account, a strict requirement is that the option Ability to use XML API is selected in the reseller subscription properties, on the Permissions tab.
• Customers have access to a limited number of operations within each particular version of XML API. Access to XML API is granted to all customers by default and it cannot be turned off.

Note: You can prohibit access to Plesk through XML API or restrict access by IP addresses. Learn more in the Administrator's Guide, section Restricting Access via XML API.

What Protocol Versions Are in Use

Plesk XML API protocol evolves in sync with Plesk constantly: When new features appear in Plesk, they are implemented in the protocol. Here are the versions of XML API protocol recommended for use with the later versions of Plesk:

Note: Starting from Plesk 12, the version attribute can be omitted. And we strongly recommend that you omit it. In this case, the latest available version will be used. This will help you ensure that your code is operable after switching to a new version of Plesk.

Backward Compatibility

Every version of Plesk supports several versions of XML API that were released with and before this version of Plesk. For instance, Plesk 11.0 supports version 1.6.3.5 of XML API, and it is also compatible with versions 1.6.3.4 and earlier.

GUIDs and Descriptors

XML API guide has twoconceptual topics - GUIDs and descriptors. The first one, GUIDs, concerns identifying objects in Plesk, and the second one defines a way to retrieve currently supported object properties. You should read about them in sections GUIDs Overview and Descriptors Overview to efficiently work with the protocol.

XML API Packets

XML API packet is a simple XML document included in an HTTP message body.

In fact, XML API supports two types of packets:

• request packets - formed by a client-part software and sent to the server.
• response packets - formed by the server and sent to a client. A response packet contains the execution status of the requested operation and can contain an error message if the operation fails.

The request and response packets are organized according to the XSD files corresponding to a certain group of operations.