Cleavr API Access (Beta)

Cleavr API
#1

We’re currently inviting select users to the beta program for Cleavr’s API. If you’re part of the program, you can find the relevant API usage documentation here.

You can make use of this space to find the supported endpoints that we’ve made available so far and usage instructions, suggest new endpoints, or report any issues that you encounter with API usage.

Please don’t share this forum page with others until the API is ready for public release. During the beta, access is limited to a select group of trusted users. Please use the API responsibly, as we have yet to implement rate limiting and activity logs. Any abuse may result in your beta access being revoked.

How do i get started using Cleavr’s API?

You can start using Cleavr’s API by creating a new API Token. You can create a token by navigating to the API Tokens page from the sidebar and clicking on Add New Token.

Token Scopes

Each token has one of the following scopes:

  • Global Scope: Used by default if you’re not on a Cleavr Business subscription (no company or teams). Business company owners can create either Global or Team tokens. A global token uses the same access rules as the UI’s global view: it can reach all servers, sites, deployments, and connection profiles available to you at the account level - not only resources in a specific team.

  • Team Scope: Business company owners and team members can create team-scoped tokens for a team they belong to. These tokens can only access resources available to that team. Company members cannot create global tokens.

Note: We plan to move API access onto Cleavr Business, or a dedicated plan still to be decided. The goal is for teams and team-scoped tokens to be the standard way to limit what each token can access.

Abilities

Abilities control which HTTP methods a token may use. Choose at least one when creating a token.

Ability Methods
read GET , HEAD
write POST , PUT , PATCH
delete DELETE

Scope and abilities work together. Scope limits which resources a token can access. Abilities limit which actions it can take. Missing an ability returns 403 insufficient_scope.

API Base URL https://app.cleavr.io/api/v1

#3

Servers

API usage instructions for listing and retrieving servers.

List Servers

To list all the servers, send a GET request to /api/v1/servers.

curl https://app.cleavr.io/api/v1/servers \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN"

Retrieve an Existing Server

To retrieve information about an existing server, send a GET request to /api/v1/servers/SERVER_UUID.

curl https://app.cleavr.io/api/v1/servers/SERVER_UUID \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN"
#4

Server Users

API usage instructions for listing and retrieving server users.

List Server Users

To list all the server users on a server, send a GET request to /api/v1/server-users?server=SERVER_UUID.

curl "https://app.cleavr.io/api/v1/server-users?server=SERVER_UUID" \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN"

Retrieve an Existing Server User

To retrieve information about an existing server user, send a GET request to /api/v1/server-users/SERVER_USER_UUID.

curl https://app.cleavr.io/api/v1/server-users/SERVER_USER_UUID \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN"
#5

Sites

API usage instructions for listing, retrieving, creating, and deleting sites on a server.

List Sites

To list all the sites on a server, send a GET request to /api/v1/sites?server=SERVER_UUID.

curl "https://app.cleavr.io/api/v1/sites?server=SERVER_UUID" \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN"

Retrieve an Existing Site

To retrieve information about an existing site, send a GET request to /api/v1/sites/SITE_UUID.

curl https://app.cleavr.io/api/v1/sites/SITE_UUID \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN"

Create Site

To create a new site on the server, send a POST request /api/v1/sites providing the required attributes.

Create new Laravel Site

curl -X POST https://app.cleavr.io/api/v1/sites \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "SERVER_UUID",
    "serverUser": "SERVER_USER_UUID",
    "type": "laravel",
    "domain": "blog.example.com",
    "freeDomain": false,
    "ssl": true,
    "sslEmail": "you@example.com",
    "sslProvider": "letsencrypt",
    "supportsLivewire": false,
    "options": {
      "phpVersion": "8.5",
      "buildCommand": "npm run build",
      "enableCache": false,
      "shouldCreateDatabaseAndUser": true,
      "database": "lara_db_xyz",
      "databaseUser": "lara_user_xyz",
      "databasePassword": "choose-a-strong-password",
      "useCachingSha2Password": false
    }
  }'

