![[Jenkins]](/static/ddfb44e8/images/svgs/logo.svg){kind=logo}
REST API
Many objects of Jenkins provide the remote access API. They are available
at /.../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].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
excludequery 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.XPath filtering is powerful, and you can have it only return a very small data, but note that the server still has to build a full DOM of the raw data, which could cause a large memory spike. To avoid overloading the server, consider using the
treeparameter, or use thexpathparameter in conjunction with thetreeparameter. When used together, the result of thetreeparameter filtering is built into DOM, then the XPath is applied to compute the final return value. In this way, you can often substantially reduce the size of DOM built in memory. - JSON API
-
Access the same data as JSON for JavaScript-based access.
treemay be used. - Python API
Access the same data as Python for Python clients. This can be parsed into Python objects as
ast.literal_eval(urllib.urlopen("...").read())and the resulting object tree is identical to that of JSON.
For more information about remote API in Jenkins, see the documentation.
Controlling the amount of data you fetch
The tree query parameter allows you to explicitly specify and retrieve only
the information you are looking for, by using an XPath-ish path expression.
The value should be a list of property names to include, with sub-properties 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.
For array-type properties, a range specifier is supported. For example, tree=jobs[name]{0,10} would
retrieve the name of the first 10 jobs. The range specifier has the following variants:
- {M,N}: From the M-th element (inclusive) to the N-th element (exclusive).
- {M,}: From the M-th element (inclusive) to the end.
- {,N}: From the first element (inclusive) to the N-th element (exclusive). The same as {0,N}.
- {N}: Just retrieve the N-th element. The same as {N,N+1}.
Another way to retrieve more data is to use the depth=N query parameter.
This retrieves all the data up to the specified depth.
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.
Because of the size of the data, the depth parameter should really be only used to explore
what data Jenkins can return. Once you identify the data you want to retrieve, you can then come up with
the tree parameter to exactly specify the data you need.
Create Job
To create a new job, post config.xml to this URL with
query parameter name=JOBNAME. You need to send a Content-Type: application/xml
header. You will get a 200 status code if the creation is successful,
or 4xx/5xx code if it fails. config.xml is the format Jenkins uses to store the project
in the file system, so you can see examples of them in the Jenkins home directory, or by retrieving
the XML configuration of existing jobs from /job/JOBNAME/config.xml.
Copy Job
To copy a job, send a POST request to this URL with
three query parameters name=NEWJOBNAME&mode=copy&from=FROMJOBNAME
Create View
To create a new view, post config.xml to createView with
query parameter name=VIEWNAME. You need to send a Content-Type: application/xml
header. You will get a 200 status code if the creation is successful,
or 4xx/5xx code if it fails. config.xml is the format Jenkins uses to store the view
in the file system, so you can see examples of them in the Jenkins home directory, or by retrieving
the XML configuration of existing views from /view/VIEWNAME/config.xml.
Copy View
To copy a view, send a POST request to createView with
three query parameters name=NEWVIEWNAME&mode=copy&from=FROMVIEWNAME
Build Queue
Build queue has its own separate API.
Load Statistics
Overall load statistics of Jenkins has its own separate API.
Restarting Jenkins
Jenkins will enter into the "quiet down" mode by sending a POST request with optional reason query parameter to this URL.
You can also send another request to this URL to update the reason.
You can cancel this mode by sending a POST request to this URL. On environments
where Jenkins can restart itself (such as when Jenkins 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. (Pipeline builds may prevent Jenkins from restarting for a short period of time in some cases, but if so, they will be paused at the next available opportunity and then resumed after Jenkins restarts.)
All these URLs need Overall/Manage permission (typically granted via Overall/Administer).