API Reference
The CloudPloy REST API lets you manage servers, apps and deployments from scripts and CI. It uses JSON over HTTPS.
Base URL
https://brain.cloudploy.com/v1 All paths below are relative to this URL.
Authentication
The API uses team API tokens. A team owner or admin creates one in the console under Settings > API tokens. The token value is shown once, right after you create it. Store it somewhere safe.
Used the API before November 2026? The address changed: paths no longer start with /api, apps are addressed by their uuid, and older tokens do not carry over, so create a new one.
A token belongs to one team. It can only see and change that team's resources. You can revoke it from the same page.
Send the token as a Bearer token on every request. Also send Accept: application/json so errors come back as JSON.
curl https://brain.cloudploy.com/v1/apps \
-H "Authorization: Bearer $CLOUDPLOY_TOKEN" \
-H "Accept: application/json" Abilities
Every token can read. When you create a token, you choose whether it can also write. Each endpoint below needs one of them, and your team role still applies.
read: view account, providers, servers, apps, deployments, logs and domains.write: everything that changes something: servers, apps, deploys, env vars, domains, Git connections and billing.
Endpoints
Account & billing
/account ability: read Show the user and team the token belongs to.
/billing/checkout ability: write Start a subscription checkout. Open the returned checkout_url in a browser. Owner or admin.
Params: plan_slug, billing_period (default monthly)
Providers & credentials
/providers ability: read List the cloud providers you can provision on.
/providers/{slug}/sizes ability: read List server sizes for a provider.
/estimate-cost ability: read Estimate the monthly cost of a server size.
Params: provider, instance_type (both required, query string)
/provider-credentials ability: read List connected cloud accounts.
/provider-credentials/{id}/test ability: write Check that a connected cloud account still works. Owner or admin.
/provider-credentials/{id} ability: write Remove a connected cloud account that no live server uses. Owner or admin.
Servers
/servers ability: read List servers, newest first.
/servers/{id} ability: read Show one server.
/servers ability: write Launch a server in your AWS account. Returns at once; poll GET /servers/{id} until it is active.
Params: hostname, region, instance_type (required); provider, provider_credential_id, operating_system, disk_size, name, vpc_id, subnet_id, associate_public_ip (optional)
/servers/connect ability: write Connect a fresh server you already run, in two steps.
Params: Step 1: hostname, ip_address, ssh_port, ssh_username, fresh_server_confirmed. Returns a public key to add to the server. Step 2: server_id.
/servers/{id}/resize ability: write Change the server size.
Params: instance_type (required)
/servers/{id}/stop ability: write Stop a server.
/servers/{id}/start ability: write Start a stopped server.
/servers/{id}/restart ability: write Reboot a running server.
/servers/{id} ability: write Terminate a server. This is permanent. Refused while apps run on it.
Params: confirm=true (required, query string)
Git providers
/git-providers ability: read List connected GitHub, GitLab and Bitbucket accounts.
/git-providers ability: write Start connecting a Git provider. Returns a link the user opens in a browser. Owner or admin.
Params: provider: github, gitlab or bitbucket
/git-providers/{id}/repositories ability: read List repositories, or the branches of one repository.
Params: search, repository (optional, query string)
/git-providers/{id} ability: write Disconnect a Git provider and remove its webhooks. Owner or admin.
Apps
/apps ability: read List apps, newest first.
/apps/detect ability: read Detect the framework, port and builder of a repository branch.
Params: git_repository (required); git_branch, git_provider_id (optional)
/apps ability: write Create an app from a Git repository. Omit type to detect it.
Params: server_id, git_repository (required); git_branch, git_provider_id, name, type, subdomain, deploy, auto_deploy (optional)
/apps/{uuid} ability: read Show one app with its custom domains.
/apps/{uuid}/restart ability: write Restart the app.
/apps/{uuid}/scale ability: write Set how many containers run the app.
Params: replicas: 1 to 10, within your plan
/apps/{uuid} ability: write Delete an app with its container, files and DNS record. This is permanent.
Params: confirm=true (required, query string)
Deployments
/apps/{uuid}/deploy ability: write Queue a deployment of the app branch.
/apps/{uuid}/auto-deploy ability: write Turn deploy-on-push on or off.
Params: enabled (default true)
/apps/{uuid}/rollback ability: write Go back to the image that ran before the last deploy, without a build. For an app that never deployed, remove what the failed first deploy left.
/apps/{uuid}/deployments ability: read List deployments, newest first.
/deployments/{uuid} ability: read Show one deployment and its status.
/apps/{uuid}/deployments/{deployment_uuid}/logs ability: read Read the log lines of a deployment, oldest first.
Params: after, limit (optional, query string)
Environment variables
/apps/{uuid}/env ability: write Add, replace or remove environment variables.
Params: variables: array of { key, value, is_encrypted }; remove: array of keys (optional)
Domains & SSL
/apps/{uuid}/domains ability: read List custom domains and the DNS records to create.
/apps/{uuid}/domains ability: write Add a domain to an app.
Params: domain (required); is_primary, cloudflare_proxy (optional)
/apps/{uuid}/domains/{domain}/verify ability: write Check a domain DNS now.
/apps/{uuid}/domains/{domain}/primary ability: write Make a verified domain primary.
/apps/{uuid}/domains/{domain} ability: write Remove a domain that is not primary.
/apps/{uuid}/primary-domain ability: write Go back to the default address as the primary one.
/apps/{uuid}/redirect ability: write Redirect the default address to the primary domain, or stop.
/apps/{uuid}/ssl ability: write Re-issue or re-install the SSL certificates of the app domains.
Examples
Deploy an app
curl -X POST https://brain.cloudploy.com/v1/apps/APP_UUID/deploy \
-H "Authorization: Bearer $CLOUDPLOY_TOKEN" \
-H "Accept: application/json" Set an environment variable
curl -X PATCH https://brain.cloudploy.com/v1/apps/APP_UUID/env \
-H "Authorization: Bearer $CLOUDPLOY_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"variables":[{"key":"APP_ENV","value":"production"}]}' Errors
Failed requests return a non-2xx status and a JSON body with an error code.
{ "error": "insufficient_scope" } 401: the token is missing or invalid.403: the token lacks write (insufficient_scope), or your role does not allow it (forbidden).404: the resource does not exist or belongs to another team.409or422: the action is not allowed in the current state, or the input is invalid.429: too many requests. Wait for the number of seconds in theRetry-Afterheader.
Deleting an app or terminating a server needs confirm=true. Without it the API returns 422 and changes nothing.
MCP server
The same operations are available to AI agents through the CloudPloy MCP server at https://brain.cloudploy.com/mcp. MCP clients sign in with OAuth or use the same API token. See CloudPloy MCP.