Create new PHP Site

curl -X POST https://app.cleavr.io/api/v1/sites \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "SERVER_UUID",
    "serverUser": "SERVER_USER_UUID",
    "type": "php",
    "domain": "php.example.com",
    "freeDomain": false,
    "ssl": true,
    "sslEmail": "you@example.com",
    "sslProvider": "letsencrypt",
    "options": {
      "phpVersion": "8.5",
      "webDirectory": "",
      "enableCache": false,
      "shouldCreateDatabaseAndUser": true,
      "database": "php_db_xyz",
      "databaseUser": "php_user_xyz",
      "databasePassword": "choose-a-strong-password",
      "useCachingSha2Password": false
    }
  }'

Create new WordPress Site

Always creates a MySQL/MariaDB database.

curl -X POST https://app.cleavr.io/api/v1/sites \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "SERVER_UUID",
    "serverUser": "SERVER_USER_UUID",
    "type": "wordpress",
    "domain": "wp.example.com",
    "freeDomain": false,
    "ssl": true,
    "sslEmail": "you@example.com",
    "sslProvider": "letsencrypt",
    "options": {
      "phpVersion": "8.5",
      "enableCache": false,
      "shouldCreateDatabaseAndUser": true,
      "database": "wp_db_xyz",
      "databaseUser": "wp_user_xyz",
      "databasePassword": "choose-a-strong-password",
      "useCachingSha2Password": false,
      "performInstallSetup": true,
      "multisite": false,
      "wpAdminSetup": {
        "username": "admin",
        "password": "choose-a-strong-password",
        "email": "you@example.com",
        "siteTitle": "My Awesome Site"
      }
    }
  }'

Skip the WordPress installer: set performInstallSetup to false and remove wpAdminSetup.

Create new phpMyAdmin Site

One per server. No wildcard. MySQL/MariaDB only. Creates a user, not a database. Do not send database.

curl -X POST https://app.cleavr.io/api/v1/sites \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "SERVER_UUID",
    "serverUser": "SERVER_USER_UUID",
    "type": "phpmyadmin",
    "domain": "pma.example.com",
    "freeDomain": false,
    "ssl": true,
    "sslEmail": "you@example.com",
    "sslProvider": "letsencrypt",
    "options": {
      "phpVersion": "8.2",
      "enableCache": false,
      "shouldCreateDatabaseAndUser": true,
      "databaseUser": "phpmyadmin",
      "databasePassword": "choose-a-strong-password",
      "useCachingSha2Password": false,
      "nginxAuthEnabled": false,
      "authUsername": "superhuman",
      "authPassword": "choose-a-strong-password",
      "authAllowedIps": [],
      "authPath": "/"
    }
  }'

Create new Adonis Site

site_type_version: 5, 6, 7. Adonis 6 needs Node ≥ 20.x. Adonis 7 needs Node ≥ 24.x.

curl -X POST https://app.cleavr.io/api/v1/sites \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "SERVER_UUID",
    "serverUser": "SERVER_USER_UUID",
    "type": "adonis",
    "domain": "adonis.example.com",
    "freeDomain": false,
    "ssl": true,
    "sslEmail": "you@example.com",
    "sslProvider": "letsencrypt",
    "options": {
      "site_type_version": "7",
      "portNumber": 7011,
      "entryPoint": "server.js",
      "entryPointArgs": "",
      "nodejsVersion": "24.x",
      "enableCache": false,
      "enableViteBuildHook": false,
      "shouldCreateDatabaseAndUser": true,
      "database": "adon_db_xyz",
      "databaseUser": "adon_user_xyz",
      "databasePassword": "choose-a-strong-password"
    }
  }'

Create new Nuxt SSR Site

site_type_version: 2, 3, 4

