State Service

The state service.

Endpoints

Build Executions

GET
/api/v1/builds/executions/
List all the visible build executions for the requesting user.
GET
/api/v1/state/{project}/builds/executions/
Get the build executions by project.
GET
/api/v1/state/{project}/environments/{environment}/builds/by-name/{build}/executions/
Get the build executions.
GET
/api/v1/state/{project}/environments/{environment}/builds/by-name/{build}/executions/{build_execution_id}/
Get the build executions.
/api/v1/state/{project}/environments/{environment}/builds/by-name/{build}/executions/{build_execution_id}/cancel
Request that build execution is cancelled
PUT
/api/v1/state/{project}/environments/{environment}/builds/by-name/{build}/executions/{build_execution_id}/commit
Add commit information to a build execution
GET
/api/v1/state/{project}/environments/{environment}/builds/by-name/{build}/executions/{build_execution_id}/logs
Get build logs
/api/v1/state/{project}/environments/{environment}/builds/by-name/{build}/executions/{build_execution_id}/logs
Add build logs to a build execution item.
GET
/api/v1/state/{project}/environments/{environment}/builds/by-name/{build}/executions/{build_execution_id}/logs_ws
Real time build logs
/api/v1/state/{project}/environments/{environment}/builds/by-name/{build}/executions/{build_execution_id}/retry
Retry a finished build.

Builds

GET
/api/v1/builds/
List all the visible builds for the requesting user.
GET
/api/v1/state/{project}/builds/
Get the builds in the project.
GET
/api/v1/state/{project}/environments/{environment}/builds/
Get the builds in the environment.
/api/v1/state/{project}/environments/{environment}/builds/
Add a new build to the environment.
GET
/api/v1/state/{project}/environments/{environment}/builds/by-name/{build}/
Get the build.
PUT
/api/v1/state/{project}/environments/{environment}/builds/by-name/{build}/
Update a build. To update the private_key the update_private_key is also required to be set
DELETE
/api/v1/state/{project}/environments/{environment}/builds/by-name/{build}/
Delete a build.
/api/v1/state/{project}/environments/{environment}/builds/by-name/{build}/trigger-build
Trigger the build.
/api/v1/state/{project}/environments/{environment}/builds/webhook/{code}
Get the build.

Deployment Job Executions

GET
/api/v1/deployment-jobs/by-project/{project}/by-environment/{environment}/by-name/{deployment}/executions/
List all the visible deployment job executions for deployment job.
GET
/api/v1/deployment-jobs/by-project/{project}/by-environment/{environment}/by-name/{deployment}/executions/{execution_id}/
Get deployment job execution
/api/v1/deployment-jobs/by-project/{project}/by-environment/{environment}/by-name/{deployment}/executions/{execution_id}/cancel
Request that deployment job execution is cancelled
GET
/api/v1/deployment-jobs/by-project/{project}/by-environment/{environment}/by-name/{deployment}/executions/{execution_id}/logs
Get deployment job logs
/api/v1/deployment-jobs/by-project/{project}/by-environment/{environment}/by-name/{deployment}/executions/{execution_id}/logs
Add logs to a deployment job execution item.
GET
/api/v1/deployment-jobs/by-project/{project}/by-environment/{environment}/by-name/{deployment}/executions/{execution_id}/logs_ws
Real time deployment job logs
/api/v1/deployment-jobs/by-project/{project}/by-environment/{environment}/by-name/{deployment}/executions/{execution_id}/retry
Retry a finished deployment job.
GET
/api/v1/deployment-jobs/by-project/{project}/executions/
Get the deployment job executions by project.
GET
/api/v1/deployment-jobs/executions/
List all the visible deployment job executions for the requesting user.

Deployment Jobs

