Introduction

Welcome to the GoCD API! You can use our API to access GoCD API endpoints, which can get information about the server’s configuration and build history. In addition it can be used to update configuration and execute builds.

We currently provide language bindings in Shell! You can view code examples on the right-hand side of the page.

All APIs SHOULD be accessed from https://go-server-url:8154/go/api. All data SHOULD be sent and recieved as JSON, specifically application/vnd.go.cd.v1+json. You may access the APIs over plain text, but for security reasons we suggest that you use SSL.

API versions

It is recommended to explicitly request the version of an API via the Accept header.

Accept: application/vnd.go.cd.v1+json

Accept: application/vnd.go.cd.v2+json etc

If you specify an unsupported Accept header, GoCD will respond with the error message The url you are trying to reach appears to be incorrect.

Important: The version of an API may change in the future. If you care about the stability of the API, make sure that you are requesting a specific version in the Accept header as shown in the example above.

Authentication

All APIs require you to authenticate yourself using your username and password. Starting with version 19.2.0 of GoCD, users may also use a bearer token to authenticate. A cookie will also be returned as a result of the first authentication call. You may use this cookie for any further authentication attempts. If authentication fails, GoCD server may return status codes 401, 403 or 404.

Bearer token authentication

Available since v19.2.0.

To authorize, use this code:

# With shell, you can just pass the correct header with each request$ curl 'https://ci.example.com/go/api/current_user'\
-H 'Authentication: bearer YOUR_TOKEN'\
-H 'Accept: application/vnd.go.cd.v1+json'

Make sure to replace the YOUR_TOKEN the API token you use to access the GoCD server. The above command returns the following response:

To use Basic Authentication with the GoCD API, simply send the username and password associated with the account.

Cookie/Session authentication

Using the cookie/session returned from the previous API call, one can make further API calls. Using a cookie will dramatically improve performance of API calls especially if GoCD is authenticating against an external source like LDAP.

# With shell, you can just pass the correct header with each request$ curl 'https://ci.example.com/go/api/current_user'\
-b 'JSESSIONID=15kvus1kdrec46vk2a6jmtmo'\
-H 'Accept: application/vnd.go.cd.v1+json'

{"_links":{"self":{"href":"https://ci.example.com/go/api/current_user/access_tokens"},"doc":{"href":"https://api.gocd.org/19.2.0/#access-token"}},"_embedded":{"access_tokens":[{"_links":{"self":{"href":"https://ci.example.com/go/api/current_user/access_tokens/42"},"doc":{"href":"https://api.gocd.org/19.2.0/#access-token"},"find":{"href":"https://ci.example.com/go/api/current_user/access_tokens/:id"}},"id":42,"description":"my first token","username":"username","revoked":false,"revoke_cause":null,"revoked_by":null,"revoked_at":null,"created_at":"2019-02-20T10:45:10Z","last_used_at":null}]}}

{"_links":{"self":{"href":"https://ci.example.com/go/api/current_user/access_tokens/42"},"doc":{"href":"https://api.gocd.org/19.2.0/#access-token"},"find":{"href":"https://ci.example.com/go/api/current_user/access_tokens/:id"}},"id":42,"description":"my first token","username":"username","revoked":false,"revoke_cause":null,"revoked_by":null,"revoked_at":null,"created_at":"2019-02-20T10:45:10Z","last_used_at":null}

{"_links":{"self":{"href":"https://ci.example.com/go/api/current_user/access_tokens/42"},"doc":{"href":"https://api.gocd.org/19.2.0/#access-token"},"find":{"href":"https://ci.example.com/go/api/current_user/access_tokens/:id"}},"id":42,"description":"my first token","username":"username","revoked":true,"revoke_cause":null,"revoked_by":null,"revoked_at":null,"created_at":null,"last_used_at":null,"token":"30bd353a513ef3a2f72f46cc50d2a587b855fa04"}

{"_links":{"self":{"href":"https://ci.example.com/go/api/current_user/access_tokens/42"},"doc":{"href":"https://api.gocd.org/19.2.0/#access-token"},"find":{"href":"https://ci.example.com/go/api/current_user/access_tokens/:id"}},"id":42,"description":"token was compromised","username":"username","revoked":true,"revoke_cause":"foo","revoked_by":"jez","revoked_at":"2019-02-20T11:25:03Z","created_at":"2019-02-20T10:45:10Z","last_used_at":null}