Version entryPoint artifactPath entryPointArgs
2 .cleavr.runner.js .nuxt start
3 / 4 .cleavr.runner.mjs .output "" 
curl -X POST https://app.cleavr.io/api/v1/sites \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "SERVER_UUID",
    "serverUser": "SERVER_USER_UUID",
    "type": "nuxtServer",
    "domain": "nuxt.example.com",
    "freeDomain": false,
    "ssl": true,
    "sslEmail": "you@example.com",
    "sslProvider": "letsencrypt",
    "options": {
      "site_type_version": "4",
      "portNumber": 7011,
      "entryPoint": ".cleavr.runner.mjs",
      "entryPointArgs": "",
      "artifactPath": ".output",
      "buildCommand": "NITRO_PRESET=cleavr npm run build --production",
      "nodejsVersion": "22.x",
      "enableCache": false
    }
  }'

Create new Nuxt Static Site

site_type_version: 2, 3, 4. artifactPath is dist for 2, .output/public for 3 and 4.

curl -X POST https://app.cleavr.io/api/v1/sites \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "SERVER_UUID",
    "serverUser": "SERVER_USER_UUID",
    "type": "nuxtStatic",
    "domain": "nuxt-static.example.com",
    "freeDomain": false,
    "ssl": true,
    "sslEmail": "you@example.com",
    "sslProvider": "letsencrypt",
    "options": {
      "site_type_version": "4",
      "buildCommand": "NITRO_PRESET=cleavr npm run generate --fail-on-error",
      "artifactPath": ".output/public",
      "nodejsVersion": "22.x",
      "enableCache": false
    }
  }'

Create new Next SSR Site

curl -X POST https://app.cleavr.io/api/v1/sites \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "SERVER_UUID",
    "serverUser": "SERVER_USER_UUID",
    "type": "nextServer",
    "domain": "next.example.com",
    "freeDomain": false,
    "ssl": true,
    "sslEmail": "you@example.com",
    "sslProvider": "letsencrypt",
    "options": {
      "portNumber": 3000,
      "entryPoint": ".cleavr.runner.js",
      "entryPointArgs": "start",
      "artifactPath": ".next",
      "buildCommand": "npm run build --production",
      "nodejsVersion": "22.x",
      "enableCache": false
    }
  }'

Create new NodeJS SSR Site

Set artifactPath when the app has a build output directory.

curl -X POST https://app.cleavr.io/api/v1/sites \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "SERVER_UUID",
    "serverUser": "SERVER_USER_UUID",
    "type": "nodejs",
    "domain": "node.example.com",
    "freeDomain": false,
    "ssl": true,
    "sslEmail": "you@example.com",
    "sslProvider": "letsencrypt",
    "options": {
      "portNumber": 7011,
      "entryPoint": "index.js",
      "entryPointArgs": "",
      "buildCommand": "npm run build --production",
      "artifactPath": "",
      "nodejsVersion": "22.x",
      "enableCache": false
    }
  }'

Create new NodeJS Static Site

Set artifactPath to the build output directory (for example dist).

curl -X POST https://app.cleavr.io/api/v1/sites \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "SERVER_UUID",
    "serverUser": "SERVER_USER_UUID",
    "type": "nodejsStatic",
    "domain": "node-static.example.com",
    "freeDomain": false,
    "ssl": true,
    "sslEmail": "you@example.com",
    "sslProvider": "letsencrypt",
    "options": {
      "buildCommand": "npm run build --production",
      "artifactPath": "",
      "nodejsVersion": "22.x",
      "enableCache": false
    }
  }'

Create new Strapi Site

site_type_version: 3, 4, 5. For 4 / 5 with TypeScript, set typescriptSupport to true and artifactPath to dist.

curl -X POST https://app.cleavr.io/api/v1/sites \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "SERVER_UUID",
    "serverUser": "SERVER_USER_UUID",
    "type": "strapi",
    "domain": "strapi.example.com",
    "freeDomain": false,
    "ssl": true,
    "sslEmail": "you@example.com",
    "sslProvider": "letsencrypt",
    "options": {
      "site_type_version": "5",
      "portNumber": 7011,
      "entryPoint": ".cleavr.runner.js",
      "entryPointArgs": "",
      "buildCommand": "npm run build --production",
      "fileUploadPath": "public/uploads",
      "typescriptSupport": false,
      "artifactPath": "build",
      "nodejsVersion": "22.x",
      "enableCache": false,
      "shouldCreateDatabaseAndUser": true,
      "database": "stra_db_xyz",
      "databaseUser": "stra_user_xyz",
      "databasePassword": "choose-a-strong-password"
    }
  }'