GET
/api/v1/deployment-jobs/
List all the visible deployment jobs for the requesting user.
GET
/api/v1/deployment-jobs/by-project/{project}/
Get deployment jobs by project
/api/v1/deployment-jobs/by-project/{project}/add
Add a new deployment job
GET
/api/v1/deployment-jobs/by-project/{project}/by-environment/{environment}/
Get deployment jobs by environment.
GET
/api/v1/deployment-jobs/by-project/{project}/by-environment/{environment}/by-name/{deployment}/
Get a deployment job.
PUT
/api/v1/deployment-jobs/by-project/{project}/by-environment/{environment}/by-name/{deployment}/
Update a deployment job.
DELETE
/api/v1/deployment-jobs/by-project/{project}/by-environment/{environment}/by-name/{deployment}/
Delete a deployment job.
/api/v1/deployment-jobs/by-project/{project}/by-environment/{environment}/by-name/{deployment}/trigger
Trigger a deployment job.
/api/v1/deployment-jobs/by-project/{project}/by-environment/{environment}/by-name/{deployment}/trigger/destroy
Request to destroy a deployment.
/api/v1/deployment-jobs/by-project/{project}/by-environment/{environment}/by-name/{deployment}/trigger/errand
Request to run an errand on a deployment.
/api/v1/deployment-jobs/by-project/{project}/by-environment/{environment}/by-name/{deployment}/trigger/smoke
Request to rerun smoke tests on a deployment.

Environments

/api/v1/state/{project}/change-environment-order
Change the order of environments
/api/v1/state/{project}/environments/
Add a new environment
GET
/api/v1/state/{project}/environments/{environment}/
Get an environment and its deployments
PUT
/api/v1/state/{project}/environments/{environment}/
Update environment metadata.
DELETE
/api/v1/state/{project}/environments/{environment}/
Hard delete an environment.
GET
/api/v1/state/{project}/environments/{environment}/providers/
Get providers present in the environment.

Internal

GET
/
Home
GET
/health
Healthcheck endpoint

Pipeline Executions

GET
/api/v1/pipelines/by-project/{project}/by-name/{pipeline}/executions/
Get a pipeline's executions.
GET
/api/v1/pipelines/by-project/{project}/by-name/{pipeline}/executions/{pipeline_execution_id}/
Get the pipeline execution.
/api/v1/pipelines/by-project/{project}/by-name/{pipeline}/executions/{pipeline_execution_id}/cancel
Request that pipeline execution is cancelled
GET
/api/v1/pipelines/by-project/{project}/by-name/{pipeline}/executions/{pipeline_execution_id}/confirmation/{code}/approve
Confirm pipeline step
GET
/api/v1/pipelines/by-project/{project}/by-name/{pipeline}/executions/{pipeline_execution_id}/confirmation/{code}/disapprove
Confirm pipeline step
/api/v1/pipelines/by-project/{project}/by-name/{pipeline}/executions/{pipeline_execution_id}/retry
Retry the pipeline.
GET
/api/v1/pipelines/by-project/{project}/executions/
Get the pipeline executions by project.

Pipelines

GET
/api/v1/pipelines/
Get all visible pipelines.
GET
/api/v1/pipelines/by-project/{project}/
Get pipelines by project
/api/v1/pipelines/by-project/{project}/add
Add a new pipeline
GET
/api/v1/pipelines/by-project/{project}/by-name/{pipeline}/
Get a pipeline.
PUT
/api/v1/pipelines/by-project/{project}/by-name/{pipeline}/
Update a pipeline.
DELETE
/api/v1/pipelines/by-project/{project}/by-name/{pipeline}/
Delete a pipeline.
/api/v1/pipelines/by-project/{project}/by-name/{pipeline}/trigger
Trigger a pipeline.
/api/v1/pipelines/by-project/{project}/pipelines/webhook/{code}
Trigger webhook
GET
/api/v1/pipelines/executions/
Get all visible pipeline executions.

Project Namespaces

GET
/api/v1/state/namespaces
Get all namespaces for this user
/api/v1/state/{project}/add-namespace
Add a namespace to this project
GET
/api/v1/state/{project}/namespaces/
Get namespaces for this project

Projects

