Coolify Octri Demo
POST/servers

Create a server

Creates a server with the supplied connection details and configuration. Set server_role to specify whether the server handles deployments, builds, or both, and use proxy_type to choose its proxy configuration. A 201 response returns the new server's UUID.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

10 body fields

Configuration for the new server. The schema does not mark any individual property as required.

descriptionstringoptional
The description of the server.
instant_validatebooleanoptional
Instant validate.
ipstringoptional
The IP of the server.
is_build_serverbooleandeprecatedoptional
Deprecated: use server_role instead. true sets server_role to build, false sets it to both. Must not conflict with server_role.
namestringoptional
The name of the server. Must not contain control characters such as new lines.
portintegeroptional
The port of the server.
private_key_uuidstringoptional
The UUID of the private key.
proxy_typestringoptional
The proxy type.
Allowed:traefikcaddynone
server_rolestringoptional
Server role.
Allowed:deploymentbuildboth
userstringoptional
The user of the server.

5 status codes
201Returns an object containing the UUID of the created server.
uuidstringoptional
The UUID of the server.
400Returned when the token is invalid.
messagestringoptional
401Returned when the request is unauthenticated.
messagestringoptional
404Returned when a requested resource cannot be found.
messagestringoptional
422Returned when server configuration fails validation.
errorsobjectoptional
messagestringoptional

Error handling

A 400 indicates an invalid token; a 401 indicates an unauthenticated request; a 404 indicates a missing resource; and a 422 indicates a validation error. server_role must be deployment, build, or both, and proxy_type must be traefik, caddy, or none. name must not contain control characters such as new lines; if you use is_build_server, it must not conflict with server_role.