Create new Directus Site

site_type_version: 10, 11. directusReleaseType: patch or minor.

curl -X POST https://app.cleavr.io/api/v1/sites \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "SERVER_UUID",
    "serverUser": "SERVER_USER_UUID",
    "type": "directus",
    "domain": "directus.example.com",
    "freeDomain": false,
    "ssl": true,
    "sslEmail": "you@example.com",
    "sslProvider": "letsencrypt",
    "options": {
      "site_type_version": "11",
      "portNumber": 7011,
      "entryPoint": ".cleavr.runner.js",
      "entryPointArgs": "start",
      "buildCommand": "npx directus bootstrap",
      "artifactPath": "",
      "fileUploadPath": "uploads",
      "adminEmail": "you@example.com",
      "adminPassword": "choose-a-strong-password",
      "nodejsVersion": "22.x",
      "enableCache": false,
      "directusReleaseType": "patch",
      "shouldCreateDatabaseAndUser": true,
      "database": "dir_db_xyz",
      "databaseUser": "dir_user_xyz",
      "databasePassword": "choose-a-strong-password"
    }
  }'

Create new Generic Port Site

port is required.

curl -X POST https://app.cleavr.io/api/v1/sites \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "SERVER_UUID",
    "serverUser": "SERVER_USER_UUID",
    "type": "genericPort",
    "domain": "port.example.com",
    "freeDomain": false,
    "ssl": true,
    "sslEmail": "you@example.com",
    "sslProvider": "letsencrypt",
    "options": {
      "port": 43065,
      "enableCache": false
    }
  }'

Create new Soketi Site

One per server. No wildcard.

curl -X POST https://app.cleavr.io/api/v1/sites \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "SERVER_UUID",
    "serverUser": "SERVER_USER_UUID",
    "type": "soketi",
    "domain": "soketi.example.com",
    "freeDomain": false,
    "ssl": true,
    "sslEmail": "you@example.com",
    "sslProvider": "letsencrypt",
    "options": {
      "soketiId": "ZSuxpDT4",
      "soketiKey": "UMbdSJZZDP8D",
      "soketiSecret": "p5Pcum2pXmImduYc",
      "soketiEnableClientMessages": false,
      "port": 6001,
      "enableCache": false
    }
  }'

Create new Static HTML Site

Empty webDirectory is the site root. No leading /.

curl -X POST https://app.cleavr.io/api/v1/sites \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "SERVER_UUID",
    "serverUser": "SERVER_USER_UUID",
    "type": "static",
    "domain": "static.example.com",
    "freeDomain": false,
    "ssl": true,
    "sslEmail": "you@example.com",
    "sslProvider": "letsencrypt",
    "options": {
      "webDirectory": "",
      "enableCache": false
    }
  }'

Adjustments

Skip database setup

On Laravel, PHP, Adonis, Strapi, or Directus, remove from options:

  • shouldCreateDatabaseAndUser
  • database
  • databaseUser
  • databasePassword
  • useCachingSha2Password
  • preferredDbServer

WordPress always creates a database. phpMyAdmin always creates a user (databaseUser must be phpmyadmin; do not send database).

Temporary domain

Remove: domain, ssl, sslEmail, sslProvider

Set: "freeDomain": true

SSL is issued automatically. 202 includes generated domain and free_domain_base. Sending the removed fields returns 422. Also remove wildcard and dnsProfile.

Wildcard

Custom domain only. Not for phpmyadmin or soketi. provider: cloudflare, digitalocean, porkbun, aws.

Add:

{
  "wildcard": true,
  "dnsProfile": { "uuid": "DNS_PROFILE_UUID", "provider": "cloudflare" }
}

