Creating node with the REST API

Article ID:115003896171
2 minute readKnowledge base


  • I want to create a node with the REST API


The following is a generic solution using a JSON parameter:

curl -L -s -o /dev/null -w "%{http_code}" -u "${JENKINS_USER}:${JENKINS_PASSWORD_OR_API_TOKEN}" -H "Content-Type:application/x-www-form-urlencoded" -H "Jenkins-Crumb:${JENKINS_CRUMB}" -X POST -d 'json=${JSON_OBJECT}' "${JENKINS_URL}computer/doCreateItem?name=${NODE_NAME}&type=hudson.slaves.DumbSlave"

With the following variables:

Variable Description


The URL of the Jenkins server


Username and Password or API token of a jenkins user that has permissions to create nodes


The crumb issued by Jenkins (see CSRF Protection Explained)


The name of the node to create


The JSON representation of the nodes configuration

Here is an example of a JSON object for an SSH node (produced with CJP-CM and SSH Build Agents plugin 1.26):

    "Jenkins-Crumb": "${JENKINS_CRUMB}",
    "": [
    "launcher": {
        "": "2",
        "$class": "hudson.plugins.sshslaves.SSHLauncher",
        "credentialsId": "d436fff1-af1c-45df-8cb6-3907d119b8fa",
        "host": "host",
        "javaPath": "",
        "jvmOptions": "",
        "launchTimeoutSeconds": "",
        "maxNumRetries": "",
        "port": "22",
        "prefixStartSlaveCmd": "",
        "suffixStartSlaveCmd": "",
        "retryWaitTime": "",
        "sshHostKeyVerificationStrategy": {
            "$class": "hudson.plugins.sshslaves.verifiers.ManuallyTrustedKeyVerificationStrategy",
            "requireInitialManualTrust": true,
            "stapler-class": "hudson.plugins.sshslaves.verifiers.ManuallyTrustedKeyVerificationStrategy"
        "stapler-class": "hudson.plugins.sshslaves.SSHLauncher"
    "retentionStrategy": {
        "$class": "hudson.slaves.RetentionStrategy$Always",
        "stapler-class": "hudson.slaves.RetentionStrategy$Always"
    "type": "hudson.slaves.DumbSlave",
    "mode": "NORMAL",
    "name": "${NODE_NAME}",
    "numExecutors": "1",
    "remoteFS": "/home/jenkins",
    "nodeDescription": "Agent node description",
    "labelString": "agent-node-label",
    "nodeProperties": {
        "stapler-class-bag": "true"

Tips to get the JSON

The format of the JSON object depends on the configuration of the node you want to create but also the configuration of your controller (i.e. version of core and plugins). There is a way to retrieve the JSON object corresponding to the desired configuration using the browser developer tool. For more information about the Browser developer tools can be found in the article Required Data: Rendering Problems or Loading Issues.

Different browser have different tools, most of them are similar and enable to capture the request body of HTTP requests which is what we want. Following is an example with Chrome:

  • Go to the Manage Jenkins  Manage Nodes page

  • Click on "New Node", select "Permanent Agent", give it a name and click on "OK". You should now be on the node’s configuration page:

    jenkins node config
  • Configure the node with the values you want but DON’T SAVE YET!

  • Open the browser developer tools console with Right Click  Inspect

  • You should see the [developer console] appear:

  • Switch to the Network tab

  • Click the Clean button (second button at the top left of the Network tab)

  • Keep the console open and click on "Save" in Jenkins to save the form

You should see lots of requests appearing, one of them - the top one - is "doCreateItem":

  • Click on the doCreateItem record (a panel should appear on the right)

  • In the right panel, ensure that you are on the "Headers" tab and scroll down to the bottom to access the Form Data section where you should see the field json.

This JSON is the format the the Jenkins instance is expecting. Attributes can be set accordingly.

You can also use a XML file instead of a JSON.