The Develocity Export API allows you to pull out build data from your Develocity instance - making it easy to push your build data into other systems and use your build data for internal dashboards and graphs.

The Export API is available at https://«develocity-host»/build-export/ and provides a number of Server-Sent Event (SSE) based resources over HTTPS.

The Develocity Export API described in this document will eventually be replaced by the Develocity API. At this time, the Develocity 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 Develocity API, please consider migrating. For assistance, please contact Develocity support.

Before you get started

Server-Sent Events (SSE)

Server-Sent Events (SSE) is an API for continuously receiving push based notifications from a server over a HTTP connection. With its event based approach and a defined mechanism for reconnect-resume, SSE is ideal for real-time streaming of events from server to client but also an efficient way of streaming large volumes of data.

SSE clients are available for most programming languages. The following are some examples:

Most modern browsers provide a JavaScript SSE client. However, this implementation doesn’t provide a way to send arbitrary request headers and is lacking in other features. An alternative implementation, such as EventSourcePolyfill, is recommended.

Compression

All of the Export API resources detailed below support gzip compression which will considerably reduce the amount of data being sent over the wire. Compression can be enabled by simply adding the header Accept-Encoding: gzip to your request.

Reconnect-resume

All Export API SSE messages will have their id field set, allowing you to take advantage of reconnect-resume functionality should the connection drop.

Connecting to a resource with the Last-Event-ID http header set will resume the stream from that point. In the case of a stream that has no further messages to emit and is complete, a response status of 204 No Content will be returned and further reconnection attempts should not be attempted.

Some SSE clients include this functionality out-of-the-box.

Streaming

Some Export API resources allow opting-in to streaming by including a stream URL query parameter with any value. When enabled, the connection is long lived and new data is pushed as it becomes available. When not enabled, all data that is available at the time of the request is sent and then the connection is closed. The reference information for the API resources below indicates which support streaming.

In order to keep a streaming connection alive during periods of inactivity, a "heart beat" message is periodically sent as an SSE comment and can be safely ignored. Most SSE clients are configured to ignore such comments by default.

Streaming requests are compatible with reconnect-resume, making it convenient to have long lived processes that make streaming requests and reconnect on any connection disruption and resume processing data.

If you are accessing Develocity through a reverse proxy server you may need to explicitly disable or limit response buffering streaming to avoid new data being delayed.

Access control

By default, Develocity does not allow anonymous access to the Export API. Requests must be authenticated, and the user granted the “Export API” permission.

To check whether your user account has this permission:

  1. Sign in to Develocity

  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

If you do not have permission to access the Export API according to this page, contact your Develocity system administrator.

The Export API supports HTTP basic authentication, and bearer token authentication (since Develocity 2021.1). Bearer token authentication is recommended for clients that are capable of supporting it. If you authenticate with an external service when signing in to Develocity (e.g. an organizational SAML identity provider), only bearer token authentication is supported.

When authenticating with the Export API over a plain HTTP connection (opposed to HTTPS), your authentication credentials are potentially interceptable by someone else. Use of HTTPS is strongly recommended.

Bearer token authentication

Using bearer token authentication requires a valid Develocity “access key”.

To create an access key for your account:

  1. Sign in to Develocity:

  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”

To authenticate with an access key, the following header must be sent with each request:

Authorization: Bearer access-key

For example, given an access key of 7asejatf24zun43yshqufp7qi4ovcefxpykbwzqbzilcpwzb52ja, the following header would be required:

Authorization: Bearer 7asejatf24zun43yshqufp7qi4ovcefxpykbwzqbzilcpwzb52ja
The standard EventSource implementation available in browser runtimes doesn’t provide a way to send arbitrary request headers, and therefore does not support bearer token authentication. An alternative, such as EventSourcePolyfill, can be used instead.

Basic authentication

For user accounts that authenticate directly with Develocity with a username and password, standard HTTP Basic Authentication can be used.

Authenticating with a bearer token instead of using basic authentication is recommended.

Cross-origin requests (CORS)

Export API requests made from a browser runtime may be subject to cross origin resource sharing access control, depending on the runtime. All requests made using a bearer token respond with the HTTP headers required to allow cross-origin requests. If you are experiencing errors when making requests that mention “CORS” or “cross origin access control”, authenticating with a bearer token will allow the requests to be made.

Version 2

https://«develocity-host»/build-export/v2

Available since Develocity 2021.2.

Version 2 offers effectively the same functionality as version 1, but allows observing builds from build tools other than Gradle.

Build listing

All build listing endpoints emit build events in order of when the build was received and processed by Develocity.

GET /builds/since/:date[?stream]

Emits events for each build that has been received and processed by Develocity, since the given date.

Parameters

:date

Required

A unix-epoch-time value.

The value refers to the instant that Develocity completed receiving and processing the build. It is not the time that the build occurred.

A value of 0 will stream all builds. Times in the future are invalid and will result in an error response.

