Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Nettalco/dokploy/llms.txt

Use this file to discover all available pages before exploring further.

The Servers API allows you to register remote Linux servers, validate SSH connectivity, install Dokploy dependencies (setup), and monitor resource metrics. SSH key management is built in — you can generate, store, and rotate keys that Dokploy uses to connect to remote machines. For cluster deployments, the API also exposes Swarm node management: add workers, promote managers, and drain or remove nodes.

​
Endpoints

MethodEndpointDescription
POST/server.createRegister a new remote server
GET/server.oneFetch a server by ID
GET/server.allList all registered servers
GET/server.countCount total registered servers
POST/server.setupInstall Dokploy agent on a server
POST/server.validateTest SSH connectivity to a server
POST/server.securityConfigure security settings
POST/server.setupMonitoringInstall monitoring agent on the server
POST/server.removeRemove a registered server
POST/server.updateUpdate server configuration
GET/server.publicIpGet the server’s public IP address
GET/server.getServerTimeGet the current time on the server
GET/server.getServerMetricsFetch CPU, memory, and disk metrics
GET/server.buildServersList servers available for builds
GET/server.withSSHKeyList servers associated with an SSH key
GET/server.getDefaultCommandGet the setup command for bootstrapping
POST/sshKey.createCreate an SSH key record
POST/sshKey.removeDelete an SSH key
GET/sshKey.oneFetch an SSH key by ID
GET/sshKey.allList all SSH keys
POST/sshKey.generateGenerate a new SSH key pair
POST/sshKey.updateUpdate an SSH key
GET/cluster.getNodesList all Swarm cluster nodes
POST/cluster.addWorkerJoin a server as a Swarm worker
POST/cluster.addManagerPromote a server to Swarm manager
POST/cluster.removeWorkerDrain and remove a worker from the cluster

​
Key Endpoints

​
POST /server.create

Register a new remote server so Dokploy can deploy workloads on it.
​
name
string
required
Display name for the server.
​
ipAddress
string
required
IPv4 or IPv6 address of the remote server.
​
port
number
required
SSH port (default: 22).
​
username
string
required
SSH username (e.g., root or ubuntu).
​
sshKeyId
string
required
ID of the SSH key to use for authentication.
​
description
string
Optional description.
​
serverId
string
Unique ID of the registered server.
​
serverStatus
string
Initial status: idle, active, or error.
curl -X POST 'https://your-instance.com/api/server.create' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "prod-server-1",
    "ipAddress": "203.0.113.10",
    "port": 22,
    "username": "root",
    "sshKeyId": "key_abc123"
  }'

​
POST /server.setup

Install the Dokploy agent and required Docker dependencies on a registered server. This must be run once before the server can host workloads.
​
serverId
string
required
ID of the server to set up.
curl -X POST 'https://your-instance.com/api/server.setup' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "serverId": "srv_xyz789"
  }'

​
POST /server.validate

Test the SSH connection and confirm the server is reachable before deploying workloads.
​
serverId
string
required
ID of the server to validate.
​
success
boolean
Whether the SSH connection succeeded.
​
message
string
Descriptive result message.
curl -X POST 'https://your-instance.com/api/server.validate' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "serverId": "srv_xyz789"
  }'

​
POST /sshKey.generate

Generate a new RSA or Ed25519 key pair and store it in Dokploy. Returns the public key to add to your server’s authorized_keys.
​
name
string
required
Display name for the key.
​
description
string
Optional description.
​
sshKeyId
string
Unique ID of the generated key.
​
publicKey
string
The public key string to add to your remote server.
curl -X POST 'https://your-instance.com/api/sshKey.generate' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "prod-deploy-key",
    "description": "Key for production servers"
  }'

​
GET /server.getServerMetrics

Retrieve real-time CPU, memory, and disk utilization for a server.
​
serverId
string
required
ID of the server to query.
​
cpu
object
CPU utilization data including usage percentage.
​
memory
object
Memory usage including total, used, and free values.
​
disk
object
Disk usage including total, used, and available values.
curl -G 'https://your-instance.com/api/server.getServerMetrics' \
  -H 'x-api-key: YOUR_API_KEY' \
  --data-urlencode 'serverId=srv_xyz789'

​
Notes

Run server.setup after server.create to install Docker and the Dokploy agent. Without setup, deployments to that server will fail.
Use sshKey.generate to let Dokploy manage key generation — then copy the returned public key to your server’s ~/.ssh/authorized_keys file.

Build docs developers (and LLMs) love

Get started for freeTalk to us