{"_links":{"self":{"href":"https://ci.example.com/go/api/admin/access_tokens/42"},"doc":{"href":"https://api.gocd.org/19.2.0/#access-token"},"find":{"href":"https://ci.example.com/go/api/admin/access_tokens/:id"}},"id":42,"description":"my first token","username":"username","revoked":false,"revoke_cause":null,"revoked_by":null,"revoked_at":null,"created_at":"2019-02-20T10:45:10Z","last_used_at":null}

{"_links":{"self":{"href":"https://ci.example.com/go/api/admin/access_tokens/42"},"doc":{"href":"https://api.gocd.org/19.2.0/#access-token"},"find":{"href":"https://ci.example.com/go/api/admin/access_tokens/:id"}},"id":42,"description":"token was compromised","username":"username","revoked":true,"revoke_cause":"foo","revoked_by":"jez","revoked_at":"2019-02-20T11:25:03Z","created_at":"2019-02-20T10:45:10Z","last_used_at":null}

Allows system administrators to revoke a token belonging to any user so that the token cannot be reused again.

Agent Health

The agents API allows users to monitor if the agent is connected to the server and is authorized to perform a build.

Note: For security reasons, this endpoint is only bound to the localhost interface. If you’re accessing the endpoint from a remote machine and want to expose this endpoint externally — please see this documentation on how to configure the endpoint bind address and port.

Check agent-server connectivity

$ curl 'http://localhost:8152/health/v1/isConnectedToServer'

The above command returns a plain text response:

HTTP/1.1200OKContent-Type:text/plain; charset=utf-8
OK!

This API when invoked on an agent, will indicate if the agent-server connectivity is in a state that allows agents to run builds.

Available since v17.11.0.

HTTP Request

GET /health/v1/isConnectedToServer

You may alternatively use:

GET /health/latest/isConnectedToServer

which will render the most recent version of the api.

Returns

A status code 200 along with text OK! if all the following conditions are met:

able to establish HTTP(s) contact with the server

is authorized by the server (by an admin, or by auto-registration)

The endpoint will return status 503 in any other cases.

Two consecutive failing pings will be treated as having failed healthcheck.

Note: When a GoCD server is upgraded, the agent will automatically upgrade itself by downloading a copy from the GoCD server. During the time a new agent jar is being downloaded, this api endpoint may not be available.

To secure the http endpoint, the webhook configuration on bitbucket must specify a Basic Authentication User, the value of the Basic Authentication User should be same as the value of the webhookSecret attribute on the <server/> element in the file cruise-config.xml. Do not specify any basic authentication credentials in the webhook URL.

Returns

A text confirmation, with the http status 202 Accepted.

Hosting your repository on GitHub, or GitHub Enterprise?

Available since v17.6.0.

To notify GoCD of a push to a GitHub repository via a repository or organization webhook, configure GitHub to use the webhooks api negating the need for basic authentication on each request.

Note: Polling must be turned off for the pipeline associated with this material.

https://gocd.example.com:8154/go/api/webhooks/github/notify

To secure the http endpoint, the webhook configuration on GitHub must specify a Secret, the value of the Secret should be same as the value of the webhookSecret attribute on the <server/> element in the file cruise-config.xml. Do not specify any basic authentication credentials in the webhook URL.

Returns

A text confirmation, with the http status 202 Accepted.

Hosting your repository on GitLab?

Available since v17.11.0.

To notify GoCD of an push to GitLab repository via a group or project webhook, configure GitLab to use the webhooks api negating the need for basic authentication on each request.

Note: Polling must be turned off for the pipeline associated with this material.

https://gocd.example.com:8154/go/api/webhooks/gitlab/notify

To secure the http endpoint, the webhook configuration on GitLab must specify a Secret Token, the value of the Secret Token should be same as the value of the webhookSecret attribute on the <server/> element in the file cruise-config.xml. Do not specify any basic authentication credentials in the webhook URL.

The server may be unavailable during the time that the backup is being taken.
The response from the call will not be received till the backup is complete
(synchronous). If the data to be backed up is a lot, this can take minutes
to complete.

Get artifact directory