A special value of now will emit all builds since the current time, and only makes sense with the stream parameter.

stream

Optional

Enables streaming.

The connection will remain open indefinitely with new build events emitted as new builds are received and processsed.
Response

A stream of messages of type Build.

Example requests
Stream all builds received since June 23, 2016 until now 
https://«develocity-host»/build-export/v2/builds/since/1466640000000
Stream all builds received since January 01, 1970 until now 
https://«develocity-host»/build-export/v2/builds/since/0
Stream all builds received from now onwards, in real-time 
https://«develocity-host»/build-export/v2/builds/since/now?stream

GET /builds/sinceBuild/:buildId[?stream]

Stream summary build data for all builds received and process since after the given build ID.

Parameters

:buildId

Required

The 13 character id of the build.

stream

Optional

Enables streaming.

The connection will remain open indefinitely with new build events emitted as new builds are received and processsed.
Response

A stream of messages of type Build.

Example requests
Stream all builds received since the build with the id gkoprlkauv35q was received until now 
https://«develocity-host»/build-export/v2/builds/sinceBuild/gkoprlkauv35q
Stream all builds received since the build with the id gkoprlkauv35q was received and all future builds 
https://«develocity-host»/build-export/v2/builds/sinceBuild/gkoprlkauv35q?stream

Individual builds

GET /build/:buildId/events[?eventTypes=type1,type2,…​]

Stream build information for an individual build.

Whilst running a build, build data is mapped to a series of events. The combination of build agent and build tool version used to run the build will determine what events are produced and at what version. You can see the full list of events in the Javadoc of the Develocity Event Model. These events are serialized as JSON and streamed as the data attribute of BuildEvent messages.

It is recommended to specify the event types you require whenever possible to reduce the amount of data streamed.
Parameters

:buildId

Required

The 13 character id of the build.

eventTypes

Optional

A comma separated list of BuildEvent event types.
Event types are case sensitive and only BuildEvent messages whose event type is included in this list will be streamed.
Omitting the query parameter entirely will result in all BuildEvent messages being streamed.
See the Javadoc of the Develocity Event Model for a list of valid event types.
Response

A stream consisting of the following messages in strict order:

A 503 Service Unavailable response indicates that the build data is still being stored and is not yet ready for reading. Clients should retry the request.

Example request
Stream all events for the build with the id gkoprlkauv35q 
https://«develocity-host»/build-export/v2/build/gkoprlkauv35q/events
Stream only the BuildStarted and BuildFinished events for the build with the id gkoprlkauv35q 
https://«develocity-host»/build-export/v2/build/gkoprlkauv35q/events?eventTypes=BuildStarted,BuildFinished

Event types

Build

An example of a Build event when using the version 2 of the Export API 
id: gkoprlkauv35q
event: Build
data: {
    "buildId": "gkoprlkauv35q",
    "timestamp": 1466640000000,
    "toolType": "gradle",
    "toolVersion": "3.3",
    "agentVersion": "1.6"
}
Attribute Description

buildId

The 13 character ID of the build.

timestamp

The time the build was received and processed by Develocity as a unix-epoch-time value.

toolType

The build tool type used to run the build (one of "gradle", "maven", "bazel").

toolVersion

The build tool version used to run the build.

agentVersion

The version of the plugin or extension applied to build in order to connect with Develocity.

BuildEvent

Information about a particular event that occurred during a build.

Message data is event type and version specific. You can discover what data to expect by using the Javadoc of the Develocity Event Model. Note that some event types have an empty data payload.

id: 1
event: BuildEvent
data: {
    "timestamp":1466640000000,
    "type": {
        "majorVersion": 1,
        "minorVersion": 0,
        "eventType": "BuildStarted"
    },
    "data": {}
}
id: 2
event: BuildEvent
data: {
    "timestamp": 1466640000001,
    "type": {
        "majorVersion": 1,
        "minorVersion": 0,
        "eventType": "BuildRequestedTasks"
    },
    "data": {
        "excluded": [],
        "requested": ["build"]
    }
}
Attribute Description

timestamp

The time the event occurred as a unix-epoch-time value.

type

The specific type of the event, including event type, major and minor version. To be used in data parsing.

data

A JSON object containing properties specific to the event type and version. See the Javadoc of the Develocity Event Model for details about specific event types.

Migrating from version 1

In order to migrate from version 1 to version 2, three things are needed:

  1. Replace /v1/ with /v2/ in request URLs

  2. For the /builds endpoint, use the field toolVersion in place of gradleVersion and agentVersion in place of pluginVersion

  3. Respect the new toolType field which indicates the build tool type if interested in a particular build tool type (values are one of gradle, maven or bazel)

No other changes are required.

Version 1

https://«develocity-host»/build-export/v1

Available since Develocity 2017.1.

Version 1 is limited to builds from the Gradle build tool.

