Remote API

Many objects of Hudson provides the remote access API. They are available at /hudson/.../api/ where "..." portion is the object for which you'd like to access.

XML API

Access data exposed in HTML as XML for machine consumption. Schema is also available.

You can also specify optional XPath to control the fragment you'd like to obtain (but see below). For example, ../api/xml?xpath=/*/*[0]. If the XPath only matches a text node, the result will be sent with text/plain MIME type to simplify further processing. For XPath that matches multiple nodes, you need to also specify the "wrapper" query parameter to specify the name of the root XML element to be create so that the resulting XML becomes well-formed.

Similarly exclude query parameter can be used to exclude nodes that match the given XPath from the result. This is useful for trimming down the amount of data you fetch (but again see below). This query parameter can be specified multiple times.

JSON API

Access the same data as JSON for JavaScript-based access. Supports JSONP through the optional jsonp=callbackname query parameter.

Python API

Access the same data as Python for Python clients. This can be parsed into Python object as eval(urllib.urlopen("...").read()) and the resulting object tree is identical to that of JSON. However, when you do this, beware of the security implication. If you are connecting to a non-trusted Hudson, the server can send you malicious Python programs.

For more information about remote API in Hudson, see the documentation.

Controlling the amount of data you fetch

In all formats, the depth query parameter can be used to control the amount of data you'll receive. The default is depth=0, but by increasing this value you can get a lot of data by single remote API invocation (the downside is bigger bandwidth requirement.) Compare depth=0 and depth=1 and see what the difference is for yourself. Also note that data created by a smaller depth value is always a subset of the data created by a bigger depth value.

A newer alternative is the tree query parameter. This works with any format, e.g. JSON; is more efficient than using depth with exclude (since information does not need to be generated on the server and then discarded); and may be easier to use, since you need only know what elements you are looking for, rather than what you are not looking for (which is anyway an open-ended list when plugins can contribute API elements). The value should be a list of property names to include, with subproperties inside square braces. Try tree=jobs[name],views[name,jobs[name]] to see just a list of jobs (only giving the name) and views (giving the name and jobs they contain). Note: for array-type properties (such as jobs in this example), the name must be given in the original plural, not in the singular as the element would appear in XML (<job>). This will be more natural for e.g. json?tree=jobs[name] anyway: the JSON writer does not do plural-to-singular mangling because arrays are represented explicitly.

Create Job

To create a new job, post config.xml to this URL with query parameter name=JOBNAME. You'll get 200 status code if the creation is successful, or 4xx/5xx code if it fails. config.xml is the format Hudson uses to store the project in the file system, so you can see examples of them in /hudson/workdir.

Copy Job

To copy a job, send a POST request to this URL with three query parameters name=NEWJOBNAME&mode=copy&from=FROMJOBNAME

Build Queue

Build queue has its own separate API.

Load Statistics

Overall load statistics of Hudson has its own separate API.

Restarting Hudson

Hudson will enter into the "quiet down" mode by sending a request to this URL. You can cancel this mode by sending a request to this URL. On environments where Hudson can restart itself (such as when Hudson is installed as a Windows service), POSTing to this URL will start the restart sequence, or this URL to restart once no jobs are running. All these URLs need the admin privilege to the system.