Create custom server

Connect and configure an existing server that you already own.

Ubuntu 22.04 can no longer be chosen for os_type, but a machine that already runs it is still accepted. Ploi detects the actual operating system when it first connects and corrects os_type for you.

POST/api/servers/custom

Create a custom server

This endpoint allows you to add a custom server to Ploi. After creating the server, you'll need to add the public key to your server and trigger the installation.

Required scopes

Create servers

Required attributes

Name
type
Type
string
Description
The server type, must be any of these values: server, load-balancer, database-server, redis-server, storage-server
Name
ip
Type
string
Description
The server's IP address.
Name
ssh_port
Type
integer
Description
The SSH port the server runs on.
Name
database_type
Type
string
Description
The type of database to install, must be one of: none, mysql, mysql84, mysql9, mariadb, mariadb114, postgresql, postgresql14, postgresql15, postgresql16, postgresql17, postgresql18.
mysql84 installs MySQL 8.4 LTS and mysql9 installs MySQL 9.7 LTS. On Ubuntu 26.04 only mysql84 is available, because that release ships MySQL 8.4 in its own archive.
The bare mysql, mariadb and postgresql values follow the version we currently recommend for that engine, so what they install changes over time. Pick a versioned value if you need a specific release.
Releases that have reached end of life are no longer accepted for new servers: MySQL 8.0, MariaDB 11.2 and PostgreSQL 13 and older. Existing servers running them keep working.
Name
php_version
Type
string
Description
The PHP version installed, only applicable on the server type. Must be any of these values: none, 5.6, 7.0, 7.1, 7.2, 7.3, 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, 8.5

Optional attributes

Name
name
Type
string
Description
The server name, cannot contain any special characters and is alpha-numeric, if left empty a random name will be used.
Name
os_type
Type
string
Description
The OS version, defaults to ubuntu-26-04-lts. Available options: ubuntu-24-04-lts, ubuntu-26-04-lts, debian-12, debian-13
Name
description
Type
string
Description
Allows you to send in an additional description for your server as note.

Request

POST

/api/servers/custom

curl -X POST "https://ploi.io/api/servers/custom" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "type": "server",
    "name": "awesome-server",
    "ip": "12.34.56.78"
  }'

Response

{
  "id": 1,
  "name": "awesome-server",
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABA.... [email protected]",
  "ssh_command": "mkdir -p /root/.ssh && touch /root/.ssh/authorized_keys && echo ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABA.... [email protected] >> /root/.ssh/authorized_keys",
  "start_installation_url": "https://ploi.io/api/servers/custom/1/start",
  "message": "Server has been created! Please run the \"ssh_command\" inside this response on your server as root user. After that trigger the \"start_installation_url\" with a POST request to start the actual installation."
}

If you don't want to install this server anymore after this step, you can still remove it using the delete server endpoint.

POST/api/servers/custom/{id}/start

Start installation

After adding the public key to your server, trigger this endpoint to start the installation.

Optional attributes

Name
install_monitoring
Type
boolean
Description
Allows you to install Ploi monitoring as well, requires Pro plan or higher.
Name
webhook_url
Type
url
Description
This URL gets triggered by Ploi when installation has completed, you can use this for your own system, this will only send 1 signal, there is no retry schedule.

Request

POST

/api/servers/custom/{id}/start

curl -X POST "https://ploi.io/api/servers/custom/1/start" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

Response

{
  "message": "Server installation has started. Please make sure to not to reboot the server or do any actions on it while installation is running."
}