Develocity API Kotlin

[][14] [][7]

(formerly gradle-enterprise-api-kotlin)

A Kotlin library to access the [Develocity API][1], easy to use from:

• [Jupyter notebooks with the Kotlin kernel][29]
• [Kotlin scripts (kts)][27]
• [Kotlin projects][28]
• [Gradle tasks][36]

val api = DevelocityApi.newInstance()
api.buildsApi.getBuildsFlow(fromInstant = 0, query = "buildStartTime<-1d").forEach {
  println(it)
}

How is this different from the [official samples][33]?

The official samples are an excellent demo of the API inside a full-fledged Java project. Among other things, you might not want to maintain an OpenAPI code generation setup. Even if you do, you'll find it generates less-than-ideal or even failing code depending on your openapi-generator configuration. This library [fixes][34] those issues in generated code, implements [paging][24], [caching][13] and [env-based configuration][8] for you, while providing a JAR that's ready-to-use from any project, script or notebook.

Setup

Set up once and use the library from any notebook, script or project:

• [DEVELOCITY_URL][16]: the URL of your Develocity instance
• [DEVELOCITYAPICACHE_ENABLED][12] (optional, off by default): enables caching for some

• An access key in one of the supported locations

Setup snippets

%useLatestDescriptors
%use develocity-api-kotlin(version=2026.1.0)

@file:DependsOn("com.gabrielfeo:develocity-api-kotlin:2026.1.0")

dependencies {
  implementation("com.gabrielfeo:develocity-api-kotlin:2026.1.0")
}

Usage

The [DevelocityApi][9] interface represents the Develocity REST API. It contains all the APIs exactly as listed in the [REST API Manual][5]:

interface DevelocityApi {
  val buildsApi: BuildsApi
  val testsApi: TestsApi
  val buildCacheApi: BuildCacheApi
  val projectsApi: ProjectsApi
  val metaApi: MetaApi
  val testDistributionApi: TestDistributionApi
  val authApi: AuthApi
  // ...
}

For example, [BuildsApi][20] contains all endpoints under /api/builds/:

• [BuildsApi.getBuilds][21]: GET /api/builds
• [BuildsApi.getGradleAttributes][22]: GET /api/builds/{id}/gradle-attributes
• ...

Calling the APIs

API methods are generated as suspend functions. For most cases like scripts and notebooks, simply use [runBlocking][30]:

runBlocking {
  val builds: List<Build> = api.buildsApi.getBuilds(fromInstant = 0, query = "...")
}

Caching

HTTP caching is available, which can speed up queries significantly, but is off by default. Enable by simply setting [DEVELOCITYAPICACHE_ENABLED][12] to true. See [CacheConfig][13] for caveats.

Extensions

Explore the library's convenience extensions: [com.gabrielfeo.develocity.api.extension][25].

By default, the API's most common endpoint, /api/builds, is paginated. The library provides a [getBuildsFlow][24] extension to handle paging under-the-hood and yield all builds as you collect them:

val builds: Flow<Build> = api.buildsApi.getBuildsFlow(fromInstant = 0, query = "...")
builds.collect {
  // ...
}

Shutdown

By default, the library keeps some of its resources (like threads) alive until idle, in case they're needed again. This is an optimization of [OkHttp][4]. If you're working on a notebook or have a long-living program that fetches builds continuosly, no shutdown is needed.

val api = DevelocityApi.newInstance()
while (true) {
  delay(2.minutes)
  processNewBuilds(api.buildsApi.getBuildsFlow(query = "..."))
  // Don't worry about shutdown
}

In other cases (i.e. fetching some builds and exiting), you might want to call [DevelocityApi.shutdown()][11] so that the program exits immediately:

val api = DevelocityApi.newInstance()
printMetrics(api.buildsApi.getBuildsFlow(query = "..."))
// Call shutdown if you expect the program to exit now
api.shutdown()

Working samples

• [Jupyter notebooks with the Kotlin kernel][29]
• [Kotlin scripts (kts)][27]
• [Kotlin projects][28]

Documentation

[][7]

The javadoc of API interfaces and models, such as [BuildsApi][18] and [GradleAttributes][19], matches the [REST API Manual][5] exactly. Both these classes and Gradle's own manual are generated from the same OpenAPI spec.

Optional setup

Logging

See docs/Logging.md for how to configure logging in projects, scripts, and notebooks.

Code-based configuration

Creating a custom [Config][8] allows you to change library settings via code instead of environment variables. It also lets you share resources between the library's OkHttpClient and your own. For example:

val config = Config(
  develocityUrl = "https://ge.mycompany.com/",
  accessKey = { vault.getDevelocityAccessKey() },
  clientBuilder = existingClient.newBuilder(),
)
val api = DevelocityApi.newInstance(config)
api.buildsApi.getBuilds(fromInstant = yesterdayMilli)

See the [Config][8] documentation for more.

More info

• Use JDK 8 or 14+ to run, if you want to avoid the ["illegal reflective access" warning about

• All classes live in these packages. If you need to make small edits to scripts where there's

import com.gabrielfeo.develocity.api.*
import com.gabrielfeo.develocity.api.model.*
import com.gabrielfeo.develocity.api.model.extension.*

Issues and contributions

If you run into any problems, please open an issue to make it visible to maintainers and other users. Contributions are always welcome, although it's recommended to open an issue first. For general discussions or questions, feel free to reach out to maintainers on the [Gradle Community Slack][35].

[1]: https://docs.gradle.com/enterprise/api-manual/ [2]: https://square.github.io/retrofit/ [3]: https://github.com/square/retrofit/issues/3448 [4]: https://github.com/square/retrofit/issues/3144#issuecomment-508300518 [5]: https://docs.gradle.com/enterprise/api-manual/ref/2024.1.html [6]: https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-gradle-plugin/README.adoc [7]: https://gabrielfeo.github.io/develocity-api-kotlin/ [8]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/index.html [9]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-develocity-api/ [11]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-develocity-api/shutdown.html [12]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/-cache-config/cache-enabled.html [13]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/-cache-config/index.html [14]: https://central.sonatype.com/artifact/com.gabrielfeo/develocity-api-kotlin/2026.1.0 [16]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/server.html [17]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/access-key.html [18]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-builds-api/index.html [19]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api.model/-gradle-attributes/index.html [20]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-builds-api/index.html [21]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-builds-api/get-builds.html [22]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-builds-api/get-gradle-attributes.html [23]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-develocity-api/-default-instance/index.html [24]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api.extension/get-builds-flow.html [25]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api.extension/index.html [26]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/ [27]: ./examples/example-scripts/example-script.main.kts [28]: ./examples/example-project [29]: https://nbviewer.org/github/gabrielfeo/develocity-api-kotlin/blob/main/examples/example-notebooks/MostFrequentBuilds.ipynb [30]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/run-blocking.html [31]: ./docs/AccessKeys.md [32]: ./examples [33]: https://github.com/gradle/develocity-api-samples [34]: https://github.com/gabrielfeo/develocity-api-kotlin/blob/main/build-logic/src/functionalTest/kotlin/com/gabrielfeo/task/PostProcessGeneratedApiTest.kt#L21 [35]: https://community.gradle.org/#community-channels [36]: ./examples/example-gradle-task/ [37]: https://docs.gradle.com/develocity/gradle-plugin/current/#manualaccesskey_configuration [38]: https://docs.gradle.com/develocity/maven-extension/current/#manualaccesskey_configuration