Optional: "includeWwwSslCert": true to cover www.{domain}. sslProvider may be letsencrypt or zerossl.

Database engine

Do not send preferredDbServer when MySQL/MariaDB or PostgreSQL is already installed.

Adonis, Strapi, and Directus: omit preferredDbServer. Installed Postgres is reused. If Postgres is not installed, postgresql13 is installed.

Laravel, PHP, WordPress, and phpMyAdmin: omit preferredDbServer. Installed MySQL/MariaDB is reused. If none is installed, mysql80 is installed.

Send preferredDbServer only when that family is not installed and you want a specific version. A different version of an already-installed family returns 422. MySQL/MariaDB and PostgreSQL may coexist. WordPress and phpMyAdmin are MySQL/MariaDB only.

Values: mysql82, mysql80, mysql57, mariadb1011, mariadb1010, mariadb107, mariadb106, mariadb104, mariadb102, postgresql17, postgresql15, postgresql14, postgresql13, postgresql12

Database name: letters, numbers, _, $; unique on the server. Database user: unique on the server; must not start with pg_ on PostgreSQL.

PHP and Node

phpVersion: 8.5, 8.4, 8.3, 8.2, 8.1, 8.0, 7.4, 7.3, 7.2. That version is installed if missing. Other PHP versions on the server are left alone.

nodejsVersion: 24.x, 22.x, 20.x, 18.x, 16.x, 14.x, 12.x. One Node version per server. If Node is already installed, it is reused and nodejsVersion is ignored. Send nodejsVersion only when the server has no Node. An existing Node that is too old for Adonis 6 or 7 may be upgraded.

#6

SSL Certificates

API usage instructions for SSL certificate management.

List SSL Certificates

To list all SSL certificates for a site, send a GET request to /api/v1/sites/SITE_UUID/ssl-certificates.

curl https://app.cleavr.io/api/v1/sites/SITE_UUID/ssl-certificates \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN"

Create a Let’s Encrypt OR ZeroSSL Certificate for a Site

To create a new Let’s Encrypt/ZeroSSL certificate, send a POST request to /api/v1/sites/SITE_UUID/ssl-certificates/acme-supported-ca.

curl -X POST https://app.cleavr.io/api/v1/sites/SITE_UUID/ssl-certificates/acme-supported-ca \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": "blog.example.com",
    "email": "you@example.com",
    "provider": "zerossl"
  }'

Set provider to zerossl for a ZeroSSL certificate or letsencrypt for a Let’s Encrypt certificate.

"provider": "zerossl"

OR

"provider": "letsencrypt"

Create a Custom SSL Certificate for a Site

To create a new custom certificate, send a POST request to /api/v1/sites/SITE_UUID/ssl-certificates/custom-ssl.

curl -X POST https://app.cleavr.io/api/v1/sites/SITE_UUID/ssl-certificates/custom-ssl \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": "blog.example.com",
    "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
  }'

If you run into any errors, such as {"error":{"code":"internal_error","message":"An unexpected error occurred."}}, with the above request, please send a request using the command below:

curl -X POST \
  "https://app.cleavr.io/api/v1/sites/SITE_UUID/ssl-certificates/custom-ssl" \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "domains=blog.example.com" \
  --data-urlencode "certificate=-----BEGIN CERTIFICATE-----
MIIEmDCCA4CgAwIBAgIU...
-----END CERTIFICATE-----" \
  --data-urlencode "privateKey=-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKc...
-----END PRIVATE KEY-----"

Create CSR

To create your own certificate signing request (CSR) to use with an SSL certificate, send a POST request to /api/v1/sites/SITE_UUID/ssl-certificates/csr.

curl -X POST \
  "https://app.cleavr.io/api/v1/sites/SITE_UUID/ssl-certificates/csr" \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "domain": "blog.example.com",
    "country": "US",
    "state": "",
    "location": "",
    "organization": ""
  }'

country is required. Use a 2-letter ISO 3166-1 country code (for example US or NP ). Do not send the full country name. You can also find the country code list here.

