Remote access API

Skip to end of metadata
Go to start of metadata

Jenkins provides machine-consumable remote access API to its functionalities. Currently it comes in three flavors:

  1. XML
  2. JSON with JSONP support
  3. Python

Remote access API is offered in a REST-like style. That is, there is no single entry point for all features, and instead they are available under the ".../api/" URL where "..." portion is the data that it acts on.

For example, if your Jenkins installation sits at http://ci.jruby.org/, visiting http://ci.jruby.org/api/ will show just the top-level API features available – primarily a listing of the configured jobs for this Jenkins instance.
Or if you want to access information about a particular build, e.g. http://ci.jruby.org/job/jruby-base/lastSuccessfulBuild/, then go to http://ci.jruby.org/job/jruby-base/lastSuccessfulBuild/api/ and you'll see the list of functionalities for that build.

The work on this front is ongoing, so if you find missing features, please file an issue.

What can you do with it?

Remote API can be used to do things like these:

  1. retrieve information from Jenkins for programmatic consumption.
  2. trigger a new build
  3. create/copy jobs

Submitting jobs

For a job with no parameters, you need merely do an HTTP POST on

JENKINS_URL/job/JOBNAME/build?token=TOKEN

where TOKEN is set up in the job configuration.

If you have parameters, you need to send JSON. Here's a snipped of shell, with
a few extra newlines to be more readable.

