CloudBees Previews Public API

3 minute read
Abstract
The public REST API exposed by CloudBees Previews

Access

  • APIKey KeyParamName: X-Api-Token, KeyInQuery: false, KeyInHeader: true

Endpoints

Environments

POST /api/v1/namespaces/{namespace}/environments

Operation Id

createEnvironment

Create Environment

Description

Create a new Environment. This operation is EXPERIMENTAL and not yet supported.

Parameters
Path Parameters
NameDescriptionRequiredDefaultPattern

namespace

Environment namespace

X

null

Body Parameter
NameDescriptionRequiredDefaultPattern

Environment

Environment

-

Return Type
Content Type
  • application/json

Responses
Table 1. http response codes
CodeMessageDatatype

201

Environment created

Environment

400

Bad request

Error

401

Unauthorized

Error

403

Forbidden

Error

GET /api/v1/namespaces/{namespace}/environments/{name}

Operation Id

getEnvironment

Get an Environment

Description

Get a specific, existing Environment

Parameters
Path Parameters
NameDescriptionRequiredDefaultPattern

namespace

Environment namespace

X

null

name

Environment name

X

null

Return Type
Content Type
  • application/json

Responses
Table 2. http response codes
CodeMessageDatatype

200

Returns an environment

Environment

400

Bad request

Error

401

Unauthorized

Error

403

Forbidden

Error

404

Environment not found

Error

GET /api/v1/namespaces/{namespace}/environments/{name}/log

Operation Id

getEnvironmentLogs

Get the logs of an Environment

Description

Get the logs of an Environment

Parameters
Path Parameters
NameDescriptionRequiredDefaultPattern

namespace

Environment namespace

X

null

name

Environment name

X

null

Return Type

String

Content Type
  • text/plain

  • application/json

Responses
Table 3. http response codes
CodeMessageDatatype

200

Returns the environment's logs

String

400

Bad request

Error

401

Unauthorized

Error

403

Forbidden

Error

404

Environment not found

Error

GET /api/v1/environments

Operation Id

listEnvironments

List Environments

Description

List all Environments that match the given labels

Parameters
Query Parameters
NameDescriptionRequiredDefaultPattern

labels

Filters Environments by labels. Values must have the form <LABEL>=<VALUE>. Multiple values can be comma-separated and are treated as conjunction. Common labels include: 'repo-host', 'repo-namespace', 'repo-name', 'pr-number', 'commit-sha', 'context'.

-

null

check

If specified, the HTTP response status reflects a check on the environment search result: When set to 'ready' the server responds with 429 unless there is an environment that matches the search criteria and is ready, indicating that the client should retry the request. When a matching environment fails or terminates, the server responds with 412, indicating that the client should stop polling and fail. For disambiguation, this parameter can only be used in conjunction with the 'labels' parameter. This parameter allows you to synchronize an automated task (as a CI job) with an asynchronously created/updated environment. It works particularly well with `curl --retry 20` or `wget --tries 20 --retry-on-http-error=429`.

-

null

Return Type
Content Type
  • application/json

Responses
Table 4. http response codes
CodeMessageDatatype

200

Return a list of environments

EnvironmentList

400

Bad request

Error

401

Unauthorized

Error

403

Forbidden

Error

412

Environment failed. This response is returned only if the check parameter was set to 'ready' in order to indicate that polling should be stopped.

Error

429

Environment did not match or its final state is not known yet. The request should be retried in that case. This response is returned only if the 'check' parameter was specified. This allows you to use `curl --retry` or `wget --tries` for polling until an environment is created/updated and reaches a desired state.

Error

Models

Check

Field NameRequiredTypeDescriptionFormat

Environment

Represents the desired and current state of an Environment. It is the external representation of an Environment CRD.

Field NameRequiredTypeDescriptionFormat

metadata

X

Metadata

spec

X

EnvironmentSpec

status

EnvironmentStatus

EnvironmentList

A list of Environments.

Field NameRequiredTypeDescriptionFormat

items

X

List of Environment

EnvironmentPhase

The phase the Environment is currently in.

Field NameRequiredTypeDescriptionFormat

EnvironmentSpec

Represents the desired state of an Environment

Field NameRequiredTypeDescriptionFormat

gitSource

GitSource

ttl

String

context

X

String

EnvironmentStatus

Represents an Environment's current status

Field NameRequiredTypeDescriptionFormat

phase

X

EnvironmentPhase

error

Error

urls

List of EnvironmentURL

EnvironmentURL

An ingress URL of an Environment

Field NameRequiredTypeDescriptionFormat

url

X

String

An ingress URL the enviroment exposes

Error

An error

Field NameRequiredTypeDescriptionFormat

type

X

String

message

X

String

GitSource

Reference to the git commit the environment should be created for

Field NameRequiredTypeDescriptionFormat

cloneURL

X

String

commitSHA

X

String

Metadata