This section explains the available API endpoints, including their parameters, responses, and examples. Use this information to integrate your applications with the CloudBees platform.
Retrieve a list of endpoints
Retrieve a list of environment endpoints or a specific environment endpoint based on the provided resourceId
.
GET /v2/endpoints/list/{resourceId}
The following table outlines the parameters that can be used with this endpoint, including path and query parameters, their types, and if they are required or optional.
Parameter name | In | Type | Required | Description |
---|---|---|---|---|
|
Path |
String |
Yes |
Specify the resource ID of the tenant, org, sub-org, component, or branch for which endpoints are requested. |
|
Query |
String |
No |
Specify a string to filter the results. |
|
Query |
Array[String] |
No |
Specify a list of resource IDs to filter the results. |
|
Query |
Array[String] |
No |
Specify a list of contribution types to filter the results. |
|
Query |
Array[String] |
No |
Specify a list of contribution targets to filter the results. |
|
Query |
Array[String] |
No |
Specify a list of contribution IDs to filter the results. |
|
Query |
Boolean |
No |
Specify if disabled items are included in the response. |
|
Query |
Integer |
No |
Specify the page of results to return (default: 0 or 1). |
|
Query |
Integer |
No |
Specify the number of items per page (default: API limit). |
|
Query |
String |
No |
Specify the field to sort by. |
|
Query |
Enum(ascending or descending) |
No |
Specify the sort order (ascending or descending). |
|
Query |
Boolean |
No |
Indicates if there are more results remaining (response-only). |
|
Query |
Boolean |
No |
Specify if endpoint properties are merged with parent values. |
|
Query |
Boolean |
No |
Specify if endpoints of the resource’s parents are included in the response. |
|
Query |
Boolean |
No |
Specify if endpoints of the resource’s descendants are included in the response. |
Responses
The following table describes the status codes returned by this endpoint, including their meanings and associated schemas.
Status Code | Description | Schema |
---|---|---|
200 |
OK. Successful response with a list of endpoints. |
|
Default |
Error response with details. |
|
{ "endpoints": [ { "id": "endpoint123", "name": "exampleEndpoint", "resourceId": "resource456", "description": "Example description", "contributionType": "typeA", "contributionTargets": ["targetA", "targetB"] } ], "pagination": { "page": 1, "pageLength": 10, "lastPage": true } }
Retrieve a list of custom properties
Retrieve a list of custom properties associated with the specified organizationId
and its parent organizations. In the response, resourceId represents the relevant parent organization ID.
The hierarchy behavior may change in a future update |
GET /v2/organizations/{organizationId}/custom-properties
Parameter name | In | Type | Required? | Description |
---|---|---|---|---|
|
Path |
String |
Yes |
The UUID of the organization. |
The id field is a UUID (a universally unique identifier) that uniquely identifies the organization in the CloudBees platform
|
Responses
The following table outlines the possible responses from this endpoint, including status codes, their meanings, and the associated schemas:
Status Code | Description | Schema |
---|---|---|
200 |
Success. The request succeeded, returning a list of custom properties for the specified organization. |
|
Default |
Error. Occurs when the |
|
{ "customProperties": [ { "id": "prop123", "name": "exampleProperty", "type": "String", "description": "Example description", "resourceId": "resource456", "cascUrl": "https://casc.example.com/flag-config" } ] }
Retrieve a custom property by name
Retrieve a specific custom property using its name.
GET /v2/organizations/{organizationId}/custom-properties/by-name/{name}
Parameter name | In | Type | Required? | Description |
---|---|---|---|---|
|
Path |
String |
Yes |
The UUID of the organization. |
|
Path |
String |
Yes |
The name of the custom property |
Responses
The following table outlines the possible responses from this endpoint, including status codes, their meanings, and schema.
Status Code | Description | Schema |
---|---|---|
200 |
Success. The request succeeded, and the response includes the details of the specified custom property. |
|
Default |
Error. Occurs when the |
|
{ "customProperty": { "id": "string", "name": "string", "type": "Boolean", "description": "string", "resourceId": "string", "cascUrl": "string" } }
Add a custom property
Add a custom property to an organization.
POST /v2/organizations/{organizationId}/custom-properties
Parameter name | In | Type | Required? | Description |
---|---|---|---|---|
|
Path |
String |
Yes |
The UUID of the organization. |
{ "name": "string", "type": "Boolean | String | SemVer | Number | DateTime", "variants": ["true", "false"], "description": "string", "isPermanent": true }
Responses
The following table outlines the potential responses for this endpoint, including their status codes, descriptions, and schemas:
Status Code | Description | Schema |
---|---|---|
200 |
Success. The request succeeded, adding the custom property to the organization. |
|
Default |
Error. Occurs when the |
|
{ "customProperty": { "id": "prop123", "name": "exampleProperty", "type": "String", "description": "Example description", "resourceId": "resource456" } }
Retrieve a list of flags
Retrieve a list of feature flags for an organization.
GET /v2/organizations/{organizationId}/flags
Parameter name | In | Type | Required? | Description |
---|---|---|---|---|
|
Path |
String |
Yes |
The UUID of the organization. |
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 organization. |
|
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 organizationId |
Retrieve a flag by name
Retrieve a specific feature flag by its name.
GET /v2/organizations/{organizationId}/flags/by-name/{name}
Parameter name | In | Type | Required? | Description |
---|---|---|---|---|
|
Path |
String |
Yes |
The UUID of the organization. |
|
Path |
String |
Yes |
The flag’s 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 organization.
POST /v2/organizations/{organizationId}/flags
Parameter name | In | Type | Required? | Description |
---|---|---|---|---|
|
Path |
String |
Yes |
The UUID of the organization. |
{ "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 organization. |
|
Default |
Error. Occurs when the |
|
{ "flag": { "id": "flag123", "name": "exampleFlag", "flagType": "Boolean", "variants": ["true", "false"], "description": "Example flag description", "isPermanent": true } }
Modify a flag
Modify the configuration of an existing feature flag in a specific environment.
PUT /v2/organizations/{organizationId}/flags/{flagId}/configuration/environments/{environmentId}
Parameter name | In | Type | Required? | Description |
---|---|---|---|---|
|
Path |
String |
Yes |
The UUID of the organization. |
|
Path |
String |
Yes |
The UUID of the feature flag. |
|
Path |
String |
Yes |
The UUID 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 its unique identifier (UUID).
DELETE /v2/organizations/{organizationId}/flags/{flagId}
Parameter name | In | Type | Required? | Description |
---|---|---|---|---|
|
Path |
String |
Yes |
The UUID of the organization. |
|
Path |
String |
Yes |
The UUID 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/organizations/{organizationId}/flags/{flagId}/configuration/environments/{environmentId}
Parameters
Parameter | Location | Required? | Type | Description |
---|---|---|---|---|
|
Path |
Yes |
String |
The UUID of the organization. |
|
Path |
Yes |
String |
The UUID of the feature flag. |
|
Path |
Yes |
String |
The UUID 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/organizations/{organizationId}/flags/{flagId}/configuration/environments/{environmentId}
Parameters
Parameter | Location | Required? | Type | Description |
---|---|---|---|---|
|
Path |
Yes |
String |
The UUID of the organization. |
|
Path |
Yes |
String |
The UUID of the feature flag. |
|
Path |
Yes |
String |
The UUID 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 |
Retrieve a target group
Use the UUID to retrieve a single target group within an organization.
GET /v2/organizations/{organizationId}/target-groups/{targetGroupId}
Parameter name | In | Type | Required? | Description |
---|---|---|---|---|
|
Path |
String |
Yes |
The UUID of the organization. |
|
Path |
String |
Yes |
The UUID of the target group |
Responses
The following table outlines the possible responses from this endpoint, including status codes, their meanings, and schema.
Status Code | Description | Schema |
---|---|---|
200 |
Success. The request succeeded, and the response includes the details of the specified target group. |
|
Default |
Error. Occurs when the |
|
{ "targetGroup": { "id": "tg123", "name": "Beta Testers", "description": "Group for beta testing users", "conditions": { "attribute": "email", "operator": "endsWith", "value": "@example.com" }, "resourceId": "res-456", "cascUrl": "https://casc.example.com/config" } }
Retrieve a target group by name
Retrieve a specific target group using its name instead of its UUID. This endpoint returns details about the target group, including its description, conditions, and associated resources.
GET /v2/organizations/{organizationId}/target-groups/by-name/{name}
Parameter name | In | Type | Required? | Description |
---|---|---|---|---|
|
Path |
String |
Yes |
The UUID of the organization. |
|
Path |
String |
Yes |
The name of the target group. |
Responses
The following table outlines the possible responses for this endpoint, including status codes, their meanings, and schema.
Status Code | Description | Schema |
---|---|---|
200 |
Success. The request succeeded, and the response includes the details of the specified target group. |
|
Default |
Error. Occurs when the |
|
{ "targetGroup": { "id": "string", "name": "string", "description": "string", "conditions": {}, "resourceId": "string", "cascUrl": "string" } }
Update a target group
Update the details of an existing target group within an organization.
PUT /v2/organizations/{organizationId}/target-groups/{targetGroupId
Parameter name | In | Type | Required? | Description |
---|---|---|---|---|
|
Path |
String |
Yes |
The UUID of the organization |
|
Path |
String |
Yes |
The UUID of the target group. |
{ "name": "beta testers", "conditions": { "property": { "name": "prop2", "operator": "is-true" } } }
Responses
The following table outlines the possible responses from this endpoint, including status codes, and their meanings.
Status Code | Description |
---|---|
200 |
Success. The request succeeded, and the response includes the updated target group details. |
Default |
Error. Occurs when the request is invalid, or the user lacks sufficient permissions. The error response includes an error code, message, and metadata. |
{ "targetGroup": { "id": "tg123", "name": "Updated Beta Testers", "description": "Updated group for beta testing users", "conditions": { "attribute": "email", "operator": "contains", "value": "testuser" }, "resourceId": "res-456", "cascUrl": "https://casc.example.com/new-config" } }
{ "code": 0, "message": "Invalid request", "details": [ { "@type": "string", "additionalProp1": {} } ] }
Delete a target group
Use the CloudBees API to delete a target group from an organization.
DELETE /v2/organizations/{organizationId}/target-groups/{id}
Parameter | Type | Required? | Description |
---|---|---|---|
|
String |
Yes |
The UUID of the organization to which the target group belongs. |
|
String |
Yes |
The UUID of the target group to delete. |
curl -X DELETE -L 'https://api.cloudbees.io/v2/organizations/{organizationId}/target-groups/<targetGroupId>' \ --header 'Authorization: Bearer <personal_access_token>'
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, and the target group has been deleted. The response does not include a body. |
No content |
Default |
Error. Occurs when the |
|
{ "code": 403, "message": "Permission denied. You do not have access to delete this target group.", "details": [ { "@type": "type.googleapis.com/google.rpc.Status", "additionalProp1": {} } ] }
This action permanently deletes the target group and cannot be undone.
Ensure that no feature flags or rules depend on this target group before deleting it.
The API may return a 404 Not Found error if the target group does not exist.
|