In this tutorial, we'll show you how to get started with the ServerPilot API.
The ServerPilot API allows you to write programs that manage servers, apps, system users, and databases on your servers using HTTPS requests. The ServerPilot API is simple and powerful, allowing you to easily retrieve information and execute actions using intuitive URLs and JSON. Any server management action that you can perform through the ServerPilot control panel can also be performed with the API.
Once you've read this article, you'll want to look through our full API documentation.
The first step to using the API is to get your Client ID and generate an API Key. You will use your Client ID and API Key instead of a username and password when making requests to the ServerPilot API.
To find your Client ID and generate an API Key:
Record your Client ID and API Key now. For security purposes, your API Key will not be shown again. If lost, you will need to generate a new API Key.
Remember to keep your API Key secret! It acts like a password. If an API Key becomes compromised, generate a new one to revoke the old key's access.
We will show example API requests using the curl command. This is an easy way to demonstrate the API, though you probably will use PHP or other languages for your API programming.
For all of the examples, we will assign our Client ID and API Key to variables called CLIENTID and APIKEY, respectively. For example, in bash:
export CLIENTID=cid_2398yhfsdfhu3efui3 export APIKEY=asdm29ejfleji3ofneihf9hfdisdhf2hejiwfhsdfsdf
Don't forget to replace the above CLIENTID and APIKEY values with your own.
curl https://api.serverpilot.io/v1/servers \
-u $CLIENTID:$APIKEY
curl https://api.serverpilot.io/v1/apps \
-u $CLIENTID:$APIKEY
curl https://api.serverpilot.io/v1/apps \
-u $CLIENTID:$APIKEY \
-H "Content-Type: application/json" \
-d '{"name": "example", "sysuserid": "RvnwAIfuENyjUVnl", "runtime": "php7.0", "domains": ["example.com", "www.example.com"]}'
Connecting a server is a two-step process. First, you use the ServerPilot API to create a Server ID and Server API Key. Second, you run the ServerPilot installer on your server using that Server ID and Server API Key.
To create the Server ID and Server API Key, you would make the following API request:
curl https://api.serverpilot.io/v1/servers \
-u $CLIENTID:$APIKEY \
-H "Content-Type: application/json" \
-d '{"name": "www2"}'
The response will contain the server's ID and API Key.
Next, you would execute the ServerPilot installer. Detailed steps to do this are shown in the full ServerPilot API Documentation.
By using both ServerPilot's API and your provider's API (for example, the DigitalOcean API), you can fully automate provisioning servers and connecting them to ServerPilot.
API requests, such as "create an app," that perform work on your server return an "actionid" in the response.
{
"actionid": "dIrCNoWunW92lPjw",
"data": { ... }
}
You can use the "actionid" to check the completion status of work being performed on your server for this API request. For example, if your script needs to wait for the app to be fully created so it can begin deploying files to an app's web root directory, you would check the status of the action to determine when the app is fully created on your server.
To check the status of an action, use the following API request (replace the actionid in the URL with the actionid you are checking the status of):
curl https://api.serverpilot.io/v1/actions/dIrCNoWunW92lPjw \
-u $CLIENTID:$APIKEY
Please visit the ServerPilot API Documentation to learn more about how you can use the API to automate server and app management.