Remote API [Jenkins] (2024)

Many objects of Jenkins provide the remote access API. They are available at /jenkins/.../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.

See Also

FAQ - SadpTools / Integration / Source Code / Example of usage10分钟掌握XML、JSON及其解析_xml_tcpipstack-GitCode 开源社区XML Multiple-Choice Questions (MCQs) with Answers

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.

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 tree parameter, or use the xpath parameter in conjunction with the tree parameter. When used together, the result of the tree parameter 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. tree may 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.

Other Useful URLs

Build number

This URL returns the build number in text/plain format.

Build timestamp

This URL returns the build timestamp. You can also use the format query parameter to control the date format, which follows the SimpleDateFormat format pattern. (example) You can also use the Accept-Language HTTP header to control the locale in which the date is formatted.

Accessing Progressive Console Output

You can retrieve in-progress console output by making repeated GET requests with a parameter. You'll basically send GET request to this URL (or this URL if you want HTML that can be put into <pre> tag.) The start parameter controls the byte offset of where you start.

The response will contain a chunk of the console output, as well as the X-Text-Size header that represents the bytes offset (of the raw log file). This is the number you want to use as the start parameter for the next call.

If the response also contains the X-More-Data: true header, the server is indicating that the build is in progress, and you need to repeat the request after some delay. The Jenkins UI waits 5 seconds before making the next call. When this header is not present, you know that you've retrieved all the data and the build is complete.