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://app.cloudploy.com/api/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 Team settings → API tokens. The token value is shown once, right after you create it. Store it somewhere safe.

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://app.cloudploy.com/api/v1/apps \
  -H "Authorization: Bearer $CLOUDPLOY_TOKEN" \
  -H "Accept: application/json"

Abilities

When you create a token, you pick which abilities it has. Each endpoint below needs one of them.

  • read: view account, providers, servers, apps, deployments and logs.
  • deploy: create apps, deploy, manage env vars, domains and SSL, connect Git providers.
  • provision: create, connect, resize, start, stop and restart servers.
  • destroy: terminate servers, delete apps and credentials, roll back a failed first deployment.
  • billing: start a subscription checkout.

Endpoints

Account & billing

GET /account ability: read

Show the team the token belongs to.

POST /billing/checkout ability: billing

Start a subscription checkout.

Params: plan_slug, billing_period (default monthly)

Providers & credentials

GET /providers ability: read

List the cloud providers you can provision on.

GET /providers/{provider}/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: read

Check that a connected cloud account still works.

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

Remove a connected cloud account.

Servers

GET /servers ability: read

List servers.

GET /servers/{id} ability: read

Show one server.

GET /servers/{id}/logs ability: read

Read server logs.

Params: limit (optional)

POST /servers ability: provision

Provision a new server on your cloud account.

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: provision

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: provision

Change the server size.

Params: instance_type (required)

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

Stop a server.

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

Start a stopped server.

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

Restart a server.

POST /servers/{id}/force-complete ability: provision

Mark a stuck provisioning run as complete.

DELETE /servers/{id} ability: destroy

Terminate a server. This is permanent.

Params: confirm=true (required)

Git providers

GET /git-providers ability: read

List connected GitHub, GitLab and Bitbucket accounts.

POST /git-providers ability: deploy

Start connecting a Git provider. Returns an auth_url the user opens in a browser.

Params: provider: github, gitlab or bitbucket

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

List repositories, or branches of one repository.

Params: search, repository (optional)

Apps

GET /apps ability: read

List apps.

POST /apps ability: deploy

Create an app from a Git repository.

Params: server_id, git_repository (required); git_branch, git_provider_id, name, type, php_version, deploy, auto_deploy (optional)

GET /apps/{id} ability: read

Show one app.

GET /apps/{id}/logs ability: read

Read app logs.

Params: deployment_uuid (optional)

POST /apps/{id}/restart ability: deploy

Restart the app.

DELETE /apps/{id} ability: destroy

Delete an app. This is permanent.

Params: confirm=true (required)

Deployments

POST /apps/{id}/deploy ability: deploy

Queue a deployment from the app branch.

POST /apps/{id}/redeploy ability: deploy

Queue a redeployment.

POST /apps/{id}/auto-deploy ability: deploy

Turn deploy-on-push on or off.

Params: enabled (default true)

POST /apps/{id}/rollback ability: destroy

Clean up an app whose first deployment failed or is stuck. Removes its containers, data and DNS. Not available once the app has deployed successfully.

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

List deployments.

Params: limit (optional)

GET /apps/{id}/deployments/{deployment} ability: read

Show one deployment and its status.

Environment variables

GET /apps/{id}/env ability: deploy

List environment variables.

PATCH /apps/{id}/env ability: deploy

Set environment variables.

Params: variables: array of { key, value, is_encrypted }

Domains & SSL

POST /apps/{id}/domains ability: deploy

Add a domain to an app.

Params: domain (required), is_primary (optional)

POST /apps/{id}/ssl ability: deploy

Request an SSL certificate for the app domains.

Examples

Deploy an app

curl -X POST https://app.cloudploy.com/api/v1/apps/42/deploy \
  -H "Authorization: Bearer $CLOUDPLOY_TOKEN" \
  -H "Accept: application/json"

Set an environment variable

curl -X PATCH https://app.cloudploy.com/api/v1/apps/42/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 message. Some errors add extra fields, such as a code.

{ "error": "This token lacks the 'deploy' ability." }
  • 401: the token is missing or invalid.
  • 403: the token lacks the ability the endpoint needs.
  • 404: the resource does not exist or belongs to another team.
  • 422: the input is invalid, or the action is not allowed in the current state.
  • 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. MCP clients sign in with OAuth or use the same API token. See CloudPloy MCP.