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 17.0 1.6.8.0
Plesk Onyx 17.5 1.6.9.0
Plesk Onyx 17.8 1.6.9.1

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.

Deprecated Protocols, Operators, and Backward Compatibility

Plesk versions up to and including Plesk Onyx 17.5 support several versions of the XML API protocol, including those released earlier. For example, 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.

Starting with Plesk Onyx 17.8, the support for outdated versions of the XML API protocol has been removed. Here is a full list of the XML API protocol versions no longer supported in Plesk Onyx 17.8:

  • 1.1.0
  • 1.2.0
  • 1.3.0
  • 1.3.1
  • 1.3.2
  • 1.3.3
  • 1.3.4
  • 1.4.1
  • 1.4.1.1
  • 1.4.1.2
  • 1.5.0.0
  • 1.5.1.0
  • 1.6.0.0
  • 1.6.0.1
  • 1.6.0.2
  • 1.6.3.1
  • 1.6.3.3

If you use a version of the XML API protocol no longer supported in Plesk Onyx 17.8, we recommend that you switch to the latest XML API protocol version (1.6.9.1).

Note: The versions of the XML API protocol up to and including 1.6.5.0 are deprecated, and may become no longer supported in the future.

No Longer Supported Operators

The support for the following rarely used operators and stub operators was removed in Plesk Onyx 17.8:

Operator
ip-ban
service-node
updater
sitebuilder
webuser
migration
backup-manager
user
role
webmail
maillist
spamfilter
client-template
domain-template
plan-item
siteapp
reseller-template
business-logic-upgrade
Stub Operator
smb
wp-instance
desktop
aps-catalog
sso
migration_agent

The support for the following operators was removed in outdated XML API versions:

Operator XML API version in which the support was removed
client 1.3.5.1-1.4.0.0
subdomain 1.5.2.0-1.6.5.0
ip 1.3.5.1-1.6.3.0
event_log 1.3.5.1-1.6.5.0
dns 1.3.5.1
mail 1.3.5.1-1.6.5.0
certificate 1.3.5.1-1.6.6.0
ui 1.3.5.1-1.6.3.4
secret_key 1.4.0.0-1.6.5.0
domain_alias 1.4.0.0
db_server 1.3.5.1-1.4.2.0
virtdir 1.4.2.0-1.6.5.0
session 1.5.2.0-1.6.5.0
locale 1.5.2.0-1.6.5.0
log-rotation 1.5.2.0-1.6.5.0
protected-dir 1.5.2.0-1.6.8.0
reseller 1.6.2.0
aps 1.6.2.0-1.6.5.0
site 1.6.3.0

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.