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:

 

Plesk version XML API version

Plesk 7.5.4 for Linux/Unix

1.3.5.1

Plesk 7.5.6 for Windows

1.4.0.0

Plesk 8.0 for Linux/Unix | Plesk 7.6 for Windows

1.4.0.0, 1.4.1.0 (updated)

Plesk 7.6.1 for Windows

1.4.1.1

Plesk 8.0.1 for Linux/Unix

1.4.1.2

Plesk 8.1.0 for Linux/Unix | Plesk 8.1.0 for Windows

1.4.2.0

Plesk 8.1.1 for Linux/Unix | Plesk 8.1.1 for Windows

1.5.0.0

Plesk 8.2 for Linux/Unix | Plesk 8.2 for Windows

1.5.1.0

Plesk 8.3 for Linux/Unix | Plesk 8.3 for Windows

1.5.2.0

Plesk 8.4 for Linux/Unix | Plesk 8.6 for Linux/Unix | Plesk 8.4 for Windows | Plesk 8.6 for Windows

1.5.2.1

Plesk 9.0.0

1.6.0.0

Plesk 9.0.1

1.6.0.1

Plesk 9.0.2

1.6.0.2

Plesk 10.0

1.6.3.0

Plesk 10.1

1.6.3.1

Plesk 10.2

1.6.3.2

Plesk 10.3

1.6.3.3

Plesk 10.4

1.6.3.4

Plesk 11.0

1.6.3.5

Plesk 11.1.0

1.6.4.0

Plesk 11.5

1.6.5.0

Plesk 12.0

1.6.6.0

Plesk 12.5

1.6.7.0

Plesk Onyx

1.6.8.0

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 two conceptual 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.

In this chapter:

XML API Packets

Descriptors Overview

GUIDs Overview