To use a certificate from a CA, send a request to create a CSR, then create a new custom SSL certificate. The API returns the private key only in the create-CSR response. If you already have a certificate and private key, skip the CSR and install the custom certificate directly.

Check SSL Certificate Validity

To check the validity of an SSL certificate, send a PATCH request to /api/v1/sites/SITE_UUID/ssl-certificates/SSL_UUID/check-validity.

curl -X PATCH https://app.cleavr.io/api/v1/sites/SITE_UUID/ssl-certificates/SSL_UUID/check-validity \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN"

Delete SSL Certificate

To delete an SSL certificate, send a DELETE request to /api/v1/sites/SITE_UUID/ssl-certificates/SSL_UUID.

curl -X DELETE https://app.cleavr.io/api/v1/sites/SITE_UUID/ssl-certificates/SSL_UUID \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN"

Note

  • domains is a comma-separated list of hostnames. Do not include https:// . First value is the primary domain (the site domain). Any following values are alternate domains ( www , other hostnames). Example: blog.example.com,www.blog.example.com .

  • Ensure that alternate domains have their DNS pointed to the server’s IP address and are included in the Domain Aliases section.

  • Wait until DNS has propagated. Each domain’s A record must point to the server’s public IP. If the domain is proxied, temporarily disable proxy until after SSL has been applied.

#7

Please feel free to use the available APIs and report any issues, request support for new API endpoints, or discuss how you want to utilize API access here or directly via the Helpdesk in Cleavr’s UI. Any feedback and suggestions are appreciated.

We will keep updating this topic as we document more API endpoints.

#8

Version Control

API usage instructions for listing and retrieving version control profiles.

List Version Control Profiles

To list all version control profiles, send a GET request to /api/v1/vc-profiles.

curl https://app.cleavr.io/api/v1/vc-profiles \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN"

Retrieve an Existing Version Control Profile

To retrieve information about an existing version control profile, send a GET request to /api/v1/vc-profiles/PROFILE_UUID.

curl https://app.cleavr.io/api/v1/vc-profiles/PROFILE_UUID \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN"

Fetch Repos for a Version Control Profile

To retrieve the repository list associated with a version control profile, send a GET request to /api/v1/vc-profiles/PROFILE_UUID/repos.

curl https://app.cleavr.io/api/v1/vc-profiles/PROFILE_UUID/repos \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN"

Webapps (Deployment Workflows)

API usage instructions for listing and retrieving webapps. Webapps are called Deployment Workflows in the UI context.

List Webapps

To list all webapps, send a GET request to /api/v1/webapps.

curl -X GET "https://app.cleavr.io/api/v1/webapps" \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN_SECRET"

Retrieve an Existing Webapp

To retrieve information about an existing webapp, send a GET request to /api/v1/webapps/WEBAPP_UUID.

curl -X GET "https://app.cleavr.io/api/v1/webapps/WEBAPP_UUID" \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN_SECRET"
#9

Webapp Settings (Deployment Workflow Settings) and Deploy Webapp

Manage webapp settings, such as code repository and build settings, and deploy webapp.

Update Code Repository Settings

To update code repository settings, send a PATCH request to /api/v1/webapps/WEBAPP_UUID/settings/code-repo.

curl -X PATCH https://app.cleavr.io/api/v1/webapps/WEBAPP_UUID/settings/code-repo \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vcProfile": "VC_PROFILE_UUID",
    "repo": "owner/repo",
    "deployBranch": "develop",
    "appFolder": "apps/web",
    "pushToDeploy": true,
    "deployReleaseTags": false,
    "deployOnPrerelease": false
  }'

NOTES:

  • To deploy on code push to deployBranch, set pushToDeploy to true.
  • To deploy on code push to release tags, set pushToDeploy to true and deployReleaseTags to true.
  • To deploy on code push to release tags (pre-release), set pushToDeploy, deployReleaseTags and deployOnPrerelease to true.
  • Make sure to provide repo in the format owner/repo.

Update Build Settings