GET
/api/v1/state/
List a user's state projects
GET
/api/v1/state/__get_projects_by_group
Get projects by group name
GET
/api/v1/state/{project}/
Get a state project and its environments.
PUT
/api/v1/state/{project}/
Update a project's metadata.
DELETE
/api/v1/state/{project}/
Hard delete a state project.
/api/v1/state/{project}/add-project
Add a state project.
GET
/api/v1/state/{project}/can-manage-subscriptions
Can user manage project subscriptions?
/api/v1/state/{project}/import-environments
Import environments from a local state file.
GET
/api/v1/state/{project}/logo
Get a state project's logo.
GET
/api/v1/state/{project}/rbac/valid-roles
See the valid roles that can be assigned with this endpoint.
GET
/api/v1/state/{project}/service-accounts/
Retrieve service accounts that have access to this project
/api/v1/state/{project}/service-accounts/{name}/
Add a service account to a project
DELETE
/api/v1/state/{project}/service-accounts/{name}/
Delete a service account from this project

Repositories

GET
/api/v1/state/{project}/repositories/
Retrieve repositories that are associated to this project
/api/v1/state/{project}/repositories/add-repository
Add a repository to this project
PUT
/api/v1/state/{project}/repositories/{name}/
Update a repository that is associated to this project
DELETE
/api/v1/state/{project}/repositories/{name}/
Delete a repository that is associated to this project

State

GET
/api/v1/state/{project}/environments/{environment}/deployments/
Get a deployment.
/api/v1/state/{project}/environments/{environment}/deployments/
Add a deployment.
PUT
/api/v1/state/{project}/environments/{environment}/deployments/
Update a deployment.
DELETE
/api/v1/state/{project}/environments/{environment}/deployments/
Hard delete a deployment.

Schemas

Build

Description:
Describes a build and its steps.
Type:
object
FieldTypeDescriptionExample
branch
string
The branch of the code repository to pull from.
disabled
bool
Disable this build from executing.
environment
string
The state project environment (read-only)
escape_auth_token
string
The Escape authentication token to use for this build.
id
string
The internal build ID (read-only)
name
string
The name of the build.
private_key
string
The private key (if any) to use to pull the repository.
project
string
The state project (read-only)
remote_escape_worker_url
string
A URL for a remote Escape worker.
repo
string
The code repository to pull from.
service_account_name
string
The name of the service account used for this build.
service_account_team
string
The team of the service account used for this build.
status
enum
Build status. Read only.
"new"
"pending"
"running"
"ok"
"failed"
steps[BuildStep]
steps_from_yml
bool
Steps are defined in repositry as code.
update_private_key
bool
Only used for PUTs. Whether or not to update the private key.
webhook_token
string
A read-only token for the buildNotification webhook.

BuildExecution

Description:
Type:
object
FieldTypeDescriptionExample
id
string
(Read only) the build exeution ID.

BuildExecutions

Description:

Builds

Description:
Build map keyed by Build name.
Type:
{
string
: Build }

BuildStep

Description:
Type:
object
FieldTypeDescriptionExample
build_on_file_changes[
string
]
Build step when these files are changed.
cache_release
bool
Should the release be cached?
fat_package
bool
Should the build a fat package?
force_overwrite
bool
Should the release be pushed forcefully?
ignore_file_changes[
string
]
Ignore these files changes when determing whether ot build a step or not.
override_namespace
string
Override the namespace of the release
plan_location
string
The location of the Escape plan.
providers{
string
: DeploymentName }
Provider mapping
push_release
bool
Should the release be pushed?
run_build
bool
Should the build step be run?
run_deploy
bool
Should the deploy step be run?
run_destroy
bool
Should the destroy step be run?
run_destroy_build
bool
Should the destroy build step be run?
run_destroy_deploy
bool
Should the destroy deploy step be run?
run_smoke
bool
Should the smoke step be run?
run_tests
bool
Should the test and smoke step be run?
skip_if_exists
bool
Should the build be run if the release already exists?
tag_git
bool
Tag the current commit with the version upon a successful release?
variables{
string
:
string
}
Variable mapping

DeploymentJob

