Servers and Cloud accounts

Servers, SSH keys, Cloud accounts for AWS and Google Cloud, Swarm nodes, containers and Traefik.

Services run on a Server (any Ubuntu machine Cloudgate reaches over SSH) or in a Cloud account (AWS or Google Cloud). These routes add and set up Servers, manage SSH keys and Cloud accounts, and work with the Docker containers and Swarm nodes on a Server.

Every request goes to https://cloudgate.octabyte.app/backend on the Hosted instance, or to your console address followed by /backend when you self-host. Send a Personal key in x-api-key and the Organization in x-organization-id; Authentication shows how to make the key, and Errors explains every refusal. The examples setCLOUDGATE_KEY and CLOUDGATE_ORG_ID in the shell first. To do the same in the console, read Servers in the user guide.

Servers

List Servers

GET/servers

Who can call it: Owner or Admin. Needs server: read, which a custom role can also grant.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/servers \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Create a Server

POST/servers

Who can call it: Owner or Admin. Needs server: create, which a custom role can also grant.

Request body

Field	Type	Notes
`name`required	string	Not empty.
`description`	string
`ipAddress`required	string	Not empty.
`port`	integer	1 to 65535. Default `22`.
`username`	string	Not empty. Default `"root"`.
`sshKeyId`required	string	Not empty.
`serverType`	string	One of `deploy`, `build`.

Responses

201 Created: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/servers \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "eu-web-1",
    "ipAddress": "203.0.113.10",
    "sshKeyId": "iZkFPYk8xvwqVUUogewwk"
  }'

Get a Server

GET/servers/{id}

Who can call it: Owner or Admin. Needs server: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Server's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/servers/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Update a Server

PATCH/servers/{id}

Who can call it: Owner or Admin. Needs server: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Server's id.

Request body

Field	Type	Notes
`name`	string	Not empty.
`description`	string or null
`ipAddress`	string	Not empty.
`port`	integer	1 to 65535.
`username`	string	Not empty.
`sshKeyId`	string	Not empty.
`serverType`	string	One of `deploy`, `build`.
`command`	string

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PATCH https://cloudgate.octabyte.app/backend/servers/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "eu-web-1",
    "description": "Storefront for Northwind Labs",
    "ipAddress": "203.0.113.10"
  }'

Delete a Server

DELETE/servers/{id}

Who can call it: Owner or Admin. Needs server: delete, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Server's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X DELETE https://cloudgate.octabyte.app/backend/servers/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Validate a Server

GET/servers/{id}/validate

Who can call it: Owner or Admin. Needs server: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Server's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/servers/RAU6yAYUXFRdXdPLyLoPC/validate \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Audit a Server

GET/servers/{id}/audit

Who can call it: Owner or Admin. Needs server: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Server's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/servers/RAU6yAYUXFRdXdPLyLoPC/audit \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Set up a Server

POST/servers/{id}/setup

Provision the host and answer when the script ends.

Who can call it: Owner or Admin. Needs server: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Server's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/servers/RAU6yAYUXFRdXdPLyLoPC/setup \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Forget the host key

POST/servers/{id}/forget-host-key

Forget the Server's recorded host key, after a deliberate reinstall, so the next connect records the new one. A change to the Server row, so server:create as PATCH is.

Who can call it: Owner or Admin. Needs server: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Server's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/servers/RAU6yAYUXFRdXdPLyLoPC/forget-host-key \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Start maintenance on a Server

POST/servers/{id}/start-maintenance

Who can call it: Owner or Admin. Needs server: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Server's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/servers/RAU6yAYUXFRdXdPLyLoPC/start-maintenance \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

End maintenance on a Server

POST/servers/{id}/end-maintenance

End the Server's Maintenance; 409 when it is not in maintenance.

Who can call it: Owner or Admin. Needs server: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Server's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/servers/RAU6yAYUXFRdXdPLyLoPC/end-maintenance \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

SSH keys

List SSH keys

GET/ssh-keys

Who can call it: Owner or Admin. Needs sshKeys: read, which a custom role can also grant.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/ssh-keys \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Create an SSH key

POST/ssh-keys

Who can call it: Owner or Admin. Needs sshKeys: create, which a custom role can also grant.

Request body

Field	Type	Notes
`name`required	string	Not empty.
`description`	string
`publicKey`	string	Not empty.
`privateKey`	string	Not empty.
`type`	string	One of `rsa`, `ed25519`.

Responses

201 Created: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/ssh-keys \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "deploy-key"
  }'

Get an SSH key

GET/ssh-keys/{id}

