Creating node with the REST API


  • 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:

JENKINS_URLThe URL of the Jenkins server
JENKINS_USER / JENKINS_PASSWORD_OR_API_TOKENUsername and Password or API token of a jenkins user that has permissions to create nodes
JENKINS_CRUMBThe crumb issued by Jenkins (see CSRF Protection Explained)
NODE_NAMEThe name of the node to create
JSON_OBJECTThe 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:

  • 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.

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

Have more questions?


  • 2
    Owen.liu Please Update

    Is there a way to delete a slave via remote API?

  • 0
    Marco Valente

    This did not work for me in the scenario of passing a file. Please note that to pass a file as a parameter I had to not specify the content-type and pass

    -F json=@/etc/jenkins/jnlp-init.json

    For example

  • 0
    Anoop Vijayan

    Aug. 28,2019:

    This just does not work. I have spent couple of hours on this and get a NullPointerException. I am giving up here :(

    Sept. 23,2020:

    Sorry I was using the url without quotes. The exception details could have been better. Nevertheless, it works now !

    Edited by Anoop Vijayan
  • 0
    Joe Franklin

    This guy has scripted it and it works well for me:


Please sign in to leave a comment.