API reference

9 minute read

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.

Endpoint
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

resourceId

Path

String

Yes

Specify the resource ID of the tenant, org, sub-org, component, or branch for which endpoints are requested.

filter.search

Query

String

No

Specify a string to filter the results.

filter.resourceIds

Query

Array[String]

No

Specify a list of resource IDs to filter the results.

filter.contributionTypes

Query

Array[String]

No

Specify a list of contribution types to filter the results.

filter.contributionTargets

Query

Array[String]

No

Specify a list of contribution targets to filter the results.

filter.contributionIds

Query

Array[String]

No

Specify a list of contribution IDs to filter the results.

filter.includeDisabled

Query

Boolean

No

Specify if disabled items are included in the response.

pagination.page

Query

Integer

No

Specify the page of results to return (default: 0 or 1).

pagination.pageLength

Query

Integer

No

Specify the number of items per page (default: API limit).

pagination.sort.fieldName

Query

String

No

Specify the field to sort by.

pagination.sort.order

Query

Enum(ascending or descending)

No

Specify the sort order (ascending or descending).

pagination.lastPage

Query

Boolean

No

Indicates if there are more results remaining (response-only).

merged

Query

Boolean

No

Specify if endpoint properties are merged with parent values.

parents

Query

Boolean

No

Specify if endpoints of the resource’s parents are included in the response.

children

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.

api.endpoint.EndpointsResponse

Default

Error response with details.

google.rpc.Status

Response example
{ "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
Endpoint
GET /v2/organizations/{organizationId}/custom-properties
Parameter name In Type Required? Description

organizationId

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.

api.CustomProperty.ListCustomPropertiesResponse

Default

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

google.rpc.Status

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

Endpoint
GET /v2/organizations/{organizationId}/custom-properties/by-name/{name}
Parameter name In Type Required? Description

organizationId

Path

String

Yes

The UUID of the organization.

name

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.

api.customProperty.GetCustomPropertyResponse

Default

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

google.rpc.Status

Response example
{ "customProperty": { "id": "string", "name": "string", "type": "Boolean", "description": "string", "resourceId": "string", "cascUrl": "string" } }

Add a custom property

Add a custom property to an organization.

Endpoint
POST /v2/organizations/{organizationId}/custom-properties
Parameter name In Type Required? Description

organizationId

Path

String

Yes

The UUID of the organization.

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

api.CustomProperty.AddCustomPropertyResponse

Default

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

google.rpc.Status

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

Endpoint
GET /v2/organizations/{organizationId}/flags
Parameter name In Type Required? Description

organizationId

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.

api.flag.ListFlagsResponse

Default

Error. Occurs when the id 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 organizationId

Retrieve a flag by name

Retrieve a specific feature flag by its name.

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

organizationId

Path

String

Yes

The UUID of the organization.

name

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.

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 organization.

Endpoint
POST /v2/organizations/{organizationId}/flags
Parameter name In Type Required? Description

organizationId

Path

String

Yes

The UUID of the organization.

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 organization.

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 } }

Modify a flag

Modify the configuration of an existing feature flag in a specific environment.

Endpoint
PUT /v2/organizations/{organizationId}/flags/{flagId}/configuration/environments/{environmentId}
Parameter name In Type Required? Description

organizationId

Path

String

Yes

The UUID of the organization.

flagId

Path

String

Yes

The UUID of the feature flag.

environmentId

Path

String

Yes

The UUID 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 organizationId, 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 its unique identifier (UUID).

Endpoint
DELETE /v2/organizations/{organizationId}/flags/{flagId}
Parameter name In Type Required? Description

organizationId

Path

String

Yes

The UUID of the organization.

flagId

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 organizationId 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/organizations/{organizationId}/flags/{flagId}/configuration/environments/{environmentId}

Parameters

Parameter Location Required? Type Description

organizationId

Path

Yes

String

The UUID of the organization.

flagId

Path

Yes

String

The UUID of the feature flag.

environmentId

Path

Yes

String

The UUID 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 organizationId, 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/organizations/{organizationId}/flags/{flagId}/configuration/environments/{environmentId}

Parameters

Parameter Location Required? Type Description

organizationId

Path

Yes

String

The UUID of the organization.

flagId

Path

Yes

String

The UUID of the feature flag.

environmentId

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

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 organizationId, 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.

Retrieve a target group

Use the UUID to retrieve a single target group within an organization.

Endpoint
GET /v2/organizations/{organizationId}/target-groups/{targetGroupId}
Parameter name In Type Required? Description

organizationId

Path

String

Yes

The UUID of the organization.

targetGroupId

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.

api.targetGroup.GetTargetGroupResponse

Default

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

google.rpc.Status

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

Endpoint
GET /v2/organizations/{organizationId}/target-groups/by-name/{name}
Parameter name In Type Required? Description

organizationId

Path

String

Yes

The UUID of the organization.

name

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.

api.targetGroup.GetTargetGroupResponse.

Default

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

google.rpc.Status

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

Endpoint
PUT /v2/organizations/{organizationId}/target-groups/{targetGroupId
Parameter name In Type Required? Description

organizationId

Path

String

Yes

The UUID of the organization

targetGroupId

Path

String

Yes

The UUID of the target group.

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

Response example
{ "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" } }
Default error response example
{ "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.

Endpoint
DELETE /v2/organizations/{organizationId}/target-groups/{id}
Table 1. Path parameters
Parameter Type Required? Description

organizationId

String

Yes

The UUID of the organization to which the target group belongs.

targetGroupId

String

Yes

The UUID of the target group to delete.

Request example
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 organizationId or id is missing, incorrect, or the user lacks sufficient permissions. The error response includes details, including the error code, message, and metadata to assist with troubleshooting.

google.rpc.Status

Default error response example:
{ "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.