Who can call it: Owner or Admin. Needs sshKeys: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The SSH key's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/ssh-keys/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Update an SSH key

PATCH/ssh-keys/{id}

Who can call it: Owner or Admin. Needs sshKeys: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The SSH key's id.

Request body

Field	Type	Notes
`name`	string	Not empty.
`description`	string or null
`lastUsedAt`	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PATCH https://cloudgate.octabyte.app/backend/ssh-keys/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "deploy-key",
    "description": "Storefront for Northwind Labs",
    "lastUsedAt": "2026-11-12T09:30:00.000Z"
  }'

Delete an SSH key

DELETE/ssh-keys/{id}

Who can call it: Owner or Admin. Needs sshKeys: delete, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The SSH key's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X DELETE https://cloudgate.octabyte.app/backend/ssh-keys/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Cloud accounts

Get Cloud account setup

POST/cloud-accounts/setup

Who can call it: Owner or Admin. Needs cloudAccount: create, which a custom role can also grant.

Request body

Field	Type	Notes
`cloud`	string	One of `gcp`.
`cloudId`required	string	Matches `^[a-z][a-z0-9-]{4,28}[a-z0-9]$`.
`setupToken`	string	Not empty.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/cloud-accounts/setup \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "cloudId": "LFoSspSeumwYSUG6WNUby"
  }'

List Cloud accounts

GET/cloud-accounts

Who can call it: Owner or Admin. Needs cloudAccount: read, which a custom role can also grant.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/cloud-accounts \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Create a Cloud account

POST/cloud-accounts

Who can call it: Owner or Admin. Needs cloudAccount: create, which a custom role can also grant.

Request body

Field	Type	Notes
`setupToken`required	string	Not empty.
`name`required	string	1 to 100 characters.
`cloud`	string	One of `gcp`.
`cloudId`required	string	Matches `^[a-z][a-z0-9-]{4,28}[a-z0-9]$`.
`accessKeyId`	string	Matches `^[A-Z0-9]{16,128}$`.
`secretAccessKey`	string	Not empty.
`deployRoleArn`	string	Matches `^arn:aws[a-z-]*:iam::(\d{12}):role\/[\w+=,.@/-]{1,512}$`.
`taskExecutionRoleArn`	string	Matches `^arn:aws[a-z-]*:iam::(\d{12}):role\/[\w+=,.@/-]{1,512}$`.
`workloadIdentityProvider`	string	Matches `^(?:\/\/iam\.googleapis\.com\/)?(projects\/\d+\/locations\/global\/workloadIdentityPools\/[a-z0-9-]{4,32}\/providers\/[a-z0-9-]{4,32})$`.
`deployServiceAccount`	string	Matches `^[a-z][a-z0-9-]{4,28}[a-z0-9]@[a-z0-9.:-]+\.iam\.gserviceaccount\.com$`.

Responses

201 Created: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/cloud-accounts \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "setupToken": "<secret>",
    "name": "northwind-aws",
    "cloudId": "LFoSspSeumwYSUG6WNUby",
    "accessKeyId": "LX9gSGg8HxwNdNS5TUbpc",
    "secretAccessKey": "<secret>",
    "deployRoleArn": "example",
    "taskExecutionRoleArn": "example"
  }'

Get a Cloud account

GET/cloud-accounts/{id}

Who can call it: Owner or Admin. Needs cloudAccount: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Cloud account's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/cloud-accounts/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Update a Cloud account

PATCH/cloud-accounts/{id}

Who can call it: Owner or Admin. Needs cloudAccount: update, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Cloud account's id.

Request body

Field	Type	Notes
`cloud`	string	One of `gcp`.
`name`	string	1 to 100 characters.
`accessKeyId`	string	Matches `^[A-Z0-9]{16,128}$`.
`secretAccessKey`	string	Not empty.
`deployRoleArn`	string	Matches `^arn:aws[a-z-]*:iam::(\d{12}):role\/[\w+=,.@/-]{1,512}$`.
`taskExecutionRoleArn`	string	Matches `^arn:aws[a-z-]*:iam::(\d{12}):role\/[\w+=,.@/-]{1,512}$`.
`workloadIdentityProvider`	string	Matches `^(?:\/\/iam\.googleapis\.com\/)?(projects\/\d+\/locations\/global\/workloadIdentityPools\/[a-z0-9-]{4,32}\/providers\/[a-z0-9-]{4,32})$`.
`deployServiceAccount`	string	Matches `^[a-z][a-z0-9-]{4,28}[a-z0-9]@[a-z0-9.:-]+\.iam\.gserviceaccount\.com$`.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PATCH https://cloudgate.octabyte.app/backend/cloud-accounts/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "cloud": "aws",
    "name": "northwind-aws",
    "accessKeyId": "LX9gSGg8HxwNdNS5TUbpc"
  }'