To update build settings, send a PATCH request to /webapps/WEBAPP_UUID/settings/build.

Build settings are supported for the following app types: adonis , nodejs , nodejsStatic , nuxtServer, nuxtStatic , strapi , directus , nextServer , and laravel .

curl -X PATCH https://app.cleavr.io/api/v1/webapps/WEBAPP_UUID/settings/build \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "buildCommand": "npm run build --production",
    "artifactPath": "",
    "fileUploadPath": ""
  }'

Default values for each app type:

  • laravel: buildCommand: "npm run build"
  • nodejs: buildCommand: "npm run build --production"
  • nodejsStatic: buildCommand: "npm run build --production"
  • nextServer: buildCommand: "npm run build --production", artifactPath: ".next"
  • nuxtStatic (Nuxt 3 / 4): buildCommand: "NITRO_PRESET=cleavr npm run generate --fail-on-error", artifactPath: ".output/public"
  • nuxtStatic (older): same buildCommand, artifactPath: "dist"
  • nuxtServer (v2): buildCommand: "NITRO_PRESET=cleavr npm run build --production", artifactPath: ".nuxt"
  • nuxtServer (v3 / v4): same buildCommand, artifactPath: ".output"
  • strapi: buildCommand: "npm run build --production", artifactPath: "build", fileUploadPath: "public/uploads"
    (Strapi 4/5 with TypeScript enabled: artifactPath: "dist")
  • directus: buildCommand: "npx directus bootstrap", fileUploadPath: "uploads"

Deploy Webapp

To deploy a webapp, send a POST request to /api/v1/webapps/WEBAPP_UUID/deployments.

curl -X POST https://app.cleavr.io/api/v1/webapps/WEBAPP_UUID/deployments \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Content-Type: application/json"
#10

Quick Scripts

API usage instructions for quick scripts management and executing quick scripts.

List Quick Scripts

To list all the quick scripts associated with user account, send a GET request to /api/v1/quick-scripts.

curl -X GET "https://app.cleavr.io/api/v1/quick-scripts" \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Accept: application/json"

Create New Quick Script

To create a new quick script, send a POST request to /api/v1/quick-scripts.

curl -X POST "https://app.cleavr.io/api/v1/quick-scripts" \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"label":"API test script","script":"echo hello from api","notes":"created via api"}'

Retrieve an Existing Quick Script

To retrieve information about an existing quick script, send a GET request to /api/v1/quick-scripts/SCRIPT_UUID.

curl -X GET "https://app.cleavr.io/api/v1/quick-scripts/SCRIPT_UUID" \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Accept: application/json"

Update Quick Script

To update a quick script, send a PATCH request to /api/v1/quick-scripts/SCRIPT_UUID.

curl -X PATCH "https://app.cleavr.io/api/v1/quick-scripts/SCRIPT_UUID" \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"label":"API test script updated","script":"echo hello updated","notes":"updated via curl"}'

Run Quick Script

To run a quick script on a server, send a POST request to /api/v1/quick-scripts/SCRIPT_UUID/run with server uuid in the body.

curl -X POST "https://app.cleavr.io/api/v1/quick-scripts/SCRIPT_UUID/run" \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"server":"SERVER_UUID","runAs":"root","values":{}}'

Delete Quick Script

To delete a quick script, send a delete request to /api/v1/quick-scripts/SCRIPT_UUID.

curl -sS -X DELETE "https://app.cleavr.io/api/v1/quick-scripts/SCRIPT_UUID" \
  -H "Authorization: Bearer cleavr_YOUR_TOKEN" \
  -H "Accept: application/json"
#11
#12

Hello everyone,

We’re excited to share that one of our most awaited features is now live! :fire:

You can now use Cleavr’s API to manage your resources programmatically. Automate server management, integrate Cleavr into your own workflows, and build tools and services on top of Cleavr.

API support is available on Cleavr’s Business subscriptions and active trials.

Read the API documentation.

Give Cleavr’s API a try and let us know if you have any feedback or suggestions.

We’re excited to see the doors this opens for Cleavr and our users.