Flags

5 minute read

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.

Endpoint
GET /v2/applications/{applicationId}/flags
Parameter name In Type Required? Description

applicationId

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.

api.flag.ListFlagsResponse

Default

Error. Occurs when the applicationId is missing or incorrect, or the user lacks sufficient permissions.

google.rpc.Status

Response example
{ "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.

Endpoint
GET /v2/applications/{applicationId}/flags/by-name/{name}
Parameter name In Type Required? Description

applicationId

Path

String

Yes

The application ID.

name

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.

api.flag.GetFlagResponse

Default

Error. Occurs when the id or name is missing, or incorrect, or the user lacks sufficient permissions.

google.rpc.Status

Response example
{ "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.

Endpoint
POST /v2/applications/{applicationId}/flags
Parameter name In Type Required? Description

applicationId

Path

String

Yes

The application ID.

Request body example
{ "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.

api.flag.AddFlagResponse

Default

Error. Occurs when the id is missing or incorrect, or the user lacks sufficient permissions.

google.rpc.Status

Response example
{ "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.
Endpoint
PUT /v2/applications/{applicationId}/flags/{flagId}/configuration/environments/{environmentId}
Parameter name In Type Required? Description

applicationId

Path

String

Yes

The application ID.

flagId

Path

String

Yes

The feature flag ID.

environmentId

Path

String

Yes

The ID of the environment where the flag is configured.

Request body

{ "defaultValue": 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 flag configuration has been updated.

No content.

Default

Error. Occurs when the applicationId, flagId, or environmentId is missing or incorrect, or the user lacks sufficient permissions.

google.rpc.Status

Response example
{ "configuration": { "enabled": true, "defaultValue": true, "conditions": [], "variantsEnabled": false } }

Delete a flag

Delete an existing feature flag using the application ID and the flag ID.

Endpoint
DELETE /v2/applications/{applicationId}/flags/{flagId}
Parameter name In Type Required? Description

applicationId

Path

String

Yes

The application ID.

flagId

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 applicationId or flagId is missing or incorrect, or the user lacks sufficient permissions.

google.rpc.Status

Response example
{ "message": "Flag deleted successfully." }

Retrieve a flag configuration

Retrieve the configuration settings for a specific feature flag in an environment.

Endpoint
GET /v2/applications/{applicationId}/flags/{flagId}/configuration/environments/{environmentId}

Parameters

Parameter Location Required? Type Description

applicationId

Path

Yes

String

The application ID.

flagId

Path

Yes

String

The feature flag ID.

environmentId

Path

Yes

String

The ID of the environment endpoint where the flag is configured.

Response

A successful request returns the flag configuration details.

Response example
{ "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": "" } } ] }

Possible responses

Status Code Description

200

Success. Returns the flag configuration details.

Default

Error. Occurs when the applicationId, flagId, or environmentId is missing or incorrect, or the user lacks sufficient permissions.

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

applicationId

Path

Yes

String

The application ID.

flagId

Path

Yes

String

The feature flag ID.

environmentId

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

enabled

Boolean

Indicates if the feature flag is active (true) or inactive (false).

defaultValue

Object

The default value assigned to the flag when no conditions are met.

conditions

Object

Defines rules that determine when and how the flag is enabled. This property supports a conditional language for targeting users based on attributes.

stickinessProperty

String

Property used for consistent flag evaluation across sessions. This is typically a unique identifier, such as rox.distinct_id.

variantsEnabled

Boolean

Specifies if flag variants are enabled. When true, multiple variations of the flag can be used.

Possible responses

Status Code Description

200

Success. The flag configuration has been updated.

Default

Error. Occurs when the applicationId, flagId, or environmentId is missing, incorrect, or the user lacks sufficient permissions.

Response body properties

The response body contains the updated flag configuration. The structure is similar to the request body.