Projects, Environments and Plans

Projects, Environments, Templates, Project config, Plans and the variables wired between Services.

A Project groups the Environments of one product, and each Environment holds its Services. A Project config (cloudgate.yaml) describes the Services; Cloudgate turns a change into a Plan you review and apply.

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 Projects and Environments in the user guide.

Projects

List Projects

GET/projects

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/projects \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Create a Project

POST/projects

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

Request body

Field	Type	Notes
`name`required	string	Not empty.
`description`	string
`env`	string

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/projects \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "storefront"
  }'

Get a Project

GET/projects/{id}

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
`id`required	path	string	The Project's id.

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/projects/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Update a Project

PATCH/projects/{id}

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
`id`required	path	string	The Project's id.

Request body

Field	Type	Notes
`name`	string	Not empty.
`description`	string
`env`	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 You may not reach what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PATCH https://cloudgate.octabyte.app/backend/projects/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "storefront",
    "description": "Storefront for Northwind Labs",
    "env": "NODE_ENV=production"
  }'

Delete a Project

DELETE/projects/{id}

?force=true is the escape hatch for a Server that is gone for good: it deletes the Project even though Cloudgate could not confirm every Service under it is torn down, and the response names each workload left behind. Default false, a string query parameter compared to 'true' like the force on all eight per-Service delete routes.

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

Parameters

Name	In	Type	Notes
`id`required	path	string	The Project's id.
`force`required	query	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 DELETE "https://cloudgate.octabyte.app/backend/projects/RAU6yAYUXFRdXdPLyLoPC?force=example" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Environments

List Environments for a Project

GET/environments

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
`projectId`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 You may not reach what it touches. The error body.

curl "https://cloudgate.octabyte.app/backend/environments?projectId=VxDmR4XpiQmCSASM7JYyc" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Create an Environment

POST/environments

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

Request body

Field	Type	Notes
`name`required	string	Not empty.
`description`	string
`projectId`required	string	Not empty.
`env`	string
`deployTarget`	object
`deployTarget.kind`required	string	One of `cloud`.
`deployTarget.serverId`	string	Not empty.
`deployTarget.cloudAccountId`	string	Not empty.
`deployTarget.region`	string	Not empty.
`configBranch`	string or null	Up to 255 characters. Matches `^$\|^(?!-)(?!.\.\.)(?!.\/\/)[^\s~^:?*[\\]+(?<![./])$`.

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/environments \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "production",
    "projectId": "VxDmR4XpiQmCSASM7JYyc"
  }'

Get an Environment

GET/environments/{id}

The environment plus the services deployed in it.

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
`id`required	path	string	The Environment's id.

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/environments/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Update an Environment

PATCH/environments/{id}

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
`id`required	path	string	The Environment's id.

Request body

Field	Type	Notes
`name`	string	Not empty.
`description`	string
`env`	string
`deployTarget`	object
`deployTarget.kind`required	string	One of `cloud`.
`deployTarget.serverId`	string	Not empty.
`deployTarget.cloudAccountId`	string	Not empty.
`deployTarget.region`	string	Not empty.
`configBranch`	string or null	Up to 255 characters. Matches `^$\|^(?!-)(?!.\.\.)(?!.\/\/)[^\s~^:?*[\\]+(?<![./])$`.

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 You may not reach what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PATCH https://cloudgate.octabyte.app/backend/environments/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "production",
    "description": "Storefront for Northwind Labs",
    "env": "NODE_ENV=production"
  }'

Delete an Environment

DELETE/environments/{id}

?force=true is the escape hatch for a Server that is gone for good: it deletes the Environment even though Cloudgate could not confirm every Service in it is torn down, and the response names each workload left behind.

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

Parameters

Name	In	Type	Notes
`id`required	path	string	The Environment's id.
`force`required	query	string
`deleteData`required	query	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 DELETE "https://cloudgate.octabyte.app/backend/environments/RAU6yAYUXFRdXdPLyLoPC?force=example&deleteData=example" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

List Deployments in an Environment

GET/environments/{id}/deployments

Every Deployment of every service in this Environment.

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

Parameters

