Environments API examples

This page provides examples for creating, retrieving, and managing environments in CloudBees platform. It includes links to related API topics, such as working with flags in an environment — as well as an end-to-end example for creating, linking, and deleting an ephemeral environment. Ephemeral environments are short-lived and useful for SDK installation, testing, and CI/CD workflows.

Use this page to explore available endpoints, understand request and response formats, and integrate environment management into your automation workflows.

The following API references provide details for working with environments and other entities:

Example end-to-end use case, ephemeral environment

Ephemeral environments are short-lived environments commonly used for SDK installation, testing, or CI/CD workflows. This example shows how to create, link, and delete an environment programmatically using CloudBees APIs.

You can use these endpoints as part of your SDK installation workflow to:

Create an environment (if you don’t have one yet).
Create or select an application.
Link the application to the environment.
Delete the environment when you’re done.

This is a simple, flexible way to create and destroy environments quickly.

Step 1: Create an ephemeral environment

Create a new environment endpoint (environment) resource under your organization.

Endpoint

POST /v1/resources/{organizationId}/endpoints

In this context, {organizationId} is the resourceId used to create endpoints (environments).

Request example

{
  "id": "",
  "parentId": "",
  "resourceId": "62c842de-a50d-48bb-9f86-19a43af9e7d8",
  "name": "production",
  "description": "Production environment (ephemeral)",
  "contributionId": "cb.configuration.basic-environment",
  "contributionType": "cb.platform.environment",
  "contributionTargets": ["cb.configuration.environments"],
  "properties": [
    { "name": "properties", "isSecret": false },
    { "name": "approvers", "isSecret": false }
  ]
}▼

Response example

{
  "id": "13796f74-092f-453d-a215-a15904378f83"
}▼

You can also use this step to create a permanent environment — just omit the word ephemeral in your name or description.

Step 2: Create an application (or reuse an existing one)

Use this API to create a new application and link it to your environment.

Endpoint

POST /v1/organizations/{organizationId}/services

Request example

{
  "service": {
    "id": "",
    "name": "cbp",
    "description": "",
    "repositoryUrl": "",
    "endpointId": "",
    "defaultBranch": "",
    "linkedComponentIds": null,
    "linkedEnvironmentIds": ["13796f74-092f-453d-a215-a15904378f83"],
    "components": null,
    "environments": null,
    "organizationId": "62c842de-a50d-48bb-9f86-19a43af9e7d8",
    "serviceType": "APPLICATION"
  }
}▼

Response example

{
  "service": {
    "id": "f7b22218-537b-4b0e-ae9c-c4097b08185a",
    "name": "cbp",
    "linkedEnvironmentIds": [
      "13796f74-092f-453d-a215-a15904378f83"
    ]
  }
}▼

Optional: Get existing applications in your organization

If you prefer to reuse an existing application, retrieve them using this filtered API call.

Endpoint

GET /v1/organizations/{organizationId}/services?typeFilter=APPLICATION_FILTER

Response example

{
  "service": []
}▼

{
  "service": [
    {
      "id": "f7b22218-537b-4b0e-ae9c-c4097b08185a",
      "name": "cbp",
      "serviceType": "APPLICATION"
    }
  ]
}▼

Step 3: Link environments to an existing application

If you created the application earlier without linking an environment, you can add the link now.

Endpoint

PUT /v1/organizations/{organizationId}/services/{applicationId}

Request example

{
  "service": {
    "id": "",
    "name": "cbp",
    "description": "",
    "repositoryUrl": "",
    "endpointId": "",
    "defaultBranch": "",
    "linkedComponentIds": null,
    "linkedEnvironmentIds": [
      "13796f74-092f-453d-a215-a15904378f83",
      "d3458b5c-492f-4547-8b92-c45a8084cfdf"
    ],
    "components": null,
    "environments": null,
    "organizationId": "62c842de-a50d-48bb-9f86-19a43af9e7d8",
    "serviceType": "APPLICATION"
  }
}▼

Step 4: Delete the ephemeral environment

To clean up, delete the environment by deleting the associated endpoint. You must specify both the resource_id (your organizationId) and the id (the environmentId).

Endpoint

DELETE /v1/resources/{resource_id}/endpoints/{id}

Request example

curl -X DELETE https://api.cloudbees.io/v1/resources/62c842de-a50d-48bb-9f86-19a43af9e7d8/endpoints/13796f74-092f-453d-a215-a15904378f83 \
  --header "Authorization: Bearer <personal_access_token>"▼

Response example

{
  "message": "Environment deleted successfully."
}▼

This example is ideal for setting up ephemeral environments for SDK installation or preview testing. After linking the environment to your application and installing the SDK, a default feature flag is automatically added when your application runs.