Configuration as Code (CasC) HTTP API

You can use HTTP API endpoints to manage CasC bundles and create a new item in the operations center based on a CasC items.yaml file.

Authentication and authorization

To access the CasC API, you need an API authentication token and administrator access rights. Refer to API authentication for more information.

Endpoints and methods

Endpoint Description Parameters Prerequisites

GET ${JENKINS_URL}/casc-bundle/list

Lists all available controller CasC bundles on the operations center.

None.

CloudBees CI or CloudBees Jenkins Platform 2.249.2.3 or later
CloudBees CasC Server Plugin

GET ${JENKINS_URL}/casc-bundle-mgnt/check-bundle-update

Checks for bundle updates. If a bundle update is available, you can issue the /casc-bundle-reload-bundle command to immediately apply the updated bundle without restarting the instance.

None.

If using CloudBees CI or CloudBees Jenkins Platform 2.303.3.3: CloudBees CasC API Plugin (Deprecated), version 1.41
If using CloudBees CI or CloudBees Jenkins Platform 2.319.1.5 or later: CloudBees CasC Client Plugin, version 1.44 or later

POST ${JENKINS_URL}/casc-bundle/regenerate-token

Regenerates the controller bundle token and returns the new bundle information when successful.

Name: controllerPath
- Parameter type: Query string parameter
- Data type: string
- Description: The full path of the controller item in the operations center. For example, folder1/controller1.

CloudBees CI or CloudBees Jenkins Platform 2.249.2.3 or later
CloudBees CasC Server Plugin

The bundleId parameter has been deprecated in version 2.289.1.2. The controllerPath parameter should be used for all new applications.

POST ${JENKINS_URL}/casc-bundle/set-availability-pattern

Specifies the availability pattern, to define the path to controllers that can use the bundle.

Name: bundleId
- Parameter type: Query string parameter
- Data type: string
- Description: The name of the folder that contains the CasC bundle. For example, casc-bundle-java.
Name: regex
- Parameter type: Query string parameter
- Data type: string
- Description: The full path to one or more controllers that can use the bundle. This must be a regular expression and defines the bundles you can assign to a controller. For example, folder1/.* to use the bundle with any controller in the "folder1" folder.

CloudBees CI or CloudBees Jenkins Platform 2.289.2.2 or later
CloudBees CasC Server Plugin

POST ${JENKINS_URL}/casc-bundle/set-global-availability-pattern-behavior

Specifies the default global availability pattern behavior for the controller CasC bundle.

Name: visibility
- Parameter type: Query string parameter
- Data type: string
- Description: When the parameter value is true, all CasC bundles that do not have a regex availability pattern defined can be used by any controller. This option provides more flexibility, but is less secure.

CloudBees CI or CloudBees Jenkins Platform 2.289.2.2 or later
CloudBees CasC Server Plugin

POST ${JENKINS_URL}/casc-bundle/clear-availability-pattern

Uses the availability pattern defined in the bundle.yaml file and clears the availability pattern for the controller CasC bundle if previously defined.

Name: bundleId
- Parameter type: Query string parameter
- Data type: string
- Description: The name of the folder that contains the CasC bundle. For example, casc-bundle-java.

CloudBees CI or CloudBees Jenkins Platform 2.303.3.3 or later
CloudBees CasC Server Plugin

POST ${JENKINS_URL}/casc-bundle/set-controller-to-bundle

Assigns a new controller path and returns the new bundle information when successful.

For this command to be successful, you must first define the availability pattern for the bundle by sending the /casc-bundle/set-availability-pattern or /casc-bundle/set-global-availability-pattern-behavior request.

Name: bundleId
- Parameter type: Query string parameter
- Data type: string
- Description: The name of the folder that contains the CasC bundle. For example, casc-bundle-java.
Name: controllerPath
- Parameter type: Query string parameter
- Data type: string
- Description: The full path of the controller item in the operations center. For example, folder1/controller1.

CloudBees CI or CloudBees Jenkins Platform 2.289.2.2 or later
CloudBees CasC Server Plugin

POST ${JENKINS_URL}/casc-bundle/set-default-bundle

Specifies a default bundle that is pre-selected in the operations center controller configuration screen when setting up a new controller.

The default bundle is pre-selected for controllers that match the availability pattern of the default bundle. To set the availability pattern of the default bundle, you can use the /casc-bundle/set-availability-pattern or /casc-bundle/set-global-availability-pattern-behavior request.

Specifying a default bundle does not assign the bundle to a controller. When setting up a new controller in the operations center, you must click Save or Apply from the controller configuration screen to assign the pre-selected bundle to the controller.

Name: bundleId
- Parameter type: Query string parameter
- Data type: string
- Description: The name of the folder that contains the CasC bundle. For example, casc-bundle-java.

CloudBees CI or CloudBees Jenkins Platform 2.289.2.2 or later
CloudBees CasC Server Plugin

POST ${JENKINS_URL}/casc-bundle-mgnt/reload-bundle

Applies the bundle update without restarting the instance when possible.

None.