Delete a Cloud account

DELETE/cloud-accounts/{id}

Who can call it: Owner or Admin. Needs cloudAccount: delete, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Cloud account's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X DELETE https://cloudgate.octabyte.app/backend/cloud-accounts/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get the setup template

GET/cloud-accounts/{id}/template

The setup template (AWS) or script (Google) at the current version, for "permissions out of date" and a key change.

Who can call it: Owner or Admin. Needs cloudAccount: update, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Cloud account's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/cloud-accounts/RAU6yAYUXFRdXdPLyLoPC/template \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Check a Cloud account now

POST/cloud-accounts/{id}/check

Who can call it: Owner or Admin. Needs cloudAccount: update, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Cloud account's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/cloud-accounts/RAU6yAYUXFRdXdPLyLoPC/check \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Make a new key (Google Cloud)

POST/cloud-accounts/{id}/key

"New key" on a Google Cloud account: a new key pair, pending until a check signed with it passes, and the setup with a JWKS of both public halves. Nothing signs with it yet, so 200.

Who can call it: Owner or Admin. Needs cloudAccount: update, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Cloud account's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/cloud-accounts/RAU6yAYUXFRdXdPLyLoPC/key \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Check the new key

POST/cloud-accounts/{id}/key/check

The check signed with the pending key: a pass switches to it, a failure (400) changes nothing.

Who can call it: Owner or Admin. Needs cloudAccount: update, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Cloud account's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/cloud-accounts/RAU6yAYUXFRdXdPLyLoPC/key/check \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Cluster

Get nodes

GET/cluster/nodes

Who can call it: Owner or Admin. Needs server: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serverId`	query	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/cluster/nodes \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Add worker

GET/cluster/add-worker

Who can call it: Owner or Admin. Needs server: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serverId`	query	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/cluster/add-worker \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Add manager

GET/cluster/add-manager

Who can call it: Owner or Admin. Needs server: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serverId`	query	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/cluster/add-manager \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Remove worker

DELETE/cluster/nodes/{nodeId}

Who can call it: Owner or Admin. Needs server: delete, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`nodeId`required	path	string	The node's id. Not empty. Matches `^[a-zA-Z0-9.\-_]+$`.
`serverId`	query	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X DELETE https://cloudgate.octabyte.app/backend/cluster/nodes/RyQdjwrNeb3aZNKkK3HMv \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Swarm

Get nodes

GET/swarm/nodes

Who can call it: Owner or Admin. Needs server: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serverId`	query	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/swarm/nodes \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get node info

GET/swarm/nodes/{nodeId}

Who can call it: Owner or Admin. Needs server: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`nodeId`required	path	string	The node's id. Not empty. Matches `^[a-zA-Z0-9.\-_]+$`.
`serverId`	query	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/swarm/nodes/RyQdjwrNeb3aZNKkK3HMv \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get node apps

GET/swarm/apps

Who can call it: Owner or Admin. Needs server: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serverId`	query	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/swarm/apps \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get app infos

GET/swarm/apps/info

Who can call it: Owner or Admin. Needs server: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`appName`	query	array of string
`serverId`	query	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/swarm/apps/info \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get container stats

GET/swarm/stats

Who can call it: Owner or Admin. Needs server: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serverId`	query	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/swarm/stats \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Containers

Get containers

GET/docker/containers

