Custom properties API

The Custom properties API allows you to create, read, update, and delete custom properties that are used in targeting conditions and target groups.

List custom properties

Retrieves all custom properties for an application.

Request

GET /v2/applications/{applicationId}/custom-properties▼

Path parameters

Parameter Type Required Description

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

applicationId

string

Yes

The application ID

Response

{
  "customProperties": [
    {
      "id": "p8a7b6c5-d4e3-f210-9876-543210abcdef",
      "name": "subscription_plan",
      "type": "String",
      "description": "User subscription level"
    },
    {
      "id": "p9b8a7c6-e5d4-f321-0987-654321bcdef0",
      "name": "isBetaUser",
      "type": "Boolean",
      "description": "Whether user is enrolled in beta"
    },
    {
      "id": "p0c9b8a7-f6e5-d432-1098-765432cdef01",
      "name": "monthly_sessions",
      "type": "Number",
      "description": "Number of sessions this month"
    }
  ]
}▼

Example

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

Create a custom property

Creates a new custom property.

Request

POST /v2/applications/{applicationId}/custom-properties▼

Path parameters

Parameter Type Required Description

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

applicationId

string

Yes

The application ID

Request body

{
  "name": "account_tier",
  "type": "String",
  "description": "User account tier (free, pro, enterprise)"
}▼

Field Type Required Description

Field	Type	Required	Description
`name`	string	Yes	Unique property name
`type`	string	Yes	Property type: `Boolean`, `String`, `Number`, `Semver`, or `DateTime`
`description`	string	No	Human-readable description

name

string

Yes

Unique property name

type

string

Yes

Property type: Boolean, String, Number, Semver, or DateTime

description

string

Human-readable description

Response

{
  "customProperty": {
    "id": "p1d0c9b8-a7f6-e543-2109-876543def012",
    "name": "account_tier",
    "type": "String",
    "description": "User account tier (free, pro, enterprise)"
  }
}▼

Example

curl -X POST \
  "https://api.cloudbees.io/v2/applications/a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1/custom-properties" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "account_tier",
    "type": "String",
    "description": "User account tier (free, pro, enterprise)"
  }'▼

Get a custom property by ID

Retrieves a specific custom property by its ID.

Request

GET /v2/applications/{applicationId}/custom-properties/{id}▼

Path parameters

Parameter Type Required Description

Parameter	Type	Required	Description
`applicationId`	string	Yes	The application ID
`id`	string	Yes	The custom property ID

applicationId

string

Yes

The application ID

id

string

Yes

The custom property ID

Example

curl -X GET \
  "https://api.cloudbees.io/v2/applications/a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1/custom-properties/p9b8a7c6-e5d4-f321-0987-654321bcdef0" \
  -H "Authorization: Bearer YOUR_TOKEN"▼

Get a custom property by name

Retrieves a specific custom property by its name.

Request

GET /v2/applications/{applicationId}/custom-properties/by-name/{name}▼

Path parameters

Parameter Type Required Description

Parameter	Type	Required	Description
`applicationId`	string	Yes	The application ID
`name`	string	Yes	The custom property name

applicationId

string

Yes

The application ID

name

string

Yes

The custom property name

Example

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

Update a custom property

Updates an existing custom property.

Request

PUT /v2/applications/{applicationId}/custom-properties/{id}▼

Path parameters

Parameter Type Required Description

Parameter	Type	Required	Description
`applicationId`	string	Yes	The application ID
`id`	string	Yes	The custom property ID

applicationId

string

Yes

The application ID

id

string

Yes

The custom property ID

Request body

{
  "name": "account_tier",
  "type": "String",
  "description": "Updated description for account tier"
}▼

You cannot change the type of an existing property while it is in use by flags or target groups.

Example

curl -X PUT \
  "https://api.cloudbees.io/v2/applications/a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1/custom-properties/p9b8a7c6-e5d4-f321-0987-654321bcdef0" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "account_tier",
    "type": "String",
    "description": "Updated description"
  }'▼

Delete a custom property

Deletes a custom property. This action cannot be undone.

Request

DELETE /v2/applications/{applicationId}/custom-properties/{id}▼

Path parameters

Parameter Type Required Description

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

applicationId

string

Yes

The application 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/custom-properties/p9b8a7c6-e5d4-f321-0987-654321bcdef0" \
  -H "Authorization: Bearer YOUR_TOKEN"▼

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

Get flag usage per environment

Retrieves the flags that use this property, organized by environment.

Request

GET /v2/applications/{applicationId}/custom-properties/{id}/flag-usage-per-environment▼

Response

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

Get target group usage

Retrieves the target groups that use this property.

Request

GET /v2/applications/{applicationId}/custom-properties/{id}/target-group-usage▼

Response

{
  "targetGroupUsage": [
    {
      "id": "tg-123",
      "name": "PremiumUsers"
    },
    {
      "id": "tg-456",
      "name": "BetaUsers"
    }
  ]
}▼

Property types

Custom properties support the following types:

Type Description Example Values

Type	Description	Example Values
`Boolean`	True or false values	`true`, `false`
`String`	Text values	`"premium"`, `"user@example.com"`
`Number`	Numeric values (integers or decimals)	`42`, `3.14`, `100`
`Semver`	Semantic version strings	`"1.0.0"`, `"2.3.1-beta"`
`DateTime`	ISO 8601 date/time strings	`"2024-01-15T10:30:00Z"`

Boolean

True or false values

true, false

String

Text values

"premium", "user@example.com"

Number

Numeric values (integers or decimals)

42, 3.14, 100

Semver

Semantic version strings

"1.0.0", "2.3.1-beta"

DateTime

ISO 8601 date/time strings

"2024-01-15T10:30:00Z"

Type-specific operators

Different property types support different comparison operators:

Type Supported Operators

Type	Supported Operators
Boolean	`is-undefined`, `is-true`, `is-false`
String	`is-undefined`, `eq`, `ne`, `in-array`, `regex`
Number	`is-undefined`, `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in-array`
Semver	`is-undefined`, `semver-eq`, `semver-ne`, `semver-gt`, `semver-gte`, `semver-lt`, `semver-lte`
DateTime	`is-undefined`, `eq`, `ne`, `gt`, `gte`, `lt`, `lte`

Boolean

is-undefined, is-true, is-false

String

is-undefined, eq, ne, in-array, regex

Number

is-undefined, eq, ne, gt, gte, lt, lte, in-array

Semver

is-undefined, semver-eq, semver-ne, semver-gt, semver-gte, semver-lt, semver-lte

DateTime

is-undefined, eq, ne, gt, gte, lt, lte