About REST API

You interact with Plesk via REST API by sending API requests in the form of HTTP requests. REST API is based on OpenAPI Specification 2.0 (formerly Swagger Specification).

Note: You can use REST API only with Plesk Onyx 17.8 and later. If you are running Plesk Onyx 17.5 or earlier, use XML API instead.

Only the Plesk administrator can use REST API.

There are various tools for working with API requests:

  • API clients, software with a graphical interface for sending and receiving API requests, for example Postman.
  • Command line tools such as curl.
  • Swagger tools.

Regardless of the tool you choose, a typical API request consists of the following components:

  • HTTP method
  • URL
  • Data type
  • Transferred data
  • Authorization methods

Let's look closely at each one of them. 

Next in this section:

1 HTTP method

2 URL

3 Data Type

4 Transferred Data

5 Authentication Methods

6 Examples

Configuring the REST API properties via panel.ini

 

1 HTTP method

Depending on the action you want to perform, you use various HTTP methods in requests:

Method Usage

GET

Retrieves information about the object. Requests using the GET method are read-only and will not affect any of the queried objects.

DELETE

Removes the object from the Plesk server.

PUT

Updates the information about the object.

POST

Creates a new object.

The data specified in the request determines what response you get back. Usually, the response contains a body with the information you have requested and an HTTP status code. The HTTP status code indicates if the request was successful or not. In general, if you receive a 2xx status code, the request was successful. Both 4xx and 5xx status codes mean that there has been an error processing your request. 4xx status codes tell you that the error is on your side (for example, bad syntax of the request), while 5xx status codes mean that the error is on the server’s side.

To choose which HTTP method to use, see the REST API autogenerated reference.

 

2 URL

To communicate with Plesk via REST API, you need to send your API requests to a specific URL. The URL looks like this:

https://<hostname or IP address>:8443/api/v2/<API endpoint>

The API endpoint varies depending on the Plesk object you want to interact with. For example, the API endpoint for Plesk users is /clients.

To see the REST API description, access the following URL:

https://<hostname or IP address>:8443/api/v2/swagger.yml

You can use this URL to generate the API reference.

To learn which API endpoint you need to use, see the REST API autogenerated reference.

 

3 Data Type

Information you send in requests and receive in responses has the form of JSON objects. In each API request, you must declare the content type you transfer in a request and expect in a response via the HTTP headers:

Content-Type: application/json

Accept: application/json

 

4 Transferred Data

With certain API requests, you need to send data in the JSON format inside the request body. For example, to create a customer, you need to post the following request body:

{
  "name": "John Doe",
  "login": "john_doe",
  "password": "password",
  "email": "john@doe.com",
  "company": "Plesk",
  "type": "customer”
}

To see examples of data required by each API request, see the REST API autogenerated reference.

 

5 Authentication Methods

Each REST API request must be authenticated and sent via HTTPS. To authenticate requests, you need to use either basic authentication or API keys. We recommend that you choose API keys because they are more secure.

Basic Authentication

For basic authentication, you need to provide the credentials of one of the following users:

  • The Plesk administrator.
  • (Plesk for Linux) The root user.
  • (Plesk for Windows) The administrator user

You can do it by adding the Authorization HTTP header that contains the word Basic followed by a whitespace character and a base64-encoded string username:password, for example:

Authorization: Basic YWRtaW46c2V0dXA=

Alternatively, if you use curl, you can specify the credentials via the --user or -u option, for example:

--user root:password

API keys

To create an API key, send the POST request with an empty request body {} to the following URL:

https://<hostname or IP address>:8443/api/v2/auth/keys

Note that you need to use basic authentication in the request above to create an API key.

Optionally, while creating an API key, you can provide the following parameters in the request body:

Parameter Description Type

login

The login of a Plesk user who will have the secret key. If the parameter is not specified, the Plesk administrator’s login is used.

string

ip

The IP address that will be linked to an API key. If the parameter is not specified, the IP address of the sender will be used.

string

description

(Optional) Additional information about an API key.

string

For example, to create an API key, you can send the request with the following body:

{
  "login": "administrator",
  "ip": "212.192.122.46",
  "description": "Secret Key"
}

When you have created an API key, pass it with each request instead of basic authentication. To do so, add the X-API-Key: key header:

X-API-Key: 78711059-23bb-cf6f-b07f-985e1995d2e2

Note: The REST API does not allow passing API keys in URL arguments.

Alternatively, you can create an API key using the secret_key utility, for example:

plesk bin secret_key -c -ip-address 10.58.108.104

In the output, you receive the key:

4897e11f-d053-0f83-1ac0-38b3822cfba8

Learn more about the secret_key utility on Linux and Windows.

 

6 Examples

Let’s see how to use REST API on practical examples using the curl command. The IP address of our Plesk server is https://10.58.108.104.

Note: If Plesk is secured with a self-signed or invalid SSL/TLS certificate, use the –k or –insecure options with the curl command to allow insecure SSL connections.

First, we create an API key to use it later for authentication:

curl -X POST --user root:password -H "Content-Type: application/json" -H "Accept: application/json" -d'{}' "https://10.58.108.104:8443/api/v2/auth/keys"

The key was created:

{"key":"5c6f1a8a-1263-7444-24e5-fcfd7b4dcdc6"}

Now we will use this API key to authenticate all following requests. Let’s get a list of all domains hosted on the server:

curl -X GET -H "X-API-Key: 5c6f1a8a-1263-7444-24e5-fcfd7b4dcdc6" -H "Content-Type: application/json" -H "Accept: application/json" "https://10.58.108.104:8443/api/v2/domains"

Then, we add a new customer:

curl -X POST "X-API-Key: 5c6f1a8a-1263-7444-24e5-fcfd7b4dcdc6" -H "Content-Type: application/json" -H "Accept: application/json" -d '{"name":"John Doe","login":"john_doe","password":"password","email":"john@doe.com","type":"customer","company":"Plesk"}'  "https://10.58.108.105:8443/api/v2/clients"

The customer was added:

{"id":2,"guid":"9d4eb47b-817e-4c6b-b0ee-f2b7691986df"}