Overview
API
Request a demo
API Documentation

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.
POST
/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
POST
/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
POST
/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.
POST
/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.
POST
/api/v1/state/{project}/environments/{environment}/builds/by-name/{build}/trigger-build
Trigger the build.
POST
/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
POST
/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
POST
/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
POST
/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
POST
/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.
POST
/api/v1/deployment-jobs/by-project/{project}/by-environment/{environment}/by-name/{deployment}/trigger
Trigger a deployment job.
POST
/api/v1/deployment-jobs/by-project/{project}/by-environment/{environment}/by-name/{deployment}/trigger/destroy
Request to destroy a deployment.
POST
/api/v1/deployment-jobs/by-project/{project}/by-environment/{environment}/by-name/{deployment}/trigger/errand
Request to run an errand on a deployment.
POST
/api/v1/deployment-jobs/by-project/{project}/by-environment/{environment}/by-name/{deployment}/trigger/smoke
Request to rerun smoke tests on a deployment.

Environments

POST
/api/v1/state/{project}/change-environment-order
Change the order of environments
POST
/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.
POST
/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
POST
/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
POST
/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.
POST
/api/v1/pipelines/by-project/{project}/by-name/{pipeline}/trigger
Trigger a pipeline.
POST
/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
POST
/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.
POST
/api/v1/state/{project}/add-project
Add a state project.
GET
/api/v1/state/{project}/can-manage-subscriptions
Can user manage project subscriptions?
POST
/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
POST
/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
POST
/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.
POST
/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
Field Type Description Example
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
Field Type Description Example
id
string
 (Read only) the build exeution ID.

BuildExecutions

Description:
Type:
[BuildExecution]

Builds

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

BuildStep

Description:
Type:
object
Field Type Description Example
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
Field Type Description Example
id
string
name
string

DeploymentJobExecution

Description:
Type:
object
Field Type Description Example
deployment_job DeploymentJob
id
string

DeploymentJobExecutions

Description:
Type:
[DeploymentJobExecution]

DeploymentJobs

Description:
Type:
[DeploymentJob]

DeploymentName

Description:
Type:
string

ExecutionID

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

Namespace

Description:
Namespace.
Type:
object
Field Type Description Example
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
Field Type Description Example
permission
string
 The user's permission on this namespace.
project
string
 The project this namespace is owned by.

NamespacesPayload

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

Pipeline

Description:
Type:
object
Field Type Description Example
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
Field Type Description Example
pipeline Pipeline pipeline
run_nr
int
 run_nr
status
enum
 Pipeline status.
"new"
"pending"
"running"
"ok"
"failed"

PipelinePhase

Description:
Type:
object
Field Type Description Example
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
Field Type Description Example
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
Field Type Description Example
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 }