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.
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.
{ "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.
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 asBearer <personal_access_token>
.
{ "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.
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>'
{ "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.
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" }'
{ "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.
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 asBearer <personal_access_token>
.
{ "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.
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 asBearer <personal_access_token>
.
{ "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.
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>'
{ "message": "Target group deleted successfully." }
|
Example workflow configuration
Define and configure workflows in the CloudBees platform based on repository events, such as a push
to the main branch.
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.