json="{\"parameter\": [{\"name\": \"taskfile\", \"value\": \"$taskfile\"},
{\"name\": \"task\", \"value\": \"$task\"},
{\"name\": \"jobParameters\", \"value\": \"$jobargs\"}], \"\": \"\"}"
url=http://ci.jruby.org/job/jruby-base/build

curl -X POST $url -d token=zorn --data-urlencode json="$json"

Another example - sending file as a parameter. If you have a "File Parameter" you can do following:

curl http://jenkins/job/$JOB_NAME/build -F file0=@PATH_TO_FILE -F json='{"parameter": [{"name":"FILE_LOCATION_AS_SET_IN_JENKINS", "file":"file0"}]}' --user USER:PASSWORD

Remote API and security

When your Jenkins is secured, you can use HTTP BASIC authentication to authenticate remote API requests. See Authenticating scripted clients for more details.

CSRF Protection

If your Jenkins uses the "Prevent Cross Site Request Forgery exploits" security option (which it should), when you make a POST request, you have to send a CSRF protection token as an HTTP request header.
For curl/wget you can obtain the header needed in the request from the URL http://server/jenkins/crumbIssuer/api/xml (or /api/json). Something like this:

wget -q --output-document - \
'http://server/jenkins/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,":",//crumb)'

This will print something like ".crumb:1234abcd", which you should add to the subsequent request.

Sample code

A simple client is available to demonstrate how you can invoke the XML from Java (Java source)

XPath selection

The XML API supports a selection by XPath by using the query parameter 'xpath'. This is convenient for extracting information in environments where XML manipulation is tedious (such as shell script.) See issue #626 for an example of how to use this.
See .../api/ on your Jenkins server for more up-to-date details.

XPath exclusion

Similar to the 'xpath' query parameter above, you can use (possibly multiple) 'exclude' query patterns to exclude nodes from the resulting XML. All the nodes that match the specified XPath will be removed from the XML.
See .../api/ on your Jenkins server for more up-to-date details.

Depth control

Sometimes the remote API doesn't give you enough information in one call. For example, if you'd like to find out all the last successful build of a given view, you'd realize that the invocation to the remote API of the view won't give you this, and you'd have to recursively call the remote API of each project to find this out. The depth control, introduced in 1.167, solves this problem. To understand this feature, it's good to start with how the remote API works.

The data model that Jenkins maintains internally can be thought of as a big tree structure, and when you make a remote API call, you are getting a small subtree of it. The subtree is rooted at the object for which you made a remote API call, and the sub-tree is cut beyond certain depth to avoid returning too much data. You can adjust this cut-off behavior by specifying the depth query parameter. When you specify a positive depth value, the subtree cut-off happens that much later.

So the net result is, if you specify a bigger depth value, you'll see that the remote API will now return more data. Because of the algorithm, this works in such a way that the data returned by a bigger depth value includes all the data returned by smaller
depth value.

See .../api/ on your Jenkins server for more up-to-date details.

Python API wrappers

JenkinsAPI is an object-oriented python wrapper for the Python REST API which aims to provide a more conventionally pythonic way of controlling a Jenkins server. It provides a higher-level API containing a number of convenience functions. Services offered currently include:

  • Query the test-results of a completed build
  • Get objects representing the latest builds of a job
  • Search for artifacts by simple criteria
  • Block until jobs are complete
  • Install artifacts to custom-specified directory structures
  • username/password auth support for jenkins instances with auth turned on
  • Ability to search for builds by subversion revision
  • Ability to add/remove/query jenkins slaves

Ruby API wrappers

Jenkins API Client is an object oriented ruby wrapper project that consumes Jenkins's JSON API and aims at providing access to all remote API Jenkins provides. It is available as a Rubygem and can be useful to interact with the Job, Node, View, BuildQueue, and System related functionalities. Services currently offered include:

  • Creating jobs by sending xml file or by specifying params as options with more customization options including source control, notifications, etc.
  • Building jobs (with params), stopping builds, querying details of recent builds, obtaining build params, etc.
  • Listing jobs available in Jenkins with job name filter, job status filter.
  • Adding/removing downstream projects.
  • Chaining jobs i.e given a list of projects each project is added as a downstream project to the previous one.
  • Obtaining progressive console output.
  • Username/password based authentication.
  • Command Line Interface with a lot of options provided in the libraries.
  • Creating, listing views.
  • Adding jobs to views and removing jobs from views.
  • Adding/removing jenkins slaves, querying details of slaves.
  • Obtaining the tasks in build queue, and their age, cause, reason, ETA, ID, params and much more.
  • Quiet down, cancel quiet down, safe restart, force restart, and wait till Jenkins becomes available after a restart.
  • Ability to list installed/available plugins, obtain information about plugins, install/uninstall plugins and much more with plugins.

This project is in rapid development and new features are getting added every day. Watch the progress here.

Detecting Jenkins version

To check the version of Jenkins, load the top page (or, as of 1.483, any /api/* page too) and check for the X-Jenkins response header. This contains the version number of Jenkins, like "1.404" This is also a good way to check if an URL is a Jenkins URL.

Discovering Jenkins on the network

Jenkins instances listen on UDP port 33848. Whenever a UDP packet is received, it will respond with a short XML fragment that shows the connection information. This XML has the following format:

<hudson>
  <version>1.380</version>           <!-- version of Jenkins -->
  <url>http://somwhere/jenkins/</url> <!-- HTTP URL. Not available if not configured -->
  <slave-port>12345</slave-port>     <!-- if TCP slave listener port is configured, its number -->
</hudson>

By using this, a client can use a UDP broadcast to try to discover nearby Jenkins instances. This is primarily useful for Swarm Plugin.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Oct 27, 2009

    Alejandro Pérez García says:

    Spanish tutorial about how to launch a build from a Subversion's hook, using the...

    Spanish tutorial about how to launch a build from a Subversion's hook, using the remote API

    http://www.adictosaltrabajo.com/tutoriales/tutoriales.php?pagina=hudsonSubversionPush

  2. Apr 11, 2010

    Gabor Engler says:

    On the Parameterized Build page (http://wiki.jenkins-ci.org/display/HUDSON/Param...

    On the Parameterized Build page (http://wiki.jenkins-ci.org/display/HUDSON/Parameterized+Build) you can find other useful information about remote API feature:

    e.g.: Remote build with multiple parameters: http://server/job/myjob/buildWithParameters?PARAM1=Value1&PARAM2=Value2

    1. Oct 27, 2010

      holger horn says:

      I tried to trigger remotly by URL a job with multiple parameters like this : ht...

      I tried to trigger remotly by URL a job with multiple parameters like this :

      http://server/job/myjob/buildWithParameters?PARAM1=Value1&PARAM2=Value2

      exactly this is not working, what am I doing wrong?

      is someone there who has tried it with success?

      I tried also to send same request with JSON, like described above. no success too... I used this URL:

      Unable to render embedded object: File (parameter.BMP) not found.

      can someone help me? what am I doing wrong?

  3. Apr 30, 2010

    Joel Beaudoin says:

    Is there any way to use this API to tell Hudson to "keep this build forever" for...

    Is there any way to use this API to tell Hudson to "keep this build forever" for a particular build. I am working on some automation for publishing a particular build to an FTP site and this is one of the steps I would like performed. So far, I haven't been able to figure out a programmatic way to mark a given build as "keep" in Hudson. Ideas?

    1. Jul 14, 2010

      Joel Beaudoin says:

      After looking into this a bit closer, I figured out how to do this. A simple wge...

      After looking into this a bit closer, I figured out how to do this. A simple wget/curl of something like:

      http://company.com/hudson/view/ViewNameHere/job/JobNameHere/nn/toggleLogKeep

      or outside of a view like

      http://company.com/hudson/job/JobNameHere/nn/toggleLogKeep

      Replacing ViewNameHere and JobNameHere as appropriate and specifying the build number in place of 'nn'. Obvious after viewing the HTML, but it would be cool to have a page documenting this type of thing. Just an idea ... I sure don't have the time to do it 8-(

      1. Jul 22, 2010

        Joel Beaudoin says:

        Here is a simple python example to do this toggling. Most of the logic is to dea...

        Here is a simple python example to do this toggling. Most of the logic is to deal with the 403 that Hudson returns to request authorization:

        
        import urllib2
        import base64
        
        class HudsonToggleKeep:
        
            def __init__(self):
                self.username = 'username'
                self.password = 'password'
                self.server   = 'https://server.com'
        
                pass_mgr = urllib2.HTTPPasswordMgrWithDefaultRealm()
                pass_mgr.add_password(None, self.server, self.username, self.password)
        
                b_auth = urllib2.HTTPBasicAuthHandler(pass_mgr)
                d_auth = urllib2.HTTPDigestAuthHandler(pass_mgr)
        
                self.url_opener = urllib2.build_opener(b_auth, d_auth,
                                                       self.HudsonFormLoginHandler(self))
        
                urllib2.install_opener(self.url_opener)
        
        
            class HudsonFormLoginHandler(urllib2.BaseHandler):
                def __init__(self, parent):
                    self.p = parent
        
                def http_error_403(self, req, fp, code, msg, headers):
                    for h in self.p.url_opener.handlers:
                        if isinstance(h, self.p.HTTPOpenHandlerBasicAuthNoChallenge):
                            return
        
                    self.p.url_opener.add_handler(
                        self.p.HTTPOpenHandlerBasicAuthNoChallenge(self.p.username,
                                                                   self.p.password))
                    fp.close()
                    return self.p.url_opener.open(req)
        
            class HTTPOpenHandlerBasicAuthNoChallenge(urllib2.BaseHandler):
        
                auth_header = 'Authorization'
        
                def __init__(self, username, password):
                    raw = "%s:%s" % (username, password)
                    self.auth = 'Basic %s' % base64.b64encode(raw).strip()
        
                def default_open(self, req):
                    req.add_header(self.auth_header, self.auth)
        
        
        
        if __name__ == "__main__":
            hp = HudsonToggleKeep()
            req = urllib2.Request("https://server.com/hudson/view/MyView/job/MyJob/15/toggleLogKeep")
            d = urllib2.urlopen(req).read()
        
        1. Jun 24, 2011

          Jim Divine says:

          Here's an easier way to do the forced basic authentication. import urllib2 imp...

          Here's an easier way to do the forced basic authentication.

          import urllib2
          import base64
          
          def urlopen(url, data=None):
              '''Open a URL using the urllib2 opener.'''
              request = urllib2.Request(url, data)
              base64string = base64.encodestring('%s:%s' % (JENKINS_LOGIN, JENKINS_PASSWD)).replace('\n', '')
              request.add_header("Authorization", "Basic %s" % base64string)
              response = urllib2.urlopen(request)
              return response
          

          Then use this urlopen function instead of urllib2.urlopen.

          1. Mar 03, 2012

            Joel Beaudoin says:

            Much simpler and solves a problem that I'm having with the method I was using pr...

            Much simpler and solves a problem that I'm having with the method I was using previously. Thanks for sharing!

      2. Jun 21, 2011

        Danny Staple says:

        My version of that is: wget --no-proxy ${BUILD_URL}/toggleLogKeep --quiet --sp...

        My version of that is:

        wget --no-proxy ${BUILD_URL}/toggleLogKeep --quiet --spider --http-user="<username>" --auth-no-challenge --http-password="<password>"

        The --quiet means that it doesn't show progress etc, --spider means you don't get some HTML downloaded. The auth is as above.

        The --no-proxy is needed to prevent proxies trying to cache this and causing weird behaviour. If you are the wrong side of the proxy from the jenkins/hudson box you'll need to leave that in of course.

  4. Jul 20, 2010

    William Luo says:

    python sample code of hudson remote api #!/usr/bin/env python # this script ...

    python sample code of hudson remote api

    #!/usr/bin/env python
    
    # this script is only demo purpose which is designed to get properties of job, queue, like
    # nextBuildNumber. But note the logistics might not be correct
    
    import urllib2
    
    #call api of job 'git_plugin_test'
    url="http://localhost:9001/job/git_plugin_test/api/python?depth=0"
    response=urllib2.urlopen(url)
    build_dict=eval(response.read())
    
    #call api of job 'queue' of hudson (global but not specific for one job)
    url="http://localhost:9001/queue/api/python?depth=0"
    response=urllib2.urlopen(url)
    queue_dict=eval(response.read())
    
    print ''*40,'build dict',''*40
    #print properties of job
    for eachKey in build_dict:
        print eachKey,build_dict[eachKey]
        print
    
    print ''*40,'queue dict',''*40
    #look through items in queue and can be extended to forecast the job build
    #number in for one item in queue
    for index in range(1,len(queue_dict['items'])):
        print ''*40,'queue hash',''*40
        qi_action=queue_dict['items'][index]['actions']
        list_para=qi_action[0]['parameters']
        for index1 in range(0,len(list_para)):
            print list_para[index1]
            if list_para[index1]['name'] == 'SLEEP_TIME' and list_para[index1]['value'] == '62':
                print "OK"
    
    #only valid when no more than one build found in queue
    if build_dict['inQueue']:
        build_number=int(build_dict['nextBuildNumber']) + 1
    else:
        build_number=int(build_dict['nextBuildNumber'])
    print "Hudson Build URL:",build_dict['url']+str(build_number)
    print "Current build tree:"+build_dict['builds'][0]['url']
    
  5. Jan 04, 2011

    Christopher Marsh-Bourdon says:

    Is there any way to access the configuration of the Jobs, I tried the following,...

    Is there any way to access the configuration of the Jobs, I tried the following, but with no success:

    http://company.com/hudson/job/JOBNAME/configure/api/xml

    This just yielded a 404, so either this functionality doesn't exist, or I have erred on the URL.

    1. Jan 04, 2011

      Joel Beaudoin says:

      You can access a job's configuration via: http://company.com/hudson/job/JOBNAME...

      You can access a job's configuration via:

      http://company.com/hudson/job/JOBNAME/config.xml

      You can find out this and other cool things via:

      http://company.com/hudson/job/JOBNAME/api/

      Hope this helps,
      Joel

      1. Jan 04, 2011

        Christopher Marsh-Bourdon says:

        A big thanks Joel; that was exactly what I was after.

        A big thanks Joel; that was exactly what I was after.

  6. Feb 19, 2011

    Victor Rodrigues says:

    Could I get a JSON containing the jobs that are currently being executed? I wis...

    Could I get a JSON containing the jobs that are currently being executed?

    I wish I could get build history through JSON api also. Is there any uri I'm missing?

    Thanks!

    Victor

    1. Mar 11, 2011

      Gstad Winkldorff says:

      "Could I get a JSON containing the jobs that are currently being executed?" I s...

      "Could I get a JSON containing the jobs that are currently being executed?"

      I second that request.

      Best regards.

      Gstad

  7. May 27, 2011

    Scal Pa says:

    Could someone show a working code sample on how to trigger a paramtrized job usi...

    Could someone show a working code sample on how to trigger a paramtrized job using JQuery?
    I use no authentication of any kind at Jenkins level and there is no "Build Trigger" option enabled for the job. Here is the piece of code I try but I arways get back a status code of [0] with a failure:

    var jqxhr = $.post(
            "http://servername:3333/job/jobname/buildWithParameters",
           { "PARAM_ID": "1", "PARAM_VALUE1": "1", "PARAM_VALUE2": "*firefox" },
            "html"
        )
        .success(function () { alert("success"); })
        .error(function (xhr, ajaxOptions, thrownError) { alert("Error\nxhr.status = \[" + xhr.status + "\]\n xhr.statusText: \[" + xhr.statusText + "\]\najaxOptions = \[" + ajaxOptions + "\]"); })
        .complete(function () { alert("complete"); }
    );
    

    Can someone please confirm this is the correct way or point out errors/mistakes I'm doing with this remote api call?

    Thanks!

  8. Mar 14, 2012

    Harish Kayarohanam says:

    Is there a way to add jenkins plugin using Remote access API   ?  

    Is there a way to add jenkins plugin using Remote access API   ?  

    1. Sep 20, 2012

      Jesse Glick says:

      See /pluginManager/api/ for information on this.

      See /pluginManager/api/ for information on this.

  9. Sep 24, 2012

    Roger Myung says:

    I'm able to successfully post a build using the instructions here. However, my s...

    I'm able to successfully post a build using the instructions here. However, my script has difficulty telling whether it succeeded.

    I get a HTTP/1.1 302 Found back.

    Is there a way to get confirmation from Jenkins that the build was added to the queue?  Even better, can I get the build number, and/or get notification when the build finishes?

  10. Oct 19, 2012

    Sanjoy Ghosh says:

    I am running Hudson job remotely through separate application using remote acces...

    I am running Hudson job remotely through separate application using remote access api. But how shall I get the build status of my request build as soon as the build is finished.

  11. Oct 25, 2012

    Matt Don says:

    Has anyone been able to get authentication working with an API token using groov...

    Has anyone been able to get authentication working with an API token using groovy HTTPBuilder?  I know the example on this site shows groovy with HTTPclient, but I'm just wondering if its possible with HTTPBuilder.  I can do basic pre-emptive authentication with username password, but I can't get it to work with the API token.

  12. Nov 08

    Nane Nare Hambardzumyan says:

    is it possible ignore certificate during connection? i get _ssl.c:504: error...

    is it possible ignore certificate during connection? i get _ssl.c:504: error:14077438:SSL routines:SSL23_GET_SERVER_HELLO:tlsv1 alert internal error during connection