The Gradle Enterprise API allows programmatic interaction with various aspects of Gradle Enterprise, from configuration to inspecting build data.
Fundamentals
The Gradle Enterprise API is a REST-style API using JSON as the data format.
OpenAPI
The API is defined using the OpenAPI standard, which is a declarative specification that allows tools and libraries to generate client code. The specification can be found in the Reference section.
Versioning and compatibility
The API is generally backwards compatible.
New functionality (e.g. endpoints, response attributes) may be added in new major versions (i.e. 2022.1, 2022.2).
Breaking changes will occur infrequently if at all, and only after a reasonable deprecation period. Deprecations will be communicated by:
-
The release notes for the major Gradle Enterprise version introducing the deprecation.
-
The
deprecated
annotation within the OpenAPI specification. -
The
Deprecated
HTTP response header (indicating when the operation was deprecated). -
The
Sunset
HTTP response header (indicating when the operation will be removed).
API documentation may be refined in patch releases, along with implementation defects that cause deviation from the specification.
Getting started
Access control
All requests must provide a Gradle Enterprise access key as “bearer token”.
To create an access key:
-
Sign in to Gradle Enterprise.
-
Access "My settings" from the user menu in the top right-hand corner of the page.
-
Access "Access keys" from the left-hand menu.
-
Click "Generate" on the right-hand side and copy the generated access key.
Different requests require different user permissions, as describe via the API specification.
To view the permissions assigned to you:
-
Sign in to Gradle Enterprise.
-
Access "My settings" from the user menu in the top right-hand corner of the page.
-
Access "Permissions" from the left-hand menu.
-
Check if you have the required permissions.
If you do not have the required permission, contact your Gradle Enterprise administrator.
Making a request
The following example demonstrates using cURL
to make a request to the builds
endpoint, which requires the “Access build data via the API” permission.
$ curl -H "Authorization: Bearer 7asejatf24zun43yshqufp7qi4ovcefxpykbwzqbzilcpwzb52ja" "https://ge.mycompany.com/api/builds?since=0&maxBuilds=3"
[ { "id": "7asfp6iy3d5ey", "availableAt": 1645452789334, "buildToolType": "gradle", "buildToolVersion": "7.4", "buildAgentVersion": "3.8.1" }, { "id": "1saxebtd5d4xs", "availableAt": 1645452795414, "buildToolType": "maven", "buildToolVersion": "3.8.4", "buildAgentVersion": "1.12.4" }, { "id": "hx4k23knk64ri", "availableAt": 1645453205526, "buildToolType": "gradle", "buildToolVersion": "7.4", "buildAgentVersion": "3.8.1" } ]
The builds
endpoint can be used to discover the builds observed by the system. This example fetches the 3 oldest builds due to the since=0&maxBuilds=3
parameters.
Next steps
Check out the sample project.
To learn more about the functionality provided by the API and what you can do with it, see Reference.
Reference
The reference documentation is useful for discovering the functionality of the API.
The reference specification is the API described using the OpenAPI standard and is useful for generating client code with OpenAPI-based tooling.
Appendix A: About the Export API
The Gradle Enterprise API described in this document will eventually replace the Gradle Enterprise Export API. At this time, the Gradle Enterprise API does not allow consuming the raw events of a build as the Export API does.
If your existing usage of the Export API can be replaced with the easier-to-use Gradle Enterprise API, please consider migrating. For assistance, please contact Gradle Enterprise support.
Appendix B: Release history
2022.4
-
Add new
/api/test-distribution/*
endpoints for managing API keys and agent pools -
Add new
/api/builds/{id}/gradle-projects
endpoint -
Add new
/api/builds/{id}/maven-modules
endpoint -
Introduce
fromInstant
,fromBuild
,reverse
query parameters on the/api/builds
operation query -
Deprecate
since
andsinceBuild
query parameters on the/api/builds
operation query
2022.3
-
Add
taskExecution.nonCacheabilityCategory
andtaskExecution.nonCacheabilityReason
to/api/builds/{id}/gradle-build-cache-performance
operation response -
Add
goalExecution.nonCacheabilityCategory
andgoalExecution.nonCacheabilityReason
to/api/builds/{id}/maven-build-cache-performance
operation response -
Add
taskExecution.taskType
to/api/builds/{id}/gradle-build-cache-performance
operation response -
Add
goalExecution.mojoType
to/api/builds/{id}/maven-build-cache-performance
operation response -
Add
buildCaches.remote.type
to/api/builds/{id}/gradle-build-cache-performance
operation response -
Add
buildCaches.remote.className
to/api/builds/{id}/gradle-build-cache-performance
operation response -
Add a
title
to/api/builds
inlined query parameters schema
2022.2
-
Improve OpenAPI specification examples
-
Add
buildCaches.local.isPushEnabled
to/api/builds/{id}/maven-build-cache-performance
operation response
2022.1
-
Initial release