├── CHANGELOG.md └── README.md /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | ## 2020-08-05 4 | 5 | - Added SSH key management. 6 | 7 | ## 2018-07-18 8 | 9 | - Added server creation `enable_ssh_password_auth` option. 10 | 11 | ## 2018-07-10 12 | 13 | - Added server `plan` field. 14 | 15 | ## 2018-04-19 16 | 17 | - Added server `available_runtimes` field. 18 | 19 | ## 2017-10-09 20 | 21 | - Added PHP 7.2 runtime. 22 | 23 | ## 2017-07-19 24 | 25 | - Added server `deny_unknown_domains` field. 26 | 27 | ## 2016-08-30 28 | 29 | - Added `datecreated` field to app information in responses. 30 | 31 | ## 2016-08-23 32 | 33 | - Passwords cannot be longer than 200 characters. 34 | 35 | ## 2016-08-11 36 | 37 | - Added AutoSSL and ForceSSL management. 38 | 39 | ## 2016-07-29 40 | 41 | - Added PHP 7.1 runtime. 42 | 43 | ## 2015-08-21 44 | 45 | - Added PHP 7.0 runtime. 46 | - Clarified `actionid` only available in response if server configuration required. 47 | 48 | ## 2014-09-03 49 | 50 | - Added references to PHP 5.6 51 | 52 | ## 2014-08-26 53 | 54 | - Tried to define more clearly what the steps are to connecting a new server 55 | to ServerPilot. 56 | 57 | ## 2014-08-22 58 | 59 | - Reformatted curl commands to appear to use environment variables. Replace 60 | '{CLIENTID}:{APIKEY}' with '$CLIENTID:$APIKEY'. 61 | - Document possible HTTP status codes. 62 | - Document structure of JSON object in body of 4xx and 5xx responses. 63 | - Document validation policies for `name` and `password` fields. 64 | 65 | ## 2014-07-24 66 | 67 | - Added some clarification to the "Update an App" section. Add and remove 68 | operations for the `domains` array are not supported. You must provide the 69 | *complete* list of domains on any update to the `domains` field. 70 | 71 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # ServerPilot API v1.0 2 | 3 | The ServerPilot API is RESTful and allows you to manage ServerPilot resources 4 | using HTTP requests. All responses return JSON objects, including errors. 5 | 6 | ## Authentication 7 | 8 | The ServerPilot API supports authentication through Basic Auth. You must provide 9 | your `client_id` and API `key`. All requests require authentication. 10 | 11 | You can manage your API credentials from your 12 | [account](https://manage.serverpilot.io/#account). 13 | 14 | Only one API key is active at a time. Take care to keep your API key secret! 15 | 16 | 17 | ## Base URL 18 | 19 | To ensure data privacy, all API requests must be made over HTTPS. Unencrypted 20 | requests made over plain HTTP are not supported. 21 | 22 | ``` 23 | https://api.serverpilot.io/v1 24 | ``` 25 | 26 | ## HTTP Status Code Summary 27 | 28 | **200 OK** - Everything worked as expected. 29 | 30 | **400 Bad Request** - We couldn't understand your request. Typically missing a parameter or header. 31 | 32 | **401 Unauthorized** - Either no authentication credentials were provided or they are invalid. 33 | 34 | **402 Payment Required** - Account does not have a valid credit card on file. 35 | 36 | **403 Forbidden** - Typically when trying to alter or delete protected resources. 37 | 38 | **404 Not Found** - You requested a resource that does not exist. 39 | 40 | **409 Conflict** - Typically when trying creating a resource that already exists. 41 | 42 | **500 Server Error** - Something unexpected happened on ServerPilot's end. 43 | 44 | 45 | ### Errors 46 | 47 | When you a receive a response with a status code in the 4xx or 5xx range, you'll receive a JSON object in the body with details. The object will have a `error` and `message` key, like so: 48 | 49 | ``` 50 | { 51 | "error": { 52 | "message": "Password must be at least 8 characters." 53 | } 54 | } 55 | ``` 56 | 57 | ### Limits 58 | 59 | There is no limit to the number of servers on an account. 60 | 61 | Each account can have at most 1000 SSH keys. 62 | 63 | Each server can have at most 1000 system users. 64 | 65 | Each system user can have at most 1000 apps and 100 SSH keys. 66 | 67 | Each app can have at most 300 domains and 1000 databases. 68 | 69 | 70 | # Resources & Methods 71 | 72 | **Servers** 73 | 74 | * [List All Servers](#list-all-servers) 75 | * [Connect a New Server](#connect-a-new-server) 76 | * [Retrieve an Existing Server](#retrieve-an-existing-server) 77 | * [Delete a Server](#delete-a-server) 78 | * [Update a Server](#update-a-server) 79 | 80 | **SSH Keys** 81 | 82 | * [List SSH Keys](#list-ssh-keys) 83 | * [Add an SSH Key](#add-an-ssh-key) 84 | * [Retrieve an Existing SSH Key](#retrieve-an-existing-ssh-key) 85 | * [Rename an SSH Key](#rename-an-ssh-key) 86 | * [Delete an SSH Key](#delete-an-ssh-key) 87 | 88 | **System Users** 89 | 90 | * [List All System Users](#list-all-system-users) 91 | * [Create a System User](#create-a-system-user) 92 | * [Change the Password of a System User](#change-the-password-of-a-system-user) 93 | * [Retrieve an Existing System User](#retrieve-an-existing-system-user) 94 | * [Add an SSH Key to a System User](#add-an-ssh-key-to-a-system-user) 95 | * [Remove an SSH Key from a System User](#remove-an-ssh-key-from-a-system-user) 96 | * [List SSH Keys of a System User](#list-ssh-keys-of-a-system-user) 97 | * [Delete a System User](#delete-a-system-user) 98 | * [Update a System User](#update-a-system-user) 99 | 100 | **Apps** 101 | 102 | * [List All Apps](#list-all-apps) 103 | * [Create an App](#create-an-app) 104 | * [Get Details of an App](#get-details-of-an-app) 105 | * [Delete an App](#delete-an-app) 106 | * [Update an App](#update-an-app) 107 | * [Add a Custom SSL Cert](#add-a-custom-ssl-cert) 108 | * [Enable AutoSSL](#enable-autossl) 109 | * [Delete a Custom SSL Cert or Disable AutoSSL](#delete-a-custom-ssl-cert-or-disable-autossl) 110 | * [Enable or Disable ForceSSL](#enable-or-disable-forcessl) 111 | 112 | **Databases** 113 | 114 | * [List All Databases](#list-all-databases) 115 | * [Create a Database](#create-a-database) 116 | * [Retrieve an Existing Database](#retrieve-an-existing-database) 117 | * [Delete a Database](#delete-a-database) 118 | * [Update a Database User Password](#update-a-database-user-password) 119 | 120 | **Actions** 121 | 122 | * [Check the Status of an Action](#check-the-status-of-an-action) 123 | 124 | ## Servers 125 | 126 | Servers are 64-bit Ubuntu LTS systems, such Ubuntu 14.04, that are managed by 127 | ServerPilot. 128 | 129 | Every App, Database, and System User is related to a Server. By default, all 130 | Servers will have a `serverpilot` System User. 131 | 132 | ### List All Servers 133 | ```GET /servers``` 134 | 135 | ``` 136 | $ curl https://api.serverpilot.io/v1/servers \ 137 | -u $CLIENTID:$APIKEY 138 | ``` 139 | 140 | ```json 141 | { 142 | "data": [ 143 | { 144 | "id": "FqHWrrcUfRI18F0l", 145 | "name": "www1", 146 | "plan": "economy", 147 | "autoupdates": true, 148 | "firewall": true, 149 | "deny_unknown_domains": true, 150 | "available_runtimes": ["php5.6", "php7.0", "php7.1", "php7.2"], 151 | "lastaddress": "1.2.3.4", 152 | "lastconn": 1403130552, 153 | "datecreated": 1403130551 154 | }, { 155 | "id": "4zGDDO2xg30yEeum", 156 | "name": "www3", 157 | "plan": "business", 158 | "autoupdates": true, 159 | "firewall": true, 160 | "deny_unknown_domains": true, 161 | "available_runtimes": ["php5.6", "php7.0", "php7.1", "php7.2"], 162 | "lastaddress": "1.2.3.4", 163 | "lastconn": 1403130554, 164 | "datecreated": 1403130553 165 | }] 166 | } 167 | ``` 168 | 169 | ### Connect a New Server 170 | 171 | Use this method to tell ServerPilot that you plan to connect a new server. 172 | 173 | Once you have the `id` and `apikey`, you'll need to: 174 | 175 | * download the `serverpilot-installer` script, and 176 | * run the script with the values specific to your server. 177 | 178 | If you were to manually log in to your server and do this, it would look like: 179 | 180 | ``` 181 | $ export SERVERID=JvFFIQn2WV8VHDsP 182 | $ export SERVERAPIKEY=4lW87naDckYJq1carYffSAwBISa0wfVp5TYh3m3fQSA 183 | $ sudo apt-get update && sudo apt-get -y install wget ca-certificates && \ 184 | sudo wget -nv -O serverpilot-installer https://download.serverpilot.io/serverpilot-installer && \ 185 | sudo sh serverpilot-installer \ 186 | --server-id=$SERVERID \ 187 | --server-apikey=$SERVERAPIKEY 188 | ``` 189 | 190 | ServerPilot will install Nginx, Apache, PHP, and MySQL. You can just sit back and relax. 191 | 192 | 193 | ```POST /servers``` 194 | 195 | | Name | Type | Description 196 | | ------ | :------: | :--------------------------------------- 197 | | `name` | `string` | **Required**. The nickname of the Server. Length must be between 1 and 255 characters. Characters can be of lowercase ascii letters, digits, a period, or a dash ('abcdefghijklmnopqrstuvwxyz0123456789-'), but must start with a lowercase ascii letter and end with either a lowercase ascii letter or digit. `www.store2` is a valid name, while `.org.company` nor `www.blog-` are. 198 | | `plan` | `string` | The plan the server is on. Must be either `economy`, `business`, or `first_class`. If not specified, defaults to `economy`. 199 | | `enable_ssh_password_auth` | `bool` | If `true`, password authentication for SSH/SFTP logins is enabled when the server is being initially configured by ServerPilot. If `false`, has no effect (does not disable passwored authentication). Defaults to `false`. 200 | 201 | ``` 202 | $ curl https://api.serverpilot.io/v1/servers \ 203 | -u $CLIENTID:$APIKEY \ 204 | -H "Content-Type: application/json" \ 205 | -d '{"name": "www2"}' 206 | ``` 207 | 208 | ```json 209 | { 210 | "actionid": "tW2fu4hjHnsix6Rn", 211 | "data": 212 | { 213 | "id": "UXOSIYrdtL4cSGp3", 214 | "name": "www2", 215 | "plan": "economy", 216 | "autoupdates": true, 217 | "firewall": true, 218 | "deny_unknown_domains": true, 219 | "available_runtimes": ["php5.6", "php7.0", "php7.1", "php7.2"], 220 | "lastaddress": null, 221 | "lastconn": null, 222 | "datecreated": 1403130553, 223 | "apikey": "nqXUevYSkpW09YKy7CY7PdnL14Q1HIlAfniJZwzjqNQ" 224 | } 225 | } 226 | ``` 227 | 228 | ### Retrieve an Existing Server 229 | ```GET /servers/:id``` 230 | 231 | ``` 232 | $ curl https://api.serverpilot.io/v1/servers/UXOSIYrdtL4cSGp3 \ 233 | -u $CLIENTID:$APIKEY \ 234 | ``` 235 | 236 | ```json 237 | { 238 | "data": 239 | { 240 | "id": "UXOSIYrdtL4cSGp3", 241 | "name": "www2", 242 | "plan": "economy", 243 | "autoupdates": true, 244 | "firewall": true, 245 | "deny_unknown_domains": true, 246 | "available_runtimes": ["php5.6", "php7.0", "php7.1", "php7.2"], 247 | "lastaddress": "1.2.3.4", 248 | "lastconn": 1403130554, 249 | "datecreated": 1403130553 250 | } 251 | } 252 | ``` 253 | 254 | ### Delete a Server 255 | ```DELETE /servers/:id``` 256 | 257 | ``` 258 | $ curl https://api.serverpilot.io/v1/servers/4zGDDO2xg30yEeum \ 259 | -u $CLIENTID:$APIKEY \ 260 | -X DELETE 261 | ``` 262 | 263 | ```json 264 | { 265 | "data": {} 266 | } 267 | ``` 268 | 269 | ### Update a Server 270 | ```POST /servers/:id``` 271 | 272 | | Name | Type | Description 273 | | ---------------------- | :------: | :--------------------------------------- 274 | | `plan` | `string` | The plan the server is on. Must be either `economy`, `business`, or `first_class`. 275 | | `firewall` | `bool` | Describes the "enabled" state of the server's firewall. `false` means the firewall is not enabled. 276 | | `autoupdates` | `bool` | Describes the "enabled" state of automatic system updates. `false` means automatic system updates are not enabled. 277 | | `deny_unknown_domains` | `bool` | Whether requests for domains not associated with any app are denied (`true`) or are sent to the default app (`false`). 278 | 279 | ``` 280 | $ curl https://api.serverpilot.io/v1/servers/UXOSIYrdtL4cSGp3 \ 281 | -u $CLIENTID:$APIKEY \ 282 | -H "Content-Type: application/json" \ 283 | -d '{"firewall": false}' 284 | ``` 285 | 286 | ```json 287 | { 288 | "actionid": "g3kiiYzxPgAjbwcY", 289 | "data": 290 | { 291 | "id": "UXOSIYrdtL4cSGp3", 292 | "name": "www2", 293 | "plan": "economy", 294 | "autoupdates": true, 295 | "firewall": false, 296 | "deny_unknown_domains": true, 297 | "lastaddress": "1.2.3.4", 298 | "available_runtimes": ["php5.6", "php7.0", "php7.1", "php7.2"], 299 | "lastconn": 1403130554, 300 | "datecreated": 1403130553 301 | } 302 | } 303 | ``` 304 | 305 | ## SSH Keys 306 | 307 | SSH Keys are managed account-wide. Once an SSH Key is added to your account, 308 | it can be assigned to one or more System Users. 309 | 310 | ### List SSH Keys 311 | ```GET /sshkeys``` 312 | 313 | ``` 314 | $ curl https://api.serverpilot.io/v1/sshkeys \ 315 | -u $CLIENT_ID:$API_KEY 316 | ``` 317 | 318 | ```json 319 | { 320 | "data": [ 321 | { 322 | "id": "aUAG0Z3p0F3xmc6R", 323 | "name": "joe's key", 324 | "sha256_fingerprint": "SHA256:...", 325 | "public_key": "ssh-rsa ...", 326 | "datecreated": 1403139066 327 | }, 328 | { 329 | "id": "QecKhpb14kk2a6H3", 330 | "name": "jenny's key", 331 | "sha256_fingerprint": "SHA256:...", 332 | "public_key": "ssh-rsa ...", 333 | "datecreated": 1403139067 334 | } 335 | ] 336 | } 337 | ``` 338 | 339 | ### Add an SSH Key 340 | ```POST /sshkeys``` 341 | 342 | The public key must be a string in the format: 343 | 344 | KEY_TYPE PEM_ENCODED_KEY OPTIONAL_COMMENT 345 | 346 | This is the same format as the contents of a `.pub` file created with the 347 | `ssh-keygen` command. 348 | 349 | The `KEY_TYPE` must be either `ssh-rsa` or `ssh-ed25519`. 350 | 351 | | Name | Type | Description 352 | | ------------ | :------: | :--------------------------------------- 353 | | `name` | `string` | **Required**. The name of the SSH Key. Length must be between 1 and 50 characters. Characters can be any printable character other than `<`, `>`, and `"`. 354 | | `public_key` | `string` | **Required**. The public key to add. 355 | 356 | ``` 357 | $ curl https://api.serverpilot.io/v1/sshkeys \ 358 | -u $CLIENT_ID:$API_KEY \ 359 | -H "Content-Type: application/json" \ 360 | -d '{"name": "joe's key", "public_key": "ssh-rsa ..."}' 361 | ``` 362 | 363 | ```json 364 | { 365 | "data": 366 | { 367 | "id": "aUAG0Z3p0F3xmc6R", 368 | "name": "joe's key", 369 | "sha256_fingerprint": "SHA256:...", 370 | "public_key": "ssh-rsa ...", 371 | "datecreated": 1403139066 372 | } 373 | } 374 | ``` 375 | 376 | ### Retrieve an Existing SSH Key 377 | ```GET /sshkeys/:id``` 378 | 379 | Returns the SSH Key's details in addition to a list of System Users using this 380 | SSH Key. 381 | 382 | ``` 383 | $ curl https://api.serverpilot.io/v1/sshkeys/aUAG0Z3p0F3xmc6R \ 384 | -u $CLIENT_ID:$API_KEY 385 | ``` 386 | 387 | ```json 388 | { 389 | "data": 390 | { 391 | "id": "aUAG0Z3p0F3xmc6R", 392 | "name": "joe's key", 393 | "sha256_fingerprint": "SHA256:...", 394 | "public_key": "ssh-rsa ...", 395 | "datecreated": 1403139066, 396 | "sysusers": [ 397 | { 398 | "id": "PdmHhsb3fnaZ2r5f", 399 | "name": "serverpilot", 400 | "serverid": "FqHWrrcUfRI18F0l", 401 | "datecreated": 1403084618 402 | }, 403 | { 404 | "id": "RvnwAIfuENyjUVnl", 405 | "name": "serverpilot", 406 | "serverid": "FqHWrrcUfRI18F0l", 407 | "datecreated": 1402875948 408 | } 409 | ] 410 | } 411 | } 412 | ``` 413 | 414 | ### Rename an SSH Key 415 | ```POST /sshkeys/:id``` 416 | 417 | | Name | Type | Description 418 | | ------ | :------: | :---------- 419 | | `name` | `string` | **Required**. The new name of the SSH Key. Length must be between 1 and 50 characters. Characters can be any printable character other than `<`, `>`, and `"`. 420 | 421 | ``` 422 | $ curl https://api.serverpilot.io/v1/sshkeys/RvnwAIfuENyjUVnl \ 423 | -u $CLIENT_ID:$API_KEY \ 424 | -H "Content-Type: application/json" \ 425 | -d '{"name": "new name for joe's key"}' 426 | ``` 427 | 428 | ```json 429 | { 430 | "data": 431 | { 432 | "id": "aUAG0Z3p0F3xmc6R", 433 | "name": "new name for joe's key", 434 | "sha256_fingerprint": "SHA256:...", 435 | "public_key": "ssh-rsa ...", 436 | "datecreated": 1403139066 437 | } 438 | } 439 | ``` 440 | 441 | ### Delete an SSH Key 442 | ```DELETE /sshkeys/:id``` 443 | 444 | Delete an SSH Key so that it will no longer be available for assignment to 445 | System Users. 446 | 447 | An SSH Key can't be deleted if it is currently in use by any System Users. 448 | 449 | ``` 450 | $ curl https://api.serverpilot.io/v1/sshkeys/aUAG0Z3p0F3xmc6R \ 451 | -u $CLIENT_ID:$API_KEY \ 452 | -X DELETE 453 | ``` 454 | 455 | ```json 456 | { 457 | "data": {} 458 | } 459 | ``` 460 | 461 | ## System Users 462 | 463 | System Users are Linux user accounts that ServerPilot creates on your Server. 464 | Every App belongs to and runs as one of these System Users. You can log in to 465 | your Server as a System User via SSH to deploy an App or view an App's log 466 | files. 467 | 468 | By default, ServerPilot creates the `serverpilot` System User. 469 | 470 | The home directory of each System User created by ServerPilot is 471 | 472 | ``` 473 | /srv/users/USERNAME 474 | ``` 475 | 476 | Under the System User's home directory are additional directories: 477 | 478 | * `apps` — each app has its own directory under here. 479 | * `log` — each app has its log files here. 480 | 481 | ### List All System Users 482 | ```GET /sysusers``` 483 | 484 | ``` 485 | $ curl https://api.serverpilot.io/v1/sysusers \ 486 | -u $CLIENTID:$APIKEY 487 | ``` 488 | 489 | ```json 490 | { 491 | "data": [ 492 | { 493 | "id": "PdmHhsb3fnaZ2r5f", 494 | "name": "serverpilot", 495 | "serverid": "FqHWrrcUfRI18F0l" 496 | }, 497 | { 498 | "id": "RvnwAIfuENyjUVnl", 499 | "name": "serverpilot", 500 | "serverid": "4zGDDO2xg30yEeum" 501 | }] 502 | } 503 | ``` 504 | 505 | ### Create a System User 506 | ```POST /sysusers``` 507 | 508 | | Name | Type | Description 509 | | ----------- | :------: | :--------------------------------------- 510 | | `serverid` | `string` | **Required**. The id of the Server. 511 | | `name` | `string` | **Required**. The name of the System User. Length must be between 3 and 32 characters. Characters can be of lowercase ascii letters, digits, or a dash ('abcdefghijklmnopqrstuvwxyz0123456789-'), but must start with a lowercase ascii letter. `user-32` is a valid name, while `3po` is not. 512 | | `password` | `string` | The password of the System User. If user has no password, they will not be able to SSH/SFTP in with a password. No leading or trailing whitespace is allowed and the password must be at least 8 and no more than 200 characters long. 513 | | `sshkey_id` | `string` | The id of an SSH Key to add to the System User. If the user does not have an SSH Key, they will not be able to SSH/SFTP in using public key authentication. 514 | 515 | ``` 516 | $ curl https://api.serverpilot.io/v1/sysusers \ 517 | -u $CLIENTID:$APIKEY \ 518 | -H "Content-Type: application/json" \ 519 | -d '{"serverid": "FqHWrrcUfRI18F0l", "name": "derek", "password": "hlZkUk"}' 520 | ``` 521 | 522 | ```json 523 | { 524 | "actionid": "nnpgQoNzSK11fuTe", 525 | "data": 526 | { 527 | "id": "PPkfc1NECzvwiEBI", 528 | "name": "derek", 529 | "serverid": "FqHWrrcUfRI18F0l" 530 | } 531 | } 532 | ``` 533 | 534 | ### Change the Password of a System User 535 | ```POST /sysusers/:id``` 536 | 537 | | Name | Type | Description 538 | | ---------- | :------: | :---------- 539 | | `password` | `string` | **Required**. The new password of the System User. If user has no password, they will not be able to log in with a password. No leading or trailing whitespace is allowed and the password must be at least 8 and no more than 200 characters long. 540 | 541 | ``` 542 | $ curl https://api.serverpilot.io/v1/sysusers/RvnwAIfuENyjUVnl \ 543 | -u $CLIENT_ID:$API_KEY \ 544 | -H "Content-Type: application/json" \ 545 | -d '{"password": "2short"}' 546 | ``` 547 | 548 | ```json 549 | { 550 | "actionid": "OF42xCWkKcaX3qG2", 551 | "data": 552 | { 553 | "id": "RvnwAIfuENyjUVnl", 554 | "name": "serverpilot", 555 | "serverid": "4zGDDO2xg30yEeum" 556 | } 557 | } 558 | ``` 559 | 560 | ### Retrieve an Existing System User 561 | ```GET /sysusers/:id``` 562 | 563 | ``` 564 | $ curl https://api.serverpilot.io/v1/sysusers/PPkfc1NECzvwiEBI \ 565 | -u $CLIENTID:$APIKEY 566 | ``` 567 | 568 | ```json 569 | { 570 | "data": 571 | { 572 | "id": "PPkfc1NECzvwiEBI", 573 | "name": "derek", 574 | "serverid": "FqHWrrcUfRI18F0l" 575 | } 576 | } 577 | ``` 578 | 579 | ### Delete a System User 580 | ```DELETE /sysusers/:id``` 581 | 582 | **Warning**: Deleting a System User will delete all Apps (and Databases) 583 | associated. 584 | 585 | ``` 586 | $ curl https://api.serverpilot.io/v1/sysusers/PPkfc1NECzvwiEBI \ 587 | -u $CLIENTID:$APIKEY \ 588 | -X DELETE 589 | ``` 590 | 591 | ```json 592 | { 593 | "actionid": "9tvygrrXZulYuizz", 594 | "data": {} 595 | } 596 | ``` 597 | 598 | ### Update a System User 599 | ```POST /sysusers/:id``` 600 | 601 | 602 | | Name | Type | Description 603 | | ---------- | :------: | :---------- 604 | | `password` | `string` | **Required**. The new password of the System User. If user has no password, they will not be able to log in with a password. No leading or trailing whitespace is allowed and the password must be at least 8 and no more than 200 characters long. 605 | 606 | ``` 607 | $ curl https://api.serverpilot.io/v1/sysusers/RvnwAIfuENyjUVnl \ 608 | -u $CLIENTID:$APIKEY \ 609 | -H "Content-Type: application/json" \ 610 | -d '{"password": "mRak7S"}' 611 | ``` 612 | 613 | ```json 614 | { 615 | "actionid": "OF42xCWkKcaX3qG2", 616 | "data": 617 | { 618 | "id": "RvnwAIfuENyjUVnl", 619 | "name": "serverpilot", 620 | "serverid": "4zGDDO2xg30yEeum" 621 | } 622 | } 623 | ``` 624 | 625 | ### Add an SSH Key to a System User 626 | ```POST /sysusers/:id/sshkeys``` 627 | 628 | | Name | Type | Description 629 | | ----------- | :------: | :---------- 630 | | `sshkey_id` | `string` | **Required**. The id of the SSH Key to add to this System User. 631 | 632 | ``` 633 | $ curl https://api.serverpilot.io/v1/sysusers/RvnwAIfuENyjUVnl/sshkeys \ 634 | -u $CLIENT_ID:$API_KEY \ 635 | -H "Content-Type: application/json" \ 636 | -d '{"sshkey_id": "aUAG0Z3p0F3xmc6R"}' 637 | ``` 638 | 639 | ```json 640 | { 641 | "actionid": "OF42xCWkKcaX3qG2", 642 | "data": {} 643 | } 644 | ``` 645 | 646 | ### Remove an SSH Key from a System User 647 | ```DELETE /sysusers/:sysuser_id/sshkeys/:sshkey_id``` 648 | 649 | ``` 650 | $ curl https://api.serverpilot.io/v1/sysusers/RvnwAIfuENyjUVnl/sshkeys/aUAG0Z3p0F3xmc6R \ 651 | -u $CLIENT_ID:$API_KEY \ 652 | -X DELETE 653 | ``` 654 | 655 | ```json 656 | { 657 | "actionid": "OF42xCWkKcaX3qG2", 658 | "data": {} 659 | } 660 | ``` 661 | 662 | ### List SSH Keys of a System User 663 | ```GET /sysusers/:id/sshkeys``` 664 | 665 | ``` 666 | $ curl https://api.serverpilot.io/v1/sysusers/RvnwAIfuENyjUVnl/sshkeys \ 667 | -u $CLIENT_ID:$API_KEY 668 | ``` 669 | 670 | ```json 671 | { 672 | "data": [ 673 | { 674 | "id": "aUAG0Z3p0F3xmc6R", 675 | "name": "joe's key", 676 | "sha256_fingerprint": "SHA256:...", 677 | "public_key": "ssh-rsa ...", 678 | "datecreated": 1403139066 679 | }, 680 | { 681 | "id": "QecKhpb14kk2a6H3", 682 | "name": "jenny's key", 683 | "sha256_fingerprint": "SHA256:...", 684 | "public_key": "ssh-rsa ...", 685 | "datecreated": 1403139067 686 | } 687 | ] 688 | } 689 | ``` 690 | 691 | ## Apps 692 | 693 | Apps are your web applications. Sometimes people call apps "websites". 694 | 695 | ServerPilot currently supports PHP 5.4, 5.5, 5.6, 7.0, 7.1, and 7.2 apps. 696 | 697 | ServerPilot configures your servers with Nginx as the public-facing webserver. 698 | All requests are proxied to Apache 2.4 so your apps can use .htaccess files. 699 | PHP is configured to run via FPM. Each app can have multiple MySQL databases. 700 | 701 | The web root directory for each app is: 702 | 703 | ``` 704 | /srv/users/serverpilot/apps/{APPNAME}/public 705 | ``` 706 | 707 | ServerPilot does not manage DNS for you. In order for you to access your apps 708 | by their domain name, you must make the appropriate changes in your domain's 709 | DNS zone so that your domain name resolves to your server's IP address. You can 710 | do this where you currently manage DNS for your domain. 711 | 712 | ### List All Apps 713 | ```GET /apps``` 714 | 715 | ``` 716 | $ curl https://api.serverpilot.io/v1/apps \ 717 | -u $CLIENTID:$APIKEY 718 | ``` 719 | 720 | ```json 721 | { 722 | "data": [ 723 | { 724 | "id": "c77JD4gZooGjrF8K", 725 | "datecreated": 1403139066, 726 | "name": "blog", 727 | "sysuserid": "RvnwAIfuENyjUVnl", 728 | "domains": ["www.myblog.com", "blog.com"], 729 | "ssl": null, 730 | "serverid": "4zGDDO2xg30yEeum", 731 | "runtime": "php7.0" 732 | }, 733 | { 734 | "id": "B1w7yc1tfUPQLIKS", 735 | "datecreated": 1403143012, 736 | "name": "store", 737 | "sysuserid": "RvnwAIfuENyjUVnl", 738 | "domains": ["www.mystore.com", "mystore.com"], 739 | "ssl": { 740 | "key": "-----BEGIN PRIVATE KEY----- ...", 741 | "cert": "-----BEGIN CERTIFICATE----- ...", 742 | "cacerts": "-----BEGIN CERTIFICATE----- ...", 743 | "auto": false, 744 | "force": false 745 | }, 746 | "serverid": "4zGDDO2xg30yEeum", 747 | "runtime": "php7.0" 748 | }] 749 | } 750 | ``` 751 | 752 | ### Create an App 753 | ```POST /apps``` 754 | 755 | | Name | Type | Description 756 | | ----------- | :------------: | :--------------------------------------- 757 | | `name` | `string` | **Required**. The nickname of the App. Length must be between 3 and 30 characters. Characters can be of lowercase ascii letters and digits. 758 | | `sysuserid` | `string` | **Required**. The System User that will "own" this App. Since every System User is specific to a Server, this implicitly determines on which Server the App will be created. 759 | | `runtime` | `string` | **Required**. The PHP runtime for this App. Must be a runtime listed in the server's `available_runtimes`. 760 | | `domains` | `array` | An array of domains that will be used in the webserver's configuration. If you set your app's domain name to *example.com*, Nginx and Apache will be configured to listen for both *example.com* and *www.example.com*. **Note**: The complete list of domains must be included in every update to this field. 761 | | `wordpress` | `object` | If present, installs WordPress on the App. Value is a JSON object containing keys `site_title`, `admin_user`, `admin_password`, and `admin_email`, each with values that are strings. The `admin_password` value must be at least 8 and no more than 200 characters long. 762 | 763 | Creating an App without WordPress: 764 | 765 | ``` 766 | $ curl https://api.serverpilot.io/v1/apps \ 767 | -u $CLIENTID:$APIKEY \ 768 | -H "Content-Type: application/json" \ 769 | -d '{"name": "gallery", "sysuserid": "RvnwAIfuENyjUVnl", "runtime": "php7.0", "domains": ["example.com", "www.example.com"]}' 770 | ``` 771 | 772 | Creating an App with WordPress: 773 | 774 | ``` 775 | $ curl https://api.serverpilot.io/v1/apps \ 776 | -u $CLIENTID:$APIKEY \ 777 | -H "Content-Type: application/json" \ 778 | -d '{"name": "wordpress", "sysuserid": "RvnwAIfuENyjUVnl", "runtime": "php7.0", "domains": ["example.com", "www.example.com"], "wordpress": {"site_title": "My WordPress Site", "admin_user": "admin", "admin_password": "mypassword", "admin_email": "example@example.com"}}' 779 | ``` 780 | 781 | ```json 782 | { 783 | "actionid": "dIrCNoWunW92lPjw", 784 | "data": 785 | { 786 | "id": "nlcN0TwdZAyNEgdp", 787 | "datecreated": 1403143012, 788 | "name": "gallery", 789 | "sysuserid": "RvnwAIfuENyjUVnl", 790 | "domains": ["www.example.com", "example.com"], 791 | "ssl": null, 792 | "serverid": "4zGDDO2xg30yEeum", 793 | "runtime": "php7.0" 794 | } 795 | } 796 | ``` 797 | 798 | ### Get Details of an App 799 | ```GET /apps/:id``` 800 | 801 | ``` 802 | $ curl https://api.serverpilot.io/v1/apps/nlcN0TwdZAyNEgdp \ 803 | -u $CLIENTID:$APIKEY 804 | ``` 805 | 806 | ```json 807 | { 808 | "data": 809 | { 810 | "id": "nlcN0TwdZAyNEgdp", 811 | "datecreated": 1403143012, 812 | "name": "gallery", 813 | "sysuserid": "RvnwAIfuENyjUVnl", 814 | "domains": ["www.example.com", "example.com", "foo.com"], 815 | "ssl": { 816 | "key": "-----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----", 817 | "cert": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----", 818 | "cacerts": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----", 819 | "auto": false, 820 | "force": false 821 | }, 822 | "autossl": { 823 | "available": true, 824 | "domains": ["www.example.com", "example.com"] 825 | }, 826 | "serverid": "4zGDDO2xg30yEeum", 827 | "runtime": "php7.0" 828 | } 829 | } 830 | ``` 831 | 832 | The value of `auto` in the `ssl` object indicates whether AutoSSL is currently 833 | enabled for the app. In the example above, since `auto` is `false` and there is 834 | an SSL certificate, the SSL certificate is a custom certificate rather than an 835 | AutoSSL certificate. 836 | 837 | To know whether AutoSSL is available for an app, use the `autossl` key. If the 838 | value of `available` is `true`, there will also be a `domains` key with a list 839 | of the domains in the currently available AutoSSL certificate. Note that the 840 | `autossl` key is only available through this app details API, not through the 841 | [apps list API](#list-all-apps) that lists all apps of the account. 842 | 843 | ### Delete an App 844 | ```DELETE /apps/:id``` 845 | 846 | ``` 847 | $ curl https://api.serverpilot.io/v1/apps/B1w7yc1tfUPQLIKS \ 848 | -u $CLIENTID:$APIKEY \ 849 | -X DELETE 850 | ``` 851 | 852 | ```json 853 | { 854 | "actionid": "88Ypexhx28Y63eyA", 855 | "data": {} 856 | } 857 | ``` 858 | 859 | 860 | ### Update an App 861 | ```POST /apps/:id``` 862 | 863 | | Name | Type | Description 864 | | --------- | :------------: | :--------------------------------------- 865 | | `runtime` | `string` | The PHP runtime for this App. Must be a runtime listed in the server's `available_runtimes`. 866 | | `domains` | `array` | An array of domains that will be used in the webserver's configuration. If you set your app's domain name to *example.com*, Nginx and Apache will be configured to listen for both *example.com* and *www.example.com*. **Note**: The complete list of domains must be included in every update to this field. 867 | 868 | ``` 869 | $ curl https://api.serverpilot.io/v1/apps/nlcN0TwdZAyNEgdp \ 870 | -u $CLIENTID:$APIKEY \ 871 | -H "Content-Type: application/json" \ 872 | -d '{"runtime": "php5.6"}' 873 | ``` 874 | 875 | ```json 876 | { 877 | "actionid": "KlsNzLikw3BRvShc", 878 | "data": 879 | { 880 | "id": "nlcN0TwdZAyNEgdp", 881 | "datecreated": 1403143012, 882 | "name": "gallery", 883 | "sysuserid": "RvnwAIfuENyjUVnl", 884 | "domains": ["www.example.com", "example.com"], 885 | "ssl": null, 886 | "serverid": "4zGDDO2xg30yEeum", 887 | "runtime": "php5.6" 888 | } 889 | } 890 | ``` 891 | 892 | ### Add a Custom SSL Cert 893 | ```POST /apps/:id/ssl``` 894 | 895 | A custom SSL cert cannot be added to an app that is using AutoSSL. To replace 896 | AutoSSL with a custom SSL certificate, you must first disable AutoSSL on the 897 | app before adding the custom SSL certificate. 898 | 899 | | Name | Type | Description 900 | | --------- | :------: | :--------------------------------------- 901 | | `key` | `string` | **Required**. The contents of the private key. 902 | | `cert` | `string` | **Required**. The contents of the certificate. 903 | | `cacerts` | `string` | **Required**. The contents of the CA certificate(s). If none, `null` is acceptable. 904 | 905 | ```php 906 | $sslkey, 922 | "cert" => $sslcert, 923 | "cacerts" => null 924 | ); 925 | $data_string = json_encode($data); 926 | 927 | $ch = curl_init("https://api.serverpilot.io/v1/apps/$appid/ssl"); 928 | curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); 929 | curl_setopt($ch, CURLOPT_USERPWD, "$clientid:$apikey"); 930 | curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST"); 931 | curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string); 932 | curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); 933 | curl_setopt($ch, CURLOPT_HTTPHEADER, array( 934 | 'Content-Type: application/json', 935 | 'Content-Length: ' . strlen($data_string)) 936 | ); 937 | // Uncomment the following line for debugging. 938 | //curl_setopt($ch, CURLOPT_VERBOSE, true); 939 | 940 | $result = curl_exec($ch); 941 | curl_close($ch); 942 | 943 | echo json_encode(json_decode($result), JSON_PRETTY_PRINT); 944 | ``` 945 | 946 | ```json 947 | { 948 | "actionid": "BzcMNZ9sdBY62vTd", 949 | "data": 950 | { 951 | "key": "-----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----", 952 | "cert": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----", 953 | "cacerts": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----" 954 | } 955 | } 956 | ``` 957 | 958 | ### Enable AutoSSL 959 | ```POST /apps/:id/ssl``` 960 | 961 | AutoSSL can only be enabled when an AutoSSL certificate is available for an 962 | app. To determine if an AutoSSL certificate is available for an app, use the 963 | [app details API call](#get-details-of-an-app). 964 | 965 | Additionally, AutoSSL cannot be enabled when an app currently has a custom SSL 966 | certificate. To enable AutoSSL when an app is already using a custom SSL, first 967 | [delete the app's custom SSL certificate](#delete-a-custom-ssl-cert-or-disable-autossl). 968 | 969 | Note that disabling AutoSSL is not done through this API call but instead is 970 | done by [deleting SSL from the app](#delete-a-custom-ssl-cert-or-disable-autossl). 971 | 972 | | Name | Type | Description 973 | | --------- | :------------: | :--------------------------------------- 974 | | `auto` | `bool` | Value must be `true`. 975 | 976 | ``` 977 | $ curl https://api.serverpilot.io/v1/apps/nlcN0TwdZAyNEgdp/ssl \ 978 | -u $CLIENTID:$APIKEY \ 979 | -H "Content-Type: application/json" \ 980 | -d '{"auto": true}' 981 | ``` 982 | 983 | ```json 984 | { 985 | "actionid": "pneQJGaAwIyIojW8", 986 | "data": 987 | { 988 | "key": "-----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----", 989 | "cert": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----", 990 | "cacerts": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----", 991 | "auto": true, 992 | "force": false 993 | } 994 | } 995 | ``` 996 | 997 | ### Delete a Custom SSL Cert or Disable AutoSSL 998 | ```DELETE /apps/:id/ssl``` 999 | 1000 | ``` 1001 | $ curl https://api.serverpilot.io/v1/apps/nlcN0TwdZAyNEgdp/ssl \ 1002 | -u $CLIENTID:$APIKEY \ 1003 | -X DELETE 1004 | ``` 1005 | 1006 | ```json 1007 | { 1008 | "actionid": "I1nUHIUR0yzBLESI", 1009 | "data": {} 1010 | } 1011 | ``` 1012 | 1013 | ### Enable or Disable ForceSSL 1014 | ```POST /apps/:id/ssl``` 1015 | 1016 | ForceSSL can only be enabled when an app already has SSL enabled. 1017 | 1018 | You cannot enable ForceSSL at the same time as adding a custom SSL certificate 1019 | or enabling AutoSSL. You must make a separate API call to enable or disable 1020 | ForceSSL. 1021 | 1022 | ForceSSL will be automatically disabled if SSL is deleted from an app. 1023 | 1024 | | Name | Type | Description 1025 | | --------- | :------------: | :--------------------------------------- 1026 | | `force` | `bool` | Whether forced redirection from HTTP to HTTPS is enabled. 1027 | 1028 | ``` 1029 | $ curl https://api.serverpilot.io/v1/apps/nlcN0TwdZAyNEgdp/ssl \ 1030 | -u $CLIENTID:$APIKEY \ 1031 | -H "Content-Type: application/json" \ 1032 | -d '{"force": true}' 1033 | ``` 1034 | 1035 | ```json 1036 | { 1037 | "actionid": "S8zEaeSMrD5gSt9A", 1038 | "data": 1039 | { 1040 | "key": "-----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----", 1041 | "cert": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----", 1042 | "cacerts": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----", 1043 | "auto": false, 1044 | "force": true 1045 | } 1046 | } 1047 | ``` 1048 | 1049 | ## Databases 1050 | 1051 | Databases are MySQL databases. Each Database is associated with an App. 1052 | 1053 | There is only one Database User for each Database. 1054 | 1055 | ### List All Databases 1056 | ```GET /dbs``` 1057 | 1058 | ``` 1059 | $ curl https://api.serverpilot.io/v1/dbs \ 1060 | -u $CLIENTID:$APIKEY 1061 | ``` 1062 | 1063 | ```json 1064 | { 1065 | "data": [ 1066 | { 1067 | "id": "hdXkAZchuj27Hm1L", 1068 | "name": "wordpress", 1069 | "appid": "c77JD4gZooGjrF8K", 1070 | "serverid": "4zGDDO2xg30yEeum", 1071 | "user": { 1072 | "id": "vt08Qz9kjOC3RVLr", 1073 | "name": "robert" 1074 | } 1075 | }] 1076 | } 1077 | ``` 1078 | 1079 | ### Create a Database 1080 | ```POST /dbs``` 1081 | 1082 | | Name | Type | Description 1083 | | ---------------- | :------: | :--------------------------------------- 1084 | | `appid` | `string` | **Required**. The id of the App. 1085 | | `name` | `string` | **Required**. The name of the database. Length must be between 3 and 64 characters. Characters can be of lowercase ascii letters, digits, or a dash ('abcdefghijklmnopqrstuvwxyz0123456789-'). 1086 | | `user` | `object` | **Required**. A JSON object containing `name` and `password` name/value pairs. 1087 | | `user[name]` | `string` | **Required**. The name of the Database User. Length must be at most 16 characters. 1088 | | `user[password]` | `string` | **Required**. The password of the Database User. No leading or trailing whitespace is allowed and the password must be at least 8 and no more than 200 characters long. 1089 | 1090 | ``` 1091 | $ curl https://api.serverpilot.io/v1/dbs \ 1092 | -u $CLIENTID:$APIKEY \ 1093 | -H "Content-Type: application/json" \ 1094 | -d '{"appid": "nlcN0TwdZAyNEgdp", "name": "gallerydb", "user": {"name": "arturo", "password": "8apNPT"}}' 1095 | ``` 1096 | 1097 | ```json 1098 | { 1099 | "actionid": "gPFiWP9hFNUxvT70", 1100 | "data": 1101 | { 1102 | "id": "8PV1OIAlAW3jbGmM", 1103 | "name": "gallerydb", 1104 | "appid": "nlcN0TwdZAyNEgdp", 1105 | "serverid": "4zGDDO2xg30yEeum", 1106 | "user": { 1107 | "id": "k2HWtU33mpUsfOdA", 1108 | "name": "arturo" 1109 | } 1110 | } 1111 | } 1112 | ``` 1113 | 1114 | ### Retrieve an Existing Database 1115 | ```GET /dbs/:id``` 1116 | 1117 | ``` 1118 | $ curl https://api.serverpilot.io/v1/dbs/8PV1OIAlAW3jbGmM \ 1119 | -u $CLIENTID:$APIKEY 1120 | ``` 1121 | 1122 | ```json 1123 | { 1124 | "data": 1125 | { 1126 | "id": "8PV1OIAlAW3jbGmM", 1127 | "name": "gallerydb", 1128 | "appid": "nlcN0TwdZAyNEgdp", 1129 | "serverid": "4zGDDO2xg30yEeum", 1130 | "user": { 1131 | "id": "k2HWtU33mpUsfOdA", 1132 | "name": "arturo" 1133 | } 1134 | } 1135 | } 1136 | ``` 1137 | 1138 | ### Delete a Database 1139 | ```DELETE /dbs/:id``` 1140 | 1141 | ``` 1142 | $ curl https://api.serverpilot.io/v1/dbs/8PV1OIAlAW3jbGmM \ 1143 | -u $CLIENTID:$APIKEY \ 1144 | -X DELETE 1145 | ``` 1146 | 1147 | ```json 1148 | { 1149 | "actionid": "AtzNxxz4fZv3zJ9D", 1150 | "data": {} 1151 | } 1152 | ``` 1153 | 1154 | ### Update the Database User Password 1155 | ```POST /dbs/:id``` 1156 | 1157 | | Name | Type | Description 1158 | | ---------------- | :------: | :---------- 1159 | | `user` | `object` | **Required**. A JSON object containing `id` and `password` name/value pairs. 1160 | | `user[id]` | `string` | **Required**. The id of the Database User. 1161 | | `user[password]` | `string` | **Required**. The *new* password of the Database User. No leading or trailing whitespace is allowed and the password must be at least 8 and no more than 200 characters long. 1162 | 1163 | ``` 1164 | $ curl https://api.serverpilot.io/v1/dbs/8PV1OIAlAW3jbGmM \ 1165 | -u $CLIENTID:$APIKEY \ 1166 | -d '{"user": {"id": "k2HWtU33mpUsfOdA", "password": "8aTWa7"}}' 1167 | ``` 1168 | 1169 | ```json 1170 | { 1171 | "actionid": "VfH12ukDJFv0RZAO", 1172 | "data": 1173 | { 1174 | "id": "8PV1OIAlAW3jbGmM", 1175 | "name": "gallerydb", 1176 | "appid": "nlcN0TwdZAyNEgdp", 1177 | "serverid": "4zGDDO2xg30yEeum", 1178 | "user": { 1179 | "id": "k2HWtU33mpUsfOdA", 1180 | "name": "arturo" 1181 | } 1182 | } 1183 | } 1184 | ``` 1185 | 1186 | ## Actions 1187 | 1188 | Actions are a record of work done on ServerPilot resources. These can be things 1189 | like the creation of an App, deploying SSL, deleting an old Database, etc. 1190 | 1191 | All methods that modify a resource will have an `actionid` top-level key in the 1192 | JSON response if any server configuration was required. The `actionid` can be 1193 | used to track the `status` of the Action. 1194 | 1195 | **Possible values of Action `status`** 1196 | 1197 | | Status | Description 1198 | | --------- | ----------- 1199 | | `success` | Action was completed successfully. 1200 | | `open` | Action has not completed yet. 1201 | | `error` | Action has completed but there were errors. 1202 | 1203 | ### Check the Status of an Action 1204 | ```GET /actions/:id``` 1205 | 1206 | ``` 1207 | $ curl https://api.serverpilot.io/v1/actions/g3kiiYzxPgAjbwcY \ 1208 | -u $CLIENTID:$APIKEY 1209 | ``` 1210 | 1211 | ```json 1212 | { 1213 | "data": 1214 | { 1215 | "id": "g3kiiYzxPgAjbwcY", 1216 | "serverid": "4zGDDO2xg30yEeum", 1217 | "status": "success", 1218 | "datecreated": 1403138066 1219 | } 1220 | } 1221 | ``` 1222 | --------------------------------------------------------------------------------