Target groups API

The Target Groups API allows you to create, read, update, and delete target groups that define reusable targeting rules for flag conditions.

List target groups

Retrieves all target groups for an application.

Request

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

Path parameters

Parameter Type Description

Parameter	Type	Description
`applicationId`	string	Required. The application ID

applicationId

string

Required. The application ID

Response

{
  "targetGroups": [
    {
      "id": "tg-123",
      "name": "BetaUsers",
      "description": "Users enrolled in the beta program",
      "conditions": {
        "operator": "and",
        "conditions": [
          {
            "property": "isBetaUser",
            "operator": "is-true"
          }
        ]
      }
    }
  ]
}▼

Example

curl -X GET \
  "https://api.cloudbees.io/v2/applications/a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1/target-groups" \
  -H "Authorization: Bearer YOUR_TOKEN"▼

Create a target group

Creates a new target group.

Request

POST /v2/applications/{applicationId}/target-groups▼

Path parameters

Parameter Type Description

Parameter	Type	Description
`applicationId`	string	Required. The application ID

applicationId

string

Required. The application ID

Request body

{
  "name": "PremiumUsers",
  "description": "Users with premium subscription",
  "conditions": {
    "operator": "and",
    "conditions": [
      {
        "property": "subscription_plan",
        "operator": "in-array",
        "operand": ["premium", "enterprise"]
      }
    ]
  }
}▼

Field Type Required Description

Field	Type	Required	Description
`name`	string	Yes	Unique name for the target group
`description`	string	No	Human-readable description
`conditions`	object	Yes	Targeting conditions (see Condition structure)

name

string

Yes

Unique name for the target group

description

string

Human-readable description

conditions

object

Yes

Targeting conditions (see Condition structure)

Response

{
  "targetGroup": {
    "id": "tg-new-456",
    "name": "PremiumUsers",
    "description": "Users with premium subscription",
    "conditions": {
      "operator": "and",
      "conditions": [
        {
          "property": "subscription_plan",
          "operator": "in-array",
          "operand": ["premium", "enterprise"]
        }
      ]
    }
  }
}▼

Example

curl -X POST \
  "https://api.cloudbees.io/v2/applications/a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1/target-groups" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PremiumUsers",
    "description": "Users with premium subscription",
    "conditions": {
      "operator": "and",
      "conditions": [
        {
          "property": "subscription_plan",
          "operator": "in-array",
          "operand": ["premium", "enterprise"]
        }
      ]
    }
  }'▼

Get a target group by ID

Retrieves a specific target group by its ID.

Request

GET /v2/applications/{applicationId}/target-groups/{id}▼

Path parameters

Parameter Type Description

Parameter	Type	Description
`applicationId`	string	Required. The application ID
`id`	string	Required. The target group ID

applicationId

string

Required. The application ID

id

string

Required. The target group ID

Example

curl -X GET \
  "https://api.cloudbees.io/v2/applications/a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1/target-groups/tg-456" \
  -H "Authorization: Bearer YOUR_TOKEN"▼

Get a target group by name

Retrieves a specific target group by its name.

Request

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

Path parameters

Parameter Type Description

Parameter	Type	Description
`applicationId`	string	Required. The application ID
`name`	string	Required. The target group name

applicationId

string

Required. The application ID

name

string

Required. The target group name

Example

curl -X GET \
  "https://api.cloudbees.io/v2/applications/a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1/target-groups/by-name/BetaUsers" \
  -H "Authorization: Bearer YOUR_TOKEN"▼

Update a target group

Updates an existing target group.

Request

PUT /v2/applications/{applicationId}/target-groups/{id}▼

Path parameters

Parameter Type Description

Parameter	Type	Description
`applicationId`	string	Required. The application ID
`id`	string	Required. The target group ID

applicationId

string

Required. The application ID

id

string

Required. The target group ID

Request body

{
  "name": "PremiumUsers",
  "description": "Updated description",
  "conditions": {
    "operator": "or",
    "conditions": [
      {
        "property": "subscription_plan",
        "operator": "eq",
        "operand": "premium"
      },
      {
        "property": "subscription_plan",
        "operator": "eq",
        "operand": "enterprise"
      }
    ]
  }
}▼

Example

curl -X PUT \
  "https://api.cloudbees.io/v2/applications/a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1/target-groups/tg-456" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PremiumUsers",
    "description": "Updated description",
    "conditions": {
      "operator": "or",
      "conditions": [
        {
          "property": "subscription_plan",
          "operator": "eq",
          "operand": "premium"
        }
      ]
    }
  }'▼

Delete a target group

