API examples to manage personal access tokens, applications, and flags

This page provides examples of using CloudBees platform APIs to manage Personal Access Tokens (PATs), environments, applications, target groups, and feature flags. These examples demonstrate how to authenticate, retrieve resources, and configure feature flags.

For a complete end-to-end flow including environments, applications, and SDK setup, refer to Ephemeral environments: create, link, and destroy quickly.

Base URL

All API calls use the following base URL:

https://api.cloudbees.io/

Generate a personal access token

To access the APIs, you need a personal access token. Tokens are linked to your user account and inherit all associated permissions.

Treat your personal access token like a password. Keep it secure and do not share it.

Use it in the Authorization header:

Authorization: Bearer <personal_access_token>

Retrieve an organization ID

Use this endpoint to retrieve your organization’s UUID (organizationId) using its domain name.

Request

curl -G -L 'https://api.cloudbees.io/v1/organizations/name' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <personal_access_token>' \
  --data 'name=<domain_name>'▼

Response

{
  "organization": {
    "organizationId": "<organization_id>",
    "displayName": "your organization",
    "domainName": "<domain_name>"
  }
}▼

Ephemeral environments: create, link, and destroy quickly

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.

Retrieve applications using a type filter

Retrieve a list of applications created under your organization. Applications can be linked to environments.

Request

GET /v1/organizations/{orgId}/services?typeFilter=APPLICATION_FILTER▼

Response

{
  "service": [
    {
      "id": "app-123",
      "name": "BeaconWeather",
      "description": "Weather app for mobile"
    },
    {
      "id": "app-456",
      "name": "AnalyticsService"
    }
  ]
}▼

The response uses the service key, which includes all application-type services.

Create and link applications

Refer to Ephemeral environments: create, link, and destroy quickly for a complete example that includes creating an application and linking it to one or more environments.

Retrieve environments linked to an application

Retrieve all environments that an application is linked to.

Request

curl -L 'https://api.cloudbees.io/v2/applications/<application_id>/environments' \
  --header 'Authorization: Bearer <personal_access_token>'▼

Response

{
  "environments": [
    {
      "id": "env-001",
      "name": "Staging",
      "status": "active"
    },
    {
      "id": "env-002",
      "name": "Production",
      "status": "active"
    }
  ]
}▼

Retrieve all flags in an application

Retrieve a list of all feature flags configured in a given application.

Request

curl -L 'https://api.cloudbees.io/v2/applications/<application_id>/flags' \
  --header 'Authorization: Bearer <personal_access_token>'▼

Response

{
  "flags": [
    {
      "id": "flag123",
      "name": "exampleFlag",
      "flagType": "Boolean",
      "variants": ["true", "false"],
      "description": "Example flag description",
      "isPermanent": true
    }
  ]
}▼

Create a flag in an application

Create a new feature flag under an application. Flags are available across all environments linked to the application.

Request

curl -X POST 'https://api.cloudbees.io/v2/applications/<application_id>/flags' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <personal_access_token>' \
  --data '{
    "name": "default.followingView",
    "flagType": "Boolean"
  }'▼

Response

{
  "flag": {
    "id": "flag123",
    "name": "default.followingView",
    "flagType": "Boolean",
    "variants": ["true", "false"],
    "description": "A new feature flag",
    "isPermanent": false
  }
}▼

Create a target group

Create a new target group for advanced targeting rules.

Request

curl -X PUT 'https://api.cloudbees.io/v2/applications/<application_id>/target-groups/<target_group_id>' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <personal_access_token>' \
  --data '{
    "name": "BetaTesters",
    "conditions": {
      "allOf": [
        {
          "property": {
            "name": "age",
            "operator": "gte",
            "operands": [18]
          }
        },
        {
          "property": {
            "name": "country",
            "operator": "in-array",
            "operands": ["US", "CA"]
          }
        }
      ]
    }
  }'▼

Response

{
  "targetGroup": {
    "id": "<target_group_id>",
    "name": "BetaTesters"
  }
}▼