Build listing

All build listing endpoints emit build events in order of when the build was received and processed by Develocity.

GET /builds/since/:date[?stream]

Emits events for each Gradle build that has been received and processed by Develocity, since the given date.

Parameters

:date

Required

A unix-epoch-time value.

The value refers to the instant that Develocity completed receiving and processing the build. It is not the time that the build occurred.

A value of 0 will stream all builds. Times in the future are invalid and will result in an error response.

A special value of now will emit all builds since the current time, and only makes sense with the stream parameter.

stream

Optional

Enables streaming.

The connection will remain open indefinitely with new build events emitted as new builds are received and processsed.
Response

A stream of messages of type Build.

Example requests
Stream all Gradle builds received since June 23, 2016 until now 
https://«develocity-host»/build-export/v1/builds/since/1466640000000
Stream all Gradle builds received since January 01, 1970 until now 
https://«develocity-host»/build-export/v1/builds/since/0
Stream all Gradle builds received from now onwards, in real-time 
https://«develocity-host»/build-export/v1/builds/since/now?stream

GET /builds/sinceBuild/:buildId[?stream]

Stream summary build data for all Gradle builds received and processed since after the given build ID.

Parameters

:buildId

Required

The 13 character id of the build.

stream

Optional

Enables streaming.

The connection will remain open indefinitely with new build events emitted as new builds are received and processsed.
Response

A stream of messages of type Build.

Example requests
Stream all Gradle builds received since the build with the id gkoprlkauv35q was received until now 
https://«develocity-host»/build-export/v1/builds/sinceBuild/gkoprlkauv35q
Stream all Gradle builds received since the build with the id gkoprlkauv35q was received and all future builds 
https://«develocity-host»/build-export/v1/builds/sinceBuild/gkoprlkauv35q?stream

Individual builds

GET /build/:buildId/events[?eventTypes=type1,type2,…​]

Stream build information for an individual build.

Whilst running a build, build data is mapped to a series of events. The combination of build agent and build tool version used to run the build will determine what events are produced and at what version. You can see the full list of events in the Javadoc of the Develocity Event Model. These events are serialized as JSON and streamed as the data attribute of BuildEvent messages.

It is recommended to specify the event types you require whenever possible to reduce the amount of data streamed.
Parameters

:buildId

Required

The 13 character id of the build. If the provided id is not for a Gradle build, no events will be streamed, and the request will result in a 400 Bad request response.

eventTypes

Optional

A comma separated list of BuildEvent event types.
Event types are case sensitive and only BuildEvent messages whose event type is included in this list will be streamed.
Omitting the query parameter entirely will result in all BuildEvent messages being streamed.
See the Javadoc of the Develocity Event Model for a list of valid event types.
Response

A stream consisting of the following messages in strict order:

A 503 Service Unavailable response indicates that the build data is still being stored and is not yet ready for reading. Clients should retry the request.

Example request
Stream all events for the Gradle build with the id gkoprlkauv35q 
https://«develocity-host»/build-export/v1/build/gkoprlkauv35q/events
Stream only the BuildStarted and BuildFinished events for the Gradle build with the id gkoprlkauv35q 
https://«develocity-host»/build-export/v1/build/gkoprlkauv35q/events?eventTypes=BuildStarted,BuildFinished

Event types

Build

An example of a Build event when using the version 1 of the Export API 
id: gkoprlkauv35q
event: Build
data: {
    "buildId": "gkoprlkauv35q",
    "timestamp": 1466640000000,
    "gradleVersion": "3.3",
    "pluginVersion": "1.6"
}
Attribute Description

buildId

The 13 character ID of the build.

timestamp

The time the build was received and processed by Develocity as a unix-epoch-time value.

gradleVersion

The version of Gradle used to run the build.

pluginVersion

The version of the Develocity plugin used.

BuildEvent

Information about a particular event that occurred during a build.

Message data is event type and version specific. You can discover what data to expect by using the Javadoc of the Develocity Event Model. Note that some event types have an empty data payload.

id: 1
event: BuildEvent
data: {
    "timestamp":1466640000000,
    "type": {
        "majorVersion": 1,
        "minorVersion": 0,
        "eventType": "BuildStarted"
    },
    "data": {}
}
id: 2
event: BuildEvent
data: {
    "timestamp": 1466640000001,
    "type": {
        "majorVersion": 1,
        "minorVersion": 0,
        "eventType": "BuildRequestedTasks"
    },
    "data": {
        "excluded": [],
        "requested": ["build"]
    }
}
Attribute Description

timestamp

The time the event occurred as a unix-epoch-time value.

type

The specific type of the event, including event type, major and minor version. To be used in data parsing.

data

A JSON object containing properties specific to the event type and version. See the Javadoc of the Develocity Event Model for details about specific event types.

Examples

Please see the Export API samples GitHub repository for working example usages of the Export API in Java and JavaScript.