API examples to manage personal access tokens, organizations, and flags

This page provides examples of using CloudBees APIs to manage personal access tokens (PATs), organizations, and feature flags. These examples demonstrate how to authenticate, retrieve resources, and configure feature flags.

The base URL for requests:

https://api.cloudbees.io/▼

Generate a personal access token

To access the APIs, follow the instructions for creating a token. They are linked to your user account and inherit all associated permissions.

Treat your personal access token like a password. Keep it secure, and do not share it.

Authenticate by including the token in the authorization header.

Authorization: Bearer <personal_access_token>▼

Retrieve an organization ID

All calls within the feature management API identify resources by their universally unique identifier (UUID). Since each resource belongs to an organization, you must first retrieve its UUID.

The organizationId field (the organization ID) is a UUID that uniquely identifies the organization in the CloudBees platform Organization profile. Refer to Organizations and sub-organizations for more information.

Request

curl -G -L 'https://api.cloudbees.io/v1/organizations/name' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <personal_access_token>' \
  --data 'name=<domain_name>'▼

domain_name: The domain name of your organization.

Response

{
  "organization": {
    "organizationId": "<organization_id>",
    "displayName": "your organization",
    "domainName": "<domain_name>",
    "isDisabled": false,
    "childOrganizations": [],
    "parentId": "00000000-0000-0000-0000-000000000000",
    "description": " ",
    "metadata": {},
    "audit": null,
    "properties": {}
  }
}▼

organization_id: The organization ID.

Retrieve a list of environments

To make other calls targeting specific resources within an organization, retrieve a list of environments within that organization.

Request

curl -G -L 'https://api.cloudbees.io/v2/endpoints/list/<organization_id>' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <personal_access_token>' \
  --data 'filter.contributionTypes=cb.platform.environment' \
  --data 'parents=true'▼

organization_id: The organization ID.
Authorization header: Include your personal access token as Bearer <personal_access_token>.

Response

{
  "endpoints": [
    {
      "id": "<environment_id>",
      "name": "production",
      "resourceId": "<resource_uuid>",
      "contributionType": "cb.platform.environment",
      "description": "Production environment"
    }
  ],
  "pagination": {
    "page": 1,
    "lastPage": true
  }
}▼

environment_id: The environment ID.

The environment ID (the environment_id field) is a UUID that uniquely identifies the environment in the CloudBees platform, and the flag ID (the flagId field) is a UUID that uniquely identifies the feature flag in the CloudBees platform.

Retrieve all flags

Retrieve all flags for a specific organization and environment.

Request

curl -L 'https://api.cloudbees.io/v2/organizations/<organization_id>/environments/<environment_id>/configuration' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <personal_access_token>'▼

Response

{
  "flags": [
    {
      "id": "flag123",
      "name": "exampleFlag",
      "flagType": "Boolean",
      "variants": ["true", "false"],
      "description": "Example flag description",
      "isPermanent": true
    }
  ]
}▼

Create a flag

Create a new flag in an organization.

Request

curl -L 'https://api.cloudbees.io/v2/organizations/<organization_id>/flags' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <personal_access_token>' \
  --data '{
    "name": "default.followingView",
    "flagType": "Boolean"
  }'▼

Response

{
  "flag": {
    "id": "flag123",
    "name": "default.followingView",
    "flagType": "Boolean",
    "variants": ["true", "false"],
    "description": "A new feature flag",
    "isPermanent": false
  }
}▼

Advanced: create a target group

Create a target group with advanced conditions, including nested conditions and property-based rules.

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

Request

curl -X PUT -L 'https://api.cloudbees.io/v2/organizations/<organizationId>/target-groups/<targetGroupId>' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <personal_access_token>' \
  --data '{
    "name": "BetaTesters",
    "conditions": {
      "allOf": [
        {
          "allOf": [
            {
              "group": {
                "id": "f409b00999-375c-4e63-52220-ad7123456789c1"
              }
            }
          ]
        },
        {
          "property": {
            "name": "age",
            "operator": "gte",
            "operands": [5]
          }
        },
        {
          "property": {
            "name": "name",
            "operator": "in-array",
            "operands": ["bob", "sue"]
          }
        }
      ]
    }
  }'▼

organizationId: The organization ID.
targetGroupId: The target group ID.
Authorization header: Include your personal access token as Bearer <personal_access_token>.

Response

{
  "targetGroup": {
    "name": "BetaTesters",
    "conditions": {
      "allOf": [
        {
          "allOf": [
            {
              "group": {
                "id": "f409b00999-375c-4e63-52220-ad7123456789c1"
              }
            }
          ]
        },
        {
          "property": {
            "name": "age",
            "operator": "gte",
            "operands": [5]
          }
        },
        {
          "property": {
            "name": "name",
            "operator": "in-array",
            "operands": ["bob", "sue"]
          }
        }
      ]
    }
  }
}▼

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.

Request

curl -L 'https://api.cloudbees.io/v2/organizations/<organization_id>/target-groups/by-name/<name>' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <personal_access_token>'▼

organizationId: The organization ID.
name: The name of the target group.
Authorization header: Include your personal access token as Bearer <personal_access_token>.

Response

{
  "targetGroup": {
    "id": "string",
    "name": "string",
    "description": "string",
    "conditions": {},
    "resourceId": "string",
    "cascUrl": "string"
  }
}▼

Delete a target group

Delete a specific target group from an organization using its ID.

Request

curl -X DELETE -L 'https://api.cloudbees.io/v2/organizations/<organizationId>/target-groups/<targetGroupId>' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <personal_access_token>'▼

Response

{
  "message": "Target group deleted successfully."
}▼

This action is irreversible—once a target group is deleted, it cannot be restored.
Ensure that no feature flags or rules depend on this target group before deleting it.
If the target group does not exist, the API may return a 404 Not Found error.

Example workflow configuration

Define and configure workflows in the CloudBees platform based on repository events, such as a push to the main branch.

Request

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: build-n-deploy
# This repository event triggers the workflow.
on:
  push:
    branches:
      - 'main'▼

This example defines an event-driven automation workflow. Because repository events trigger it, the API does not return a response.