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 UUID

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

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 UUID of the organization.

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 UUID of the organization.
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 UUID of the environment.

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.

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 UUID of the organization.
targetGroupId: The UUID of the target group.
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 UUID. 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 UUID of the organization
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 UUID.

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.