Name	In	Type	Notes
`id`required	path	string	The Environment'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/environments/RAU6yAYUXFRdXdPLyLoPC/deployments \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

List networks in an Environment

GET/environments/{id}/networks

The Environment's networks in Cloud accounts, with status and idle cost.

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
`id`required	path	string	The Environment's id.

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/environments/RAU6yAYUXFRdXdPLyLoPC/networks \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

List Domains in an Environment

GET/environments/{id}/domains

Every domain answered by a service in this Environment.

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

Parameters

Name	In	Type	Notes
`id`required	path	string	The Environment'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/environments/RAU6yAYUXFRdXdPLyLoPC/domains \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

List health in an Environment

GET/environments/{id}/health

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

Parameters

Name	In	Type	Notes
`id`required	path	string	The Environment'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/environments/RAU6yAYUXFRdXdPLyLoPC/health \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Retry deleting an Environment

POST/environments/{id}/delete/retry

Retry an Environment's incomplete Delete in a Cloud account: its cloud Services' Deletes and its networks' removals again, from the kept states.

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

Parameters

Name	In	Type	Notes
`id`required	path	string	The Environment'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/environments/RAU6yAYUXFRdXdPLyLoPC/delete/retry \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Forget the incomplete delete of an Environment

POST/environments/{id}/delete/forget

Forget an Environment's incomplete Delete: its rows dropped, what is left in AWS written into the audit entry.

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

Parameters

Name	In	Type	Notes
`id`required	path	string	The Environment'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/environments/RAU6yAYUXFRdXdPLyLoPC/delete/forget \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Templates

List Templates

GET/templates

The Template catalogue as this instance offers it, and the saved copy it came from.

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
`baseUrl`	query	any

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 You may not reach what it touches. The error body.

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

List Template tags

GET/templates/tags

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
`baseUrl`	query	any

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 You may not reach what it touches. The error body.

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

Get a Template setup form

GET/templates/{templateId}/setup

The setup form: the template's asked values, and each of a Project's Environments with whether it can take the template, and why not.

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
`templateId`required	path	string	The template's id.
`projectId`	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 You may not reach what it touches; 404 Nothing with that id in this Organization. The error body.

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

Set up a Template

POST/templates/setup

Sets a Template up: writes its Pending setup and Setup record, adds its renamed entries to the config and opens the Plan.

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

Request body

Field	Type	Notes
`projectId`	string	Not empty.
`templateId`required	string	Not empty.
`environmentId`	string	Not empty.
`newProject`	object
`newProject.name`required	string	Not empty.
`newProject.deployTarget`	object
`newProject.deployTarget.kind`required	string	One of `cloud`.
`newProject.deployTarget.serverId`	string	Not empty.
`newProject.deployTarget.cloudAccountId`	string	Not empty.
`newProject.deployTarget.region`	string	Not empty.
`setupName`required	string	Not empty.
`values`	map of string	Default `{}`.
`hosts`	map of string	Default `{}`.
`autoApply`	boolean

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/templates/setup \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "templateId": "EFf3wDYHXvEABzcMdbj87",
    "setupName": "example"
  }'

Pending setups

List pending setups

GET/environments/{environmentId}/pending-setups

The Environment's Pending setups, each value as present only, and the notes of those the 30-day sweep dropped.

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

Parameters

Name	In	Type	Notes
`environmentId`required	path	string	The Environment'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/environments/UVFRqyCfWEtSm6NdDvrZc/pending-setups \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Delete a pending setup

DELETE/environments/{environmentId}/pending-setups/{pendingSetupId}

Cancels one Pending setup; answers it, and the plan made again.

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

Parameters

Name	In	Type	Notes
`environmentId`required	path	string	The Environment's id.
`pendingSetupId`required	path	string	The pending setup'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/environments/UVFRqyCfWEtSm6NdDvrZc/pending-setups/JtMYMUJfYPfSAYho98iCz \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Project config

Get a Project config

GET/projects/{projectId}/config

The config's location, its version and, kept in Cloudgate, its text: what a working copy is downloaded from.

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
`projectId`required	path	string	The Project's id.

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/projects/VxDmR4XpiQmCSASM7JYyc/config \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Make Plans from a Project config

