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

This page provides examples for using CloudBees APIs to manage Personal Access Tokens (PATs), organizations, and feature flags. Follow these examples to authenticate, retrieve resources, and configure flags.

The base URL for requests:

https://api.cloudbees.io/▼

Generate a PAT

To access the APIs, generate a Personal Access Token (PAT). Follow the instructions for creating a PAT, which is tied to your user account and inherits all associated permissions.

Your personal access token is used like a password to access platform APIs. Keep it secure and do not share it.

Authenticate with your user token by adding an authorization header containing your token.

Authorization: Bearer <PERSONAL_ACCESS_TOKEN>▼

Retrieve the organization UUID

All calls within the feature management API require the UUIDs of resources. Each resource is contained within an organization. Retrieve the UUID of an organization by calling the following endpoint:

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": {
    "id": "<ORG_ID>",
    "displayName": "your organization",
    "domainName": "<DOMAIN_NAME>",
    "isDisabled": false,
    "childOrganizations": [],
    "parentId": "00000000-0000-0000-0000-000000000000",
    "description": "",
    "metadata": {},
    "audit": null,
    "properties": {}
  }
}▼

<ORG_ID>: The UUID of the organization.

Get the environment

To make other calls targeting specific resources within an organization, retrieve the list of environments:

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.
<PERSONAL_ACCESS_TOKEN>: Your 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.

Get a list of 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": 0
}'▼

Response:

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

Modify a flag

To configure a flag for a production environment, update its configuration:

Request:

curl -X PUT -L 'https://api.cloudbees.io/v2/organizations/<ORGANIZATION_ID>/flags/<FLAG_ID>/configuration/environments/<ENVIRONMENT_ID>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <PERSONAL_ACCESS_TOKEN>' \
--data '{
  "defaultValue": true
}'▼

Response:

{
  "configuration": {
    "enabled": true,
    "defaultValue": true,
    "conditions": [],
    "variantsEnabled": false
  }
}▼

Delete a flag

Delete a flag using its UUID:

Request:

curl -X DELETE -L 'https://api.cloudbees.io/v2/organizations/<ORGANIZATION_ID>/flags/<FLAG_ID>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <PERSONAL_ACCESS_TOKEN>'▼

Response:

{
  "message": "Flag 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. For example:

Request:

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

No response is applicable for this configuration example, as it defines an event-driven automation workflow.