The above command returns the contents of the directory you requested as a compressed zip file.

Gets an artifact directory by its path.

Available since v14.3.0.

HTTP Request

GET /go/files/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/:job_name/*path_to_directory.zip

The path_to_directory can be a nested directory for e.g. target/dist.zip
Since it may take an undetermined amount of time to compress a directory, the server may return a 202 Accepted code to indicate that it is compressing the requested directory.

Users are expected to poll the url every few seconds to check if the directory is available.

Returns

One of -

A status code 202 Accepted to acknowledge your request to compress the contents of the requested directory.

Uploads local files as artifacts to the GoCD server. This is done by creating a zip file of the files which need to be uploaded. The GoCD
server will unzip the files, once it is uploaded, allowing multiple files to be uploaded at a time.

Dashboard pipeline pause information object

{"pause_info":{"paused":true,"paused_by":"John","pause_reason":"Pipeline Under Maintenance","paused_at":"2019-03-01T06:43:38Z"}}

Attribute

Type

Description

paused

Boolean

Whether the current pipeline instance is paused.

paused_by

String

The name of the user who paused the pipeline.

pause_reason

String

The pause cause of the pipeline.

paused_at

String

The pipeline paused at time.

Dashboard pipeline pipeline-instance object

{"instances":[{"label":"1","counter":1,"triggered_by":"Triggered by changes","scheduled_at":"2018-11-21T09:43:07Z","_embedded":{"stages":[{"name":"up42_stage","counter":"1","status":"Building","approved_by":"changes","scheduled_at":"2018-11-21T09:43:07Z"}]}}]}

{"_links":{"self":{"href":"https://ci.example.com/go/api/dashboard"},"doc":{"href":"https://api.go.cd/current/#dashboard"}},"_personalization":"2356e5d4241f22987d8f8cb8920913fda237385b423bd7eec7e97b2a9eb1be1a","_embedded":{"pipeline_groups":[{"_links":{"doc":{"href":"https://api.go.cd/current/#pipeline-groups"},"self":{"href":"https://ci.example.com/go/api/config/pipeline_groups"}},"name":"first","pipelines":["up42"],"can_administer":true}],"environments":[{"_links":{"doc":{"href":"https://api.gocd.org/current/#environment-config"},"self":{"href":"https://ci.example.com/go/api/admin/environments/asd"}},"name":"asd","pipelines":["up42"],"can_administer":true}],"pipelines":[{"_links":{"self":{"href":"https://ci.example.com/go/api/pipelines/up42/history"},"doc":{"href":"https://api.go.cd/current/#pipelines"}},"name":"up42","last_updated_timestamp":1542863609039,"locked":false,"pause_info":{"paused":false,"paused_by":null,"pause_reason":null},"can_operate":true,"can_administer":true,"can_unlock":true,"can_pause":true,"from_config_repo":false,"_embedded":{"instances":[{"_links":{"self":{"href":"https://ci.example.com/go/api/pipelines/up42/instance/1"}},"label":"1","counter":1,"triggered_by":"Triggered by changes","scheduled_at":"2018-11-21T09:43:07Z","_embedded":{"stages":[{"_links":{"self":{"href":"https://ci.example.com/go/api/stages/up42/1/up42_stage/1"}},"name":"up42_stage","counter":"1","status":"Building","approved_by":"changes","scheduled_at":"2018-11-21T09:43:07Z"}]}}]}}]}}

Lists pipelines on Dashboard along with pipeline groups and environments information.

Available since v18.12.0.

HTTP Request

GET /go/api/dashboard

Returns

An array of pipelines on Dashboard.

Encryption

The encryption API allows users with any administrator privilege to get the cipher text(encrypted text) corresponding to any plain text value. You may use this cipher text in other APIs that allow you to configure the pipelines and templates.

Important:This API is rate limited to 30 requests per minute to prevent brute force attacks that may allow attackers to guess the cipher key. The number of requests is configurable by the system property
go.encryption.api.max.requests. Please check this documentation on how to configure system properties.

The number of jobs to run. If set to null (default), one job will be created. If set to the literal string all, the job will be run on all agents. If set to a positive integer, the specified number of jobs will be created. Can be one of null, Integer, all.

timeout

Number

The time period(in minute) after which the job will be terminated by GoCD if it has not generated any output.

The file or folder to publish to the server. Should be specified if type is either test or build.

destination

String

The destination is relative to the artifacts folder of the current job instance on the server side. If it is not specified, the artifact will be stored in the root of the artifacts directory. Should be specified if type is either test or build.

id

String

The artifact id for an external artifact. This id can be used later in a downstream fetch task. Should be specified if type is external.

store_id

String

The artifact store id referencing an existing global artifact store. Should be specified if type is external.

configuration

Array

A list of key-value pairs which defines the plugin configuration. Should be specified if type is external.

Note:
The update pipeline API requires that you submit the If-Match
header with the latest ETag value that is representative of the current
pipeline config resource.

This is required in order to avoid the “lost update” problem, where a client
`GET`s a resource’s state, modifies it and `PUT`s it back to the server, while
another user has modified the state of the pipeline config, leading to a
conflict.

Note:
The update template config API requires that you submit the If-Match
header with the latest ETag value that is representative of the current
template resource.

This is required in order to avoid the “lost update” problem, where a client
`GET`s a resource’s state, modifies it and `PUT`s it back to the server, while
another user has modified the state of the template config, leading to a
conflict.

Note:
The update template authorization API requires that you submit the If-Match
header with the latest ETag value that is representative of the current
template resource.

This is required in order to avoid the “lost update” problem, where a client
`GET`s a resource’s state, modifies it and `PUT`s it back to the server, while
another user has modified the state of the template config, leading to a
conflict.

Note:
The update pipeline group API requires that you submit the If-Match
header with the latest ETag value that is representative of the current
role.

This is required in order to avoid the “lost update” problem, where a client
`GET`s a resource’s state, modifies it and `PUT`s it back to the server, while
another user has modified the state of the pipeline group config, leading to a
conflict.

Note:
The update environment API requires that you submit the If-Match
header with the latest ETag value that is representative of the current
environment config resource.

This is required in order to avoid the “lost update” problem, where a client
`GET`s a resource’s state, modifies it and `PUT`s it back to the server, while
another user has modified the state of the environment config, leading to a
conflict.

Available since v16.7.0.

HTTP Request

PUT /go/api/admin/environments/:environment_name

All of the following properties must be specified. Not specifying a property will either fail the request or make that value blank during the update.

Attribute

Type

Description

name

String

The name of environment.

pipelines

Array

List of pipeline names that should be part of this environment.

agents

Array

List of agent uuids that should be part of this environment.

environment_variables

Array

The list of environment variables that will be passed to all tasks (commands) that are part of this environment.

Note:
The update elastic agent profile API requires that you submit the If-Match
header with the latest ETag value that is representative of the current
elastic agent resource.

This is required in order to avoid the “lost update” problem, where a client
`GET`s a resource’s state, modifies it and `PUT`s it back to the server, while
another user has modified the state of the elastic agent config, leading to a
conflict.

The plugin status object

Array of messages stating the reason why the plugin isn’t loaded. The messages are shown only if the status is invalid.

The plugin vendor object

{"name":"GoCD contributors","url":"http://thoughtworks.com"}

Attribute

Type

Description

name

String

Name of the plugin author.

url

String

Link to know more details about the plugin author.

The plugin about object

{"name":"GitHub Pull Requests Builder","version":"1.3.3","target_go_version":"15.1.0","description":"Plugin that polls a GitHub repository for pull requests and triggers a build for each of them","target_operating_systems":[],"vendor":{"name":"GoCD contributors","url":"http://thoughtworks.com"}}

The list of properties that can be used to configure a package material. A form is created for the user based on these properties. No request is currently made to fetch the view for package settings.

repository_settings

Object

The list of properties that can be used to configure package repositories. A form is created for the user based on these properties. No request is currently made to fetch the view for repository settings.

Note:
The update plugin settings API requires that you submit the If-Match
header with the latest ETag value that is representative of the current
plugin settings resource.

This is required in order to avoid the “lost update” problem, where a client
`GET`s a resource’s state, modifies it and `PUT`s it back to the server, while
another user has modified the state of the plugin settings resource, leading to a
conflict.

SCMs

The global scm config object

Available since v16.7.0.

Attribute

Type

Description

id

String

Each material is associated with an id by which it can be referenced in the pipelines. If the id is not provided during creation, a uuid will be generated. Id is mandatory while providing data for update.

Note:
The update pluggable SCM API requires that you submit the If-Match
header with the latest ETag value that is representative of the current
SCM config resource.

This is required in order to avoid the “lost update” problem, where a client
`GET`s a resource’s state, modifies it and `PUT`s it back to the server, while
another user has modified the state of the scm config, leading to a
conflict.

Note:
The update repository API requires that you submit the If-Match
header with the latest ETag value that is representative of the current
repository config resource.

This is required in order to avoid the “lost update” problem, where a client
`GET`s a resource’s state, modifies it and `PUT`s it back to the server, while
another user has modified the state of the repository config, leading to a
conflict.

Packages

The package config object

Available since v16.12.0.

Attribute

Type

Description

name

String

The name of the package.

id

String

Each material is associated with an id by which it can be referenced in the pipelines. If the id is not provided during creation, a uuid will be generated. Id is mandatory while providing data for update.

auto_update

Boolean

Whether the material is set to poll for new changes. Defaults to true.

package_repo

Object

The package repo object provides the id and name of the repository to which the package belongs.

configuration

Object

The list of properties (key-value pairs) to be provided for using the plugin.

Note:
The update package API requires that you submit the If-Match
header with the latest ETag value that is representative of the current
package config resource.

This is required in order to avoid the “lost update” problem, where a client
`GET`s a resource’s state, modifies it and `PUT`s it back to the server, while
another user has modified the state of the package config, leading to a
conflict.

Note:
The update authorization configuration API requires that you submit the If-Match
header with the latest ETag value that is representative of the current
authorization configuration.

This is required in order to avoid the “lost update” problem, where a client
`GET`s a resource’s state, modifies it and `PUT`s it back to the server, while
another user has modified the state of the elastic agent config, leading to a
conflict.

Note:
The update role API requires that you submit the If-Match
header with the latest ETag value that is representative of the current
role.

This is required in order to avoid the “lost update” problem, where a client
`GET`s a resource’s state, modifies it and `PUT`s it back to the server, while
another user has modified the state of the elastic agent config, leading to a
conflict.

Config Repo

The config repo API allows admin users to define and manage config repos using which pipelines defined in external repositories can be included in GoCD, thereby allowing users to have their Pipeline as code.

The config repo object

Available since v17.12.0.

Attribute

Type

Description

id

String

Each config repo is associated with an unique id by which it can be referenced. Id is mandatory field for config repo.

Note:
The update config repo API requires that you submit the If-Match
header with the latest ETag value that is representative of the current
config repo config resource.

This is required in order to avoid the “lost update” problem, where a client
`GET`s a resource’s state, modifies it and `PUT`s it back to the server, while
another user has modified the state of the config repo config, leading to a
conflict.

A boolean indicating whether the content can be successfully merged and array of errors (if content isn’t mergeable).

Artifact Store

The artifact store API allows admin users to define and manage configuration of external artifact repository. The artifact plugin will use the artifact store config to upload artifact to an external repository.

Note:
The update artifact store API requires that you submit the If-Match
header with the latest ETag value that is representative of the current
artifact store.

This is required in order to avoid the “lost update” problem, where a client
`GET`s a resource’s state, modifies it and `PUT`s it back to the server, while
another user has modified the state of the elastic agent config, leading to a
conflict.

Server Health Messages

The server health messages API allows users to see any errors and warnings generated by the GoCD server as part of its normal routine. These messages are also visible in on the “errors and warnings” modal box on all pages of the GoCD server.

[{"message":"Job 'Security-Checks/test/dependency-check' is not responding","detail":"Job <a href='/go/tab/build/detail/Security-Checks/847/test/1/dependency-check'>Security-Checks/test/dependency-check</a> is currently running but has not shown any console activity in the last 26 minute(s). This job may be hung.","level":"WARNING","time":"2018-02-27T07:36:30Z"}]

Note:
The update system admins API requires that you submit the If-Match
header with the latest ETag value that is representative of the current
role.

This is required in order to avoid the “lost update” problem, where a client
`GET`s a resource’s state, modifies it and `PUT`s it back to the server, while
another user has modified the state of the elastic agent config, leading to a
conflict.