Who can call it: Owner or Admin. Needs docker: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serverId`	query	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/docker/containers \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get containers by owner label

GET/docker/containers/search

Who can call it: Owner, Admin or Member. Needs service: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`appName`required	query	string	Not empty. Matches `^[a-zA-Z0-9.\-_]+$`.
`appType`	query	string	One of `stack`, `docker-compose`.
`serverId`	query	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl "https://cloudgate.octabyte.app/backend/docker/containers/search?appName=example" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get containers by app label

GET/docker/containers/by-label

Who can call it: Owner or Admin. Needs docker: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`appName`required	query	string	Not empty. Matches `^[a-zA-Z0-9.\-_]+$`.
`type`required	query	string	One of `standalone`, `swarm`.
`serverId`	query	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl "https://cloudgate.octabyte.app/backend/docker/containers/by-label?appName=example&type=example" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get stack containers by app name

GET/docker/containers/stack

Who can call it: Owner or Admin. Needs docker: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`appName`required	query	string	Not empty. Matches `^[a-zA-Z0-9.\-_]+$`.
`serverId`	query	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl "https://cloudgate.octabyte.app/backend/docker/containers/stack?appName=example" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get service containers by app name

GET/docker/containers/service

Who can call it: Owner or Admin. Needs docker: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`appName`required	query	string	Not empty. Matches `^[a-zA-Z0-9.\-_]+$`.
`serverId`	query	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl "https://cloudgate.octabyte.app/backend/docker/containers/service?appName=example" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get service running containers

GET/docker/services/{serviceType}/{serviceId}/containers

A Service's running containers, for its Shell tab.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Parameters

Name	In	Type	Notes
`serviceType`required	path	string	Service type. One of `application`, `postgres`, `mysql`, `mariadb`, `mongo`, `redis`, `compose`, `libsql`.
`serviceId`required	path	string	The Service's id. Not empty.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/docker/services/application/ikGaJLrdLoCZDcimNaVV3/containers \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get config

GET/docker/containers/{containerId}/config

Who can call it: Owner or Admin. Needs docker: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`containerId`required	path	string	The container's id. Not empty. Matches `^[a-zA-Z0-9.\-_]+$`.
`serverId`	query	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/docker/containers/Y7q4jyCHZuvUeEBovMvby/config \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Restart container

POST/docker/containers/{containerId}/restart

Who can call it: Owner or Admin. Needs docker: write, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`containerId`required	path	string	The container's id. Not empty. Matches `^[a-zA-Z0-9.\-_]+$`.

Request body

Field	Type	Notes
`serverId`	string or null

Responses

204 No content: Done. The answer has no body.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/docker/containers/Y7q4jyCHZuvUeEBovMvby/restart \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "serverId": "Ni7mAbWKjbWy4KErPjtrY"
  }'

Start container

POST/docker/containers/{containerId}/start

Who can call it: Owner or Admin. Needs docker: write, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`containerId`required	path	string	The container's id. Not empty. Matches `^[a-zA-Z0-9.\-_]+$`.

Request body

Field	Type	Notes
`serverId`	string or null

Responses

204 No content: Done. The answer has no body.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/docker/containers/Y7q4jyCHZuvUeEBovMvby/start \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "serverId": "Ni7mAbWKjbWy4KErPjtrY"
  }'

Stop container

POST/docker/containers/{containerId}/stop

Who can call it: Owner or Admin. Needs docker: write, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`containerId`required	path	string	The container's id. Not empty. Matches `^[a-zA-Z0-9.\-_]+$`.

Request body

Field	Type	Notes
`serverId`	string or null

Responses

204 No content: Done. The answer has no body.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/docker/containers/Y7q4jyCHZuvUeEBovMvby/stop \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "serverId": "Ni7mAbWKjbWy4KErPjtrY"
  }'

Kill container

POST/docker/containers/{containerId}/kill

Who can call it: Owner or Admin. Needs docker: write, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`containerId`required	path	string	The container's id. Not empty. Matches `^[a-zA-Z0-9.\-_]+$`.

Request body

Field	Type	Notes
`serverId`	string or null

Responses

204 No content: Done. The answer has no body.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/docker/containers/Y7q4jyCHZuvUeEBovMvby/kill \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "serverId": "Ni7mAbWKjbWy4KErPjtrY"
  }'

Remove container

DELETE/docker/containers/{containerId}

Who can call it: Owner or Admin. Needs docker: write, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`containerId`required	path	string	The container's id. Not empty. Matches `^[a-zA-Z0-9.\-_]+$`.
`serverId`	query	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X DELETE https://cloudgate.octabyte.app/backend/docker/containers/Y7q4jyCHZuvUeEBovMvby \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Upload file to container

POST/docker/containers/{containerId}/upload

Who can call it: Owner or Admin. Needs docker: write, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`containerId`required	path	string	The container's id. Not empty. Matches `^[a-zA-Z0-9.\-_]+$`.

Request body

Field	Type	Notes
`destinationPath`required	string	Not empty.
`serverId`	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/docker/containers/Y7q4jyCHZuvUeEBovMvby/upload \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "destinationPath": "/"
  }'

Traefik

Config status

GET/traefik/config-status

Who can call it: Owner, Admin or Member. Needs service: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`applicationId`required	query	string	Not empty.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl "https://cloudgate.octabyte.app/backend/traefik/config-status?applicationId=j9ct9tCzxUD9FjoxV2gtc" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Console config status

GET/traefik/config-status/console

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/traefik/config-status/console \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Something missing or wrong on this page? Email support@octabyte.io, or start a free trial and try it in the console.