If using CloudBees CI or CloudBees Jenkins Platform 2.303.3.3: CloudBees CasC API Plugin (Deprecated), version 1.41
If using CloudBees CI or CloudBees Jenkins Platform 2.319.1.5 or later: CloudBees CasC Client Plugin, version 1.44 or later

POST ${JENKINS_URL}/casc-items/create-items

Creates a new item in the operations center based on an items.yaml file stored in the local filesystem.

Name: path
- Parameter type: Query string parameter
- Data type: string
- Description: The full path of the folder in the operations center where the item is created. The folder path must exist in the operations center prior to issuing the command. For example, /folder1. To create the item at the root of the operations center, you can omit this parameter.
Name: yaml
- Parameter type: Query string parameter
- Data type: string
- Description: The full path on the local filesystem to the items.yaml file. For example, /casc/items.yaml.

If using CloudBees CI or CloudBees Jenkins Platform 2.303.3.3: CloudBees CasC API Plugin (Deprecated), version 1.41
If using CloudBees CI or CloudBees Jenkins Platform 2.319.1.5 or later: CloudBees CasC Items API Plugin, version 1.1.1 or later

POST ${JENKINS_URL}/casc-bundle/set-master-to-bundle

Assigns a new controller path and returns the new bundle information when successful.

If you are using CloudBees CI 2.277.4.2 - 2.289.1.2, and you send the /casc-bundle/set-master-to-bundle endpoint, no bundles are available to assign to the controller. You must first sign in to the operations center as a user with the Administer permission, navigate to the Configuration as Code bundles screen, define the Availability pattern, and then issue the request to assign a bundle to a controller.

Name: bundleId
- Parameter type: Query string parameter
- Data type: string
- Description: The name of the folder that contains the CasC bundle. For example, casc-bundle-java.
Name: masterPath
- Parameter type: Query string parameter
- Data type: string
- Description: The full path of the controller item in the operations center. For example, folder1/controller1.

CloudBees CI or CloudBees Jenkins Platform 2.249.2.3 - 2.289.2.2
CloudBees CasC Server Plugin

The /casc-bundle/set-master-to-bundle request has been deprecated in version 2.289.2.2 due to offensive terminology. The /casc-bundle/set-controller-to-bundle endpoint should be used for all new applications.

Request examples

In the request examples "admin" is the name of the user attempting to send the request and "https://my-operations-center.com/" is the operations center URL.

Table 2. Request examples
Endpoint	Request example
GET `/casc-bundle/list`	`curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XGET "https://my-operation-center.com/casc-bundle/list"`
GET `/casc-bundle-mgnt/check-bundle-update`	`curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XGET "https://my-operation-center.com/casc-bundle-mgnt/check-bundle-update"`
POST `/casc-bundle/regenerate-token`	`curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/regenerate-token?controllerPath=folder1/controller1"`
POST `/casc-bundle/set-availability-pattern`	`curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-availability-pattern?bundleId=casc-bundle-java&regex=folder1.*"`
POST `/casc-bundle/set-global-availability-pattern-behavior`	`curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-global-availability-pattern-behavior?visibility=true"`
POST `/casc-bundle/clear-availability-pattern`	`curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com//casc-bundle/clear-availability-pattern?bundleId=casc-bundle-java"`
POST `/casc-bundle/set-controller-to-bundle`	`curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-controller-to-bundle?bundleId=casc-bundle-java&controllerPath=folder1/controller1"`
POST `/casc-bundle/set-default-bundle`	`curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-default-bundle?bundleId=casc-bundle-java"`
POST `/casc-bundle-mgnt/reload-bundle`	`curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle-mgnt/reload-bundle"`
POST `/casc-items/create-items`	`curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-items/create-items?path=/folder1" --data-binary @/casc/items.yaml -H "Content-Type:text/yaml"`
POST `/casc-bundle/set-master-to-bundle`	`curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-master-to-bundle?bundleId=casc-bundle-java&masterPath=folder1/controller1"`

Response examples

Response examples are formatted for better readability.

{
    "bundles":[
        {
            "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
            "regex": "folder1/.*",
            "name": "casc-bundle-java",
            "availabilityPatternFromYaml": true,
            "url": "https://my-operation-center.com/config-bundle/casc-bundle-java",
            "token": "",
            "usedBy": [
                "folder1/controller1"
            ],
            "availableFor": [
                "folder1/controller1",
                "folder1/controller2"
            ]
        }
    ]
}

{
    "update-available": true
}

{
    "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
    "regex": "folder1/.*",
    "name": "casc-bundle-java",
    "availabilityPatternFromYaml": true,
    "url": "https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token": ""
}

{
    "controllers": [
        "folder1/controller1",
        "folder1/controller2"
    ]
}

{
    "visibility": true
}

{
    "controllers": [
        "folder1/controller1",
        "folder1/controller2"
    ]
}

{
    "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
    "regex": "folder1/.*",
    "name": "casc-bundle-java",
    "availabilityPatternFromYaml": true,
    "url": "https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token": ""
}

{
    "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
    "regex": "folder1/.*",
    "name": "casc-bundle-java",
    "availabilityPatternFromYaml": true,
    "url": "https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token": ""
}

