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:

  1. Sign in to Gradle Enterprise.

  2. Access "My settings" from the user menu in the top right-hand corner of the page.

  3. Access "Access keys" from the left-hand menu.

  4. 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:

  1. Sign in to Gradle Enterprise.

  2. Access "My settings" from the user menu in the top right-hand corner of the page.

  3. Access "Permissions" from the left-hand menu.

  4. 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.

2022.4

Older Versions

2022.3

Documentation

Specification (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)

2022.2

Documentation

Specification (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)

2022.1

Documentation

Specification (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)

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

8th December 2022

  • 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 and sinceBuild query parameters on the /api/builds operation query

2022.3

10th August 2022

  • Add taskExecution.nonCacheabilityCategory and taskExecution.nonCacheabilityReason to /api/builds/{id}/gradle-build-cache-performance operation response

  • Add goalExecution.nonCacheabilityCategory and goalExecution.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

19th April 2022

  • Improve OpenAPI specification examples

  • Add buildCaches.local.isPushEnabled to /api/builds/{id}/maven-build-cache-performance operation response

2022.1

17th March 2022

  • Initial release