CloudPloy

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

GET /account ability: read

Show the user and team the token belongs to.

POST /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

GET /providers ability: read

List the cloud providers you can provision on.

GET /providers/{slug}/sizes ability: read

List server sizes for a provider.

GET /estimate-cost ability: read

Estimate the monthly cost of a server size.

Params: provider, instance_type (both required, query string)

GET /provider-credentials ability: read

List connected cloud accounts.

POST /provider-credentials/{id}/test ability: write

Check that a connected cloud account still works. Owner or admin.

DELETE /provider-credentials/{id} ability: write

Remove a connected cloud account that no live server uses. Owner or admin.

Servers

GET /servers ability: read

List servers, newest first.

GET /servers/{id} ability: read

Show one server.

POST /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)

POST /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.

POST /servers/{id}/resize ability: write

Change the server size.

Params: instance_type (required)

POST /servers/{id}/stop ability: write

Stop a server.

POST /servers/{id}/start ability: write

Start a stopped server.

POST /servers/{id}/restart ability: write

Reboot a running server.

DELETE /servers/{id} ability: write

Terminate a server. This is permanent. Refused while apps run on it.

Params: confirm=true (required, query string)

Git providers

GET /git-providers ability: read

List connected GitHub, GitLab and Bitbucket accounts.

POST /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

GET /git-providers/{id}/repositories ability: read

List repositories, or the branches of one repository.

Params: search, repository (optional, query string)

DELETE /git-providers/{id} ability: write

Disconnect a Git provider and remove its webhooks. Owner or admin.

Apps

GET /apps ability: read

List apps, newest first.

POST /apps/detect ability: read

Detect the framework, port and builder of a repository branch.

Params: git_repository (required); git_branch, git_provider_id (optional)

POST /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)

GET /apps/{uuid} ability: read

Show one app with its custom domains.

POST /apps/{uuid}/restart ability: write

Restart the app.

POST /apps/{uuid}/scale ability: write

Set how many containers run the app.

Params: replicas: 1 to 10, within your plan

DELETE /apps/{uuid} ability: write

Delete an app with its container, files and DNS record. This is permanent.

Params: confirm=true (required, query string)

Deployments

POST /apps/{uuid}/deploy ability: write

Queue a deployment of the app branch.

POST /apps/{uuid}/auto-deploy ability: write

Turn deploy-on-push on or off.

Params: enabled (default true)

POST /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.

GET /apps/{uuid}/deployments ability: read

List deployments, newest first.

GET /deployments/{uuid} ability: read

Show one deployment and its status.

GET /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

PATCH /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

GET /apps/{uuid}/domains ability: read

List custom domains and the DNS records to create.

POST /apps/{uuid}/domains ability: write

Add a domain to an app.

Params: domain (required); is_primary, cloudflare_proxy (optional)

POST /apps/{uuid}/domains/{domain}/verify ability: write

Check a domain DNS now.

POST /apps/{uuid}/domains/{domain}/primary ability: write

Make a verified domain primary.

DELETE /apps/{uuid}/domains/{domain} ability: write

Remove a domain that is not primary.

DELETE /apps/{uuid}/primary-domain ability: write

Go back to the default address as the primary one.

PUT /apps/{uuid}/redirect ability: write

Redirect the default address to the primary domain, or stop.

POST /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.
  • 409 or 422: 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 the Retry-After header.

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.