Target groups

This page provides API reference details for managing target groups in CloudBees platform. Target groups allow you to define user segments based on attributes and conditions for use in feature flag targeting. This page includes endpoints for retrieving, creating, updating, and deleting target groups, along with request and response examples to help you implement advanced targeting rules within your applications.

Retrieve a target group

Use the target group ID to retrieve a single target group within an application.

The target group ID (the targetGroupId field) is a UUID that uniquely identifies the target group in the CloudBees platform.

Endpoint

GET /v2/applications/{applicationId}/target-groups/{targetGroupId}

Parameter name In Type Required? Description

Parameter name	In	Type	Required?	Description
`applicationId`	Path	String	Yes	The application ID.
`targetGroupId`	Path	String	Yes	The target group ID.

applicationId

Path

String

Yes

The application ID.

targetGroupId

Path

String

Yes

The target group ID.

Responses

The following table outlines the possible responses from this endpoint, including status codes, their meanings, and schema.

Status Code Description 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 `applicationId`, or `targetGroupId` is missing, incorrect, or the user lacks sufficient permissions.	`google.rpc.Status`

200

Success. The request succeeded, and the response includes the details of the specified target group.

api.targetGroup.GetTargetGroupResponse

Default

Error. Occurs when the applicationId, 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 ID. This endpoint returns details about the target group, including its description, conditions, and associated resources.

Endpoint

GET /v2/applications/{applicationId}/target-groups/by-name/{name}

Parameter name In Type Required? Description

Parameter name	In	Type	Required?	Description
`applicationId`	Path	String	Yes	The application ID.
`name`	Path	String	Yes	The name of the target group.

applicationId

Path

String

Yes

The application ID.

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

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 `applicationId`, or `name` is missing, incorrect, or the user lacks sufficient permissions.	`google.rpc.Status`

200

Success. The request succeeded, and the response includes the details of the specified target group.

api.targetGroup.GetTargetGroupResponse

Default

Error. Occurs when the applicationId, 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 application.

Endpoint

PUT /v2/applications/{applicationId}/target-groups/{targetGroupId}

Parameter name In Type Required? Description

Parameter name	In	Type	Required?	Description
`applicationId`	Path	String	Yes	The application ID.
`targetGroupId`	Path	String	Yes	The target group ID.

applicationId

Path

String

Yes

The application ID.

targetGroupId

Path

String

Yes

The target group ID.

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.

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

Endpoint

DELETE /v2/applications/{applicationId}/target-groups/{targetGroupId}

Table 1. Path parameters
Parameter	Type	Required?	Description
`applicationId`	String	Yes	The application ID to which the target group belongs.
`targetGroupId`	String	Yes	The ID of the target group to delete.

Request example

curl -X DELETE -L 'https://api.cloudbees.io/v2/applications/{applicationId}/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

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 `applicationId` 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`

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