Deletes a target group. This action cannot be undone.

Request

DELETE /v2/applications/{applicationId}/target-groups/{id}▼

Path parameters

Parameter Type Description

Parameter	Type	Description
`applicationId`	string	Required. The application ID
`id`	string	Required. The target group ID

applicationId

string

Required. The application ID

id

string

Required. The target group ID

Response

Returns an empty response with status 200 on success.

Example

curl -X DELETE \
  "https://api.cloudbees.io/v2/applications/a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1/target-groups/tg-456" \
  -H "Authorization: Bearer YOUR_TOKEN"▼

If the property is being used in any flags or target +groups, you must remove those references before deletion. The system prevents deletion of properties that are currently in use.

List target groups with flag usage

Retrieves all target groups along with the flags that use them.

Request

GET /v2/applications/{applicationId}/target-groups/with-flags-usage▼

Response

{
  "targetGroups": [
    {
      "id": "tg-123",
      "name": "BetaUsers",
      "flagUsage": [
        {
          "id": "f8e7d6c5-b4a3-2f1e-0d9c-8b7a6f5e4d3c",
          "name": "default.newFeature"
        },
        {
          "id": "f0d9c8b7-a6f5-4e3d-2c1b-0a9f8e7d6c5b",
          "name": "default.anotherFeature"
        }
      ],
      "updated": "2024-02-01T14:22:00Z"
    }
  ]
}▼

Get target group flag usage per environment

Retrieves flag usage statistics for a target group across environments.

Request

GET /v2/applications/{applicationId}/target-groups/{id}/flag-usage-per-environment▼

Response

{
  "environments": [
    {
      "environmentId": "e4b7c2d9-8f5a-4c3e-b1d6-a9f3e7c5b8d2",
      "environmentName": "Production",
      "flags": [
        {
          "id": "f8e7d6c5-b4a3-2f1e-0d9c-8b7a6f5e4d3c",
          "name": "default.newFeature"
        }
      ]
    }
  ]
}▼

Condition structure

Target groups use conditions to define who belongs to the group.

Root structure

{
  "operator": "and",
  "conditions": [
    // Array of condition objects
  ]
}▼

Field Type Description

Field	Type	Description
`operator`	string	Logic between conditions: `and` or `or`
`conditions`	array	Array of condition objects

operator

string

Logic between conditions: and or or

conditions

array

Array of condition objects

Condition operators

Operator Operand Type Description

Operator	Operand Type	Description
`is-undefined`	None	Property is not set
`is-true`	None	Boolean property is true
`is-false`	None	Boolean property is false
`eq`	String, Number	Equals
`ne`	String, Number	Not equals
`gt`	Number	Greater than
`gte`	Number	Greater than or equal
`lt`	Number	Less than
`lte`	Number	Less than or equal
`in-array`	Array	Value is in the provided array
`regex`	String	Matches regular expression
`semver-eq`	String	Semantic version equals
`semver-gte`	String	Semantic version greater than or equal

is-undefined

None

Property is not set

is-true

None

Boolean property is true

is-false

None

Boolean property is false

eq

String, Number

Equals

ne

String, Number

Not equals

gt

Number

Greater than

gte

Number

Greater than or equal

lt

Number

Less than

lte

Number

Less than or equal

in-array

Array

Value is in the provided array

regex

String

Matches regular expression

semver-eq

String

Semantic version equals

semver-gte

String

Semantic version greater than or equal

Example conditions

Boolean property

{
  "property": "isBetaUser",
  "operator": "is-true"
}▼

String comparison

{
  "property": "subscription_plan",
  "operator": "eq",
  "operand": "enterprise"
}▼

Array membership

{
  "property": "user_id",
  "operator": "in-array",
  "operand": ["user-001", "user-002", "user-003"]
}▼

Regex pattern

{
  "property": "email",
  "operator": "regex",
  "operand": ".*@cloudbees\\.com$"
}▼

Numeric comparison

{
  "property": "monthly_sessions",
  "operator": "gt",
  "operand": 100
}▼

Target groups API

List target groups

Request

Path parameters

Response

Example

Create a target group

Request

Path parameters

Request body

Response

Example

Get a target group by ID

Request

Path parameters

Example

Get a target group by name

Request

Path parameters

Example

Update a target group

Request

Path parameters

Request body

Example

Delete a target group

Request

Path parameters

Response

Example

List target groups with flag usage

Request

Response

Get target group flag usage per environment

Request

Response

Condition structure

Root structure

Condition operators

Example conditions

Boolean property

String comparison

Array membership

Regex pattern

Numeric comparison

Next steps