POST/projects/{projectId}/config/plans

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

Parameters

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

Request body

Field	Type	Notes
`text`required	string	1 to 262144 characters.
`version`	integer	At least 0. More than true.

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; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/projects/VxDmR4XpiQmCSASM7JYyc/config/plans \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "text": "example"
  }'

Preview moving a Project config

POST/projects/{projectId}/config/move/preview

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

Parameters

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

Request body

Field	Type	Notes
`to`required	object
`to.kind`required	string	One of `repository`.
`to.fromEnvironmentId`	string or null	Not empty.
`to.gitProviderId`	string	Not empty.
`to.repository`	string	Up to 512 characters. Matches `^[^/\s]+(\/[^/\s]+)+$`.
`to.path`	string	Up to 1024 characters. Matches `^(?!\/)(?!(.*\/)?\.\.?(\/\|$))[^\s\\]+$`.

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/projects/VxDmR4XpiQmCSASM7JYyc/config/move/preview \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "to": {
      "kind": "cloudgate"
    }
  }'

Move a Project config

POST/projects/{projectId}/config/move

A move's confirm: refused if the preview's reads changed; switches the location, dismisses the open plans and stores the previewed ones open; a move out also stores the kept copy and clears every Config branch. Applies nothing.

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

Parameters

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

Request body

Field	Type	Notes
`to`required	object
`to.kind`required	string	One of `repository`.
`to.fromEnvironmentId`	string or null	Not empty.
`to.gitProviderId`	string	Not empty.
`to.repository`	string	Up to 512 characters. Matches `^[^/\s]+(\/[^/\s]+)+$`.
`to.path`	string	Up to 1024 characters. Matches `^(?!\/)(?!(.*\/)?\.\.?(\/\|$))[^\s\\]+$`.
`reads`required	array of object	Up to 1000 items.
`reads[].environmentId`required	string	Not empty.
`reads[].commitSha`required	string or null	Not empty.
`reads[].textHash`required	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; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/projects/VxDmR4XpiQmCSASM7JYyc/config/move \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "to": {
      "kind": "cloudgate"
    },
    "reads": [
      {
        "environmentId": "UVFRqyCfWEtSm6NdDvrZc",
        "commitSha": "example",
        "textHash": "example"
      }
    ]
  }'

Project config schema

Get the Project config schema

GET/schema/project-config/v1.json

The schema; anyone may read it.

Who can call it: Public: no key needed.

Responses

200 OK: The draft-07 JSON Schema of a version 1 Project config

curl https://cloudgate.octabyte.app/backend/schema/project-config/v1.json

Plans

Get an Environment's config copy

GET/environments/{environmentId}/config

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

Parameters

Name	In	Type	Notes
`environmentId`required	path	string	The Environment'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/environments/UVFRqyCfWEtSm6NdDvrZc/config \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

List repository-sourced Services

GET/environments/{environmentId}/config/repository-sources

The Services whose source the config, as this Environment reads it, names as a repository: cloudgate deploy refuses to upload to one. Only Config names, providers and repositories; never the text.

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

Parameters

Name	In	Type	Notes
`environmentId`required	path	string	The Environment'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.

Fields of the `200` answer
Field	Type	Notes
`keptIn`always	string or null	One of `cloudgate`, `repository`, `null`.
`readable`always	boolean
`services`always	array of object
`services[].configName`always	string
`services[].provider`always	string
`services[].repository`always	string

curl https://cloudgate.octabyte.app/backend/environments/UVFRqyCfWEtSm6NdDvrZc/config/repository-sources \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

List where each config entry's code comes from

GET/environments/{environmentId}/config/sources

Every entry of the config, as this Environment reads it, and where its code comes from: a root cloudgate deploy in a Project folder builds the ones from a subfolder of it. Never the text.

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

Parameters

Name	In	Type	Notes
`environmentId`required	path	string	The Environment'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.

Fields of the `200` answer
Field	Type	Notes
`keptIn`always	string or null	One of `cloudgate`, `repository`, `null`.
`readable`always	boolean
`services`always	array of object
`services[].configName`always	string
`services[].kind`always	string
`services[].source`always	string	One of `folder`, `repository`, `image`, `console`, `none`.
`services[].folder`always	string or null

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