Description:
Type:
object
FieldTypeDescriptionExample
id
string
name
string

DeploymentJobExecution

Description:
Type:
object
FieldTypeDescriptionExample
deployment_jobDeploymentJob
id
string

DeploymentJobExecutions

Description:

DeploymentJobs

Description:

DeploymentName

Description:
Type:
string

ExecutionID

Description:
This payload is usally returned for the trigger endpoints.
Type:
object
FieldTypeDescriptionExample
id
string
The execution ID

Namespace

Description:
Namespace.
Type:
object
FieldTypeDescriptionExample
description
string
Optional namespace description.
logo
string
Optional namespace logo.
name
string
The namespace name.
org_url
string
Optional namespace organisation URL.
project
string
The namespace project.

NamespacePayload

Description:
Type:
object
FieldTypeDescriptionExample
permission
string
The user's permission on this namespace.
project
string
The project this namespace is owned by.

NamespacesPayload

Description:
Namespaces payload.
Type:
object
FieldTypeDescriptionExample
namespaces{
string
: NamespacePayload }
pipeline

Pipeline

Description:
Type:
object
FieldTypeDescriptionExample
disabled
bool
Disable this pipeline from executing.
name
string
The name of the pipeline
permission
enum
A permission. One of read, write, owner.
"read"
"write"
"owner"
phases[PipelinePhase]phases
project
string
The state project this pipeline is part of.
service_account_name
string
The name of the service account used for this pipeline.
status
enum
Pipeline status. Read only.
"new"
"pending"
"running"
"ok"
"failed"
triggers[PipelineTrigger]Triggers to start the pipeline

PipelineExecution

Description:
Type:
object
FieldTypeDescriptionExample
pipelinePipelinepipeline
run_nr
int
run_nr
status
enum
Pipeline status.
"new"
"pending"
"running"
"ok"
"failed"

PipelinePhase

Description:
Type:
object
FieldTypeDescriptionExample
name
string
The name of the phase
status
enum
Pipeline status. Read only.
"new"
"pending"
"running"
"ok"
"failed"
steps[PipelineStep]steps

PipelineStep

Description:
Type:
object
FieldTypeDescriptionExample
application
string
Tag release step - name of application in namepsace
build
string
build
deployment
string
deployment
environment
string
environment
errand_inputs
object
inputs for the errand.
errand_name
string
name for the errand.
ignore_failure
bool
Ignore the result of pipeline.
name
string
namespace
string
Tag release step - namespace
pipeline
string
pipeline
project
string
project
status
enum
Pipeline status. Read only.
"queued"
"new"
"pending"
"running"
"ok"
"failed"
tag
string
Tag release step - tag name
tag_tagged_version
string
Tag release step - The name of tag on tagged version
tag_version
enum
Tag release step - Which version of application to tag
"highest-version-in-pipeline"
"last-version-in-pipeline"
"tagged-version"
team
string
Confirmation step - team
trigger_pipeline_on_build
bool
Trigger pipeline on build.
trigger_pipeline_on_deploy
bool
Trigger pipeline on deploy.
type
enum
type
"build"
"pipeline-trigger"
"webhook-trigger"
"confirmation"
"deploy"
"run-smoke"
"run-destroy"
"run-errand"
update_version
enum
should update deployment job version.
"dont-update"
"last-version-in-pipeline"
"latest-version"
"version-from-deployment-job"
"tagged-version"
update_version_deployment
string
should use deployment job's version.
update_version_environment
string
should use deployment job's version.
user
string
Confirmation step - user
wait_for_pipeline
bool
Wait for pipeline to finish.
webhook_url
string
Trigger webhook as step

PipelineTrigger

Description:
Type:
object
FieldTypeDescriptionExample
id
string
The internal build ID (read-only)
type
enum
type
"webhook"
webhooktoken
string
webhook token

StateBuilds

Description:
Environment builds keyed by environment name.
Type:
{
string
: Builds }

UserBuilds

Description:
Builds keyed by project name.
Type:
{
string
: StateBuilds }