{
    "reloaded": true
}

{
    "basePath": "/folder1"
}

{
    "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
    "regex": "folder1/.*",
    "name": "casc-bundle-java",
    "availabilityPatternFromYaml": true,
    "url": "https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token": ""
}

Response model

Table 3. Response model
Element	Type	Description
availableFor	array of objects	Controllers that can be assigned to the bundle based on the availability pattern.
availabilityPatternFromYaml	string	Returns `true` if the availability pattern is defined in the `bundle.yaml` file. Returns `false` if the availability pattern is defined in the UI or using the `/casc-bundle/set-availability-pattern` request.
bundles	array of objects	All bundles available on the operations center.
controllers	array of objects	The full paths of all controllers that can use the bundle.
linkFileContent	string	Contains two entries in string format wrapped in quotes and separated by newline characters: url and token. The url is the bundle URL where the operations center exposes its content. The token is the access token for the bundle.
name	string	The name of the folder that contains the CasC bundle. For example, `casc-bundle-java`.
regex	string	The full path to one or more controllers in the operations center that can use the bundle. This must be a regular expression. It defines the bundles you can assign to a controller. For example, `folder1/.*`.
token	string	The access token for the bundle.
url	string	The bundle URL where the operations center exposes its content.
usedBy	string	The names of controllers assigned to the bundle.
visibility	string	The default global availability pattern behavior for the bundle.

Status and error codes

Table 4. Status and error codes
Code	Description
200	Success
403	Not authorized. Administrator permission required.
404	The provided controller path, endpoint, or method cannot be found.
500	Server error.

Examples for configuring a controller using CasC

Once the CasC bundle has been configured in the operations center, you can define an availability pattern to make the bundle available to controllers, assign the bundle to a controller, and specify a default bundle.

Send the GET /casc-bundle/list request to list all available CasC bundles on the operations center. For example:

curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XGET "https://my-operation-center.com/casc-bundle/list"

In this example, there is one bundle named casc-bundle-java:

{
    "bundles":[
        {
            "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
            "regex": "",
            "name": "casc-bundle-java",
            "availabilityPatternFromYaml": true,
            "url": "https://my-operation-center.com/config-bundle/casc-bundle-java",
            "token": "",
            "usedBy": [],
            "availableFor": []
        }
    ]
}

Define the availability pattern for the bundle. You have two options:
- Option 1: Send the POST /casc-bundle/set-availability-pattern request to define the path to the controllers that can use the bundle. For example:
  curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-availability-pattern?bundleId=casc-bundle-java&regex=folder1.*"
  If successful, a list of all controllers that can use the bundle is returned:
  { "controllers": [ "folder1/controller1", "folder1/controller2" ] }
- Option 2: Send the POST /casc-bundle/set-global-availability-pattern-behavior request to define the default global availability pattern behavior for bundles that do not have an availability pattern defined. This option provides more flexibility, but is less secure. For example:
  curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-global-availability-pattern-behavior?visibility=true"
  If successful, the default global availability pattern behavior is returned:
  { "visibility": true }

Send the POST /casc-bundle/set-controller-to-bundle request to assign a bundle to a controller. For example:

curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-controller-to-bundle?bundleId=casc-bundle-java&controllerPath=folder1/controller1"

If successful, the bundle information is returned:

{
    "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
    "regex": "folder1/.*",
    "name": "casc-bundle-java",
    "availabilityPatternFromYaml": true,
    "url": "https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token": ""
}

Send the GET /casc-bundle/list request again. For example:

curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XGET "https://my-operation-center.com/casc-bundle/list"

The casc-bundle-java bundle is now assigned to folder/controller1 and also available for assignment to folder1/controller2, based on the availability pattern you defined.

{
    "bundles":[
        {
            "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
            "regex": "folder1/.*",
            "name": "casc-bundle-java",
            "availabilityPatternFromYaml": true,
            "url": "https://my-operation-center.com/config-bundle/casc-bundle-java",
            "token": "",
            "usedBy": [
                "folder1/controller1"
            ],
            "availableFor": [
                "folder1/controller1",
                "folder1/controller2"
            ]
        }
    ]
}

Optionally, specify a default bundle to pre-select a bundle in the controller configuration screen when setting up a new controller. For example, to specify casc-bundle-java as the default bundle, send the POST /casc-bundle/set-default-bundle request:

curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-default-bundle?bundleId=casc-bundle-java"

If successful, the default bundle information is returned:

{
    "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
    "regex": "folder1/.*",
    "name": "casc-bundle-java",
    "availabilityPatternFromYaml": true,
    "url": "https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token": ""
}

In August 2020, the Jenkins project voted to replace the term master with controller. We have taken a pragmatic approach to cleaning these up, ensuring the least amount of downstream impact as possible. CloudBees is committed to ensuring a culture and environment of inclusiveness and acceptance - this includes ensuring the changes are not just cosmetic ones, but pervasive. As this change happens, please note that the term master has been replaced through the latest versions of the CloudBees documentation with controller (as in managed controller, client controller, team controller) except when still used in the UI or in code.