This page provides API reference details for creating, retrieving, updating, and deleting feature flags in CloudBees platform. It includes request and response examples, required parameters, and schema information for working with flags at the application and environment level.
Use these APIs to manage the full lifecycle of feature flags, including creating flags, retrieving flag metadata, updating flag configurations in specific environments, and deleting flags as needed.
Retrieve a list of flags
Retrieve a list of feature flags associated with the specified environment and its linked applications.
GET /v2/applications/{applicationId}/flags
| Parameter name | In | Type | Required? | Description |
|---|---|---|---|---|
|
Path |
String |
Yes |
The application ID. |
Responses
The following table outlines the possible responses for this endpoint, including status codes, their meanings, and the schemas that describe the structure of the returned data or errors.
| Status Code | Description | Schema |
|---|---|---|
200 |
Success. The request succeeded, returning a list of feature flags for the specified application. |
|
Default |
Error. Occurs when the |
|
{ "flags": [ { "id": "000000000-0000-0000-0000-123456879",(1) "name": "exampleFlag", "flagType": "Boolean", "variants": ["true", "false"], "description": "Example flag description", "isPermanent": true, "resourceId": "org-456", "cascUrl": "https://casc.example.com/flag-config" } ] }
| 1 | The id is the flagId. The resourceId is the applicationId. |
Retrieve a flag by name
Retrieve a specific feature flag by its name.
GET /v2/applications/{applicationId}/flags/by-name/{name}
| Parameter name | In | Type | Required? | Description |
|---|---|---|---|---|
|
Path |
String |
Yes |
The application ID. |
|
Path |
String |
Yes |
The flag name. |
Responses
The following table describes the possible responses for this endpoint, including their status codes, what they indicate, and the schemas that define the structure of the returned data or errors.
| Status Code | Description | Schema |
|---|---|---|
200 |
Success. The request succeeded, and the response includes the details of the specified feature flag. |
|
Default |
Error. Occurs when the |
|
{ "flag": { "id": "38a8e81d-605e-4aab-b6eb-27ad3b329afe", "name": "exampleFlag", "flagType": "Boolean", "variants": ["true", "false"], "description": "Example flag description", "isPermanent": true, "cascUrl": "f409b00999-375c-4et3-52220-ad7123456789c1", "resourceId": "c463be63-ef27-4c74-a05v-65d8c07a2a03" } }
Add a new flag
Add a new feature flag to an application.
POST /v2/applications/{applicationId}/flags
| Parameter name | In | Type | Required? | Description |
|---|---|---|---|---|
|
Path |
String |
Yes |
The application ID. |
{ "name": "exampleFlag", "flagType": "Boolean", "variants": ["true", "false"], "description": "Example flag description", "isPermanent": true }
Responses
The following table outlines the possible responses for this endpoint, including status codes, their meanings, and the schemas that describe the structure of the returned data or errors.
| Status Code | Description | Schema |
|---|---|---|
200 |
Success. The request succeeded, adding a feature flag to the specified application. |
|
Default |
Error. Occurs when the |
|
{ "flag": { "id": "flag123", "name": "exampleFlag", "flagType": "Boolean", "variants": ["true", "false"], "description": "Example flag description", "isPermanent": true } }
Update a flag in an environment
Modify the configuration of an existing feature flag in a specific environment.
The environment ID (the environmentId field) is a UUID that uniquely identifies the environment in the CloudBees platform, and the flag ID (the flagId field) is a UUID that uniquely identifies the feature flag in the CloudBees platform.
|
PUT /v2/applications/{applicationId}/flags/{flagId}/configuration/environments/{environmentId}
| Parameter name | In | Type | Required? | Description |
|---|---|---|---|---|
|
Path |
String |
Yes |
The application ID. |
|
Path |
String |
Yes |
The feature flag ID. |
|
Path |
String |
Yes |
The ID of the environment where the flag is configured. |
Responses
The following table outlines the possible responses for this endpoint, including status codes, their meanings, and the schemas that describe the structure of the returned data or errors.
| Status Code | Description | Schema |
|---|---|---|
200 |
Success. The flag configuration has been updated. |
No content. |
Default |
Error. Occurs when the |
|
{ "configuration": { "enabled": true, "defaultValue": true, "conditions": [], "variantsEnabled": false } }
Delete a flag
Delete an existing feature flag using the application ID and the flag ID.
DELETE /v2/applications/{applicationId}/flags/{flagId}
| Parameter name | In | Type | Required? | Description |
|---|---|---|---|---|
|
Path |
String |
Yes |
The application ID. |
|
Path |
String |
Yes |
The ID of the feature flag to be deleted. |
Responses
The following table outlines the possible responses for this endpoint, including status codes, their meanings, and the schemas that describe the structure of the returned data or errors.
| Status Code | Description | Schema |
|---|---|---|
200 |
Success. The feature flag was successfully deleted. |
No content. |
Default |
Error. Occurs when the |
|
{ "message": "Flag deleted successfully." }
Retrieve a flag configuration
Retrieve the configuration settings for a specific feature flag in an environment.
GET /v2/applications/{applicationId}/flags/{flagId}/configuration/environments/{environmentId}
Parameters
| Parameter | Location | Required? | Type | Description |
|---|---|---|---|---|
|
Path |
Yes |
String |
The application ID. |
|
Path |
Yes |
String |
The feature flag ID. |
|
Path |
Yes |
String |
The ID of the environment endpoint where the flag is configured. |
Response
A successful request returns the flag configuration details.
{ "configurations": [ { "flagId": "flagId", "flagName": "newFlag25", "description": "testing has perm", "labels": [ "l1", "l2", "l3", "l4" ], "created": "2024-10-30T20:28:41.379Z", "updated": "2024-11-01T12:48:46.852Z", "configuration": { "enabled": true, "defaultValue": [ { "option": true, "percentage": 75 }, { "option": false, "percentage": 25 } ], "conditions": null, "stickinessProperty": "rox.distinct_id", "variantsEnabled": false, "resourceId": "uuid", "cascUrl": "" } } ] }
Update a flag configuration
Modify the configuration settings of an existing feature flag in an environment.
Endpoint
PATCH /v2/applications/{applicationId}/flags/{flagId}/configuration/environments/{environmentId}
Parameters
| Parameter | Location | Required? | Type | Description |
|---|---|---|---|---|
|
Path |
Yes |
String |
The application ID. |
|
Path |
Yes |
String |
The feature flag ID. |
|
Path |
Yes |
String |
The ID of the environment where the flag is configured. |
Request body
Example
{ "configuration": { "enabled": false, "defaultValue": { "valueWrittenInCode": true }, "conditions": null, "stickinessProperty": "rox.distinct_id", "variantsEnabled": false } }
Request body properties
| Property | Type | Description |
|---|---|---|
|
Boolean |
Indicates if the feature flag is active ( |
|
Object |
The default value assigned to the flag when no conditions are met. |
|
Object |
Defines rules that determine when and how the flag is enabled. This property supports a conditional language for targeting users based on attributes. |
|
String |
Property used for consistent flag evaluation across sessions. This is typically a unique identifier, such as |
|
Boolean |
Specifies if flag variants are enabled. When |