Get an Environment's Plan

GET/environments/{environmentId}/plan

The open plan, else the latest, else { plan: null }.

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

Parameters

Name	In	Type	Notes
`environmentId`required	path	string	The Environment'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/environments/UVFRqyCfWEtSm6NdDvrZc/plan \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Check for changes (make a Plan)

POST/environments/{environmentId}/plan

"Check for changes": makes a plan, which replaces the open one.

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

Parameters

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

Responses

201 Created: 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/environments/UVFRqyCfWEtSm6NdDvrZc/plan \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Dismiss the open Plan

POST/environments/{environmentId}/plan/dismiss

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

Parameters

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

Request body

Field	Type	Notes
`planId`required	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; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/environments/UVFRqyCfWEtSm6NdDvrZc/plan/dismiss \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "planId": "TDA7nK94CPMWcM9WinnP5"
  }'

Apply the open Plan

POST/environments/{environmentId}/plan/apply

Applies the open plan: creates, changes, then confirmed destroys, each on its own.

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

Parameters

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

Request body

Field	Type	Notes
`planId`required	string	Not empty.
`confirmDestroy`	array of string	Up to 1000 items. Default `[]`.
`confirmUpgrade`	array of string	Up to 1000 items. Default `[]`.
`deleteFilesOf`	array of string	Up to 1000 items. Default `[]`.
`deleteDataOf`	array of string	Up to 1000 items. Default `[]`.
`folderSourcesDeployedNext`	boolean	Default `false`.

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/environments/UVFRqyCfWEtSm6NdDvrZc/plan/apply \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "planId": "TDA7nK94CPMWcM9WinnP5"
  }'

Wired variables

Get a Service's wired variables

GET/services/{serviceType}/{serviceId}/links

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

Parameters

Name	In	Type	Notes
`serviceType`required	path	string	Service type.
`serviceId`required	path	string	The Service'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/services/application/ikGaJLrdLoCZDcimNaVV3/links \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Set a Service's wired variables

PUT/services/{serviceType}/{serviceId}/links

Sets the whole set of links, as a console Save of a Cloudgate-kept config. PROJECT_CONFIG_REPOSITORY_KEPT (409, with a pointer) on a repository-kept one, LINK_NEEDS_PROJECT_CONFIG where there is none, LINK_REFUSED for a link its plan would refuse.

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

Parameters

Name	In	Type	Notes
`serviceType`required	path	string	Service type.
`serviceId`required	path	string	The Service's id.

Request body

Field	Type	Notes
`links`required	array of object	Up to 200 items.
`links[].name`required	string	Matches `^[^\s=]+$`.
`links[].source`required	string	Matches `^[a-z][a-z0-9-]{0,62}$`.
`links[].output`required	string	Matches `^[a-z][a-z_]*$`.

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 PUT https://cloudgate.octabyte.app/backend/services/application/ikGaJLrdLoCZDcimNaVV3/links \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "links": [
      {
        "name": "storefront",
        "source": "example",
        "output": "example"
      }
    ]
  }'

Network cloud resources

List network cloud resources

GET/environments/{id}/networks/{networkId}/resources

What Cloudgate made for the network: type, AWS id, region and tags only.

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

Parameters

Name	In	Type	Notes
`id`required	path	string	The network cloud resource's id.
`networkId`required	path	string	The network'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/environments/RAU6yAYUXFRdXdPLyLoPC/networks/58NEZf7DioTCmGut6EJ3y/resources \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Rebuild a network cloud resource

POST/environments/{id}/networks/{networkId}/state/rebuild

Discards an unreadable state and plans an adopt by tag; confirmed by the Environment's name.

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

Parameters

Name	In	Type	Notes
`id`required	path	string	The network cloud resource's id.
`networkId`required	path	string	The network's id.

Request body

Field	Type	Notes
`confirmName`required	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; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/environments/RAU6yAYUXFRdXdPLyLoPC/networks/58NEZf7DioTCmGut6EJ3y/state/rebuild \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "confirmName": "example"
  }'

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