Flags API

The Flags API allows you to create, read, update, and delete feature flags programmatically.

List flags

Retrieves all flags for an application.

Request

GET /v2/applications/{applicationId}/flags▼

Path parameters

Parameter Type Description

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

applicationId

string

Required. The application ID

Query parameters

Parameter Type Description

Parameter	Type	Description
`configStateEnvs`	array	Optional. Environment IDs to include configuration states for

configStateEnvs

array

Optional. Environment IDs to include configuration states for

Response

{
  "flags": [
    {
      "id": "f7d3c8a1-4b2e-5f9a-b6c4-e1d8f3a7b5c2",
      "name": "default.newDashboard",
      "description": "Enables the new dashboard experience",
      "flagType": "Boolean",
      "variants": ["false", "true"],
      "labels": ["frontend", "q1-release"],
      "isPermanent": false,
      "created": "2024-01-15T10:30:00Z",
      "updated": "2024-02-01T14:22:00Z",
      "configStates": [
        {
          "environmentId": "e4b7c2d9-8f5a-4c3e-b1d6-a9f3e7c5b8d2",
          "enabled": true,
          "updated": "2024-02-01T14:22:00Z"
        }
      ]
    }
  ]
}▼

Example

curl -X GET \
  "https://api.cloudbees.io/v2/applications/a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1/flags?configStateEnvs=e4b7c2d9-8f5a-4c3e-b1d6-a9f3e7c5b8d2" \
  -H "Authorization: Bearer YOUR_TOKEN"▼

Create a flag

Creates a new feature flag.

Request

POST /v2/applications/{applicationId}/flags▼

Path parameters

Parameter Type Description

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

applicationId

string

Required. The application ID

Request body

{
  "name": "default.newFeature",
  "description": "Enables the new feature",
  "flagType": "Boolean",
  "labels": ["frontend"]
}▼

Field Type Required Description

Field	Type	Required	Description
`name`	string	Yes	Flag name with namespace (e.g., `default.flagName`)
`description`	string	No	Human-readable description
`flagType`	string	No	Type: `Boolean`, `String`, or `Number`. Default: `Boolean`
`variants`	array	No	Available values for String/Number flags
`labels`	array	No	Labels for organization
`isPermanent`	boolean	No	Whether the flag is permanent (cannot be deleted)

name

string

Yes

Flag name with namespace (e.g., default.flagName)

description

string

Human-readable description

flagType

string

Type: Boolean, String, or Number. Default: Boolean

variants

array

Available values for String/Number flags

labels

array

Labels for organization

isPermanent

boolean

Whether the flag is permanent (cannot be deleted)

Response

{
  "flag": {
    "id": "f9c8b7a6-5d4e-3f2a-1b0c-9e8d7c6b5a4f",
    "name": "default.newFeature",
    "description": "Enables the new feature",
    "flagType": "Boolean",
    "labels": ["frontend"],
    "created": "2024-02-04T10:00:00Z"
  }
}▼

Example

curl -X POST \
  "https://api.cloudbees.io/v2/applications/a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1/flags" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "default.newFeature",
    "description": "Enables the new feature",
    "flagType": "Boolean",
    "labels": ["frontend"]
  }'▼

Get a flag by ID

Retrieves a specific flag by its ID.

Request

GET /v2/applications/{applicationId}/flags/{id}▼

Path parameters

Parameter Type Description

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

applicationId

string

Required. The application ID

id

string

Required. The flag ID

Response

{
  "flag": {
    "id": "f7d3c8a1-4b2e-5f9a-b6c4-e1d8f3a7b5c2",
    "name": "default.newDashboard",
    "description": "Enables the new dashboard experience",
    "flagType": "Boolean",
    "variants": ["false", "true"],
    "labels": ["frontend"],
    "isPermanent": false,
    "created": "2024-01-15T10:30:00Z",
    "updated": "2024-02-01T14:22:00Z"
  }
}▼

Example

curl -X GET \
  "https://api.cloudbees.io/v2/applications/a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1/flags/f8e7d6c5-b4a3-2f1e-0d9c-8b7a6f5e4d3c" \
  -H "Authorization: Bearer YOUR_TOKEN"▼

Get a flag by name

Retrieves a specific flag by its name.

Request

GET /v2/applications/{applicationId}/flags/by-name/{name}▼

Path parameters

Parameter Type Description

Parameter	Type	Description
`applicationId`	string	Required. The application ID
`name`	string	Required. The flag name (URL-encoded)

applicationId

string

Required. The application ID

name

string

Required. The flag name (URL-encoded)

Example

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

Update a flag

Updates an existing flag’s metadata.

Request

PUT /v2/applications/{applicationId}/flags/{id}▼

Path parameters

Parameter Type Description

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

applicationId

string

Required. The application ID

id

string

Required. The flag ID

Request body

{
  "name": "default.newDashboard",
  "description": "Updated description",
  "labels": ["frontend", "updated"]
}▼

Response

{
  "flag": {
    "id": "f7d3c8a1-4b2e-5f9a-b6c4-e1d8f3a7b5c2",
    "name": "default.newDashboard",
    "description": "Updated description",
    "labels": ["frontend", "updated"],
    "updated": "2024-02-04T12:00:00Z"
  }
}▼

Example

curl -X PUT \
  "https://api.cloudbees.io/v2/applications/a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1/flags/f8e7d6c5-b4a3-2f1e-0d9c-8b7a6f5e4d3c" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "labels": ["frontend", "updated"]
  }'▼

Delete a flag

Deletes a feature flag. This action cannot be undone.

Request

DELETE /v2/applications/{applicationId}/flags/{id}▼

Path parameters

Parameter Type Description

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

applicationId

string

Required. The application ID

id

string

Required. The flag 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/flags/f8e7d6c5-b4a3-2f1e-0d9c-8b7a6f5e4d3c" \
  -H "Authorization: Bearer YOUR_TOKEN"▼

Deleting a flag removes all its configurations across all environments. This action cannot be undone.

List labels

Retrieves all unique labels used across flags in an application.

Request

GET /v2/applications/{applicationId}/flags/labels▼

Response

{
  "labels": [
    "frontend",
    "backend",
    "experimental",
    "q1-release"
  ]
}▼

Example

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

Get flag configuration state

Retrieves the configuration state for a flag across environments.

Request

GET /v2/applications/{applicationId}/flags/{id}/configuration-state▼

Response

{
  "configurationStates": [
    {
      "environmentId": "e4b7c2d9-8f5a-4c3e-b1d6-a9f3e7c5b8d2",
      "enabled": true,
      "updated": "2024-02-01T14:22:00Z"
    },
    {
      "environmentId": "e7e0f5g2-1b8d-7f6b-e4g9-d2g6f0e8d8g5",
      "enabled": true,
      "updated": "2024-01-28T09:15:00Z"
    }
  ]
}▼

Get flag usage per environment

Retrieves usage statistics for a flag across environments.

Request

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

Response

{
  "environments": [
    {
      "environmentId": "e4b7c2d9-8f5a-4c3e-b1d6-a9f3e7c5b8d2",
      "environmentName": "Production",
      "usageCount": 1500
    }
  ]
}▼

Flags API

List flags

Request

Path parameters

Query parameters

Response

Example

Create a flag

Request

Path parameters

Request body

Response

Example

Get a flag by ID

Request

Path parameters

Response

Example

Get a flag by name

Request

Path parameters

Example

Update a flag

Request

Path parameters

Request body

Response

Example

Delete a flag

Request

Path parameters

Response

Example

List labels

Request

Response

Example

Get flag configuration state

Request

Response

Get flag usage per environment

Request

Response

Next steps