NAV Navbar
Logo
shell
Switch version:

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[.VERSION]+json. You may access the APIs over plain text, but for security reasons we suggest that you use TLS.

API versions

It is recommended to explicitly request the version of an API via the Accept: application/vnd.go.cd[.VERSION]+json header, with an appropriate version. Some examples are:

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

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

Each documented API endpoint shows the correct version to use in its usage documentation.

Beginning with GoCD version 19.8, it is possible to omit the version number by specifying Accept: application/vnd.go.cd+json. This will render the latest version.

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

GoCD Deprecated APIs

GoCD may deprecate APIs for any of the following reasons:

In order to convey the API deprecation information to the API consumers, GoCD adds following deprecation headers for a deprecated API:

Revoking deprecations

Occasionally, the deprecation of an API may be modified/reversed for some unavoidable reasons. In such situations, the subsequent GoCD releases will provide the updated deprecated headers with information relevant to the decision. Refer changelog section for the list of deprecated APIs.

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. 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 'Authorization: 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:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "doc": {
      "href": "https://api.gocd.org/#users"
    },
    "current_user": {
      "href": "https://ci.example.com/go/api/current_user"
    },
    "self": {
      "href": "https://ci.example.com/go/api/users/username"
    },
    "find": {
      "href": "https://ci.example.com/go/api/users/:login_name"
    }
  },
  "login_name": "username",
  "display_name": "username",
  "enabled": true,
  "email": "demo@example.com",
  "email_me": true,
  "checkin_aliases": []
}

To generate an access token, navigate to https://ci.example.com:8154/go/access_tokens, or use the access token API.

Basic authentication

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' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

Make sure to replace the username and password with the username and password that you use to access the GoCD server. The above command returns the following response:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "doc": {
      "href": "https://api.gocd.org/#users"
    },
    "current_user": {
      "href": "https://ci.example.com/go/api/current_user"
    },
    "self": {
      "href": "https://ci.example.com/go/api/users/username"
    },
    "find": {
      "href": "https://ci.example.com/go/api/users/:login_name"
    }
  },
  "login_name": "username",
  "display_name": "username",
  "enabled": true,
  "email": "demo@example.com",
  "email_me": true,
  "checkin_aliases": []
}

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

section_marker_placeholder:Config

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.

The artifact store object

Available since v18.7.0.

{
  "id": "docker",
  "plugin_id": "cd.go.artifact.docker",
  "properties": [
    {
      "key": "RegistryURL",
      "value": "docker-registry-url"
    }
  ]
}

Attribute Type Description
id String The identifier of the artifact store.
plugin_id String The plugin identifier of the artifact plugin.
properties Array The list of configuration properties that represent the configuration of this artifact store.

Get all artifact stores

$ curl 'https://ci.example.com/go/api/admin/artifact_stores' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links" : {
    "self" : {
      "href" : "https://ci.example.com/go/api/admin/artifact_stores"
    },
    "doc" : {
      "href" : "https://api.gocd.org/current/#artifact_stores"
    },
    "find" : {
      "href" : "https://ci.example.com/go/api/admin/artifact_stores/:id"
    }
  },
  "_embedded" : {
    "artifact_stores" : [ {
      "_links" : {
        "self" : {
          "href" : "https://ci.example.com/go/api/admin/artifact_stores/hub.docker"
        },
        "doc" : {
          "href" : "https://api.gocd.org/current/#artifact_stores"
        },
        "find" : {
          "href" : "https://ci.example.com/go/api/admin/artifact_stores/:id"
        }
      },
      "id" : "hub.docker",
      "plugin_id" : "cd.go.artifact.docker.registry",
      "properties" : [ {
        "key" : "RegistryURL",
        "value" : "https://your_docker_registry_url"
      }, {
        "key" : "Username",
        "value" : "admin"
      }, {
        "key" : "Password",
        "encrypted_value" : "AES:tdfTtYtIUSAF2JXJP/3YwA==:43Kjidjuh42NHKisCAs/BQ=="
      } ]
    } ]
  }
}

Lists all available artifact stores.

Available since v18.7.0.

HTTP Request

GET /go/api/admin/artifact_stores

Returns

An array of artifact store object.

Get an artifact store

$ curl 'https://ci.example.com/go/api/admin/artifact_stores/docker' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "fff30fd05db389acded4e993c1ecd5a4"
{
  "_links" : {
    "self" : {
      "href" : "https://ci.example.com/go/api/admin/artifact_stores/hub.docker"
    },
    "doc" : {
      "href" : "https://api.gocd.org/current/#artifact_stores"
    },
    "find" : {
      "href" : "https://ci.example.com/go/api/admin/artifact_stores/:id"
    }
  },
  "id" : "hub.docker",
  "plugin_id" : "cd.go.artifact.docker.registry",
  "properties" : [ {
    "key" : "RegistryURL",
    "value" : "https://your_docker_registry_url"
  }, {
    "key" : "Username",
    "value" : "admin"
  }, {
    "key" : "Password",
    "encrypted_value" : "AES:tdfTtYtIUSAF2JXJP/3YwA==:43Kjidjuh42NHKisCAs/BQ=="
  } ]
}

Gets an artifact store for specified id.

Available since v18.7.0.

HTTP Request

GET /go/api/admin/artifact_stores/:storeId

Returns

The artifact store object.

Create an artifact store

$ curl 'https://ci.example.com/go/api/admin/artifact_stores' \
  -u 'username:password' \
  -H 'Accept: application/vnd.go.cd.v1+json' \
  -H 'Content-Type: application/json' \
  -X POST -d '{
    "id": "docker",
    "plugin_id": "cd.go.artifact.docker.registry",
    "properties" : [ {
      "key" : "RegistryURL",
      "value" : "https://your_docker_registry_url"
    }, {
      "key" : "Username",
      "value" : "admin"
    }, {
      "key" : "Password",
      "value" : "badger"
    }]
}'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "e239974f09be2d88565c584c01ba0954"
{
  "_links" : {
    "self" : {
      "href" : "https://ci.example.com/go/api/admin/artifact_stores/docker"
    },
    "doc" : {
      "href" : "https://api.gocd.org/current/#artifact_stores"
    },
    "find" : {
      "href" : "https://ci.example.com/go/api/admin/artifact_stores/:id"
    }
  },
  "id" : "docker",
  "plugin_id" : "cd.go.artifact.docker.registry",
  "properties" : [ {
    "key" : "RegistryURL",
    "value" : "https://your_docker_registry_url"
  }, {
    "key" : "Username",
    "value" : "admin"
  }, {
    "key" : "Password",
    "encrypted_value" : "AES:UbZMF/cQZCcywknuzW6r4Q==:Qbz5so1iz3WS2a4FSW775A=="
  } ]
}

Creates an artifact store

Available since v18.7.0.

HTTP Request

POST /go/api/admin/artifact_stores

Returns

The artifact store object.

Update an artifact store

$ curl 'https://ci.example.com/go/api/admin/artifact_stores/docker' \
  -u 'admin:badger' \
  -H 'Accept: application/vnd.go.cd.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'If-Match: "e239974f09be2d88565c584c01ba0954"' \
  -X PUT -d '{
    "id": "docker",
    "plugin_id": "cd.go.artifact.docker.registry",
    "properties" : [ {
      "key" : "RegistryURL",
      "value" : "https://your_docker_registry_url"
    }, {
      "key" : "Username",
      "value" : "admin"
    }, {
      "key" : "Password",
      "value" : "new_password"
    }]
}'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "fe2670c76227d5d96f76007f3803dc68"
{
  "_links" : {
    "self" : {
      "href" : "https://ci.example.com/go/api/admin/artifact_stores/docker"
    },
    "doc" : {
      "href" : "https://api.gocd.org/current/#artifact_stores"
    },
    "find" : {
      "href" : "https://ci.example.com/go/api/admin/artifact_stores/:id"
    }
  },
  "id" : "docker",
  "plugin_id" : "cd.go.artifact.docker.registry",
  "properties" : [ {
    "key" : "RegistryURL",
    "value" : "https://your_docker_registry_url"
  }, {
    "key" : "Username",
    "value" : "admin"
  }, {
    "key" : "Password",
    "encrypted_value" : "AES:yIow3jqZjP+mWuKubdwhTw==:safdVBEoe6sIjuuILGP53g=="
  } ]
}

Update some attributes of an artifact store.

Available since v18.7.0.

HTTP Request

PUT /go/api/admin/artifact_stores/:storeId

Returns

The updated The artifact store object..

Delete an artifact store

$ curl 'https://ci.example.com/go/api/admin/artifact_stores/docker' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -X DELETE

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "message": "The artifactStore 'docker' was deleted successfully."
}

Deletes the artifact store.

Available since v18.7.0.

HTTP Request

DELETE /go/api/admin/artifact_stores/:storeId

Returns

A message if the artifact store is deleted or not.

Artifacts Config

The artifacts config API allows admins to configure the artifacts directory and purge settings.

The Artifacts Config Object

Available since v19.11.0.

Attribute Type Description
artifacts_dir String This directory is where GoCD will store its information, including artifacts published by jobs. You can use an absolute path or a relative path which will take the server installed directory as the root.
purge_settings Object The attributes for purge settings.

The Purge Settings Object

Available since v19.11.0.

Attribute Type Description
purge_start_disk_space Number Purge artifacts when disk space is lower than purge_start_disk_space GB.
purge_upto_disk_space Number Purge artifacts till available disk space is greater than purge_upto_disk_space GB. This attribute must be defined if purge_start_disk_space is defined.

Get artifacts Config

$ curl 'https://ci.example.com/go/api/admin/config/server/artifact_config' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
Etag: "17f5a9edf150884e5fc4315b4a7814cd"
{
  "_links" : {
    "doc" : {
      "href" : "https://api.gocd.org/current/#artifacts-config"
    },
    "self" : {
      "href" : "http://ci.example.com/go/api/admin/config/server/artifact_config"
    }
  },
  "artifacts_dir" : "foo",
  "purge_settings" : {
    "purge_start_disk_space" : 10.0,
    "purge_upto_disk_space" : 20.0
  }
}

Available since v19.11.0.

HTTP Request

GET /go/api/admin/config/server/artifact_config

Returns

A artifacts config object.

Update artifacts Config

$ curl 'https://ci.example.com/go/api/admin/config/server/artifact_config' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "17f5a9edf150884e5fc4315b4a7814cd"' \
      -X PUT \
      -d '{
            "artifacts_dir": "foobar",
            "purge_settings":{
              "purge_start_disk_space": 30,
              "purge_upto_disk_space": 60
            }
          }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links" : {
    "doc" : {
      "href" : "https://api.gocd.org/current/#artifacts-config"
    },
    "self" : {
      "href" : "http://ci.example.com/go/api/admin/config/server/artifact_config"
    }
  },
  "artifacts_dir" : "foobar",
  "purge_settings" : {
    "purge_start_disk_space" : 30.0,
    "purge_upto_disk_space" : 60.0
  }
}

Available since v19.11.0.

HTTP Request

PUT /go/api/admin/config/server/artifact_config

Returns

A artifacts config object.

Authorization Configuration

The Authorization configuration API allows admin users to manage authorization configuration. This config will later be used by a plugin to authorize a user in the GoCD server.

The authorization configuration object

Available since v17.5.0.

Attribute Type Description
id String The identifier of the authorization configuration.
plugin_id String The plugin identifier of the authorization plugin.
allow_only_known_users_to_login String Allow only those users to login who have explicitly been added by an administrator.
properties Array The list of configuration properties that represent the configuration of this authorization configuration.

Get all authorization configurations

$ curl 'https://ci.example.com/go/api/admin/security/auth_configs' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/security/auth_configs"
    },
    "doc": {
      "href": "https://api.gocd.org/#authorization-configuration"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/security/auth_configs/:auth_config_id"
    }
  },
  "_embedded": {
    "auth_configs": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/security/auth_configs/ldap"
          },
          "doc": {
            "href": "https://api.gocd.org/#authorization-configuration"
          },
          "find": {
            "href": "https://ci.example.com/go/api/admin/security/auth_configs/:auth_config_id"
          }
        },
        "id": "ldap",
        "plugin_id": "cd.go.authentication.ldap",
        "allow_only_known_users_to_login": false,
        "properties": [
          {
            "key": "Url",
            "value": "ldap://ldap.server.url"
          }
        ]
      }
    ]
  }
}

Lists all available authorization configurations.

Updated to version v2 since v19.11.0.

Available since v17.5.0.

HTTP Request

GET /go/api/admin/security/auth_configs

Returns

An array of authorization configurations object.

Get an authorization configuration

$ curl 'https://ci.example.com/go/api/admin/security/auth_configs/ldap' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/security/auth_configs/ldap"
    },
    "doc": {
      "href": "https://api.gocd.org/#authorization-configuration"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/security/auth_configs/:auth_config_id"
    }
  },
  "id": "ldap",
  "plugin_id": "cd.go.authentication.ldap",
  "allow_only_known_users_to_login": false,
  "properties": [
    {
      "key": "Url",
      "value": "ldap://ldap.server.url:389"
    },
    {
      "key": "SearchBase",
      "value": "ou=users,ou=system"
    },
    {
      "key": "ManagerDN",
      "value": "uid=admin,ou=system"
    },
    {
      "key": "SearchFilter",
      "value": "uid"
    },
    {
      "key": "Password",
      "encrypted_value": "GLzARJ+Qr+M="
    },
    {
      "key": "DisplayNameAttribute",
      "value": "displayName"
    },
    {
      "key": "EmailAttribute",
      "value": "mail"
    }
  ]
}

Gets authorization configuration for specified id.

Updated to version v2 since v19.11.0.

Available since v17.5.0.

HTTP Request

GET /go/api/admin/security/auth_configs/:auth_config_id

Returns

The authorization configuration object.

Create an authorization configuration

$ curl 'https://ci.example.com/go/api/admin/security/auth_configs' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json' \
      -H 'Content-Type: application/json' \
      -X POST -d '{
        "id": "ldap",
        "plugin_id": "cd.go.authentication.ldap",
        "allow_only_known_users_to_login": false,
        "properties": [
          {
            "key": "Url",
            "value": "ldap://ldap.server.url:389"
          },
          ...
        ]
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/security/auth_configs/ldap"
    },
    "doc": {
      "href": "https://api.gocd.org/#authorization-configuration"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/security/auth_configs/:auth_config_id"
    }
  },
  "id": "ldap",
  "plugin_id": "cd.go.authentication.ldap",
  "allow_only_known_users_to_login": false,
  "properties": [
    {
      "key": "Url",
      "value": "ldap://ldap.server.url:389"
    },
    {
      "key": "SearchBase",
      "value": "ou=users,ou=system"
    },
    {
      "key": "ManagerDN",
      "value": "uid=admin,ou=system"
    },
    {
      "key": "SearchFilter",
      "value": "uid"
    },
    {
      "key": "Password",
      "encrypted_value": "GLzARJ+Qr+M="
    },
    {
      "key": "DisplayNameAttribute",
      "value": "displayName"
    },
    {
      "key": "EmailAttribute",
      "value": "mail"
    }
  ]
}

Creates an authorization configuration

Updated to version v2 since v19.11.0.

Available since v17.5.0.

HTTP Request

POST /go/api/admin/security/auth_configs

Returns

The authorization configuration object.

Update an authorization configuration

$ curl 'https://ci.example.com/go/api/admin/security/auth_configs/ldap' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"' \
      -X PUT \
      -d '{
        "plugin_id": "cd.go.authentication.ldap",
        "allow_only_known_users_to_login": false,
        "properties": [
          {
            "key": "Url",
            "value": "ldap://ldap.server.url:10389"
          },
          {
            "key": "SearchBase",
            "value": "ou=users,ou=system"
          },
          {
            "key": "ManagerDN",
            "value": "uid=admin,ou=system"
          }
          ...
        ]
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "61406622382e51c2079c11dcbdb978fb"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/security/auth_configs/ldap"
    },
    "doc": {
      "href": "https://api.gocd.org/#authorization-configuration"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/security/auth_configs/:auth_config_id"
    }
  },
  "id": "ldap",
  "plugin_id": "cd.go.authentication.ldap",
  "allow_only_known_users_to_login": false,
  "properties": [
    {
      "key": "Url",
      "value": "ldap://ldap.server.url:10389"
    },
    {
      "key": "SearchBase",
      "value": "ou=users,ou=system"
    },
    {
      "key": "ManagerDN",
      "value": "uid=admin,ou=system"
    },
    {
      "key": "SearchFilter",
      "value": "uid"
    },
    {
      "key": "Password",
      "encrypted_value": "GLzARJ+Qr+M="
    },
    {
      "key": "DisplayNameAttribute",
      "value": "displayName"
    },
    {
      "key": "EmailAttribute",
      "value": "mail"
    }
  ]
}

Update some attributes of an authorization configuration.

Updated to version v2 since v19.11.0.

Available since v17.5.0.

HTTP Request

PUT /go/api/admin/security/auth_configs/:auth_config_id

Returns

The updated authorization configuration object.

Delete an authorization configuration

$ curl 'https://ci.example.com/go/api/admin/security/auth_configs/ldap' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json' \
      -X DELETE

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
  "message": "The security auth config 'ldap' was deleted successfully."
}

Deletes the authorization configuration.

Updated to version v2 since v19.11.0.

Available since v17.5.0.

HTTP Request

DELETE /go/api/admin/security/auth_configs/:auth_config_id

Returns

A message if the authorization configuration is deleted or not.

Backup Config

The Backup Config API allows users to configure backup settings for the GoCD server.

The Backup Config Object

Available since v19.6.0.

Attribute Type Description
schedule String The backup schedule. See the quartz documentation for syntax and examples.
post_backup_script String The script that will be executed once the backup finishes. See the gocd documentation for details.
email_on_failure Boolean If set to true, an email will be sent when backup fails.
email_on_success Boolean If set to true, an email will be sent when backup completes successfully.

Get Backup Config

$ curl 'https://ci.example.com/go/api/config/backup' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/config/backup"
    },
    "doc": {
      "href": "https://api.gocd.org/#backup-config"
    }
  },
  "email_on_failure" : false,
  "email_on_success" : false,
  "post_backup_script" : "/usr/local/bin/copy-gocd-backup-to-s3",
  "schedule" : "0 0 2 * * ?"
}

Available since v19.6.0.

HTTP Request

GET /go/api/config/backup

Returns

A backup config object.

Create or Update Backup Config

$ curl 'https://ci.example.com/go/api/config/backup' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{
            "email_on_failure" : false,
            "email_on_success" : false,
            "post_backup_script" : "/usr/local/bin/copy-gocd-backup-to-s3",
            "schedule" : "0 0 2 * * ?"
          }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/config/backup"
    },
    "doc": {
      "href": "https://api.gocd.org/#backup-config"
    }
  },
  "email_on_failure" : false,
  "email_on_success" : false,
  "post_backup_script" : "/usr/local/bin/copy-gocd-backup-to-s3",
  "schedule" : "0 0 2 * * ?"
}

Available since v19.6.0.

HTTP Request

POST /go/api/config/backup

PUT /go/api/config/backup

Returns

A backup config object.

Delete Backup Config

$ curl 'https://ci.example.com/go/api/config/backup' </span>
      -u 'username:password' </span>
      -H 'Accept: application/vnd.go.cd.v1+json' </span>
      -X DELETE

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"message" : "Backup config was deleted successfully!"
}

Available since v19.6.0.

HTTP Request

DELETE /go/api/config/backup

Returns

A message confirmation if the backup config was deleted.

Cluster Profiles

The cluster profiles API allows users with admin authorization to manage cluster profiles.

The cluster profile object

Available since v19.3.0.

Attribute Type Description
id String The identifier of the cluster profile.
plugin_id String The plugin identifier of the cluster profile.
properties Array The list of configuration properties that represent the configuration of this profile.

Get all cluster profiles

$ curl 'https://ci.example.com/go/api/admin/elastic/cluster_profiles' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "32628084ef10b0c82a55f8f2f867d8d0"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles"
    },
    "doc": {
      "href": "https://api.gocd.org/#cluster-profiles"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles/:id"
    }
  },
  "_embedded": {
    "profiles": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles/prod-cluster"
          },
          "doc": {
            "href": "https://api.gocd.org/#cluster-profiles"
          },
          "find": {
            "href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles/:id"
          }
        },
        "id": "prod-cluster",
        "plugin_id": "cd.go.contrib.elastic-agent.docker",
        "properties": [
          {
            "key": "GoServerUrl",
            "value": "https://ci.example.com/go"
          }
        ]
      }
    ]
  }
}

Lists all available cluster profiles.

Available since v19.3.0.

HTTP Request

GET /go/api/admin/elastic/cluster_profiles

Returns

An array of cluster profiles.

Get a cluster profile

$ curl 'https://ci.example.com/go/api/admin/elastic/cluster_profiles/prod-cluster' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles/prod-cluster"
    },
    "doc": {
      "href": "https://api.gocd.org/#cluster-profiles"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles/:id"
    }
  },
  "id": "prod-cluster",
  "plugin_id": "cd.go.contrib.elastic-agent.docker",
  "properties": [
    {
      "key": "GoServerUrl",
      "value": "https://ci.example.com/go"
    }
  ]
}

Gets cluster profile config for specified profile id.

Available since v19.3.0.

HTTP Request

GET /go/api/admin/elastic/cluster_profiles/:id

Returns

The cluster profile object.

Create a cluster profile

$ curl 'https://ci.example.com/go/api/admin/elastic/cluster_profiles' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -H 'Content-Type: application/json' \
      -X POST -d '{
        "id": "prod-cluster",
        "plugin_id": "cd.go.contrib.elastic-agent.docker",
        "properties": [
          {
            "key": "GoServerUrl",
            "value": "https://ci.example.com/go"
          }
        ]
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles/prod-cluster"
    },
    "doc": {
      "href": "https://api.gocd.org/#cluster-profiles"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles/:id"
    }
  },
  "id": "prod-cluster",
  "plugin_id": "cd.go.contrib.elastic-agent.docker",
  "properties": [
    {
      "key": "GoServerUrl",
      "value": "https://ci.example.com/go"
    }
  ]
}

Creates a cluster profile

Available since v19.3.0.

HTTP Request

POST /go/api/admin/elastic/cluster_profiles

Returns

The cluster profile object.

Update a cluster profile

$ curl 'https://ci.example.com/go/api/admin/elastic/cluster_profiles/prod-cluster' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"' \
      -X PUT \
      -d '{
        "plugin_id": "cd.go.contrib.elastic-agent.docker",
        "properties": [
          {
            "key": "GoServerUrl",
            "value": "https://ci.example.com/go"
          }
        ]
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "61406622382e51c2079c11dcbdb978fb"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles/prod-cluster"
    },
    "doc": {
      "href": "https://api.gocd.org/#cluster-profiles"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles/:id"
    }
  },
  "id": "prod-cluster",
  "plugin_id": "cd.go.contrib.elastic-agent.docker",
  "properties": [
    {
      "key": "GoServerUrl",
      "value": "https://ci.example.com/go"
    }
  ]
}

Update some attributes of a cluster profile.

Available since v19.3.0.

HTTP Request

PUT /go/api/admin/elastic/cluster_profiles/:id

Returns

The updated cluster profile object.

Delete a cluster profile

$ curl 'https://ci.example.com/go/api/admin/elastic/cluster_profiles/prod-cluster' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -X DELETE

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "message": "Cluster profile 'prod-cluster' was deleted successfully."
}

Deletes the cluster profile.

Available since v19.3.0.

HTTP Request

DELETE /go/api/admin/elastic/cluster_profiles/:id

Returns

A message if the cluster profile is deleted or not.

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.
plugin_id String The name of the config repo plugin.
material Object The material to be used by the config repo.
configuration Object The list of properties (key-value pairs) to be provided for using the plugin.
rules Array The list of rules, which allows restricting the entities that the config repo can refer to. Referring to the GoCD entities is denied by default, an explicit rule should be added to allow a specific resource to allow the config repo to refer it. Since v20.2.0.

The config repo definition object

Available since v20.1.0.

Attribute Type Description
environments Array The list of environments defined in config repository.
groups Array The list of pipeline groups defined in config repository.

The config repo environment definition object

Attribute Type Description
name String The name of an environment.

The config repo pipeline groups definition object

Attribute Type Description
name String The name of a pipeline group.
pipelines Array The list of pipeline information defined in config repository.

The config repo pipeline definition object

Attribute Type Description
name String The name of a pipeline.

The config repo rule object

Attribute Type Description
directive String The type of rule which can be either allow or deny.
action String The action that is being controlled via this rule. Only refer is supported as of now.
type String The type of entity that the rule is applied on. Currently environment, pipeline and pipeline_group are supported.
resource String The actual entity on which the rule is applied. Resource should be the name of the entity or a wildcard which matches one or more entities.

The configuration property object

{
  "configuration": [
    {
      "key": "username",
      "value": "admin"
    },
    {
      "key": "password",
      "encrypted_value": "1f3rrs9uhn63hd"
    },
    {
      "key": "url",
      "value": "https://github.com/sample/example.git",
      "is_secure": true
    }
  ]
}

Attribute Type Description
key String The name of the property key.
value String The value of the property. You MUST specify one of value or encrypted_value.
encrypted_value String The encrypted value of the property. You MUST specify one of value or encrypted_value.
is_secure Boolean Specify whether the given property is secure or not. If true and encrypted_value is not specified, GoCD will store the value in encrypted format.

The config repository material object

Attribute Type Description
type String The type of a material. Can be one of git, svn, hg, p4, tfs.
attributes Object The attributes for each material type.

The git material attributes

{
  "type": "git",
  "attributes": {
    "url": "https://github.com/gocd/api.go.cd",
    "username": "bob",
    "encrypted_password": "aSdiFgRRZ6A=",
    "branch": "master",
    "auto_update": true
  }
}

Attribute Type Description
url String The URL of the git repository.
username String The user account for the remote repository. Since v19.4.0.
password String The password for the specified user. Since v19.4.0.
encrypted_password String The encrypted password for the specified user. Since v19.4.0.
branch String The git branch to build.
auto_update Boolean Whether to poll for new changes or not.

The svn material attributes

{
  "type": "svn",
  "attributes": {
    "url": "svn://svn.example.com/myProject/trunk",
    "username": "admin",
    "auto_update": true,
    "encrypted_password": "aSdiFgRRZ6A=",
    "check_externals": true
  }
}

Attribute Type Description
url String The URL of the subversion repository.
username String The user account for the remote repository.
password String The password for the specified user.
encrypted_password String The encrypted password for the specified user.
auto_update Boolean Whether to poll for new changes or not.
check_externals Boolean Whether the changes o the externals will trigger the pipeline automatically or not.

The mercurial material attributes

{
  "type": "hg",
  "attributes": {
    "url": "http://hg.example.com/hg/api.go.cd",
    "username": "bob",
    "encrypted_password": "aSdiFgRRZ6A=",
    "branch": "feature",
    "auto_update": true
  }
}

Attribute Type Description
url String The URL of the mercurial repository.
username String The user account for the remote repository. Since v19.4.0.
password String The password for the specified user. Since v19.4.0.
encrypted_password String The encrypted password for the specified user. Since v19.4.0.
branch String The mercurial branch to build. Since v19.4.0.
auto_update Boolean Whether to poll for new changes or not.

The perforce material attributes

{
  "type": "p4",
  "attributes": {
    "port": "p4.example.com:8080",
    "use_tickets": true,
    "view": "sample_view",
    "auto_update": true,
    "username": "admin",
    "encrypted_password": "aSdiFgRRZ6A="
  }
}

Attribute Type Description
port String Perforce server connection to use ([transport:]host:port).
use_tickets Boolean Whether to work with the Perforce tickets or not.
view String The Perforce view.
auto_update Boolean Whether to poll for new changes or not.
username String The username to be used.
password String The password for the specified user.
encrypted_password String The encrypted password for the specified user.

The tfs material attributes

{
  "type": "tfs",
  "attributes": {
    "url": "http://tfs.exampe.com:8000/tfs",
    "project_path": "$/",
    "domain": "corporate/domain",
    "username": "admin",
    "encrypted_password": "aSdiFgRRZ6A="
  }
}

Attribute Type Description
url String The URL for the Collection on the TFS Server.
project_path String The project path within the TFS collection.
domain String The domain name for TFS authentication credentials.
auto_update Boolean Whether to poll for new changes or not.
username String The username of the account to access the TFS collection.
password String The password of the account to access the TFS collection.
encrypted_password String The encrypted password of the account to access the TFS collection.

Get all Config repos

$ curl 'https://ci.example.com/go/api/admin/config_repos' \
      -u 'username:password' \
      -H 'Accept:application/vnd.go.cd.v4+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/config_repos"
    }
  },
  "_embedded": {
    "config_repos": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/config_repos/repo1"
          },
          "doc": {
            "href": "https://api.gocd.org/#config-repos"
          },
          "find": {
            "href": "https://ci.example.com/go/api/admin/config_repos/:id"
          }
        },
        "id": "repo1",
        "plugin_id": "json.config.plugin",
        "material": {
          "type": "git",
          "attributes": {
            "url": "https://github.com/config-repo/gocd-json-config-example.git",
            "username": "bob",
            "encrypted_password": "aSdiFgRRZ6A=",
            "branch": "master",
            "auto_update": true
          }
        },
        "configuration": [
        ],
        "rules": [
          {
            "directive": "allow",
            "action": "refer",
            "type": "pipeline_group",
            "resource": "*"
          }
        ]
      }
    ]
  }
}

Lists all available config repos, these are config repositories that are present in the in cruise-config.xml.

Updated to version v4 since v20.8.0.

Available since v17.12.0.

HTTP Request

GET /go/api/admin/config_repos

Returns

A list of config-repo objects

Get a Config repo

$ curl 'https://ci.example.com/go/api/admin/config_repos/repo1' \
      -u 'username:password' \
      -H 'Accept:application/vnd.go.cd.v4+json' \
      -i

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
ETag: "05548388f7ef5042cd39f7fe42e85735"

{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/config_repos/repo1"
    },
    "doc": {
      "href": "https://api.gocd.org/#config-repos"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/config_repos/:id"
    }
  },
  "id": "repo1",
  "plugin_id": "json.config.plugin",
  "material": {
    "type": "git",
    "attributes": {
      "url": "https://github.com/config-repo/gocd-json-config-example.git",
      "username": "bob",
      "encrypted_password": "aSdiFgRRZ6A=",
      "branch": "master",
      "auto_update": true
    }
  },
  "configuration": [
  ],
  "rules": [
    {
      "directive": "allow",
      "action": "refer",
      "type": "pipeline_group",
      "resource": "*"
    }
  ]
}

Gets the config repo object for a specified id.

Updated to version v4 since v20.8.0.

Available since v17.12.0.

HTTP Request

GET /go/api/admin/config_repos/:id

Returns

A config-repo object

Create a Config repo

$   curl 'http://ci.example.com/go/api/admin/config_repos' \
  -u 'username:password' \
  -H 'Accept:application/vnd.go.cd.v4+json' \
  -H 'Content-Type:application/json' \
  -X POST -d '{
    "id": "repo-2",
    "plugin_id": "json.config.plugin",
    "material": {
      "type": "git",
      "attributes": {
        "url": "https://github.com/config-repo/gocd-json-config-example2.git",
        "username": "bob",
        "password": "pass",
        "branch": "master",
        "auto_update": true
      }
    },
    "configuration": [
      {
       "key": "pattern",
       "value": "*.myextension"
     }
    ],
    "rules": [
      {
        "directive": "allow",
        "action": "refer",
        "type": "pipeline_group",
        "resource": "*"
      }
    ]
  }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/config_repos/repo-2"
    },
    "doc": {
      "href": "https://api.gocd.org/#config-repos"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/config_repos/:id"
    }
  },
  "id": "repo-2",
  "plugin_id": "json.config.plugin",
  "material": {
    "type": "git",
    "attributes": {
      "url": "https://github.com/config-repo/gocd-json-config-example2.git",
      "username": "bob",
      "encrypted_password": "aSdiFgRRZ6A=",
      "branch": "master",
      "auto_update": true
    }
  },
  "configuration": [
    {
      "key": "pattern",
      "value": "*.myextension"
    }
  ],
  "rules": [
    {
      "directive": "allow",
      "action": "refer",
      "type": "pipeline_group",
      "resource": "*"
    }
  ]
}

Create a config repo object.

Updated to version v4 since v20.8.0.

Available since v17.12.0.

HTTP Request

POST /go/api/admin/config_repos

Returns

A new config-repo object

Note: since version 18.12.0, it is not possible anymore to provide a material name as redundant with the id.

Update Config repo

$ curl 'https://ci.example.com/go/api/admin/config_repos/repo-1' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v4+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "e064ca0fe5d8a39602e19666454b8d77"' \
      -X PUT \
      -d '{
            "id": "repo-1",
            "plugin_id": "json.config.plugin",
            "material": {
              "type": "git",
              "attributes": {
                "url": "https://github.com/config-repo/gocd-json-config-example2.git",
                "username": "bob",
                "password": "pass",
                "branch": "master",
                "auto_update": true
              }
            },
            "configuration": [
              {
               "key": "pattern",
               "value": "*.myextension"
             }
            ],
            "rules": [
              {
                "directive": "allow",
                "action": "refer",
                "type": "environment",
                "resource": "*"
              }
            ]
          }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
ETag: "e89135b38ddbcd9380c83eb524647bdd"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/config_repos/repo-2"
    },
    "doc": {
      "href": "https://api.gocd.org/#config-repos"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/config_repos/:id"
    }
  },
  "id": "repo-2",
  "plugin_id": "json.config.plugin",
  "material": {
    "type": "git",
    "attributes": {
      "url": "https://github.com/config-repo/gocd-json-config-example2.git",
      "username": "bob",
      "encrypted_password": "aSdiFgRRZ6A=",
      "branch": "master",
      "auto_update": true
    }
  },
  "configuration": [
    {
      "key": "pattern",
      "value": "*.myextension"
    }
  ],
  "rules": [
    {
      "directive": "allow",
      "action": "refer",
      "type": "environment",
      "resource": "*"
    }
  ]
}

Update config repos for specified config repo id.

Updated to version v4 since v20.8.0.

Available since v17.12.0.

HTTP Request

PUT /go/api/admin/config_repos/:id

Returns

The updated config-repo object

Delete a Config repo

$ curl 'https://ci.example.com/go/api/admin/config_repos/repo-1' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v4+json' \
      -X DELETE

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
{
  "message": "The config repo 'repo-1' was deleted successfully."
}

Deletes the config repo.

Updated to version v4 since v20.8.0.

Available since v17.12.0.

HTTP Request

DELETE /go/api/admin/config_repos/:id

Returns

A message whether the config repo is deleted or not.

Export pipeline config to config repo format

$   curl 'http://ci.example.com/go/api/admin/export/pipelines/pip1?plugin_id=yaml.config.plugin' \
  -u 'username:password' \
  -H 'Accept: application/vnd.go.cd.v1+json' \

The above command returns YML structured like this:

HTTP/1.1 200 OK
Content-Type: application/x-yaml; charset=utf-8
ETag: "92d3496403f7a3240fc0ba8895c5abfef24a72255360ebf1c04b4eb304a63eaa"
Content-Disposition: attachment; filename="pip1.gocd.yaml"
format_version: 3
pipelines:
  pip1:
    group: second
    label_template: ${COUNT}
    lock_behavior: none
    materials:
      git:
        git: foo
        shallow_clone: false
        auto_update: true
        branch: master
    stages:
    - defaultStage:
        fetch_materials: true
        keep_artifacts: false
        clean_workspace: false
        approval:
          type: success
        jobs:
          defaultJob:
            timeout: 0
            tasks:
            - nant:
                run_if: passed

Exports pipeline configurations into a format consumable by the specified config repo plugin.

Available since v19.1.0.

HTTP Request

GET /go/api/admin/export/pipelines/:pipeline_name

Returns

The format and contents of the response as well as the Content-Type are determined by the specified config repo plugin.

Preflight check of config repo configurations

$ curl "https://ci.example.com/go/api/admin/config_repo_ops/preflight?pluginId=yaml.config.plugin&repoId=myExistingRepo" \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -F 'files[]=@path/to/file1.gocd.yaml' \
      -F 'files[]=@path/to/file2.gocd.yaml'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "errors" : [ ],
  "valid" : true
}

Checks posted definition file(s) for syntax and merge errors without updating the current GoCD configuration.

Available since v19.2.0.

HTTP Request

When validating definitions before the corresponding config repo configuration has been added to GoCD, do not supply a repoId parameter:

POST /go/api/admin/config_repo_ops/preflight?pluginId=:plugin_id

When validating definition updates to an existing config repo configuration, the repoId parameter is required:

POST /go/api/admin/config_repo_ops/preflight?pluginId=:plugin_id&repoId=:config_repo_id

Returns

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

Trigger update of config repository

$ curl "https://ci.example.com/go/api/admin/config_repos/config_repo_id/trigger_update" \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v4+json' \
      -H 'X-GoCD-Confirm: true'\
      -X POST

The above command returns JSON structured like this:

HTTP/1.1 201 Created
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
{
  "message": "OK"
}

Triggers the update for config repository to get latest revisions.

Updated to version v4 since v20.8.0.

Available since v20.2.0.

HTTP Request

POST /go/api/admin/config_repos/:config_repo_id/trigger_update

Returns

one of -

Status of config repository update

$ curl "https://ci.example.com/go/api/admin/config_repos/config_repo_id/status" \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v4+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
{
  "in_progress": false
}

Get the status of config repository update operation.

Updated to version v4 since v20.8.0.

Available since v20.2.0.

HTTP Request

GET /go/api/admin/config_repos/:config_repo_id/status

Returns

Boolean which indicates that the update of config repository is in progress or not.

Definitions defined in config repo

$ curl "https://ci.example.com/go/api/admin/config_repos/config_repo_id/definitions" \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v4+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
{
  "environments": [{
      "name": "dev"
  }],
  "groups": [{
      "name": "config-repo-group",
      "pipelines": [{
          "name": "up43"
      }]
  }]
}

Get the entities defined in config repository.

Updated to version v4 since v20.8.0.

Available since v20.2.0.

HTTP Request

GET /go/api/admin/config_repos/:config_repo_id/definitions

Returns

The config repository definition object

Configuration Repository

This endpoint allows you to clone and fetch a copy of the configuration repository.

Clone the configuration repository

git clone 'https://username:password@ci.example.com/go/api/config-repository.git'

Available since v16.6.0.

Default Job Timeout

The job timeout API allows to set default timeout value for hung jobs.

The Job Timeout Config Object

Available since v19.11.0.

Attribute Type Description
default_job_timeout String This entry will be used as the default timeout value in minutes for hung jobs. A job is considered as hung if it does not generate any console output for default_job_timeout minutes.

Get JobTimeout Config

$ curl 'https://ci.example.com/go/api/admin/config/server/default_job_timeout' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links" : {
    "doc" : {
      "href" : "https://api.gocd.org/current/#default-job-timeout"
    },
    "self" : {
      "href" : "http://ci.example.com/go/api/admin/config/server/default_job_timeout"
    }
  },
  "default_job_timeout" : "0"
}

Available since v19.11.0.

HTTP Request

GET /go/api/admin/config/server/default_job_timeout

Returns

A job-timeout object.

Update job Timeout Config

$ curl 'https://ci.example.com/go/api/admin/config/server/default_job_timeout' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -H 'Content-Type: application/json' \
      -X POST \
      -d '{
            "default_job_timeout" : "10"
          }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links" : {
    "doc" : {
      "href" : "https://api.gocd.org/current/#default-job-timeout"
    },
    "self" : {
      "href" : "http://localhost:8153/go/api/admin/config/server/default_job_timeout"
    }
  },
  "default_job_timeout" : "10"
}

Available since v19.11.0.

HTTP Request

POST /go/api/admin/config/server/default_job_timeout

PUT /go/api/admin/config/server/default_job_timeout

Returns

A job timeout object.

Elastic Agent Profiles

The elastic agent profile API allows users with admin and group admin authorization to manage profiles that allow creation elastic agents.

The elastic agent profile object

Available since v19.3.0.

Attribute Type Description
id String The identifier of the elastic agent profile.
cluster_profile_id String The identifier of the cluster profile to which current elastic agent profile belongs.
properties Array The list of configuration properties that represent the configuration of this profile.

Get all elastic agent profiles

$ curl 'https://ci.example.com/go/api/elastic/profiles' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "32628084ef10b0c82a55f8f2f867d8d0"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/elastic/profiles"
    },
    "doc": {
      "href": "https://api.gocd.org/#elastic-agent-profiles"
    },
    "find": {
      "href": "https://ci.example.com/go/api/elastic/profiles/:profile_id"
    }
  },
  "_embedded": {
    "profiles": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/elastic/profiles/unit-tests"
          },
          "doc": {
            "href": "https://api.gocd.org/#elastic-profiles"
          },
          "find": {
            "href": "https://ci.example.com/go/api/elastic/profiles/:profile_id"
          }
        },
        "id": "unit-tests",
        "cluster_profile_id": "prod-cluster",
        "properties": [
          {
            "key": "Image",
            "value": "alpine:latest"
          },
          {
            "key": "Command",
            "value": ""
          },
          {
            "key": "Environment",
            "value": ""
          },
          {
            "key": "MaxMemory",
            "value": "200M"
          },
          {
            "key": "ReservedMemory",
            "value": "150M"
          }
        ]
      }
    ]
  }
}

Lists all available elastic agent profiles.

Available since v19.3.0.

HTTP Request

GET /go/api/elastic/profiles

Returns

An array of elastic agent profiles.

Get an elastic agent profile

$ curl 'https://ci.example.com/go/api/elastic/profiles/unit-tests' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/elastic/profiles/unit-tests"
    },
    "doc": {
      "href": "https://api.gocd.org/#elastic-agent-profiles"
    },
    "find": {
      "href": "https://ci.example.com/go/api/elastic/profiles/:profile_id"
    }
  },
  "id": "unit-tests",
  "cluster_profile_id": "prod-cluster",
  "properties": [
    {
      "key": "Image",
      "value": "gocdcontrib/gocd-dev-build"
    },
    {
      "key": "Environment",
      "value": "JAVA_HOME=/opt/java\nMAKE_OPTS=-j8"
    }
  ]
}

Gets elastic agent profile config for specified profile.

Available since v19.3.0.

HTTP Request

GET /go/api/elastic/profiles/:profile_id

Returns

The elastic agent profile object.

Create an elastic agent profile

$ curl 'https://ci.example.com/go/api/elastic/profiles' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json' \
      -H 'Content-Type: application/json' \
      -X POST -d '{
        "id": "unit-tests",
        "cluster_profile_id": "prod-cluster",
        "properties": [
          {
            "key": "Image",
            "value": "gocdcontrib/gocd-dev-build"
          },
          {
            "key": "Environment",
            "value": "JAVA_HOME=/opt/java\nMAKE_OPTS=-j8"
          }
        ]
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/elastic/profiles/unit-tests"
    },
    "doc": {
      "href": "https://api.gocd.org/#elastic-profiles"
    },
    "find": {
      "href": "https://ci.example.com/go/api/elastic/profiles/:profile_id"
    }
  },
  "id": "unit-tests",
  "cluster_profile_id": "prod-cluster",
  "properties": [
    {
      "key": "Image",
      "value": "gocdcontrib/gocd-dev-build"
    },
    {
      "key": "Environment",
      "value": "JAVA_HOME=/opt/java\nMAKE_OPTS=-j8"
    }
  ]
}

Creates an elastic agent profile

Available since v19.3.0.

HTTP Request

POST /go/api/elastic/profiles

Returns

The elastic agent profile object.

Update an elastic agent profile

$ curl 'https://ci.example.com/go/api/elastic/profiles/unit-tests' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"' \
      -X PUT \
      -d '{
        "cluster_profile_id": "prod-cluster",
        "properties": [
          {
            "key": "Image",
            "value": "gocdcontrib/gocd-dev-build:1.0.0"
          },
          {
            "key": "Environment",
            "value": "JAVA_HOME=/opt/java\nMAKE_OPTS=-j8"
          }
        ]
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "61406622382e51c2079c11dcbdb978fb"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/elastic/profiles/unit-tests"
    },
    "doc": {
      "href": "https://api.gocd.org/#elastic-agent-profiles"
    },
    "find": {
      "href": "https://ci.example.com/go/api/elastic/profiles/:profile_id"
    }
  },
  "id": "unit-tests",
  "cluster_profile_id": "prod-cluster",
  "properties": [
    {
      "key": "Image",
      "value": "gocdcontrib/gocd-dev-build:1.0.0"
    },
    {
      "key": "Environment",
      "value": "JAVA_HOME=/opt/java\nMAKE_OPTS=-j8"
    }
  ]
}

Update some attributes of an elastic agent profile.

Available since v19.3.0.

HTTP Request

PUT /go/api/elastic/profiles/:profile_id

Returns

The updated elastic agent profile object.

Delete an elastic agent profile

$ curl 'https://ci.example.com/go/api/elastic/profiles/unit-tests' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json' \
      -X DELETE

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
  "message": "Elastic agent profile 'unit-test' was deleted successfully."
}

Deletes the profile.

Available since v19.3.0.

HTTP Request

DELETE /go/api/elastic/profiles/:profile_id

Returns

A message if the elastic agent profile is deleted or not.

Environment Config

The environment config API allows users with administrator role to manage environment config.

The environment config object

Available since v16.7.0.

Attribute Type Description
name String The name of environment.
pipelines Array List of pipeline names that should be added to this environment.
environment_variables Array The list of environment variables that will be passed to all tasks (commands) that are part of this environment.

Get all environments

$ curl 'https://ci.example.com/go/api/admin/environments' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v3+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "3924a894cf0e5bef02abe9de0df3bb84"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/environments"
    },
    "doc": {
      "href": "https://api.gocd.org/#environment-config"
    }
  },
  "_embedded": {
    "environments": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/environments/foobar"
          },
          "doc": {
            "href": "https://api.gocd.org/#environment-config"
          },
          "find": {
            "href": "https://ci.example.com/go/api/admin/environments/:environment_name"
          }
        },
        "name": "foobar",
        "pipelines": [
          {
            "_links": {
              "self": {
                "href": "https://ci.example.com/go/api/admin/pipelines/up42"
              },
              "doc": {
                "href": "https://api.gocd.org/#pipeline-config"
              },
              "find": {
                "href": "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
              }
            },
            "name": "up42"
          }
        ],
        "environment_variables": [
          {
            "secure": false,
            "name": "username",
            "value": "admin"
          },
          {
            "secure": true,
            "name": "password",
            "encrypted_value": "LSd1TI0eLa+DjytHjj0qjA=="
          }
        ]
      }
    ]
  }
}

Lists all available environments.

Updated to version v3 since v19.9.0.

Available since v16.7.0.

HTTP Request

GET /go/api/admin/environments

Returns

An array of environment config objects.

Get environment config

$ curl 'https://ci.example.com/go/api/admin/environments/my_environment' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v3+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "4167e3ec81fdac0fb29d854b36ceb981"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/environments/my_environment"
    },
    "doc": {
      "href": "https://api.gocd.org/#environment-config"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/environments/:environment_name"
    }
  },
  "name": "my_environment",
  "pipelines": [
    {
      "_links": {
        "self": {
          "href": "https://ci.example.com/go/api/admin/pipelines/up42"
        },
        "doc": {
          "href": "https://api.gocd.org/#pipeline-config"
        },
        "find": {
          "href": "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
        }
      },
      "name": "up42"
    }
  ],
  "environment_variables": [
    {
      "secure": false,
      "name": "username",
      "value": "admin"
    },
    {
      "secure": true,
      "name": "password",
      "encrypted_value": "LSd1TI0eLa+DjytHjj0qjA=="
    }
  ]
}

Gets environment config for specified environment name.

Updated to version v3 since v19.9.0.

Available since v16.7.0.

HTTP Request

GET /go/api/admin/environments/:environment_name

Returns

The environment config object.

Create an environment

$ curl 'https://ci.example.com/go/api/admin/environments' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v3+json' \
      -H 'Content-Type: application/json' \
      -X POST -d '{
        "name" : "new_environment",
        "pipelines" : [
          {
          "name" : "up2"
          }
        ],
        "environment_variables" : [
          {
            "name" : "username",
            "value" : "admin",
            "secure" : false
          }
        ]
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "d3b07384d113edec49eaa6238ad5ff00"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/environments/new_environment"
    },
    "doc": {
      "href": "https://api.gocd.org/#environment-config"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/environments/:environment_name"
    }
  },
  "name": "new_environment",
  "pipelines": [
    {
      "_links": {
        "self": {
          "href": "https://ci.example.com/go/api/admin/pipelines/up42"
        },
        "doc": {
          "href": "https://api.gocd.org/#pipeline-config"
        },
        "find": {
          "href": "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
        }
      },
      "name": "up42"
    }
  ],
  "environment_variables": [
    {
      "secure": false,
      "name": "username",
      "value": "admin"
    },
    {
      "secure": true,
      "name": "password",
      "encrypted_value": "LSd1TI0eLa+DjytHjj0qjA=="
    }
  ]
}

Creates an environment

Updated to version v3 since v19.9.0.

Available since v16.7.0.

HTTP Request

POST /go/api/admin/environments

The following properties may be specified:

Attribute Type Description
name String The environment config name.
pipelines Array The list of pipeline names that belongs to the specified environment.
environment_variables Array The list of environment variables that will be passed to all tasks (commands) that are part of this environment.

Returns

An environment config object.

Update an environment

$ curl 'https://ci.example.com/go/api/admin/environments/new_environment' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v3+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "26b227605daf6f2d7768c8edaf61b861"' \
      -X PUT \
      -d '{
        "name" : "new_environment",
        "pipelines" : [ { "name" : "pipeline1" } ]
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "4167e3ec81fdac0fb29d854b36ceb981"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/environments/new_environment"
    },
    "doc": {
      "href": "https://api.gocd.org/#environment-config"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/environments/:environment_name"
    }
  },
  "name": "new_environment",
  "pipelines": [
    {
      "_links": {
        "self": {
          "href": "https://ci.example.com/go/api/admin/pipelines/pipeline1"
        },
        "doc": {
          "href": "https://api.gocd.org/#pipeline-config"
        },
        "find": {
          "href": "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
        }
      },
      "name": "up42"
    }
  ],
  "environment_variables": [

  ]
}

Update some attributes of an environment.

Updated to version v3 since v19.9.0.

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.
environment_variables Array The list of environment variables that will be passed to all tasks (commands) that are part of this environment.

Returns

The updated environment config object.

Patch an environment

$ curl 'https://ci.example.com/go/api/admin/environments/new_environment' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v3+json' \
      -H 'Content-Type: application/json' \
      -X PATCH \
      -d '{
      "pipelines": {
        "add": ["up42"],
        "remove": ["sample"]
      },
      "environment_variables": {
          "add": [
            {
              "name": "GO_SERVER_URL",
              "value": "https://ci.example.com/go"
            }
          ],
          "remove": ["URL"]
      }
}'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "4167e3ec81fdac0fb29d854b36ceb981"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/environments/new_environment"
    },
    "doc": {
      "href": "https://api.gocd.org/#environment-config"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/environments/:environment_name"
    }
  },
  "name": "new_environment",
  "pipelines": [
    {
      "_links": {
        "self": {
          "href": "https://ci.example.com/go/api/admin/pipelines/pipeline1"
        },
        "doc": {
          "href": "https://api.gocd.org/#pipeline-config"
        },
        "find": {
          "href": "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
        }
      },
      "name": "up42"
    }
  ],
  "environment_variables": [
    {
      "name": "GO_SERVER_URL",
      "value": "https://ci.example.com/go",
      "secure": false
    }
  ]
}

Update some attributes of an environment.

Updated to version v3 since v19.9.0.

Available since v16.10.0.

HTTP Request

PATCH /go/api/admin/environments/:environment_name

At least one of the following properties must be specified, not specifying the property will leave it unchanged.

The environments patch operation attributes

{
  "pipelines": {
    "add": [
      "Dev",
      "Test"
    ],
    "remove": [
      "Production"
    ]
  },
  "environment_variables": {
    "add": [
      {
        "name": "GO_SERVER_URL",
        "value": "https://ci.example.com/go"
      }
    ],
    "remove": [
      "URL"
    ]
  }
}

Attribute Type Description
pipelines Object The pipelines update operation to be performed on the set of pipelines.
environment_variables Object The environment variables update operation to be performed on the set of environment variables.

The environments pipeline-update operation attributes

{
  "add": [
    "Dev",
    "Test"
  ],
  "remove": [
    "Production"
  ]
}

Attribute Type Description
add Array The list of pipelines which needs to be added to the specified environment.
remove Array The list of pipelines which needs to be removed to the specified environment.

The environments environment-variable-update operation attributes

{
  "add": [
    {
      "name": "USERNAME",
      "value": "go-user"
    },
    {
      "name": "PASSWORD",
      "encrypted_value": "1f3rrs9uhn63hd",
      "secure": true
    }
  ],
  "remove": [
    "URL"
  ]
}

Attribute Type Description
add Array The list of environment variables which needs to be added to the specified environment.
remove Array The list of environment variable names which needs to be removed to the specified environment.

Returns

The updated environment config object.

Delete an environment

$ curl 'https://ci.example.com/go/api/admin/environments/my_environment' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v3+json' \
      -X DELETE

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
  "message": "Environment 'my_environment' was deleted successfully."
}

Deletes an environment.

Updated to version v3 since v19.9.0.

Available since v16.7.0.

HTTP Request

DELETE /go/api/admin/environments/:environment_name

Returns

A message confirmation if the environment was deleted.

GoCD-level Configuration

The configuration API allows users with administration role to view and manage configuration.

Get configuration

$ curl 'https://ci.example.com/go/api/admin/config.xml' \
      -u 'username:password'

The above command returns the contents of the config file

HTTP/1.1 200 OK
X-CRUISE-CONFIG-MD5: c21b6c9f1b24a816cddf457548a987a9
Content-Type: text/xml
<?xml version="1.0" encoding="utf-8"?>
<cruise
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="cruise-config.xsd"
    schemaVersion="75">
  <server serverId="9C0C0282-A554-457D-A0F8-9CF8A754B4AB">
    <security>
      <passwordFile path="/etc/go/password.properties" />
    </security>
  </server>
  <pipelines group="defaultGroup" />
</cruise>

Gets the current configuration file.

Available since v14.3.0.

HTTP Request

GET /go/api/admin/config.xml

Other convenience APIs

GET /go/api/admin/config/current.xml

or

GET /go/api/admin/config/:md5.xml

Returns

The contents of the configuration file.

Mailserver Config

The mailserver config API allows admins to setup the SMTP server configuration, so GoCD can send emails.

The Mailserver Config Object

Available since v19.8.0.

Attribute Type Description
hostname String The SMTP server hostname (or IP address).
port Integer The SMTP server port.
username String The username required to authenticate with the SMTP server.
password String The password required to authenticate with the SMTP server.
encrypted_password String The encrypted password required to authenticate with the SMTP server.
tls Boolean Whether the SMTP server connection should should use SSL/TLS.
sender_email Boolean The email address of the sender. All emails sent by the GoCD server will use this email address in the Form field.
admin_email Boolean The email address of the server administrator. Any emails that require attention from adminstrators will be sent to this email address.

Get Mailserver Config

$ curl 'https://ci.example.com/go/api/config/mailserver' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/config/mailserver"
    },
    "doc": {
      "href": "https://api.gocd.org/#mailserver-config"
    }
  },
  "hostname" : "smtp.example.com",
  "port" : 465,
  "username" : "user@example.com",
  "encrypted_password" : "AES:lzcCuNSe4vUx+CsWgN11Uw==:Q2OlnqIf9S++yMPqSCx8qg==",
  "tls" : true,
  "sender_email" : "no-reply@example.com",
  "admin_email" : "gocd-admins@example.com"
}

Available since v19.8.0.

HTTP Request

GET /go/api/config/mailserver

Returns

A mailserver config object.

Create or Update Mailserver Config

$ curl 'https://ci.example.com/go/api/config/mailserver' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{
            "hostname" : "smtp.example.com",
            "port" : 465,
            "username" : "user@example.com",
            "password" : "p@ssw0rd",
            "tls" : true,
            "sender_email" : "no-reply@example.com",
            "admin_email" : "gocd-admins@example.com"
          }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/config/mailserver"
    },
    "doc": {
      "href": "https://api.gocd.org/#mailserver-config"
    }
  },
  "hostname" : "smtp.example.com",
  "port" : 465,
  "username" : "user@example.com",
  "encrypted_password" : "AES:lzcCuNSe4vUx+CsWgN11Uw==:Q2OlnqIf9S++yMPqSCx8qg==",
  "tls" : true,
  "sender_email" : "no-reply@example.com",
  "admin_email" : "gocd-admins@example.com"
}

Available since v19.8.0.

HTTP Request

POST /go/api/config/mailserver

PUT /go/api/config/mailserver

Returns

A mailserver config object.

Delete Mailserver Config

$ curl 'https://ci.example.com/go/api/config/mailserver' </span>
      -u 'username:password' </span>
      -H 'Accept: application/vnd.go.cd.v1+json' </span>
      -X DELETE

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"message" : "Mailserver config was deleted successfully!"
}

Available since v19.8.0.

HTTP Request

DELETE /go/api/config/mailserver

Returns

A message confirmation if the mailserver config was deleted.

Materials

The materials API allows users to query materials in the GoCD configuration.

The material object

Available since v19.6.0.

Attribute Type Description
type String The type of a material. Can be one of git, hg, svn, p4, tfs, dependency, package, plugin.
fingerprint String The fingerprint of the material.
attributes Object The attributes for each material type.

The git material attributes

{
  "type": "git",
  "attributes": {
    "url": "https://github.com/gocd/api.go.cd",
    "username": "bob",
    "encrypted_password": "aSdiFgRRZ6A=",
    "branch": "master",
    "auto_update": true
  }
}

Attribute Type Description
url String The URL of the git repository.
username String The user account for the remote repository.
password String The password for the specified user.
encrypted_password String The encrypted password for the specified user.
branch String The git branch to build.
auto_update Boolean Whether to poll for new changes or not.

The svn material attributes

{
  "type": "svn",
  "attributes": {
    "url": "svn://svn.example.com/myProject/trunk",
    "username": "admin",
    "auto_update": true,
    "encrypted_password": "aSdiFgRRZ6A=",
    "check_externals": true
  }
}

Attribute Type Description
url String The URL of the subversion repository.
username String The user account for the remote repository.
password String The password for the specified user.
encrypted_password String The encrypted password for the specified user.
auto_update Boolean Whether to poll for new changes or not.
check_externals Boolean Whether the changes o the externals will trigger the pipeline automatically or not.

The mercurial material attributes

{
  "type": "hg",
  "attributes": {
    "url": "http://hg.example.com/hg/api.go.cd",
    "username": "bob",
    "encrypted_password": "aSdiFgRRZ6A=",
    "branch": "feature",
    "auto_update": true
  }
}

Attribute Type Description
url String The URL of the mercurial repository.
username String The user account for the remote repository.
password String The password for the specified user.
encrypted_password String The encrypted password for the specified user.
branch String The mercurial branch to build.
auto_update Boolean Whether to poll for new changes or not.

The perforce material attributes

{
  "type": "p4",
  "attributes": {
    "port": "p4.example.com:8080",
    "use_tickets": true,
    "view": "sample_view",
    "auto_update": true,
    "username": "admin",
    "encrypted_password": "aSdiFgRRZ6A="
  }
}

Attribute Type Description
port String Perforce server connection to use ([transport:]host:port).
use_tickets Boolean Whether to work with the Perforce tickets or not.
view String The Perforce view.
auto_update Boolean Whether to poll for new changes or not.
username String The username to be used.
password String The password for the specified user.
encrypted_password String The encrypted password for the specified user.

The tfs material attributes

{
  "type": "tfs",
  "attributes": {
    "url": "http://tfs.exampe.com:8000/tfs",
    "project_path": "$/",
    "domain": "corporate/domain",
    "username": "admin",
    "encrypted_password": "aSdiFgRRZ6A="
  }
}

Attribute Type Description
url String The URL for the Collection on the TFS Server.
project_path String The project path within the TFS collection.
domain String The domain name for TFS authentication credentials.
auto_update Boolean Whether to poll for new changes or not.
username String The username of the account to access the TFS collection.
password String The password of the account to access the TFS collection.
encrypted_password String The encrypted password of the account to access the TFS collection.

The package material attributes

{
  "type": "package",
  "attributes": {
    "ref": "e289f497-057b-46bc-bb69-8043454f5c1b"
  }
}

Attribute Type Description
ref String The unique package repository id.

The dependency material attributes

{
  "materials": [
    {
      "type": "dependency",
      "attributes": {
        "name": "dependency",
        "pipeline": "upstream",
        "stage": "upstream_stage",
        "auto_update": true,
        "ignore_for_scheduling": false
      }
    }
  ]
}

Attribute Type Description
name String The name of this material.
pipeline String The name of a pipeline that this pipeline depends on.
stage String The name of a stage which will trigger this pipeline once it is successful.
auto_update Boolean Whether to poll for new changes or not.
ignore_for_scheduling Boolean Whether the pipeline should be triggered when there are changes in this material. Since v19.10.0.

The plugin material attributes

{
  "materials": [
    {
      "type": "plugin",
      "attributes": {
        "ref": "5e3612f7-6aa1-4d75-a9b7-6aeb52d98012",
        "filter": null,
        "invert_filter": true
      }
    }
  ]
}

Attribute Type Description
ref String The unique scm plugin repository id.
destination String The directory (relative to the pipeline directory) in which source code will be checked out.
filter Object The filter specifies files in changesets that should not trigger a pipeline automatically.
invert_filter Boolean Invert filter to enable whitelist.

The filter object

{
  "filter": {
    "ignore": [
      "README.md",
      "docs/**.html"
    ]
  }
}

Attribute Type Description
ignore String The pattern for the files to be ignored.

Get all materials

$ curl 'https://ci.example.com/go/api/config/materials' \
      -u 'username:password'
      -H 'Accept: application/vnd.go.cd.v2+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "_links": {
    "doc": {
      "href": "https://api.gocd.org/#materials"
    },
    "self": {
      "href": "https://ci.example.com/go/api/config/materials"
    }
  },
  "_embedded": {
    "materials": [
      {
        "type": "git",
        "fingerprint": "458ce82419bdbe41a4007ad713a730e5e467ed4fbefb421bf58aeff3e9c36e4b",
        "attributes": {
          "url": "https://github.com/gocd/gocd",
          "destination": null,
          "filter": null,
          "invert_filter": false,
          "name": null,
          "auto_update": false,
          "branch": "master",
          "submodule_folder": null,
          "shallow_clone": false
        }
      },
      {
        "type": "svn",
        "fingerprint": "6b0cd6b9181434866c555f3c3bb780e950389a456764c876d804c848efbad554",
        "attributes": {
          "url": "https://github.com/gocd/gocd",
          "destination": "test",
          "filter": null,
          "invert_filter": false,
          "name": null,
          "auto_update": false,
          "username": "admin",
          "encrypted_password": "AES:lTFKwi5NvrlqmQ3LOQ5UQA==:Ebggz5N27w54NrhSXKIbng==",
          "check_externals": false
        }
      },
      {
        "type": "hg",
        "fingerprint": "f6b61bc6b33e524c2a94c5be4a4661e5f1d2b74ca089418de20de10b282e39e9",
        "attributes": {
          "url": "ssh://hg@bitbucket.org/example/gocd-hg",
          "destination": "test",
          "filter": null,
          "invert_filter": false,
          "name": null,
          "auto_update": false,
          "branch": ""
        }
      },
      {
        "type": "dependency",
        "fingerprint": "21f7963a8eca6cced5b4f20b57b4e9cb8edaed29d683c83621a77dfb499c553d",
        "attributes": {
          "pipeline": "up42",
          "stage": "up42_stage",
          "name": "up42_material",
          "auto_update": true,
          "ignore_for_scheduling": false
        }
      }
    ]
  }
}

Lists all available materials, these are materials that are present in the cruise-config.xml or Config Repos.

Updated to version v2 since v19.10.0.

Available since v14.3.0.

HTTP Request

GET /go/api/config/materials

Returns

An array of material objects.

Get material modifications

$ curl 'https://ci.example.com/go/api/materials/03c8d2a131154436b6ef2d621c6f773837481aaea8c5c1bb9c0cb9b5bc64a2f1/modifications' \
      -u 'username:password'
      -H 'Accept: application/vnd.go.cd.v2+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/materials/03c8d2a131154436b6ef2d621c6f773837481aaea8c5c1bb9c0cb9b5bc64a2f1/modifications"
    },
    "doc": {
      "href": "https://api.gocd.org/#materials"
    },
    "find": {
      "href": "https://ci.example.com/go/api/materials/:fingerprint/modifications/{offset}"
    }
  },
  "_embedded": {
    "modifications": [
      {
        "email_address": null,
        "id": 7225,
        "modified_time": 1435728005000,
        "user_name": "Pick E Reader <pick.e.reader@example.com>",
        "comment": "my hola mundo changes",
        "revision": "a788f1876e2e1f6e5a1e91006e75cd1d467a0edb"
      }
    ],
    "pagination": {
      "offset": 0,
      "total": 1070,
      "page_size": 10
    }
  }
}

Get material modifications by fingerprint

Updated to version v2 since v19.10.0.

Available since v14.3.0.

HTTP Request

GET /go/api/materials/:fingerprint/modifications

With pagination

GET /go/api/materials/:fingerprint/modifications[/:offset]

Returns

A list of modification objects.

Notification Filters

The notification filters API allows the authenticated user to manage their notification filters.

The API depends on the SMTP settings and without it, the API will fail with following message.

{
  "message": "SMTP settings are currently not configured. Ask your administrator to configure SMTP settings."
}

The notification filter object

Available since v17.5.0.

Attribute Type Description
id Number The internal ID of the notification filter.
pipeline String The name of the pipeline to get notification for. Can also be [Any Pipeline] to get notification for any pipeline. This attribute MUST be specified.
stage String The name of the stage to get notification for. Can also be [Any Stage] to get notification for any stage. This attribute MUST be specified.
event String The name of event to get notificaton for. Can be one of: All, Passes, Fails, Breaks, Fixed, Cancelled. This attribute MUST be specified.
match_commits Boolean Boolean indicating if the notification filter should match only the user’s commits (true) or all commits (false).

Show all notification filters

$ curl 'https://ci.example.com/go/api/notification_filters' \
  -u 'username:password' \
  -H 'Accept: application/vnd.go.cd.v2+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
  "_links" : {
    "self" : {
      "href" : "https://ci.example.com/go/api/notification_filters"
    },
    "doc" : {
      "href" : "https://api.gocd.org/20.1.0/#notification-filters"
    }
  },
  "_embedded" : {
    "filters" : [
      {
        "id": 10,
        "pipeline": "my_pipeline",
        "stage": "[Any Stage]",
        "event": "Breaks",
        "match_commits": true
      }
    ]
  }
}

Lists all notification filters for the authenticated user.

Updated to version v2 since v20.1.0.

Available since v17.5.0.

HTTP Request

GET /go/api/notification_filters

Returns

An array of notification filter objects representing the current set the user’s notification filters.

Create a notification filter

$ curl 'https://ci.example.com/go/api/notification_filters' \
  -u 'username:password' \
  -H 'Accept: application/vnd.go.cd.v2+json' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
        "pipeline": "my_pipeline",
        "stage": "my_stage",
        "event": "Breaks",
        "match_commits": true
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
  "_links" : {
    "self" : {
      "href" : "https://ci.example.com/go/api/notification_filters/1"
    },
    "doc" : {
      "href" : "https://api.gocd.org/#notification-filters"
    },
    "find" : {
      "href" : "https://ci.example.com/go/api/notification_filters/:id"
    }
  },
  "id" : 1,
  "pipeline" : "up42",
  "stage" : "up42_stage",
  "event" : "Fails",
  "match_commits" : false
}

Creates a notification filter for the authenticated user.

Updated to version v2 since v20.1.0.

Available since v17.5.0.

HTTP Request

POST /go/api/notification_filters

The following properties may be specified:

Attribute Type Description
pipeline String The name of the pipeline to get notification for. Can also be [Any Pipeline] to get notification for any pipeline. This attribute MUST be specified.
stage String The name of the stage to get notification for. Can also be [Any Stage] to get notification for any stage. This attribute MUST be specified.
event String The name of event to get notificaton for. Can be one of: All, Passes, Fails, Breaks, Fixed, Cancelled. This attribute MUST be specified.
match_commits Boolean Boolean indicating if the notification filter should match only the user’s commits (true) or all commits (false).

Returns

A newly created notification filter object for the user.

Get a notification filter

$ curl 'https://ci.example.com/go/api/notification_filters/1' \
  -u 'username:password' \
  -H 'Accept: application/vnd.go.cd.v2+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
  "_links" : {
    "self" : {
      "href" : "https://ci.example.com/go/api/notification_filters/1"
    },
    "doc" : {
      "href" : "https://api.gocd.org/#notification-filters"
    },
    "find" : {
      "href" : "https://ci.example.com/go/api/notification_filters/:id"
    }
  },
  "id" : 1,
  "pipeline" : "up42",
  "stage" : "up42_stage",
  "event" : "Fails",
  "match_commits" : false
}

Get a notification filter for the authenticated user.

Updated to version v2 since v20.1.0.

Available since v17.5.0.

HTTP Request

GET /go/api/notification_filters/:id

The following properties may be specified:

Attribute Type Description
pipeline String The name of the pipeline to get notification for. Can also be [Any Pipeline] to get notification for any pipeline. This attribute MUST be specified.
stage String The name of the stage to get notification for. Can also be [Any Stage] to get notification for any stage. This attribute MUST be specified.
event String The name of event to get notificaton for. Can be one of: All, Passes, Fails, Breaks, Fixed, Cancelled. This attribute MUST be specified.
match_commits Boolean Boolean indicating if the notification filter should match only the user’s commits (true) or all commits (false).

Returns

A newly created notification filter object for the user.

Update a notification filter

curl 'https://ci.example.com/go/api/notification_filters/1' \
  -u 'username:password' \
  -H 'Accept: application/vnd.go.cd.v2+json' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{
        "pipeline": "up42",
        "stage": "up42_stage",
        "event": "All",
        "match_commits": false
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
  "_links" : {
    "self" : {
      "href" : "https://ci.example.com/go/api/notification_filters/1"
    },
    "doc" : {
      "href" : "https://api.gocd.org/20.1.0/#notification-filters"
    },
    "find" : {
      "href" : "https://ci.example.com/go/api/notification_filters/:id"
    }
  },
  "id" : 1,
  "pipeline" : "up42",
  "stage" : "up42_stage",
  "event" : "All",
  "match_commits" : false
}

Update a existing notification filter for the authenticated user.

Updated to version v2 since v20.1.0.

Available since v17.5.0.

HTTP Request

PATCH /go/api/notification_filters/:id

The following properties may be specified:

Attribute Type Description
pipeline String The name of the pipeline to get notification for. Can also be [Any Pipeline] to get notification for any pipeline. This attribute MUST be specified.
stage String The name of the stage to get notification for. Can also be [Any Stage] to get notification for any stage. This attribute MUST be specified.
event String The name of event to get notificaton for. Can be one of: All, Passes, Fails, Breaks, Fixed, Cancelled. This attribute MUST be specified.
match_commits Boolean Boolean indicating if the notification filter should match only the user’s commits (true) or all commits (false).

Returns

An updated notification filter object for the user.

Delete a notification filter

$ curl 'https://ci.example.com/go/api/notification_filters/1' \
  -u 'username:password' \
  -H 'Accept: application/vnd.go.cd.v2+json' \
  -X DELETE

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
  "message" : "Notification filter is successfully deleted!"
}

Deletes a notification filter for the authenticated user.

Updated to version v2 since v20.1.0.

Available since v17.5.0.

HTTP Request

DELETE /go/api/notification_filters/:id

Returns

A message if the notification filter is deleted or not.

Packages

The package definition API v2 allows users to view, create and update the packages’ configuration.

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.

The package repository object

{
  "package_repo": {
    "id": "273b246e-145d-49d2-a1a4-f0285af9cccc",
    "name": "package-repository"
  }
}

Attribute Type Description
id String The id of the package repository.
name String The name of the package repository.

Get all packages

$ curl 'https://ci.example.com/go/api/admin/packages' \
      -u 'username:password' \
      -H 'Accept:application/vnd.go.cd.v2+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/packages"
    },
    "doc": {
      "href": "https://api.gocd.org/#packages"
    }
  },
  "_embedded": {
    "packages": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/packages/f579bb13-bed3-4ad1-a547-ff9d9bcf56d4"
          },
          "doc": {
            "href": "https://api.gocd.org/#packages"
          },
          "find": {
            "href": "https://ci.example.com/go/api/admin/packages/:package_id"
          }
        },
        "name": "package",
        "id": "f579bb13-bed3-4ad1-a547-ff9d9bcf56d4",
        "auto_update": true,
        "package_repo": {
          "_links": {
            "self": {
              "href": "https://ci.example.com/go/api/admin/repositories/273b246e-145d-49d2-a1a4-f0285af9cccc"
            },
            "doc": {
              "href": "https://api.gocd.org/#package-repositories"
            },
            "find": {
              "href": "https://ci.example.com/go/api/admin/repositories/:repo_id"
            }
          },
          "id": "273b246e-145d-49d2-a1a4-f0285af9cccc",
          "name": "foo"
        },
        "configuration": [
          {
            "key": "PACKAGE_NAME",
            "value": "bar"
          }
        ]
      },
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/packages/c3e1d398-96c0-4edd-a577-9b5c769d449b"
          },
          "doc": {
            "href": "https://api.gocd.org/#packages"
          },
          "find": {
            "href": "https://ci.example.com/go/api/admin/packages/:package_id"
          }
        },
        "name": "another_package",
        "id": "c3e1d398-96c0-4edd-a577-9b5c769d449b",
        "auto_update": true,
        "package_repo": {
          "_links": {
            "self": {
              "href": "https://ci.example.com/go/api/admin/repositories/273b246e-145d-49d2-a1a4-f0285af9cccc"
            },
            "doc": {
              "href": "https://api.gocd.org/#package-repositories"
            },
            "find": {
              "href": "https://ci.example.com/go/api/admin/repositories/:repo_id"
            }
          },
          "id": "273b246e-145d-49d2-a1a4-f0285af9cccc",
          "name": "npm"
        },
        "configuration": [
          {
            "key": "PACKAGE_NAME",
            "value": "group"
          },
          {
            "key": "VERSION_SPEC",
            "value": "1"
          },
          {
            "key": "ARCHITECTURE",
            "value": "jar"
          }
        ]
      }
    ]
  }
}

Lists all available packages, these are materials that are present in the in cruise-config.xml.

Updated to version v2 since v20.3.0.

Available since v16.12.0.

HTTP Request

GET /go/api/admin/packages

Returns

A list of packages.

Get a Package Material

$ curl 'https://ci.example.com/go/api/admin/packages/package.id' \
      -u 'username:password' \
      -H 'Accept:application/vnd.go.cd.v2+json'
      -i

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "08ae92bf39fc33e9d7326feb97047417"

{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/packages/package.id"
    },
    "doc": {
      "href": "https://api.gocd.org/#packages"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/packages/:package_id"
    }
  },
  "name": "package",
  "id": "package.id",
  "auto_update": true,
  "package_repo": {
    "_links": {
      "self": {
        "href": "https://ci.example.com/go/api/admin/repositories/273b246e-145d-49d2-a1a4-f0285af9cccc"
      },
      "doc": {
        "href": "https://api.gocd.org/#package-repositories"
      },
      "find": {
        "href": "https://ci.example.com/go/api/admin/repositories/:repo_id"
      }
    },
    "id": "273b246e-145d-49d2-a1a4-f0285af9cccc",
    "name": "foo"
  },
  "configuration": [
    {
      "key": "PACKAGE_NAME",
      "value": "package_name"
    }
  ]
}

Gets the package config for a specified package id.

Updated to version v2 since v20.3.0.

Available since v16.12.0.

HTTP Request

GET /go/api/admin/packages/:package_id

Returns

A package object.

Create a Package

$ curl "https://ci.example.com/go/api/admin/packages" \
  -u 'username:password' \
  -H 'Accept: application/vnd.go.cd.v2+json' \
  -H 'Content-Type: application/json' \
  -X POST -d '{
  "id": "package-id",
  "name": "package_name",
  "auto_update": false,
  "package_repo": {
    "id": "273b246e-145d-49d2-a1a4-f0285af9cccc"
  },
  "configuration": [
    {
      "key": "PACKAGE_NAME",
      "value": "package"
    }
  ]
}'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/packages/package-id"
    },
    "doc": {
      "href": "https://api.gocd.org/#packages"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/packages/:package_id"
    }
  },
  "name": "package_name",
  "id": "package-id",
  "auto_update": false,
  "package_repo": {
    "_links": {
      "self": {
        "href": "https://ci.example.com/go/api/admin/repositories/273b246e-145d-49d2-a1a4-f0285af9cccc"
      },
      "doc": {
        "href": "https://api.gocd.org/#package-repositories"
      },
      "find": {
        "href": "https://ci.example.com/go/api/admin/repositories/:repo_id"
      }
    },
    "id": "273b246e-145d-49d2-a1a4-f0285af9cccc",
    "name": "foo"
  },
  "configuration": [
    {
      "key": "PACKAGE_NAME",
      "value": "package"
    }
  ]
}

Creates a package with specified configurations.

Updated to version v2 since v20.3.0.

Available since v16.12.0.

HTTP Request

POST /go/api/admin/packages

Returns

A new package object.

Edit a package

$ curl "https://ci.example.com/go/api/admin/packages/f579bb13-bed3-4ad1-a547-ff9d9bcf56d4" \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "08ae92bf39fc33e9d7326feb97047417"' \
-X PUT -d '{
  "id": "f579bb13-bed3-4ad1-a547-ff9d9bcf56d4",
  "name": "foo",
  "auto_update": true,
  "package_repo": {
    "id": "273b246e-145d-49d2-a1a4-f0285af9cccc"
  },
  "configuration": [{
    "key": "PACKAGE_NAME",
    "value": "update"
  }]
}'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "e89135b38ddbcd9380c83eb524647bdd"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/packages/f579bb13-bed3-4ad1-a547-ff9d9bcf56d4"
    },
    "doc": {
      "href": "https://api.gocd.org/#packages"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/packages/:package_id"
    }
  },
  "name": "foo",
  "id": "f579bb13-bed3-4ad1-a547-ff9d9bcf56d4",
  "auto_update": true,
  "package_repo": {
    "_links": {
      "self": {
        "href": "https://ci.example.com/go/api/admin/repositories/273b246e-145d-49d2-a1a4-f0285af9cccc"
      },
      "doc": {
        "href": "https://api.gocd.org/#package-repositories"
      },
      "find": {
        "href": "https://ci.example.com/go/api/admin/repositories/:repo_id"
      }
    },
    "id": "273b246e-145d-49d2-a1a4-f0285af9cccc",
    "name": "foo"
  },
  "configuration": [
    {
      "key": "PACKAGE_NAME",
      "value": "update"
    }
  ]
}

Updates global package configuration for the specified package id.

Updated to version v2 since v20.3.0.

Available since v16.12.0.

HTTP Request

PUT /go/api/admin/packages/:package_id

Returns

The updated package object.

Delete a package material

$ curl 'https://ci.example.com/go/api/admin/packages/package-id' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json' \
      -X DELETE

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
  "message": "The package definition 'package-id' was deleted successfully."
}

Deletes a package from the respective repository if it is not associated with any pipeline.

Available since v16.12.0.

HTTP Request

DELETE /go/api/admin/package/:package_id

Returns

A message confirmation if the package was deleted.

Usages of the package

$ curl 'https://ci.example.com/go/api/admin/packages/package-id/usages' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "http://test.host/go/api/admin/packages/package-id/usages"
    },
    "doc": {
      "href": "https://api.gocd.org/#packages"
    },
    "find": {
      "href": "http://test.host/go/api/admin/packages/:package_id/usages"
    }
  },
  "usages" : [
    {
      "group" : "grp1",
      "pipeline" : "pipeline1"
    }
  ]
}

Gets the list of pipelines and group which uses the said package as a material

Updated to version v2 since v20.3.0.

HTTP Request

GET /go/api/admin/package/:package_id/usages

Returns

A list of the usage object.

The usage object

{
  "pipeline": "pipeline_name",
  "group": "grp_name"
}

Attribute Type Description
pipeline String The name of the pipeline which uses the package as a material.
group String The group which the pipeline belongs to.

Package Repositories

The repositories API allows admins and pipeline group admins to view, create and update a package repository.

The package repository config object

Available since v16.12.0.

Attribute Type Description
id String Each repository is associated with an id by which it can be referenced in the . If the id is not provided during creation, a uuid will be generated. Id is mandatory while providing data for update.
name String The global name of the repository.
plugin_metadata Object The plugin metadata provides information about the plugin.
configuration Object The list of properties (key-value pairs) to be provided for using the plugin.

Get all Repositories

$ curl 'https://ci.example.com/go/api/admin/repositories' \
      -u 'username:password' \
      -H 'Accept:application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/repositories"
    },
    "doc": {
      "href": "https://api.gocd.org/#package-repositories"
    }
  },
  "_embedded": {
    "package_repositories": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/repositories/dd8926c0-3b4a-4c9e-8012-957b179cec5b"
          },
          "doc": {
            "href": "https://api.gocd.org/#package-repositories"
          },
          "find": {
            "href": "https://ci.example.com/go/api/admin/repositories/:repo_id"
          }
        },
        "repo_id": "dd8926c0-3b4a-4c9e-8012-957b179cec5b",
        "name": "repository",
        "plugin_metadata": {
          "id": "deb",
          "version": "1"
        },
        "configuration": [
          {
            "key": "REPO_URL",
            "value": "http://sample-repo"
          }
        ],
        "_embedded": {
          "packages": [
            {
              "_links": {
                "self": {
                  "href": "https://ci.example.com/go/api/admin/packages/6bba891e-2675-49af-b16d-200bd6c6801e"
                },
                "doc": {
                  "href": "https://api.gocd.org/#packages"
                },
                "find": {
                  "href": "https://ci.example.com/go/api/admin/packages/:package_id"
                }
              },
              "name": "package",
              "id": "6bba891e-2675-49af-b16d-200bd6c6801e"
            }
          ]
        }
      }
    ]
  }
}

Lists all available package repositories in cruise-config.xml.

Available since v16.12.0.

HTTP Request

GET /go/api/admin/repositories

Returns

A list of repository objects

Get a Repository

$ curl 'https://ci.example.com/go/api/admin/repositories/dd8926c0-3b4a-4c9e-8012-957b179cec5b' \
      -u 'username:password' \
      -H 'Accept:application/vnd.go.cd.v1+json' \
      -i

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/repositories/dd8926c0-3b4a-4c9e-8012-957b179cec5b"
    },
    "doc": {
      "href": "https://api.gocd.org/#package-repositories"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/repositories/:repo_id"
    }
  },
  "repo_id": "dd8926c0-3b4a-4c9e-8012-957b179cec5b",
  "name": "repository",
  "plugin_metadata": {
    "id": "deb",
    "version": "1"
  },
  "configuration": [
    {
      "key": "REPO_URL",
      "value": "http://sample-repo"
    }
  ],
  "_embedded": {
    "packages": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/packages/6bba891e-2675-49af-b16d-200bd6c6801e"
          },
          "doc": {
            "href": "https://api.gocd.org/#packages"
          },
          "find": {
            "href": "https://ci.example.com/go/api/admin/packages/:package_id"
          }
        },
        "name": "package",
        "id": "6bba891e-2675-49af-b16d-200bd6c6801e"
      }
    ]
  }
}

Get a repository for a specified id

Available since v16.12.0.

HTTP Request

GET /go/api/admin/repositories/:repo_id

Returns

A repository object

Create a Repository

$   curl -i "https://ci.example.com/go/api/admin/repositories/" \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
  "repo_id": "repository-id",
  "name": "repo.name",
  "plugin_metadata": {
    "id": "deb",
    "version": "1"
  },
  "configuration": [{
    "key": "REPO_URL",
    "value": "http://sample"
  }]
}'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/repositories/repository-id"
    },
    "doc": {
      "href": "https://api.gocd.org/#package-repositories"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/repositories/:repo_id"
    }
  },
  "repo_id": "repository-id",
  "name": "repo.name",
  "plugin_metadata": {
    "id": "deb",
    "version": "1"
  },
  "configuration": [
    {
      "key": "REPO_URL",
      "value": "http://sample"
    }
  ],
  "_embedded": {
    "packages": [

    ]
  }
}

Create the repository configuration in cruise-config.xml.

Available since v16.12.0.

HTTP Request

POST /go/api/admin/repositories

Returns

A new repository object.

Edit a repository

$ curl -i "https://ci.example.com/go/api/admin/repositories/repository-id" \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/vnd.go.cd.v1+json' \
-H 'If-Match: "e34c022772eff57ec53b6d50853be343"' \
-X PUT -d '{
  "repo_id": "repository-id",
  "name": "repo.name",
  "plugin_metadata": {
    "id": "deb",
    "version": "1"
  },
  "configuration": [{
    "key": "REPO_URL",
    "value": "http://updatedrepo"
  }]
}'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "122cd7ec0319b015653cac9a056063a7"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/repositories/repository-id"
    },
    "doc": {
      "href": "https://api.gocd.org/#package-repositories"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/repositories/:repo_id"
    }
  },
  "repo_id": "repository-id",
  "name": "repo.name",
  "plugin_metadata": {
    "id": "deb",
    "version": "1"
  },
  "configuration": [
    {
      "key": "REPO_URL",
      "value": "http://updatedrepo"
    }
  ],
  "_embedded": {
    "packages": [

    ]
  }
}

Update package repository for specified repository id.

Available since v16.12.0.

HTTP Request

PUT /go/api/admin/repositories/:repo_id

Returns

The updated repository object.

Delete a repository

$ curl -i "https://ci.example.com/go/api/admin/repositories/repository-id" \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-X DELETE

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "message": "The package repository 'repository-id' was deleted successfully."
}

Deletes a package repository from the config XML if its packages are not associated with any pipeline.

Available since v16.12.0.

HTTP Request

DELETE /go/api/admin/repositories/:repo_id

Returns

A message confirmation if the repository was deleted.

Permissions

The permissions API allows users to fetch the permissions for the GoCD entities.

Permissions

$ curl 'http://ci.example.com/go/api/auth/permissions' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "permissions": {
    "environment": {
      "view": [ "DEV", "UAT", "QA", "PROD" ],
      "administer": [ "DEV" ]
    },
    "config_repo": {
      "view": [ "dev-pipelines-repo", "prod-pipelines-repo" ],
      "administer": [ "dev-pipelines-repo" ]
    },
    "cluster_profile": {
      "view": [ "dev-cluster", "prod-cluster" ],
      "administer": [ "dev-cluster" ]
    },
    "elastic_agent_profile": {
      "view": [ "build-agent", "deploy-agent"  ],
      "administer": [ "build-agent" ]
    }
  }
}

The API supports the following query params:

Param Name Description
type The type of the gocd entity. When type is specified, GoCD will return the permissions only for the requested type.
Possible values are environment, config_repo, cluster_profile, elastic_agent_profile.

Available since v20.1.0.

HTTP Request

GET /go/api/auth/permissions

Returns

A map of entity and permissions.

Pipeline Config

The pipeline config API allows users with administrator role to manage pipeline config.

The pipeline config object

Available since v15.3.0.

Attribute Type Description
group String The name of the pipeline group to which this pipeline belongs. Since v19.10.0.
label_template String The label template to customise the pipeline instance label. Both of material names and ${COUNT} are available in the label_template. Defaults to ${COUNT}.
lock_behavior String Define the pipeline lock behavior. Can be one of lockOnFailure, unlockWhenFinished or none (default). Since v17.12.0.
name String The name of the pipeline.
template String The name of the template used by pipeline. You MUST specify atleast one stage in stages, or template.
origin Object The origin of the pipeline. Can be either gocd origin for pipelines defined in cruise-config.xml or config_repo origin for pipelines defined remotely in config repository. Since v17.4.0.
parameters Array The list of parameters to be used for substitution in a pipeline or pipeline template.
environment_variables Array The list of environment variables that will be passed to all tasks (commands) that are part of this pipeline.
materials Array The list of materials to be used by pipeline. You MUST specify atleast one material.
stages Array The list of stages. You MUST specify atleast one stage in stages, or template.
tracking_tool Object The tracking tool can be used to specify links to an issue tracker.
timer Object The timer specifies cron-like schedule to build pipeline.

The pipeline parameter object

{
  "parameters": [
    {
      "name": "VERSION",
      "value": "15.2.0"
    }
  ]
}

Attribute Type Description
name String The name of the parameter.
value String The value of the parameter.

The environment variable object

{
  "environment_variables": [
    {
      "name": "USERNAME",
      "value": "admin",
      "secure": false
    },
    {
      "name": "PASSWORD",
      "encrypted_value": "1f3rrs9uhn63hd",
      "secure": true
    },
    {
      "name": "SSH_PASSPHRASE",
      "value": "p@ssw0rd",
      "secure": true
    }
  ]
}

Attribute Type Description
name String The name of the environment variable.
value String The value of the environment variable. You MUST specify one of value or encrypted_value.
encrypted_value String The encrypted value of the environment variable. You MUST specify one of value or encrypted_value.
secure Boolean Whether environment variable is secure or not. When set to true, encrypts the value if one is specified. The default value is false.

The pipeline material object

Attribute Type Description
type String The type of a material. Can be one of git, svn, hg, p4, tfs, dependency, package, plugin.
attributes Object The attributes for each material type.

The git material attributes

{
  "materials": [
    {
      "type": "git",
      "attributes": {
        "name": "api-docs",
        "url": "https://github.com/gocd/api.go.cd",
        "username": "bob",
        "encrypted_password": "aSdiFgRRZ6A=",
        "branch": "master",
        "destination": "api.go.cd",
        "auto_update": true,
        "filter": {
          "ignore": [
            "**/*.xml",
            "**/*.html"
          ]
        },
        "invert_filter": true,
        "submodule_folder": null,
        "shallow_clone": true
      }
    }
  ]
}

Attribute Type Description
name String The name of this material.
url String The URL of the git repository.
username String The user account for the remote repository. Since v19.4.0.
password String The password for the specified user. Since v19.4.0.
branch String The git branch to build.
destination String The directory (relative to the pipeline directory) in which source code will be checked out.
auto_update Boolean Whether to poll for new changes or not.
filter Object The filter specifies files in changesets that should not trigger a pipeline automatically.
invert_filter Boolean Invert filter to enable whitelist. Since v16.7.0.
submodule_folder String The git submodule in the git repository.
shallow_clone Boolean Clone with -n (–depth) option if set to true. Since v16.3.0.

The subversion material attributes

{
  "materials": [
    {
      "type": "svn",
      "attributes": {
        "name": "svn",
        "url": "svn://svn.example.com/myProject/trunk",
        "username": "admin",
        "encrypted_password": "aSdiFgRRZ6A=",
        "destination": "myProject",
        "filter": null,
        "invert_filter": true,
        "auto_update": true,
        "check_externals": true
      }
    }
  ]
}

Attribute Type Description
name String The name of this material.
url String The URL of the subversion repository.
username String The user account for the remote repository.
password String The password for the specified user.
encrypted_password String The encrypted password for the specified user.
destination String The directory (relative to the pipeline directory) in which source code will be checked out.
filter Object The filter specifies files in changesets that should not trigger a pipeline automatically.
invert_filter Boolean Invert filter to enable whitelist. Since v16.7.0.
auto_update Boolean Whether to poll for new changes or not.
check_externals Boolean Whether the changes of the externals will trigger the pipeline automatically or not.

The mercurial material attributes

{
  "materials": [
    {
      "type": "hg",
      "attributes": {
        "name": "api-docs",
        "url": "http://hg.example.com/hg/api.go.cd",
        "username": "bob",
        "encrypted_password": "asdifgrrz6a=",
        "branch": "feature",
        "destination": "api-docs",
        "filter": null,
        "invert_filter": true,
        "auto_update": true
      }
    }
  ]
}

Attribute Type Description
name String The name of this material.
url String The URL of the mercurial repository.
username String The user account for the remote repository. Since v19.4.0.
password String The password for the specified user. Since v19.4.0.
encrypted_password String The encrypted password for the specified user. Since v19.4.0.
branch String The mercurial branch to build. Since v19.4.0.
destination String The directory (relative to the pipeline directory) in which source code will be checked out.
filter Object The filter specifies files in changesets that should not trigger a pipeline automatically.
invert_filter Boolean Invert filter to enable whitelist. Since v16.7.0.
auto_update Boolean Whether to poll for new changes or not.

The perforce material attributes

{
  "materials": [
    {
      "type": "p4",
      "attributes": {
        "name": "api-docs",
        "port": "p4.example.com:8080",
        "use_tickets": true,
        "view": "sample_view",
        "username": "admin",
        "encrypted_password": "aSdiFgRRZ6A=",
        "destination": "api-docs",
        "filter": null,
        "invert_filter": true,
        "auto_update": true
      }
    }
  ]
}

Attribute Type Description
name String The name of this material.
port String Perforce server connection to use ([transport:]host:port).
use_tickets Boolean Whether to work with the Perforce tickets or not.
view String The Perforce view.
username String The username to be used.
password String The password for the specified user.
encrypted_password String The encrypted password for the specified user.
destination String The directory (relative to the pipeline directory) in which source code will be checked out.
filter Object The filter specifies files in changesets that should not trigger a pipeline automatically.
invert_filter Boolean Invert filter to enable whitelist. Since v16.7.0.
auto_update Boolean Whether to poll for new changes or not.

The tfs material attributes

{
  "materials": [
    {
      "type": "tfs",
      "attributes": {
        "name": "tfs",
        "url": "http://tfs.exampe.com:8000/tfs",
        "project_path": "$/",
        "domain": "corporate/domain",
        "username": "admin",
        "encrypted_password": "aSdiFgRRZ6A=",
        "destination": "tfs_destination",
        "auto_update": true,
        "filter": null,
        "invert_filter": true
      }
    }
  ]
}

Attribute Type Description
name String The name of this material.
url String The URL for the Collection on the TFS Server.
project_path String The project path within the TFS collection.
domain String The domain name for TFS authentication credentials.
username String The username of the account to access the TFS collection.
password String The password of the account to access the TFS collection.
encrypted_password String The encrypted password of the account to access the TFS collection.
destination String The directory (relative to the pipeline directory) in which source code will be checked out.
auto_update Boolean Whether to poll for new changes or not.
filter Object The filter specifies files in changesets that should not trigger a pipeline automatically.
invert_filter Boolean Invert filter to enable whitelist. Since v16.7.0.

The dependency material attributes

{
  "materials": [
    {
      "type": "dependency",
      "attributes": {
        "name": "dependency",
        "pipeline": "upstream",
        "stage": "upstream_stage",
        "auto_update": true,
        "ignore_for_scheduling": false
      }
    }
  ]
}

Attribute Type Description
name String The name of this material.
pipeline String The name of a pipeline that this pipeline depends on.
stage String The name of a stage which will trigger this pipeline once it is successful.
auto_update Boolean Whether to poll for new changes or not.
ignore_for_scheduling Boolean Whether the pipeline should be triggered when there are changes in this material. Since v19.10.0.

The package material attributes

{
  "materials": [
    {
      "type": "package",
      "attributes": {
        "ref": "e289f497-057b-46bc-bb69-8043454f5c1b"
      }
    }
  ]
}

Attribute Type Description
ref String The unique package repository id.

The plugin material attributes

{
  "materials": [
    {
      "type": "plugin",
      "attributes": {
        "ref": "5e3612f7-6aa1-4d75-a9b7-6aeb52d98012",
        "filter": null,
        "invert_filter": true
      }
    }
  ]
}

Attribute Type Description
ref String The unique scm plugin repository id.
destination String The directory (relative to the pipeline directory) in which source code will be checked out.
filter Object The filter specifies files in changesets that should not trigger a pipeline automatically.
invert_filter Boolean Invert filter to enable whitelist. Updated in v20.8.0.

The filter object

{
  "filter": {
    "ignore": [
      "README.md",
      "docs/**.html"
    ]
  }
}

Attribute Type Description
ignore String The pattern for the files to be ignored.

The stage object

{
  "stages": [
    {
      "name": "my_stage",
      "fetch_materials": true,
      "clean_working_directory": false,
      "never_cleanup_artifacts": false,
      "approval": {
        "type": "success",
        "authorization": {
          "roles": [

          ],
          "users": [

          ]
        }
      },
      "environment_variables": [

      ],
      "jobs": [

      ]
    }
  ]
}

Attribute Type Description
name String The name of the stage.
fetch_materials Boolean Whether to perform material update/checkout.
clean_working_directory Boolean Whether to delete the working directory every time.
never_cleanup_artifacts Boolean Never cleanup artifacts for this stage, if purging artifacts is configured at the Server Level.
approval Object The approval specifies how stage should be triggered. Can be one of manual, success.
environment_variables Array The list of of environment variables defined here are set on the agents and can be used within your stage.
jobs Array The list of jobs.

The approval object

{
  "approval": {
    "type": "success",
    "allow_only_on_success": true,
    "authorization": {
      "roles": [

      ],
      "users": [

      ]
    }
  }
}

Attribute Type Description
type String The type of the approval on which stage will trigger. Can be one of success, manual.
allow_only_on_success Boolean Setting this attribute to true will ensure that the stage can triggered only if the previous stage (if any) has succeeded. Default is false. Since v19.8.0.
authorization Object The authorization under an approval with a manual or success type to specify who can approve this stage.

The authorization object

{
  "authorization": {
    "roles": [

    ],
    "users": [

    ]
  }
}

Attribute Type Description
users Array The list of users authorized to operate (run) on this stage.
roles Array The list of roles authorized to operate (run) on this stage.

The job object

{
  "jobs": [
    {
      "name": "my_job",
      "run_instance_count": null,
      "timeout": 0,
      "environment_variables": [

      ],
      "resources": [
        "Linux",
        "Java"
      ],
      "tasks": [

      ]
    },
    {
      "name": "unit_test",
      "run_instance_count": null,
      "timeout": 0,
      "environment_variables": [

      ],
      "elastic_profile_id": "docker.unit-test",
      "tasks": [

      ]
    }
  ]
}

Attribute Type Description
name String The name of the job.
run_instance_count Number/String 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.
environment_variables Array The list of environment variables defined here are set on the agents and can be used within your tasks.
resources Array The list of (String) resources that specifies the resource which the job requires to build. MUST NOT be specified along with elastic_profile_id.
tasks Array The list of tasks that will run as part of the job.
tabs Array The list of tabs which let you add custom tabs within the job details page.
artifacts Array The list of artifacts specifies what files the agent will publish to the server.
elastic_profile_id String The id of the elastic profile, specifying this attribute would run the job on an elastic agent asociated with this profile. MUST NOT be specified along with resources. Since v16.10.0.

The task object

Attribute Type Description
type String The type of a task. Can be one of exec, ant, nant, rake, fetch, pluggable_task.
attributes Object The attributes for each task type.

The exec task attributes

{
  "tasks": [
    {
      "type": "exec",
      "attributes": {
        "run_if": [
          "passed"
        ],
        "command": "make",
        "arguments": [
          "-j3",
          "docs",
          "instal"
        ],
        "working_directory": null
      }
    }
  ]
}

Attribute Type Description
run_if Array The run_if condition specifies when a task should be allowed to run. Can be one of passed, failed, any.
command String The name of the executable. If the executable is not on PATH, you may also specify the full path.
arguments Array The list of arguments to be passed to the executable.
working_directory String The directory in which the executable is to be executed.
on_cancel Object The task specifies a task to execute when a stage is cancelled.

The ant task attributes

{
  "tasks": [
    {
      "type": "ant",
      "attributes": {
        "run_if": [
          "passed"
        ],
        "working_directory": "script/build",
        "build_file": null,
        "target": null
      }
    }
  ]
}

Attribute Type Description
run_if Array The run_if condition specifies when a task should be allowed to run. Can be one of passed, failed, any.
build_file String The path to Ant build file.
target String The Ant target(s) to run.
working_directory String The directory in which Ant is invoked.
on_cancel Object The task specifies a task to execute when a stage is cancelled.

The nant task attributes

{
  "tasks": [
    {
      "type": "nant",
      "attributes": {
        "run_if": [
          "passed"
        ],
        "working_directory": "script/build/123",
        "build_file": null,
        "target": null,
        "nant_path": null
      }
    }
  ]
}

Attribute Type Description
run_if Array The run_if condition specifies when a task should be allowed to run. Can be one of passed, failed, any.
build_file String The path to NAnt build file.
target String The NAnt target(s) to run.
nant_path String This is the directory where the nant.exe executable is located. By default GoCD will look for nant.exe in the PATH.
working_directory String The directory in which NAnt is invoked.
on_cancel Object The task specifies a task to execute when a stage is cancelled.

The rake task attributes

{
  "tasks": [
    {
      "type": "rake",
      "attributes": {
        "run_if": [
          "passed"
        ],
        "working_directory": "sample-project",
        "build_file": null,
        "target": null
      }
    }
  ]
}

Attribute Type Description
run_if Array The run_if condition specifies when a task should be allowed to run. Can be one of passed, failed, any.
build_file String The path to rake file. Defaults to rakefile.
target String The rake target(s) to run. If not specified, rake runs the default target in the file specified by build_file.
working_directory String The directory from which rake is invoked.
on_cancel Object The task specifies a task to execute when a stage is cancelled.

The fetch task attributes

{
  "tasks": [
    {
      "type": "fetch",
      "attributes": {
        "artifact_origin": "gocd",
        "run_if": [
          "passed"
        ],
        "pipeline": "upstream",
        "stage": "upstream_stage",
        "job": "upstream_job",
        "is_source_a_file": false,
        "source": "result",
        "destination": "test"
      }
    },
    {
      "type": "fetch",
      "attributes": {
        "artifact_origin": "external",
        "pipeline": "some-upstream-pipeline",
        "stage": "defaultStage",
        "job": "defaultJob",
        "artifact_id": "s3",
        "configuration": [
          {
            "key": "dest_on_agent",
            "value": "artifact"
          }
        ]
      }
    }
  ]
}

Attribute Type Description
artifact_origin String Origin indicates whether the artifact to fetch is on the GoCD server or in an external repository. Can be one of gocd, external.
run_if Array The run_if condition specifies when a task should be allowed to run. Can be one of passed, failed, any.
pipeline String The name of direct upstream pipeline or ancestor pipeline of one of the upstream pipelines on which the pipeline of the job depends on. .
stage String The name of the stage to fetch artifacts from.
job String The name of the job to fetch artifacts from.
source String The path of the artifact directory or file of a specific job, relative to the sandbox directory. If the directory or file does not exist, the job is failed. Should be specified if origin is gocd.
is_source_a_file Boolean Whether source is a file or directory. Should be specified if origin is gocd.
destination String The path of the directory where the artifact is fetched to. Should be specified if origin is gocd.
on_cancel Object The task specifies a task to execute when a stage is cancelled.
artifact_id String The external artifact that was published by an upstream pipeline or stage. Should be specified if origin is external.
configuration Array A list of key-value pairs which defines the plugin configuration. Should be specified if origin is external.

The pluggable task object

{
  "tasks": [
    {
      "type": "pluggable_task",
      "attributes": {
        "configuration": [
          {
            "key": "ConverterType",
            "value": "jsunit"
          }
        ],
        "run_if": [
          "passed"
        ],
        "plugin_configuration": {
          "id": "xunit.converter.task.plugin",
          "version": "1"
        },
        "on_cancel": null
      }
    }
  ]
}

Attribute Type Description
run_if Array The run_if condition specifies when a task should be allowed to run. Can be one of passed, failed, any.
plugin_configuration Object The plugin configuration contains id of the plugin and version number.
configuration Array A list of key-value pairs which defines the plugin configuration.
on_cancel Object The task specifies a task to execute when a stage is cancelled.

The tab object

{
  "tabs": [
    {
      "name": "cobertura",
      "path": "target/site/cobertura/index.html"
    }
  ]
}

Attribute Type Description
name String The name of the tab which will appear in the Job detail page.
path String The relative path of a file in the server artifact destination directory of the job that will be render in the tab.

The pipeline config artifact object

{
  "artifacts": [
    {
      "source": "target",
      "destination": "result",
      "type": "build"
    },
    {
      "source": "test",
      "destination": "res1",
      "type": "test"
    },
    {
      "artifact_id": "docker-image",
      "store_id": "dockerhub",
      "type": "external",
      "configuration": [
        {
          "key": "Image",
          "value": "gocd/gocd-server"
        },
        {
          "key": "Tag",
          "value": "v${GO_PIPELINE_COUNTER}"
        }
      ]
    }
  ]
}

Attribute Type Description
type String The type of the artifact. Can be one of test, build, external.
source String 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.

The timer object

{
  "timer": {
    "spec": "0 0 22 ? * MON-FRI",
    "only_on_changes": true
  }
}

Attribute Type Description
spec String The cron-like schedule to build the pipeline.
only_on_changes Boolean Run only if the pipeline hasn’t previously run with the latest material(s).

The tracking tool object

{
  "tracking_tool": {
    "type": "generic",
    "attributes": {
      "url_pattern": "https://github.com/gocd/api.go.cd/issues/${ID}",
      "regex": "##(d+)"
    }
  }
}

Attribute Type Description
type String The type of the tracking tool is generic.
attributes Object The attributes of the tracking tool. See attributes for generic.

The generic tracking tool object

{
  "attributes": {
    "url_pattern": "https://github.com/gocd/api.go.cd/issues/${ID}",
    "regex": "##(d+)"
  }
}

Attribute Type Description
url_pattern String In generic tracking tool, the URI to your tracking tool.
regex String In generic tracking tool, the regular expression to identify card or bug numbers from your checkin comments.

The config repo origin object

{
  "_links": {
    "self": {
      "href": "http://localhost:8153/go/api/admin/config_repos/repo1"
    },
    "doc": {
      "href": "https://api.gocd.org/#config-repos"
    },
    "find": {
      "href": "http://localhost:8153/go/api/admin/config_repos/:id"
    }
  },
  "type": "config_repo",
  "id": "repo1"
}

Attribute Type Description
type String The type of origin. Can be either gocd or config_repo.
id String The identifier of the config repository. This attribute is only available if type of the origin is config_repo.

Get pipeline config

$ curl 'https://ci.example.com/go/api/admin/pipelines/my_pipeline' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v11+json' \
      -i

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v11+json; charset=utf-8
ETag: "e064ca0fe5d8a39602e19666454b8d77"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/pipelines/my_pipeline"
    },
    "doc": {
      "href": "https://api.gocd.org/#pipeline-config"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/pipelines/:name"
    }
  },
  "label_template" : "${COUNT}",
  "lock_behavior" : "lockOnFailure",
  "name" : "new_pipeline",
  "template" : null,
  "group": "new_group",
  "origin" : {
    "_links" : {
      "self" : {
        "href" : "https://ci.example.com/go/admin/config_xml"
      },
      "doc" : {
        "href" : "https://api.gocd.org/current/#get-configuration"
      }
    },
    "type" : "gocd"
  },
  "parameters" : [ ],
  "environment_variables" : [ ],
  "materials" : [ {
    "type" : "git",
    "attributes" : {
      "url" : "git@github.com:sample_repo/example.git",
      "destination" : "dest",
      "filter" : null,
      "invert_filter" : false,
      "name" : null,
      "auto_update" : true,
      "branch" : "master",
      "submodule_folder" : null,
      "shallow_clone" : false
    }
  } ],
  "stages" : [ {
    "name" : "defaultStage",
    "fetch_materials" : true,
    "clean_working_directory" : false,
    "never_cleanup_artifacts" : false,
    "approval" : {
      "type" : "success",
      "authorization" : {
        "roles" : [ ],
        "users" : [ ]
      }
    },
    "environment_variables" : [ ],
    "jobs" : [ {
      "name" : "defaultJob",
      "run_instance_count" : null,
      "timeout" : null,
      "environment_variables" : [ ],
      "resources" : [ ],
      "tasks" : [ {
        "type" : "exec",
        "attributes" : {
          "run_if" : [ "passed" ],
          "command" : "ls",
          "args" : ""
        }
      } ],
      "tabs" : [ ],
      "artifacts" : [ {
        "type" : "external",
        "artifact_id" : "docker-image",
        "store_id" : "dockerhub",
        "configuration" : [ {
          "key" : "Image",
          "value" : "gocd/gocd-server"
        }, {
          "key" : "Tag",
          "value" : "v${GO_PIPELINE_LABEL}"
        }]
      } ]
    } ]
  }, {
    "name" : "s2",
    "fetch_materials" : true,
    "clean_working_directory" : false,
    "never_cleanup_artifacts" : false,
    "approval" : {
      "type" : "success",
      "authorization" : {
        "roles" : [ ],
        "users" : [ ]
      }
    },
    "environment_variables" : [ ],
    "jobs" : [ {
      "name" : "j2",
      "run_instance_count" : null,
      "timeout" : null,
      "environment_variables" : [ ],
      "resources" : [ ],
      "tasks" : [ {
        "type" : "fetch",
        "attributes" : {
          "artifact_origin" : "external",
          "pipeline" : "",
          "stage" : "defaultStage",
          "job" : "defaultJob",
          "run_if" : [ ],
          "artifact_id" : "docker-image"
        }
      } ],
      "tabs" : [ ],
      "artifacts" : [ ]
    } ]
  } ],
  "tracking_tool" : null,
  "timer" : null
}

Gets pipeline config for specified pipeline name.

Updated to version v11 since v20.08.0.

Available since v15.3.0.

HTTP Request

GET /go/api/admin/pipelines/:pipeline_name

Returns

The pipeline config object.

Edit pipeline config

$ curl 'https://ci.example.com/go/api/admin/pipelines/my_pipeline' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v11+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "e064ca0fe5d8a39602e19666454b8d77"' \
      -X PUT \
      -d '{
            "label_template": "${COUNT}",
            "lock_behavior": "unlockWhenFinished",
            "name": "my_pipeline",
            "template": null,
            "group": "new_group",
            "materials": [
              {
                "type": "git",
                "attributes": {
                  "url": "https://github.com:sample_repo/example.git",
                  "username": "bob",
                  "password": "pass",
                  "destination": "dest",
                  "filter": null,
                  "invert_filter": false,
                  "name": null,
                  "auto_update": true,
                  "branch": "master",
                  "submodule_folder": null,
                  "shallow_clone": true
                }
              }
            ],
            "stages": [
              {
                "name": "defaultStage",
                "fetch_materials": true,
                "clean_working_directory": false,
                "never_cleanup_artifacts": false,
                "approval": {
                  "type": "success",
                  "authorization": {
                    "roles": [],
                    "users": []
                  }
                },
                "environment_variables": [],
                "jobs": [
                  {
                    "name": "defaultJob",
                    "run_instance_count": null,
                    "timeout": 0,
                    "environment_variables": [],
                    "resources": [],
                    "tasks": [
                      {
                        "type": "exec",
                        "attributes": {
                          "run_if": [
                            "passed"
                          ],
                          "command": "ls",
                          "working_directory": null
                        }
                      }
                    ],
                    "artifacts": [
                      {
                        "type": "external",
                        "artifact_id": "docker-image",
                        "store_id": "dockerhub",
                        "configuration": [
                          {
                            "key": "Image",
                            "value": "gocd/gocd-server"
                          },
                          {
                            "key": "Tag",
                            "value": "v${GO_PIPELINE_COUNTER}"
                          }
                        ]
                      }
                    ]
                  }
                ]
              },
              {
                "name": "s2",
                "jobs": [
                  {
                    "name": "j2",
                    "tasks": [
                      {
                        "type": "fetch",
                        "attributes": {
                          "artifact_origin": "external",
                          "pipeline": "",
                          "stage": "defaultStage",
                          "job": "defaultJob",
                          "artifact_id": "docker-image"
                        }
                      }
                    ]
                  }
                ]
              }
            ]
          }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v11+json; charset=utf-8
ETag: "e89135b38ddbcd9380c83eb524647bdd"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/pipelines/my_pipeline"
    },
    "doc": {
      "href": "https://api.gocd.org/#pipeline-config"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/pipelines/:name"
    }
  },
  "label_template" : "${COUNT}",
  "lock_behavior" : "lockOnFailure",
  "name" : "new_pipeline",
  "template" : null,
  "group": "new_group",
  "origin" : {
    "_links" : {
      "self" : {
        "href" : "https://ci.example.com/go/admin/config_xml"
      },
      "doc" : {
        "href" : "https://api.gocd.org/current/#get-configuration"
      }
    },
    "type" : "gocd"
  },
  "parameters" : [ ],
  "environment_variables" : [ ],
  "materials" : [ {
    "type" : "git",
    "attributes" : {
      "url" : "git@github.com:sample_repo/example.git",
      "username": "bob",
      "encrypted_password": "aSdiFgRRZ6A=",
      "destination" : "dest",
      "filter" : null,
      "invert_filter" : false,
      "name" : null,
      "auto_update" : true,
      "branch" : "master",
      "submodule_folder" : null,
      "shallow_clone" : false
    }
  } ],
  "stages" : [ {
    "name" : "defaultStage",
    "fetch_materials" : true,
    "clean_working_directory" : false,
    "never_cleanup_artifacts" : false,
    "approval" : {
      "type" : "success",
      "authorization" : {
        "roles" : [ ],
        "users" : [ ]
      }
    },
    "environment_variables" : [ ],
    "jobs" : [ {
      "name" : "defaultJob",
      "run_instance_count" : null,
      "timeout" : null,
      "environment_variables" : [ ],
      "resources" : [ ],
      "tasks" : [ {
        "type" : "exec",
        "attributes" : {
          "run_if" : [ "passed" ],
          "command" : "ls",
          "args" : ""
        }
      } ],
      "tabs" : [ ],
      "artifacts" : [ {
        "type" : "external",
        "artifact_id" : "docker-image",
        "store_id" : "dockerhub",
        "configuration" : [ {
          "key" : "Image",
          "value" : "gocd/gocd-server"
        }, {
          "key" : "Tag",
          "value" : "v${GO_PIPELINE_LABEL}"
        }]
      } ]
    } ]
  }, {
    "name" : "s2",
    "fetch_materials" : true,
    "clean_working_directory" : false,
    "never_cleanup_artifacts" : false,
    "approval" : {
      "type" : "success",
      "authorization" : {
        "roles" : [ ],
        "users" : [ ]
      }
    },
    "environment_variables" : [ ],
    "jobs" : [ {
      "name" : "j2",
      "run_instance_count" : null,
      "timeout" : null,
      "environment_variables" : [ ],
      "resources" : [ ],
      "tasks" : [ {
        "type" : "fetch",
        "attributes" : {
          "artifact_origin" : "external",
          "pipeline" : "",
          "stage" : "defaultStage",
          "job" : "defaultJob",
          "run_if" : [ ],
          "artifact_id" : "docker-image"
        }
      } ],
      "tabs" : [ ],
      "artifacts" : [ ]
    } ]
  } ],
  "tracking_tool" : null,
  "timer" : null
}

Update pipeline config for specified pipeline name.

Updated to version v11 since v20.08.0.

Available since v15.3.0.

HTTP Request

PUT /go/api/admin/pipelines/:pipeline_name

Returns

The updated pipeline config object.

Create a pipeline

$ curl 'https://ci.example.com/go/api/admin/pipelines' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v11+json' \
      -H 'Content-Type: application/json' \
      -H 'X-pause-pipeline: true' \
      -H 'X-pause-cause: "to have more control over when to start the pipeline after reviewing it"' \
      -X POST -d '{ "group": "first",
                    "pipeline": {
                    "label_template": "${COUNT}",
                    "lock_behavior": "lockOnFailure",
                    "name": "new_pipeline",
                    "template": null,
                    "materials": [
                      {
                        "type": "git",
                        "attributes": {
                          "url": "git@github.com:sample_repo/example.git",
                          "destination": "dest",
                          "filter": null,
                          "invert_filter": false,
                          "name": null,
                          "auto_update": true,
                          "branch": "master",
                          "submodule_folder": null,
                          "shallow_clone": true
                        }
                      }
                    ],
                    "stages": [
                      {
                        "name": "defaultStage",
                        "fetch_materials": true,
                        "clean_working_directory": false,
                        "never_cleanup_artifacts": false,
                        "approval": {
                          "type": "success",
                          "authorization": {
                            "roles": [],
                            "users": []
                          }
                        },
                        "environment_variables": [],
                        "jobs": [
                          {
                            "name": "defaultJob",
                            "run_instance_count": null,
                            "timeout": 0,
                            "environment_variables": [],
                            "resources": [],
                            "tasks": [
                              {
                                "type": "exec",
                                "attributes": {
                                  "run_if": [
                                    "passed"
                                  ],
                                  "command": "ls",
                                  "working_directory": null
                                }
                              }
                            ],
                            "artifacts": [
                              {
                                "type": "external",
                                "artifact_id": "docker-image",
                                "store_id": "dockerhub",
                                "configuration": [
                                  {
                                    "key": "Image",
                                    "value": "gocd/gocd-server"
                                  },
                                  {
                                    "key": "Tag",
                                    "value": "v${GO_PIPELINE_COUNTER}"
                                  }
                                ]
                              }
                            ]
                          }
                        ]
                      },
                      {
                        "name": "s2",
                        "jobs": [
                          {
                            "name": "j2",
                            "tasks": [
                              {
                                "type": "fetch",
                                "attributes": {
                                  "artifact_origin": "external",
                                  "pipeline": "",
                                  "stage": "defaultStage",
                                  "job": "defaultJob",
                                  "artifact_id": "docker-image"
                                }
                              }
                            ]
                          }
                        ]
                      }
                    ]
                }
              }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v11+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/pipelines/new_pipeline"
    },
    "doc": {
      "href": "https://api.gocd.org/#pipeline-config"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/pipelines/:name"
    }
  },
  "label_template" : "${COUNT}",
  "lock_behavior" : "lockOnFailure",
  "name" : "new_pipeline",
  "template" : null,
  "group": "new_group",
  "origin" : {
    "_links" : {
      "self" : {
        "href" : "https://ci.example.com/go/admin/config_xml"
      },
      "doc" : {
        "href" : "https://api.gocd.org/current/#get-configuration"
      }
    },
    "type" : "gocd"
  },
  "parameters" : [ ],
  "environment_variables" : [ ],
  "materials" : [ {
    "type" : "git",
    "attributes" : {
      "url" : "git@github.com:sample_repo/example.git",
      "destination" : "dest",
      "filter" : null,
      "invert_filter" : false,
      "name" : null,
      "auto_update" : true,
      "branch" : "master",
      "submodule_folder" : null,
      "shallow_clone" : false
    }
  } ],
  "stages" : [ {
    "name" : "defaultStage",
    "fetch_materials" : true,
    "clean_working_directory" : false,
    "never_cleanup_artifacts" : false,
    "approval" : {
      "type" : "success",
      "authorization" : {
        "roles" : [ ],
        "users" : [ ]
      }
    },
    "environment_variables" : [ ],
    "jobs" : [ {
      "name" : "defaultJob",
      "run_instance_count" : null,
      "timeout" : null,
      "environment_variables" : [ ],
      "resources" : [ ],
      "tasks" : [ {
        "type" : "exec",
        "attributes" : {
          "run_if" : [ "passed" ],
          "command" : "ls",
          "args" : ""
        }
      } ],
      "tabs" : [ ],
      "artifacts" : [ {
        "type" : "external",
        "artifact_id" : "docker-image",
        "store_id" : "dockerhub",
        "configuration" : [ {
          "key" : "Image",
          "value" : "gocd/gocd-server"
        }, {
          "key" : "Tag",
          "value" : "v${GO_PIPELINE_LABEL}"
        }]
      } ]
    } ]
  }, {
    "name" : "s2",
    "fetch_materials" : true,
    "clean_working_directory" : false,
    "never_cleanup_artifacts" : false,
    "approval" : {
      "type" : "success",
      "authorization" : {
        "roles" : [ ],
        "users" : [ ]
      }
    },
    "environment_variables" : [ ],
    "jobs" : [ {
      "name" : "j2",
      "run_instance_count" : null,
      "timeout" : null,
      "environment_variables" : [ ],
      "resources" : [ ],
      "tasks" : [ {
        "type" : "fetch",
        "attributes" : {
          "artifact_origin" : "external",
          "pipeline" : "",
          "stage" : "defaultStage",
          "job" : "defaultJob",
          "run_if" : [ ],
          "artifact_id" : "docker-image"
        }
      } ],
      "tabs" : [ ],
      "artifacts" : [ ]
    } ]
  } ],
  "tracking_tool" : null,
  "timer" : null
}

Create a pipeline.

Updated to version v11 since v20.08.0.

Available since v15.3.0.

HTTP Request

POST /go/api/admin/pipelines

Returns

A new pipeline config object.

Delete a pipeline

$ curl 'https://ci.example.com/go/api/admin/pipelines/my_pipeline' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v11+json' \
      -X DELETE

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v11+json; charset=utf-8
{
  "message": "Pipeline 'my_pipeline' was deleted successfully."
}

Deletes a pipeline from the config XML.

Updated to version v11 since v20.08.0.

Available since v16.6.0.

HTTP Request

DELETE /go/api/admin/pipelines/:pipeline_name

Returns

A message confirmation if the pipeline was deleted.

Extract tempate from pipeline

$ curl 'https://ci.example.com/go/api/admin/pipelines/my_pipeline/extract_to_template' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v11+json' \
      -H 'Content-Type: application/json' \
      -X PUT \
      -d '{
        "template_name": "new-template-name"
       }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v11+json; charset=utf-8
ETag: "d4fe83677faaddcbf69c580ffb7409f7"
{
  "_links" : {
    "self" : {
      "href" : "https://ci.example.com/go/api/admin/pipelines/clone1"
    },
    "doc" : {
      "href" : "https://api.gocd.org/#pipeline-config"
    },
    "find" : {
      "href" : "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
    }
  },
  "label_template" : "${COUNT}",
  "lock_behavior" : "none",
  "name" : "my_pipeline",
  "template" : "new-template-name",
  "group" : "group",
  "origin" : {
    "_links" : {
      "self" : {
        "href" : "https://ci.example.com/go/admin/config_xml"
      },
      "doc" : {
        "href" : "https://api.gocd.org/#get-configuration"
      }
    },
    "type" : "gocd"
  },
  "parameters" : [ ],
  "environment_variables" : [ ],
  "materials" : [ {
    "type" : "git",
    "attributes" : {
      "url" : "git@github.com:sample_repo/example.git",
      "username": "bob",
      "encrypted_password": "aSdiFgRRZ6A=",
      "destination" : "dest",
      "filter" : null,
      "invert_filter" : false,
      "name" : null,
      "auto_update" : true,
      "branch" : "master",
      "submodule_folder" : null,
      "shallow_clone" : false
    }
  } ],
  "stages" : null,
  "tracking_tool" : null,
  "timer" : null
}

The Extract Template API will create a new template out of the given pipeline and update the pipeline to use the same template.

Available since v19.11.0.

HTTP Request

PUT /go/api/admin/pipelines/:pipeline_name/extract_to_template

Returns

The updated pipeline config object.

Pipeline Group Config

The Pipeline Group Config API allows admin users to manage pipeline groups.

The pipeline group object

Available since v18.10.0.

Attribute Type Description
name String The name of the pipeline group.
authorization Object The authorization configuration for the pipeline group.
pipelines Array The list of pipelines that belong to the pipeline group.

The pipeline group authorization configuration

Available since v18.10.0.

Attribute Type Description
view Object The list of users and roles with view permission for this pipeline group.
operate Object The list of users and roles with operate permission for this pipeline group.
admins Object The list of users and roles with admin permission for this pipeline group.

Get all pipeline groups

$ curl 'https://ci.example.com/go/api/admin/pipeline_groups' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links" : {
    "self" : {
      "href" : "https://ci.example.com/go/api/admin/pipeline_groups"
    },
    "doc" : {
      "href" : "https://api.go.cd/current/#pipeline-group-config"
    },
    "find" : {
      "href" : "https://ci.example.com/go/api/admin/pipeline_groups/:group"
    }
  },
  "_embedded" : {
    "groups" : [ {
      "_links" : {
        "self" : {
          "href" : "https://ci.example.com/go/api/admin/pipeline_groups/first"
        },
        "doc" : {
          "href" : "https://api.go.cd/current/#pipeline-group-config"
        },
        "find" : {
          "href" : "https://ci.example.com/go/api/admin/pipeline_groups/:group"
        }
      },
      "name" : "first",
      "authorization" : {
        "view" : {
          "users" : [ "operate" ],
          "roles" : [ ]
        },
        "admins" : {
          "users" : [ "operate" ],
          "roles" : [ ]
        }
      },
      "pipelines" : [ {
        "_links" : {
          "self" : {
            "href" : "https://ci.example.com/go/api/admin/pipelines/up42"
          },
          "doc" : {
            "href" : "https://api.gocd.org/#pipeline-config"
          },
          "find" : {
            "href" : "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
          }
        },
        "name" : "up42"
      } ]
    } ]
  }
}

Available since v18.10.0.

HTTP Request

GET /go/api/admin/pipeline_groups

Returns

A list of pipeline group objects.

Get a pipeline group

$ curl 'https://ci.example.com/go/api/admin/pipeline_groups/first' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "17f5a9edf150884e5fc4315b4a7814cd"
{
  "_links" : {
    "self" : {
      "href" : "https://ci.example.com/go/api/admin/pipeline_groups/first"
    },
    "doc" : {
      "href" : "https://api.go.cd/current/#pipeline-group-config"
    },
    "find" : {
      "href" : "https://ci.example.com/go/api/admin/pipeline_groups/:group"
    }
  },
  "name" : "first",
  "authorization" : {
    "view" : {
      "users" : [ "operate" ],
      "roles" : [ ]
    },
    "admins" : {
      "users" : [ "operate" ],
      "roles" : [ ]
    }
  },
  "pipelines" : [ {
    "_links" : {
      "self" : {
        "href" : "https://ci.example.com/go/api/admin/pipelines/up42"
      },
      "doc" : {
        "href" : "https://api.gocd.org/#pipeline-config"
      },
      "find" : {
        "href" : "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
      }
    },
    "name" : "up42"
  } ]
}

Gets config for specified pipeline group.

Available since v18.10.0.

HTTP Request

GET /go/api/admin/pipeline_groups/:group_name

Returns

A pipeline group object.

Create a pipeline group

$ curl 'https://ci.example.com/go/api/admin/pipeline_groups' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -H 'Content-Type: application/json' \
      -X POST -d '{
        "name": "second",
        "authorization": {
          "view": {
            "users": ["alice"],
            "roles": ["role"]
          },
          "operate": {
            "users": ["alice"]
          },
          "admins": {
            "users": ["bob"]
          }
        }
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "f35e562b555dbbba2c92f44ebcf58c83"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/pipeline_groups/second"
    },
    "doc": {
      "href": "https://api.go.cd/current/#pipeline-group-config"
    },
    "find": {
      "href": "http://ci.example.com/go/api/admin/pipeline_groups/:group_name"
    }
  },
  "name": "second",
  "authorization": {
    "view": {
      "users": ["alice"],
      "roles": ["role"]
    },
    "operate": {
      "users": ["alice"],
      "roles": [ ]
    },
    "admins": {
      "users": ["bob"],
      "roles": [ ]
    }
  },
  "pipelines": [ ]
}

Create a pipeline group.

Available since v18.10.0.

HTTP Request

POST /go/api/admin/pipeline_groups

Returns

The new pipeline group object.

Update a pipeline group

Update authorization config of the specified pipeline group.

$ curl 'https://ci.example.com/go/api/admin/pipeline_groups/first' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "17f5a9edf150884e5fc4315b4a7814cd"' \
      -X PUT \
      -d '{
        "name": "first",
        "authorization": {
          "view": {
            "users": ["alice"],
            "roles": ["role"]
          },
          "operate": {
            "users": ["alice"]
          },
          "admins": {
            "users": ["bob"]
          }
        }
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "ae1d9184358c297a23118fe0e0e64c50"
{
  "_links" : {
    "self" : {
      "href" : "https://ci.example.com/go/api/admin/pipeline_groups/first"
    },
    "doc" : {
      "href" : "https://api.go.cd/current/#pipeline-group-config"
    },
    "find" : {
      "href" : "https://ci.example.com/go/api/admin/pipeline_groups/:group"
    }
  },
  "name" : "first",
  "authorization" : {
    "view" : {
      "users" : [ "alice" ],
      "roles" : [ "role" ]
    },
    "operate": {
      "users" : [ "alice" ],
      "roles" : [ ]
    },
    "admins" : {
      "users" : [ "bob" ],
      "roles" : [ ]
    }
  },
  "pipelines" : [ {
    "_links" : {
      "self" : {
        "href" : "https://ci.example.com/go/api/admin/pipelines/up42"
      },
      "doc" : {
        "href" : "https://api.gocd.org/#pipeline-config"
      },
      "find" : {
        "href" : "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
      }
    },
    "name" : "up42"
  } ]
}

Available since v18.10.0.

HTTP Request

PUT /go/api/admin/pipeline_groups/:group_name

Returns

The updated pipeline group object.

Delete a pipeline group

$ curl 'https://ci.example.com/go/api/admin/pipeline_groups/first' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -X DELETE

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "message": "The Pipeline group 'first' was deleted successfully."
}

Deletes the pipeline group.

Available since v18.10.0.

HTTP Request

DELETE /go/api/admin/pipeline_groups/:group_name

Returns

A message confirmation if the pipeline group was deleted.

Pluggable SCMs

The pluggable SCM API v3 allows users to view, create and update the SCM object.

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.
name String The global name of the material.
auto_update Boolean Whether the material is set to poll for new changes.
plugin_metadata Object The plugin metadata provides information about the plugin.
configuration Object The list of properties (key-value pairs) to be provided for using the plugin.

The plugin metadata object

{
  "plugin_metadata": {
    "id": "github.pr",
    "version": "1.1"
  }
}

Attribute Type Description
id String The plugin id.
version String The current version of the plugin.

The configuration property object

{
  "configuration": [
    {
      "key": "username",
      "value": "admin"
    },
    {
      "key": "password",
      "encrypted_value": "1f3rrs9uhn63hd"
    },
    {
      "key": "url",
      "value": "https://github.com/sample/example.git"
    }
  ]
}

Attribute Type Description
key String The name of the property key.
value String The value of the property. You MUST specify one of value or encrypted_value.
encrypted_value String The encrypted value of the property. You MUST specify one of value or encrypted_value.

Get all Pluggable SCM materials

$ curl 'https://ci.example.com/go/api/admin/scms' \
      -u 'username:password' \
      -H 'Accept:application/vnd.go.cd.v3+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/scms"
    },
    "doc": {
      "href": "https://api.gocd.org/#scms"
    }
  },
  "_embedded": {
    "scms": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/scms/scmName"
          },
          "doc": {
            "href": "https://api.gocd.org/#scms"
          },
          "find": {
            "href": "https://ci.example.com/go/api/admin/scms/:material_name"
          }
        },
        "id": "912ef7c8-0d82-4a5c-8f42-0a95abe82466",
        "name": "scmName",
        "plugin_metadata": {
          "id": "github.pr",
          "version": "1"
        }
      }
    ]
  }
}

Lists all available pluggable scm materials, these are materials that are present in the in cruise-config.xml.

Updated to version v3 since v20.3.0.

Available since v16.7.0.

HTTP Request

GET /go/api/admin/scms

Returns

A list of SCM objects

Get a Pluggable SCM material

$ curl 'https://ci.example.com/go/api/admin/scms/pluggable.scm.material.name' \
      -u 'username:password' \
      -H 'Accept:application/vnd.go.cd.v3+json' \
      -i

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "05548388f7ef5042cd39f7fe42e85735"

{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/scms/pluggable.scm.material.name"
    },
    "doc": {
      "href": "https://api.gocd.org/#scms"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/scms/:material_name"
    }
  },
  "id": "scmID",
  "name": "pluggable.scm.material.name",
  "plugin_metadata": {
    "id": "github.pr",
    "version": "1"
  },
  "auto_update": true,
  "configuration": [
    {
      "key": "url",
      "value": "https://github.com/sample/example.git"
    },
    {
      "key": "username",
      "value": "admin"
    },
    {
      "key": "password",
      "encrypted_value": "aSdiFgRRZ6A="
    }
  ]
}

Gets the SCM object for a specified name.

Updated to version v3 since v20.3.0.

Available since v16.7.0.

HTTP Request

GET /go/api/admin/scms/:material_name

Returns

A SCM object

Create a SCM object

$   curl 'http://ci.example.com/go/api/admin/scms' \
  -u 'username:password' \
  -H 'Accept:application/vnd.go.cd.v3+json' \
  -H 'Content-Type:application/json' \
  -X POST -d '{
  "id": "scm-id",
  "name": "foobar",
  "auto_update": true,
  "plugin_metadata": {
    "id": "github.pr",
    "version": "1"
  },
  "configuration": [
    {
      "key": "url",
      "value": "git@github.com:sample/example.git"
    },
    {
      "key": "username",
      "value": "admin"
    },
    {
      "key": "password",
      "encrypted_value": "aSdiFgRRZ6A="
    }
  ]
 }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/scms/scmName"
    },
    "doc": {
      "href": "https://api.gocd.org/#scms"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/scms/:material_name"
    }
  },
  "id": "scm-id",
  "name": "scmName",
  "plugin_metadata": {
    "id": "github.pr",
    "version": "1"
  },
  "auto_update": true,
  "configuration": [
    {
      "key": "url",
      "value": "https://github.com/sample/example.git"
    },
    {
      "key": "username",
      "encrypted_value": "50TVtMW3cBU="
    },
    {
      "key": "password",
      "encrypted_value": "aSdiFgRRZ6A="
    }
  ]
}

Create a global SCM object.

Updated to version v3 since v20.3.0.

Available since v16.7.0.

HTTP Request

POST /go/api/admin/scms

Returns

A new SCM object.

Update Pluggable SCM object

$ curl 'https://ci.example.com/go/api/admin/scms/scmName' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v3+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "e064ca0fe5d8a39602e19666454b8d77"' \
      -X PUT \
      -d '{
            "id": "scmID",
            "name": "scmName",
            "auto_update": true,
            "plugin_metadata":
            {
              "id": "github.pr",
              "version": "1"
            },
            "configuration": [
            {
              "key": "url",
              "value": "git@github.com:sample/example.git"
            },
            {
              "key": "username",
              "value": "admin"
            },
            {
              "key": "password",
              "encrypted_value": "aSdiFgRRZ6A="
            }
            ]
          }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "e89135b38ddbcd9380c83eb524647bdd"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/scms/scmName"
    },
    "doc": {
      "href": "https://api.gocd.org/#scms"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/scms/:material_name"
    }
  },
  "id": "scmID",
  "name": "scmName",
  "plugin_metadata": {
    "id": "github.pr",
    "version": "1"
  },
  "auto_update": true,
  "configuration": [
    {
      "key": "url",
      "value": "https://github.com/sample/example.git"
    },
    {
      "key": "username",
      "value": "admin"
    },
    {
      "key": "password",
      "encrypted_value": "aSdiFgRRZ6A="
    }
  ]
}

Update global scm configuration for specified scm name.

Updated to version v3 since v20.3.0.

Available since v16.7.0.

HTTP Request

PUT /go/api/admin/scms/:material_name

Returns

The updated SCM object.

Delete a Pluggable SCM material

$ curl -i 'https://ci.example.com/go/api/admin/scms/pluggable.scm.material.name' \
      -u 'username:password' \
      -H 'Accept:application/vnd.go.cd.v3+json' \
      -X DELETE

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "05548388f7ef5042cd39f7fe42e85735"

{
  "message": "Scm with name 'pluggable.scm.material.name' was deleted successfully!"
}

Delete the SCM object with the specified name.

Updated to version v3 since v20.3.0.

Available since v19.8.0.

HTTP Request

DELETE /go/api/admin/scms/:material_name

Returns

A message if the scm is deleted or not.

Usages of a pluggable SCM material

$ curl -i 'https://ci.example.com/go/api/admin/scms/pluggable.scm.material.name/usages' \
      -u 'username:password' \
      -H 'Accept:application/vnd.go.cd.v3+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json;charset=utf-8
{
  "_links": {
    "self": {
      "href": "http://test.host/go/api/admin/scms/pluggable.scm.material.name/usages"
    },
    "doc": {
      "href": "https://api.gocd.org/current/#scms"
    },
    "find": {
      "href": "http://test.host/go/api/admin/scms/:material_name/usages"
    }
  },
  "usages": [
    {
      "group": "grp1",
      "pipeline": "pipeline1"
    },
    {
      "group": "grp2",
      "pipeline": "pipeline2"
    }
  ]
}

Gets the list of pipelines and groups which use the specified pluggable SCM as a material.

Available since v20.3.0.

HTTP Request

GET /go/api/admin/scms/:material_name/usages

Returns

A list of usage objects.

Pluggable SCM usage object

{
  "pipeline": "pipeline_name",
  "group": "grp_name"
}

Attribute Type Description
group String The group to which the pipeline belongs to.
pipeline String The name of the pipeline which uses the pluggable SCM as a material.

Plugin Settings

The plugin settings API allows admin users with to manage the settings of an installed plugin. The plugin settings are currently stored and retrieved from the database for a plugin.

The plugin settings object

Available since v17.8.0.

Attribute Type Description
plugin_id String Plugin unique identifier.
configuration Object List of configuration required to configure the plugin settings.

The plugin settings property object

{
  "configuration": [
    {
      "key": "username",
      "value": "admin"
    },
    {
      "key": "password",
      "encrypted_value": "1f3rrs9uhn63hd"
    },
    {
      "key": "url",
      "value": "https://github.com/sample/example.git"
    }
  ]
}

Attribute Type Description
key String The name of the property key.
value String The value of the property. You MUST specify one of value or encrypted_value.
encrypted_value String The encrypted value of the property. You MUST specify one of value or encrypted_value.

Get Plugin Settings

$ curl 'https://ci.example.com/go/api/admin/plugin_settings/github.oauth.login' \
      -u 'username:password' \
      -H 'Accept:application/vnd.go.cd.v1+json' \
      -i

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "05548388f7ef5042cd39f7fe42e85735"

{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/plugin_settings/github.oauth.login"
    },
    "doc": {
      "href": "https://api.gocd.org/#plugin-settings"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/plugin_settings/:plugin_id"
    }
  },
  "plugin_id": "github.oauth.login",
  "configuration": [
    {
      "key": "consumer_key",
      "value": "consumerkey"
    },
    {
      "key": "consumer_secret",
      "value": "consumersecret"
    },
    {
      "key": "password",
      "encrypted_value": "aSdiFgRRZ6A="
    },
    {
      "key": "server_base_url",
      "value": "https://ci.example.com"
    }
  ]
}

Gets the stored plugin settings for the specified plugin id, if the plugin is configured.

Available since v17.9.0.

HTTP Request

GET /go/api/admin/plugin_settings/:plugin_id

Returns

A Plugin Settings object or an error 404 if the plugin was not yet configured.

Create Plugin Settings

$   curl -i 'https://ci.example.com/go/api/admin/plugin_settings' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
  "plugin_id": "github.oauth.login",
  "configuration": [
    {
      "key": "server_base_url",
      "value": "https://ci.example.com"
    },
    {
      "key": "consumer_key",
      "value": "consumerkey"
    },
    {
      "key": "consumer_secret",
      "value": "consumersecret"
    },
    {
      "key": "password",
      "encrypted_value": "aSdiFgRRZ6A="
    }
  ]
}'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/plugin_settings/github.oauth.login"
    },
    "doc": {
      "href": "https://api.gocd.org/#plugin-settings"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/plugin_settings/:plugin_id"
    }
  },
  "plugin_id": "github.oauth.login",
  "configuration": [
    {
      "key": "server_base_url",
      "value": "https://ci.example.com"
    },
    {
      "key": "consumer_key",
      "value": "consumerkey"
    },
    {
      "key": "consumer_secret",
      "value": "consumersecret"
    },
    {
      "key": "password",
      "encrypted_value": "aSdiFgRRZ6A="
    }
  ]
}

Create plugin settings for a plugin based on user inputs. The keys are dependent on the plugin to be configured. Use the result of Get plugin info to find the possible keys under extensions/plugin_settings/configurations.

Available since v17.9.0.

HTTP Request

POST /go/api/admin/plugin_settings

Returns

A new Plugin Settings object.

Update Plugin Settings

$ curl 'https://ci.example.com/go/api/admin/plugin_settings/github.oauth.login' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "05548388f7ef5042cd39f7fe42e85735"' \
-X PUT -d '{
  "plugin_id": "github.oauth.login",
  "configuration": [
    {
      "key": "server_base_url",
      "value": "https://ci.example.com"
    },
    {
      "key": "consumer_key",
      "value": "updated_consumer_key"
    },
    {
      "key": "consumer_secret",
      "value": "consumersecret"
    },
    {
      "key": "password",
      "encrypted_value": "aSdiFgRRZ6A="
    }
  ]
}'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "e89135b38ddbcd9380c83eb524647bdd"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/plugin_settings/github.oauth.login"
    },
    "doc": {
      "href": "https://api.gocd.org/#plugin-settings"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/plugin_settings/:plugin_id"
    }
  },
  "plugin_id": "github.oauth.login",
  "configuration": [
    {
      "key": "server_base_url",
      "value": "https://ci.example.com"
    },
    {
      "key": "consumer_key",
      "value": "updated_consumer_key"
    },
    {
      "key": "consumer_secret",
      "value": "consumersecret"
    },
    {
      "key": "password",
      "encrypted_value": "aSdiFgRRZ6A="
    }
  ]
}

Updates plugin settings for the specified plugin id.

Available since v17.9.0.

HTTP Request

PUT /go/api/admin/plugin_settings/:plugin_id

Returns

The updated Plugin Settings object.

Roles

The roles API allows admin users to manage roles or plugin roles. The plugin roles will later be used by the plugin to authorize user for GoCD server.

In order to create Plugin Role authorization configuration is required.

The role object

Available since v17.5.0.

Attribute Type Description
name String The name of the role.
type String Type of the role. Use gocd to create core role and plugin to create plugin role.
attributes Object Attributes are used to describes the configuration for gocd role or plugin role.
policy Object Policy is fine-grained permissions attached to the users belonging to the current role. Since v19.11.0.

The permission object

Attribute Type Description
permission String The type of permission which can be either allow or deny.
action String The action that is being controlled via this rule. Can be one of *, view, administer.
type String The type of entity that the rule is applied on. Can be one of *, environment.
resource String The actual entity on which the rule is applied. Resource should be the name of the entity or a wildcard which matches one or more entities.

The GoCD role attributes

Available since v17.5.0.

Attribute Type Description
users Array The list of users belongs to the role.

The plugin role attributes

Available since v17.5.0.

Attribute Type Description
auth_config_id String The authorization configuration identifier.
properties Array The list of configuration properties that represent the configuration of this plugin role.

Get all roles

$ curl 'https://ci.example.com/go/api/admin/security/roles' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v3+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/security/roles"
    },
    "doc": {
      "href": "https://api.gocd.org/#roles"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
    }
  },
  "_embedded": {
    "roles": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/security/roles/spacetiger"
          },
          "doc": {
            "href": "https://api.gocd.org/#roles"
          },
          "find": {
            "href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
          }
        },
        "name": "spacetiger",
        "type": "gocd",
        "attributes": {
          "users": ["alice", "bob", "robin"]
        },
        "policy": [
          {
            "permission":"allow",
            "action":"view",
            "type":"environment",
            "resource":"env_A_*"
          }]
      },
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/security/roles/blackbird"
          },
          "doc": {
            "href": "https://api.gocd.org/#roles"
          },
          "find": {
            "href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
          }
        },
        "name": "blackbird",
        "type": "plugin",
        "attributes": {
          "auth_config_id": "ldap",
          "properties": [
            {
              "key": "UserGroupMembershipAttribute",
              "value": "memberOf"
            },
            {
              "key": "GroupIdentifiers",
              "value": "ou=admins,ou=groups,ou=system,dc=example,dc=com"
            }
          ]
        },
        "policy": [
          {
            "permission":"allow",
            "action":"view",
            "type":"environment",
            "resource":"env_B_*"
          }]
      }
    ]
  }
}

Lists all available roles which includes GoCD role and plugin role.

Updated to version v3 since v19.11.0.

Available since v17.5.0.

HTTP Request

GET /go/api/admin/security/roles

Returns

An array of role object.

Get all roles by type

Get all roles by type

$ curl 'https://ci.example.com/go/api/admin/security/roles?type=gocd' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v3+json'
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/security/roles"
    },
    "doc": {
      "href": "https://api.gocd.org/#roles"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
    }
  },
  "_embedded": {
    "roles": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/security/roles/spacetiger"
          },
          "doc": {
            "href": "https://api.gocd.org/#roles"
          },
          "find": {
            "href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
          }
        },
        "name": "spacetiger",
        "type": "gocd",
        "attributes": {
          "users": ["alice", "bob", "robin"]
        },
        "policy": [
          {
            "permission":"allow",
            "action":"view",
            "type":"environment",
            "resource":"env_A_*"
          }]
      }
    ]
  }
}

List all available roles of specified type.

Updated to version v3 since v19.11.0.

Available since v17.5.0.

HTTP Request

GET /go/api/admin/security/roles?type=:role_type

Returns

An array of role object.

Get a role

$ curl 'https://ci.example.com/go/api/admin/security/roles/blackbird' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v3+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/security/roles/blackbird"
    },
    "doc": {
      "href": "https://api.gocd.org/#roles"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
    }
  },
  "name": "blackbird",
  "auth_config_id": "ldap",
  "properties": [
    {
      "key": "MemberOf",
      "value": "ou=blackbird,ou=area51,dc=example,dc=com"
    }
  ],
  "policy": [
    {
      "permission":"allow",
      "action":"view",
      "type":"environment",
      "resource":"env_A_*"
    }]
}

Gets role for specified role name.

Updated to version v3 since v19.11.0.

Available since v17.5.0.

HTTP Request

GET /go/api/admin/security/roles/:role_name

Returns

An array of role object.

Create a GoCD role

$ curl 'https://ci.example.com/go/api/admin/security/roles' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v3+json' \
      -H 'Content-Type: application/json' \
      -X POST -d '{
         "name": "new-role",
         "type": "gocd",
         "attributes" : {
          "users": ["bob"]
         },
        "policy": [
          {
            "permission":"allow",
            "action":"view",
            "type":"environment",
            "resource":"env_A_*"
          }]
        }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/security/roles/new-role"
    },
    "doc": {
      "href": "https://api.gocd.org/#roles"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
    }
  },
  "name": "new-role",
  "type": "gocd",
  "attributes": {
    "users": ["bob"]
  },
  "policy": [
    {
      "permission":"allow",
      "action":"view",
      "type":"environment",
      "resource":"env_A_*"
    }]
}

Create a GoCD role. A GoCD role is a group of users having same permissions in GoCD.

Updated to version v3 since v19.11.0.

Available since v17.5.0.

HTTP Request

POST /go/api/admin/security/roles

Returns

The role object.

Create a plugin role

$ curl 'https://ci.example.com/go/api/admin/security/roles' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v3+json' \
      -H 'Content-Type: application/json' \
      -X POST -d '{
        "name": "new-plugin-role",
        "type": "plugin",
        "attributes": {
          "auth_config_id": "ldap",
          "properties": [
            {
              "key": "UserGroupMembershipAttribute",
              "value": "memberOf"
            },
            {
              "key": "GroupIdentifiers",
              "value": "ou=devs,ou=groups,ou=system,dc=example,dc=com"
            }
          ]
        },
        "policy": [
          {
            "permission":"allow",
            "action":"view",
            "type":"environment",
            "resource":"env_A_*"
          }]
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/security/roles/blackbird1"
    },
    "doc": {
      "href": "https://api.gocd.org/#roles"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
    }
  },
  "name": "blackbird1",
  "type": "plugin",
  "attributes": {
    "auth_config_id": "ldap",
    "properties": [
      {
        "key": "UserGroupMembershipAttribute",
        "value": "memberOf"
      },
      {
        "key": "GroupIdentifiers",
        "value": "ou=admins,ou=groups,ou=system,dc=example,dc=com"
      }
    ]
  },
  "policy": [
    {
      "permission":"allow",
      "action":"view",
      "type":"environment",
      "resource":"env_A_*"
    }]
}

Plugin role is used to authorize user against external authorization server using authorization plugin.

Prerequisite to create plugin role,

  1. Install authorization plugin with can_authorize capability.
  2. Create authorization configuration.

Updated to version v3 since v19.11.0.

Available since v17.5.0.

HTTP Request

POST /go/api/admin/security/roles

Returns

The role object.

Update a role

Update attributes of the role identified by the specified role name.

$ curl 'https://ci.example.com/go/api/admin/security/roles/spacetiger' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v3+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"' \
      -X PUT \
      -d '{
        "name": "spacetiger",
        "type": "gocd",
        "attributes": {
          "users": ["alice"]
        },
        "policy": [
          {
            "permission":"allow",
            "action":"view",
            "type":"environment",
            "resource":"env_A*"
          }]
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "61406622382e51c2079c11dcbdb978fb"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/security/roles/spacetiger"
    },
    "doc": {
      "href": "https://api.gocd.org/#roles"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
    }
  },
  "name": "spacetiger",
  "type": "gocd",
  "attributes": {
    "users": [ "alice" ]
  },
  "policy": [
    {
      "permission":"allow",
      "action":"view",
      "type":"environment",
      "resource":"env_A*"
    }]
}

Updated to version v3 since v19.11.0.

Available since v17.5.0.

HTTP Request

PUT /go/api/admin/security/roles/:role_name

Returns

The role object.

Delete a role

$ curl 'https://ci.example.com/go/api/admin/security/roles/blackbird' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v3+json' \
      -X DELETE

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
  "message": "The plugin role config 'blackbird' was deleted successfully."
}

Deletes the role.

Updated to version v3 since v19.11.0.

Available since v17.5.0.

HTTP Request

DELETE /go/api/admin/security/roles/:role_name

Returns

A message if the role is deleted or not.

Bulk update roles

$ curl 'https://ci.example.com/go/api/admin/security/roles' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v3+json' \
      -X PATCH \
      -d '{
      "operations": [
        {
          "role": "role1",
          "users": {
            "add": [
              "user1",
              "user2"
            ],
            "remove": [
              "user3",
              "user4"
            ]
          }
        },
        {
          "role": "role2",
          "users": {
            "add": [
              "user2"
            ]
          }
        }
      ]
    }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/security/roles"
    },
    "doc": {
      "href": "https://api.gocd.org/#roles"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
    }
  },
  "_embedded": {
    "roles": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/security/roles/role1"
          },
          "doc": {
            "href": "https://api.gocd.org/#roles"
          },
          "find": {
            "href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
          }
        },
        "name": "role1",
        "type": "gocd",
        "attributes": {
          "users": ["user3", "user4", "robin"]
        }
      },
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/security/roles/role2"
          },
          "doc": {
            "href": "https://api.gocd.org/#roles"
          },
          "find": {
            "href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
          }
        },
        "name": "role2",
        "type": "gocd",
        "attributes": {
          "users": ["alice", "user2"]
        }
      }
    ]
  }
}

Bulk update roles.

Updated to version v3 since v19.11.0.

Available since v19.1.0.

HTTP Request

PATCH /go/api/admin/security/roles

Attribute Type Description
operations Array The bulk update operations performed on the set of roles.

Returns

An array of role object of type ‘gocd’.

The bulk update operation attributes

{
  "role": "role1",
  "users": {
    "add": [
      "User1",
      "User2"
    ],
    "remove": [
      "User3",
      "User4"
    ]
  }
}

Attribute Type Description
role String The role name which needs to be updated.
users Object The users to be added/removed for a given role.

The users to be updated

{
  "add": [
    "User1",
    "User2"
  ],
  "remove": [
    "User3",
    "User4"
  ]
}

Attribute Type Description
add Array The list of users that needs to be added to the role.
remove Array The list of users that needs to be removed from the role.

Secret Configs

The secret configs API allows users with admin privileges to configure external Secret Managers to lookup for secrets.

The secret config object

Available since v19.6.0.

Attribute Type Description
id String The identifier of the secret config.
pluginId String The identifier of the plugin to which current secret config belongs.
configuration Array The list of configuration properties that represent the configuration of this secret config.
rules Array The list of rules, which allows restricting the usage of the secret config. Referring to the secret config from other parts of configuration is denied by default, an explicit rule should be added to allow a specific resource to refer the secret config.
description String The description for this secret config.

The Rule object

Available since v19.6.0.

Attribute Type Description
directive String The type of rule which can be either allow or deny.
action String The action that is being controlled via this rule. Only refer is supported as of now.
type String The type of entity that the rule is applied on. Can be one of environment, pipeline_group, pluggable_scm, package_repository.
resource String The actual entity on which the rule is applied. Resource should be the name of the entity or a wildcard which matches one or more entities.

Get all secret configs

$ curl 'https://ci.example.com/go/api/admin/secret_configs' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "32628084ef10b0c82a55f8f2f867d8d0"
{
  "_links" : {
    "self" : {
      "href" : "https://ci.example.com/go/api/admin/secret_configs"
    },
    "doc" : {
      "href" : "https://api.gocd.org/#secret-configs"
    },
    "find" : {
      "href" : "https://ci.example.com/go/api/admin/secret_configs/:config_id"
    }
  },
  "_embedded" : {
    "secret_configs" : [ {
      "_links" : {
        "self" : {
          "href" : "https://ci.example.com/go/api/admin/secret_configs/demo"
        },
        "doc" : {
          "href" : "https://api.gocd.org/#secret-configs"
        },
        "find" : {
          "href" : "https://ci.example.com/go/api/admin/secret_configs/:config_id"
        }
      },
      "id" : "demo",
      "plugin_id" : "cd.go.secrets.file-based-plugin",
      "description" : "",
      "properties" : [ {
        "key" : "SecretsFilePath",
        "value" : "path/to/secret/file.db"
      } ],
      "rules" : [ {
        "directive" : "allow",
        "action" : "refer",
        "type" : "pipeline_group",
        "resource" : "first"
      } ]
    } ]
  }
}

Lists all available secret configurations.

Updated to version v2 since v20.8.0.

Available since v19.6.0.

HTTP Request

GET /go/api/admin/secret_configs

Returns

An array of secret configs.

Get a secret config

$ curl 'https://ci.example.com/go/api/admin/secret_configs/demo' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "465f3520fa02e65a05844a5a27f83393"
{
  "_links" : {
    "self" : {
      "href" : "https://ci.example.com/go/api/admin/secret_configs/demo"
    },
    "doc" : {
      "href" : "https://api.gocd.org/#secret-configs"
    },
    "find" : {
      "href" : "https://ci.example.com/go/api/admin/secret_configs/:config_id"
    }
  },
  "id" : "demo",
  "plugin_id" : "cd.go.secrets.file-based-plugin",
  "description" : "",
  "properties" : [ {
    "key" : "SecretsFilePath",
    "value" : "path/to/secret/file.db"
  } ],
  "rules" : [ {
    "directive" : "allow",
    "action" : "refer",
    "type" : "pipeline_group",
    "resource" : "first"
  } ]
}

Gets the secret config for the specified id.

Updated to version v2 since v20.8.0.

Available since v19.6.0.

HTTP Request

GET /go/api/admin/secret_configs/:id

Returns

The secret config object.

Create a secret config

$ curl 'https://ci.example.com/go/api/admin/secret_configs' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json' \
      -H 'Content-Type: application/json' \
      -X POST -d '{
        "id" : "demo",
        "plugin_id" : "cd.go.secrets.file-based-plugin",
        "description" : "",
        "properties" : [ {
          "key" : "SecretsFilePath",
          "value" : "/path/to/secret/file.db"
        }],
        "rules":[
          {
            "directive":"allow",
            "action":"refer",
            "type":"pipeline_group",
            "resource":"first"
          }
        ]
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "f64e700e7d94e6bc36fc56539cfe993d"
{
  "_links" : {
    "self" : {
      "href" : "https://ci.example.com/go/api/admin/secret_configs/secret-test"
    },
    "doc" : {
      "href" : "https://api.gocd.org/#secret-configs"
    },
    "find" : {
      "href" : "https://ci.example.com/go/api/admin/secret_configs/:config_id"
    }
  },
  "id" : "demo",
  "plugin_id" : "cd.go.secrets.file-based-plugin",
  "description" : "",
  "properties" : [ {
    "key" : "SecretsFilePath",
    "value" : "path/to/secret/file.db"
  } ],
  "rules" : [ {
    "directive" : "allow",
    "action" : "refer",
    "type" : "pipeline_group",
    "resource" : "first"
  } ]
}

Creates a secret config.

Updated to version v2 since v20.8.0.

Available since v19.6.0.

HTTP Request

POST /go/api/admin/secret_configs

Returns

The secret config object.

Update a secret config

$ curl 'https://ci.example.com/go/api/admin/secret_configs/secret-test' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "465f3520fa02e65a05844a5a27f83393"' \
      -X PUT \
      -d '{
        "id":"secret-test"
        "plugin_id":"cd.go.secrets.file-based-plugin",
        "properties": [
          {
            "key": "SecretsFilePath",
            "value": "updated/path/to/secret/file.db"
          }
        ],
        "rules":[
          {
            "directive":"allow",
            "action":"refer",
            "type":"pipeline_group",
            "resource":"first*"
          }
        ]
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "3b55fd5294b16a55228de0f9eef98ecb"
{
  "_links" : {
    "self" : {
      "href" : "https://ci.example.com/go/api/admin/secret_configs/secret-test"
    },
    "doc" : {
      "href" : "https://api.gocd.org/#secret-configs"
    },
    "find" : {
      "href" : "https://ci.example.com/go/api/admin/secret_configs/:config_id"
    }
  },
  "id" : "secret-test",
  "plugin_id" : "cd.go.secrets.file-based-plugin",
  "description" : "",
  "properties" : [ {
    "key" : "SecretsFilePath",
    "value" : "updated/path/to/secret/file.db"
  } ],
  "rules" : [ {
    "directive" : "allow",
    "action" : "refer",
    "type" : "pipeline_group",
    "resource" : "first*"
  } ]
}

Update some attributes of a secret config.

Updated to version v2 since v20.8.0.

Available since v19.6.0.

HTTP Request

PUT /go/api/admin/secret_configs/:id

Returns

The updated secret_config object.

Delete a secret config.

$ curl 'https://ci.example.com/go/api/admin/secret_configs/secret-test' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json' \
      -X DELETE

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
  "message": "Secret config with id 'secret-test' was deleted successfully!"
}

Deletes the config.

Updated to version v2 since v20.8.0.

Available since v19.6.0.

HTTP Request

DELETE /go/api/admin/secret_configs/:id

Returns

A message if the secret config is deleted or not.

Siteurls Config

The site urls config API allows admins to setup the server site URL and secure server site URL.

The Site Urls Config Object

Available since v19.11.0.

Attribute Type Description
siteUrl String The site URL will be used by GoCD Server to generate links for emails, feeds, etc. Format: [protocol]://[host]:[port].The protocol can be HTTP ot HTTPs.You need to define the [port] in case GoCD uses a non-standard port.
secureSiteUrl String If you wish that your primary site URL be HTTP, but still want to have HTTPS endpoints for the features that require SSL, you can specify this attribute with a value of the base HTTPS URL. Format: https://[host]:[port].

Get SiteUrls Config

$ curl 'https://ci.example.com/go/api/admin/config/server/site_urls' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "doc": {
      "href": "https://api.gocd.org/current/#siteurls-config"
    },
    "self": {
      "href": "http://ci.example.com/go/api/admin/config/server/site_urls"
    }
  },
  "site_url" : "http://foo.com",
  "secure_site_url" : "https://foo.com"
}

Available since v19.11.0.

HTTP Request

GET /go/api/admin/config/server/site_urls

Returns

A siteurls config object.

Create or Update siteUrls Config

$ curl 'https://ci.example.com/go/api/admin/config/server/site_urls' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{
            "site_url" : "http://siteUrl.com",
            "secure_site_url" : "https://secureSiteUrl.com"
          }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links" : {
    "doc" : {
      "href" : "https://api.gocd.org/current/#siteurls-config"
    },
    "self" : {
      "href" : "http://ci.example.com/go/api/admin/config/server/site_urls"
    }
  },
  "site_url" : "http://siteUrl.com",
  "secure_site_url" : "https://secureSiteUrl.com"
}

Available since v19.11.0.

HTTP Request

POST /go/api/admin/config/server/site_urls

PUT /go/api/admin/config/server/site_urls

Returns

A siteurls config object.

System Admins

The API allows admin users to manage System Admins.

The system admins object

Available since v18.8.0.

Attribute Type Description
roles Array The list of roles having system admin privileges.
users Array The list of users having system admin privileges.

Get all system admins

$ curl 'https://ci.example.com/go/api/admin/security/system_admins' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
  "_links" : {
    "doc" : {
      "href" : "https://api.gocd.org/#system_admins"
    },
    "self" : {
      "href" : "https://ci.example.com/go/api/admin/security/system_admins"
    }
  },
  "roles" : [ "manager"],
  "users" : [ "john" , "maria"]
}

Lists all system admins which includes users and roles.

Available since v18.8.0.

HTTP Request

GET /go/api/admin/security/system_admins

Returns

An array of roles and users having system admin privileges.

Update system admins

Update system admins and replace the system admins with roles and users in the request. The list of roles in the update request must be present in roles config.

$ curl 'https://ci.example.com/go/api/admin/security/system_admins' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"' \
      -X PUT \
      -d '{
            "users": ["bob", "jdoe", "john"],
            "roles": ["manager"]
          }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "61406622382e51c2079c11dcbdb978fb"
{
  "_links" : {
    "doc" : {
      "href" : "https://api.gocd.org/#system_admins"
    },
    "self" : {
      "href" : "https://ci.example.com/go/api/admin/security/system_admins"
    }
  },
  "roles" : [ "manager" ],
  "users" : [ "bob" , "jdoe", "john"]
}

Available since v18.8.0.

HTTP Request

PUT /go/api/admin/security/system_admins

Returns

The updated system admins object.

Bulk update system admins

curl 'https://ci.example.com/go/api/admin/security/system_admins' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json' \
      -H 'Content-Type: application/json' \
      -X PATCH \
      -d '{
       "operations": {
         "users": {
           "add": ["user1", "user2"],
           "remove": ["admin"]
         },
         "roles": {
           "add": ["xyz"],
           "remove": ["role1"]
         }
       }
}'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
    "_links": {
        "doc": {
            "href": "https://api.gocd.org/#system_admins"
        },
        "self": {
            "href": "http://localhost:8153/go/api/admin/security/system_admins"
        }
    },
    "roles": [
        "xyz"
    ],
    "users": [
        "user1",
        "user2"
    ]
}

Bulk update System Admins.

Available since v19.1.0.

HTTP Request

PATCH /go/api/admin/security/system_admins

Attribute Type Description
operations Object The bulk update operation performed on system admin.

Returns

The updated system admins object.

The bulk update operation attributes

{
  "users": {
    "add": [
      "User1",
      "User2"
    ],
    "remove": [
      "User3",
      "User4"
    ]
  },
  "roles": {
    "add": [
      "role1",
      "role2"
    ],
    "remove": [
      "role3",
      "role4"
    ]
  }
}

Attribute Type Description
users Object The users to be added/removed.
roles Object The roles to be added/removed.

The users to be updated

{
  "add": [
    "User1",
    "User2"
  ],
  "remove": [
    "User3",
    "User4"
  ]
}

Attribute Type Description
add Array The list of users that needs to be made system admins.
remove Array The list of users that needs to be revoked system admin access.

The roles to be updated

{
  "add": [
    "role11",
    "role2"
  ],
  "remove": [
    "role3",
    "role4"
  ]
}

Attribute Type Description
add Array The list of roles that needs to be made system admins.
remove Array The list of roles that needs to be revoked system admin access.

Template Config

The template config API allows users with administrator role to manage template config.

The shallow template config object

Available since v16.10.0.

Attribute Type Description
name String The name of the template.
can_edit Boolean This property specifies whether the current user can edit the template configuration.
can_administer Boolean This property specifies whether the current user can administer the template.
pipelines Array The list of pipelines using the current template.

The shallow pipeline config object

Available since v16.10.0.

Attribute Type Description
name String The name of the pipeline using the current template.
can_administer Boolean This property specifies whether the current user can administer the pipeline.

The template config object

Available since v16.10.0.

Attribute Type Description
name String The name of the template.
stages Array The list of stages. You MUST specify atleast one stage in stages, or template.

The template authorization object

Available since v18.2.0.

Attribute Type Description
all_group_admins_are_view_users Boolean This property specifies whether the group admins are allowed to view the template configuration.
admin Object The users and roles that have admin permissions to edit the template configuration.
view Object The explicitly configured users and roles that have permissions to view the template configuration.

The authorization object

{
  "roles": [
    "role1",
    "role2"
  ],
  "users": [
    "user1",
    "user2"
  ]
}

Attribute Type Description
users Array List of user names that should be granted the specified permission.
roles Array List of roles that should be granted the specified permission.

Get all templates

$ curl 'https://ci.example.com/go/api/admin/templates' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v7+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/templates"
    },
    "doc": {
      "href": "https://api.gocd.org/#template-config"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/templates/:template_name"
    }
  },
  "_embedded": {
    "templates": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/templates/template1"
          },
          "doc": {
            "href": "https://api.gocd.org/#template-config"
          },
          "find": {
            "href": "https://ci.example.com/go/api/admin/templates/:template_name"
          }
        },
        "name": "template1",
        "can_edit" : true,
        "can_administer" : true,
        "_embedded": {
          "pipelines": [
            {
              "_links": {
                "self": {
                  "href": "https://ci.example.com/go/api/admin/pipelines/up42"
                },
                "doc": {
                  "href": "https://api.gocd.org/#pipeline-config"
                },
                "find": {
                  "href": "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
                }
              },
              "name": "up42",
              "can_administer" : true
            }
          ]
        }
      }
    ]
  }
}

Lists all available templates with the associated pipelines’ names.

Updated to version v7 since v20.2.0.

Available since v16.10.0.

HTTP Request

GET /go/api/admin/templates

Returns

A list of template objects

Get template config

$ curl 'https://ci.example.com/go/api/admin/templates/template.name' \
      -u 'username:password' \
      -H 'Accept:application/vnd.go.cd.v7+json' \
      -i

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
ETag: "05548388f7ef5042cd39f7fe42e85735"

{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/templates/template.name"
    },
    "doc": {
      "href": "https://api.gocd.org/#template-config"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/templates/:template_name"
    }
  },
  "name" : "template.name",
  "stages" : [ {
    "name" : "defaultStage",
    "fetch_materials" : true,
    "clean_working_directory" : false,
    "never_cleanup_artifacts" : false,
    "approval" : {
      "type" : "success",
      "authorization" : {
        "roles" : [ ],
        "users" : [ ]
      }
    },
    "environment_variables" : [ ],
    "jobs" : [ {
      "name" : "defaultJob",
      "run_instance_count" : null,
      "timeout" : null,
      "environment_variables" : [ ],
      "resources" : [ ],
      "tasks" : [ {
        "type" : "exec",
        "attributes" : {
          "run_if" : [ "passed" ],
          "command" : "ls",
          "args" : ""
        }
      } ],
      "tabs" : [ ],
      "artifacts" : [ {
        "type" : "external",
        "artifact_id" : "docker-image",
        "store_id" : "dockerhub",
        "configuration" : [ {
          "key" : "Image",
          "value" : "gocd/gocd-server"
        }, {
          "key" : "Tag",
          "value" : "v${GO_PIPELINE_LABEL}"
        } ]
      } ]
    } ]
  }, {
    "name" : "s2",
    "fetch_materials" : true,
    "clean_working_directory" : false,
    "never_cleanup_artifacts" : false,
    "approval" : {
      "type" : "success",
      "authorization" : {
        "roles" : [ ],
        "users" : [ ]
      }
    },
    "environment_variables" : [ ],
    "jobs" : [ {
      "name" : "j2",
      "run_instance_count" : null,
      "timeout" : null,
      "environment_variables" : [ ],
      "resources" : [ ],
      "tasks" : [ {
        "type" : "fetch",
        "attributes" : {
          "origin" : "external",
          "pipeline" : "",
          "stage" : "defaultStage",
          "job" : "defaultJob",
          "run_if" : [ ],
          "artifact_id" : "docker-image"
        }
      } ],
      "tabs" : [ ],
      "artifacts" : [ ]
    } ]
  } ]
}

Gets template config for specified template name.

Updated to version v7 since v20.2.0.

Available since v16.10.0.

HTTP Request

GET /go/api/admin/templates/:template_name

Returns

A template object

Create template config

$   curl 'https://ci.example.com/go/api/admin/templates' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v7+json' \
      -H 'Content-Type: application/json' \
      -X POST -d '{
        "name": "template",
        "stages": [
          {
            "name": "defaultStage",
            "fetch_materials": true,
            "clean_working_directory": false,
            "never_cleanup_artifacts": false,
            "environment_variables": [],
            "jobs": [
              {
                "name": "defaultJob",
                "run_instance_count": null,
                "elastic_profile_id": "elastic_profile_id",
                "timeout": 0,
                "environment_variables": [],
                "resources": [],
                "tasks": [
                  {
                    "type": "exec",
                    "attributes": {
                      "run_if": [
                        "passed"
                      ],
                      "command": "ls",
                      "working_directory": null
                    }
                  }
                ],
                "artifacts": [
                  {
                    "type": "external",
                    "artifact_id": "docker-image",
                    "store_id": "dockerhub",
                    "configuration": [
                      {
                        "key": "Image",
                        "value": "goose"
                      },
                      {
                        "key": "Tag",
                        "value": "v${GO_PIPELINE_LABEL}"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "name": "s2",
            "jobs": [
              {
                "name": "j2",
                "tasks": [
                  {
                    "type": "fetch",
                    "attributes": {
                      "origin": "external",
                      "pipeline": "",
                      "stage": "defaultStage",
                      "job": "defaultJob",
                      "artifact_id": "docker-image"
                    }
                  }
                ]
              }
            ]
          }
        ]
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/templates/template"
    },
    "doc": {
      "href": "https://api.gocd.org/#template-config"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/templates/:template_name"
    }
  },
  "name" : "template",
  "stages" : [ {
    "name" : "defaultStage",
    "fetch_materials" : true,
    "clean_working_directory" : false,
    "never_cleanup_artifacts" : false,
    "approval" : {
      "type" : "success",
      "authorization" : {
        "roles" : [ ],
        "users" : [ ]
      }
    },
    "environment_variables" : [ ],
    "jobs" : [ {
      "name" : "defaultJob",
      "run_instance_count" : null,
      "timeout" : null,
      "environment_variables" : [ ],
      "resources" : [ ],
      "tasks" : [ {
        "type" : "exec",
        "attributes" : {
          "run_if" : [ "passed" ],
          "command" : "ls",
          "args" : ""
        }
      } ],
      "tabs" : [ ],
      "artifacts" : [ {
        "type" : "external",
        "artifact_id" : "docker-image",
        "store_id" : "dockerhub",
        "configuration" : [ {
          "key" : "Image",
          "value" : "gocd/gocd-server"
        }, {
          "key" : "Tag",
          "value" : "v${GO_PIPELINE_LABEL}"
        } ]
      } ]
    } ]
  }, {
    "name" : "s2",
    "fetch_materials" : true,
    "clean_working_directory" : false,
    "never_cleanup_artifacts" : false,
    "approval" : {
      "type" : "success",
      "authorization" : {
        "roles" : [ ],
        "users" : [ ]
      }
    },
    "environment_variables" : [ ],
    "jobs" : [ {
      "name" : "j2",
      "run_instance_count" : null,
      "timeout" : null,
      "environment_variables" : [ ],
      "resources" : [ ],
      "tasks" : [ {
        "type" : "fetch",
        "attributes" : {
          "origin" : "external",
          "pipeline" : "",
          "stage" : "defaultStage",
          "job" : "defaultJob",
          "run_if" : [ ],
          "artifact_id" : "docker-image"
        }
      } ],
      "tabs" : [ ],
      "artifacts" : [ ]
    } ]
  } ]
}

Creates a template config object.

Updated to version v7 since v20.2.0.

Available since v16.10.0.

HTTP Request

POST /go/api/admin/templates

Returns

A new template object.

Edit template config

$ curl 'https://ci.example.com/go/api/admin/templates/template' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v7+json' \
      -H 'If-Match: "05548388f7ef5042cd39f7fe42e85735"' \
      -H 'Content-Type: application/json' \
      -X PUT -d '{
        "name": "template",
        "stages": [
          {
            "name": "defaultStage",
            "fetch_materials": true,
            "clean_working_directory": false,
            "never_cleanup_artifacts": false,
            "environment_variables": [],
            "jobs": [
              {
                "name": "defaultJob",
                "run_instance_count": null,
                "elastic_profile_id": "elastic_profile_id",
                "timeout": 0,
                "environment_variables": [],
                "resources": [],
                "tasks": [
                  {
                    "type": "exec",
                    "attributes": {
                      "run_if": [
                        "passed"
                      ],
                      "command": "ls",
                      "working_directory": null
                    }
                  }
                ],
                "artifacts": [
                  {
                    "type": "external",
                    "artifact_id": "docker-image",
                    "store_id": "dockerhub",
                    "configuration": [
                      {
                        "key": "Image",
                        "value": "goose"
                      },
                      {
                        "key": "Tag",
                        "value": "v${GO_PIPELINE_LABEL}"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "name": "s2",
            "jobs": [
              {
                "name": "j2",
                "tasks": [
                  {
                    "type": "fetch",
                    "attributes": {
                      "origin": "external",
                      "pipeline": "",
                      "stage": "defaultStage",
                      "job": "defaultJob",
                      "artifact_id": "docker-image"
                    }
                  }
                ]
              }
            ]
          }
        ]
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
ETag: "e89135b38ddbcd9380c83eb524647bdd"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/templates/template"
    },
    "doc": {
      "href": "https://api.gocd.org/#template-config"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/templates/:template_name"
    }
  },
  "name" : "template",
  "stages" : [ {
    "name" : "defaultStage",
    "fetch_materials" : true,
    "clean_working_directory" : false,
    "never_cleanup_artifacts" : false,
    "approval" : {
      "type" : "success",
      "authorization" : {
        "roles" : [ ],
        "users" : [ ]
      }
    },
    "environment_variables" : [ ],
    "jobs" : [ {
      "name" : "defaultJob",
      "run_instance_count" : null,
      "timeout" : null,
      "environment_variables" : [ ],
      "resources" : [ ],
      "tasks" : [ {
        "type" : "exec",
        "attributes" : {
          "run_if" : [ "passed" ],
          "command" : "ls",
          "args" : ""
        }
      } ],
      "tabs" : [ ],
      "artifacts" : [ {
        "type" : "external",
        "artifact_id" : "docker-image",
        "store_id" : "dockerhub",
        "configuration" : [ {
          "key" : "Image",
          "value" : "gocd/gocd-server"
        }, {
          "key" : "Tag",
          "value" : "v${GO_PIPELINE_LABEL}"
        } ]
      } ]
    } ]
  }, {
    "name" : "s2",
    "fetch_materials" : true,
    "clean_working_directory" : false,
    "never_cleanup_artifacts" : false,
    "approval" : {
      "type" : "success",
      "authorization" : {
        "roles" : [ ],
        "users" : [ ]
      }
    },
    "environment_variables" : [ ],
    "jobs" : [ {
      "name" : "j2",
      "run_instance_count" : null,
      "timeout" : null,
      "environment_variables" : [ ],
      "resources" : [ ],
      "tasks" : [ {
        "type" : "fetch",
        "attributes" : {
          "origin" : "external",
          "pipeline" : "",
          "stage" : "defaultStage",
          "job" : "defaultJob",
          "run_if" : [ ],
          "artifact_id" : "docker-image"
        }
      } ],
      "tabs" : [ ],
      "artifacts" : [ ]
    } ]
  } ]
}

Update template config for specified template name.

Updated to version v7 since v20.2.0.

Available since v16.10.0.

HTTP Request

PUT /go/api/admin/template/:template_name

Returns

The updated template object.

Delete a template

$ curl 'https://ci.example.com/go/api/admin/templates/template_name' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v7+json' \
      -X DELETE

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
{
  "message": "The template 'template_name' was deleted successfully."
}

Deletes a template from the config XML if it is not associated with any pipeline.

Updated to version v7 since v20.2.0.

Available since v16.10.0.

HTTP Request

DELETE /go/api/admin/templates/:template_name

Returns

A message confirmation if the template was deleted.

Get parameters for a template

$ curl 'https://ci.example.com/go/api/admin/templates/template_name/parameters' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v7+json' 

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
{
  "_links" : {
    "self" : {
      "href" : "http://go-server-url/go/api/admin/templates/template-name"
    },
    "doc" : {
      "href" : "https://api.gocd.org/#template-config"
    },
    "find" : {
      "href" : "http://go-server-url/go/api/admin/templates/:template_name"
    }
  },
  "name" : "template-name",
  "parameters" : [ "resources", "command" ]
}

Returns a list of parameters which needs to be defined while using the same in a pipeline config

Available since v20.2.0.

HTTP Request

GET /go/api/admin/templates/:template_name/parameters

Returns

A list of string.

Get template authorization

$ curl -i 'https://ci.example.com/go/api/admin/templates/template_name/authorization' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "all_group_admins_are_view_users": true,
  "admin": {
    "roles": [
      "xyz"
    ],
    "users": [

    ]
  },
  "view": {
    "roles": [

    ],
    "users": [
      "user"
    ]
  }
}

Returns template authorization for the specified template name.

Available since v18.2.0.

HTTP Request

GET /go/api/admin/templates/:template_name/authorization

Returns

The template authorization object.

Update template authorization

$ curl 'https://ci.example.com/go/api/admin/templates/template_name/authorization' \
-u 'username:password' \
-H 'Accept:  application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "d124ed4db70c23110924f488a031c8c9"' \
-X PUT -d '{
"all_group_admins_are_view_users": true,
"admin": {
  "roles": [],
  "users": [
    "user"
  ]
},
"view": {
  "roles": [
    "xyz"
  ],
  "users": [
    "view"
  ]
}
}'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "all_group_admins_are_view_users": true,
  "admin": {
    "roles": [

    ],
    "users": [
      "user"
    ]
  },
  "view": {
    "roles": [
      "xyz"
    ],
    "users": [
      "view"
    ]
  }
}

Update template authorization for the specified template.

Available since v18.2.0.

HTTP Request

PUT /go/api/admin/templates/:template_name/authorization

Returns

The template authorization object.

section_marker_placeholder:Runtime

Access Tokens

Access tokens allow users to make API calls to GoCD using a bearer token instead of username and password.

The access token object

Available since v19.2.0.

Attribute Type Description
description String The user provided description of the token.
token String The value of the token. This will be rendered only once when the token is created.
username String The username of the user that created the token.
revoked Boolean If the token has been revoked.
revoke_cause String The reason why the token was revoked.
revoked_at Timestamp The time when the token was revoked.
revoked_by String The username of the user that revoked the token.
created_at Timestamp The time when the token was created.
last_used_at Timestamp The time when the token was last used to authenticate with the server.
revoked_because_user_deleted Boolean Indicates if the token was revoked because a system adminstrator deleted the user.

Get all tokens for current user

$ curl 'https://ci.example.com/go/api/current_user/access_tokens' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_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
    } ]
  }
}

Lists all tokens belonging to a user.

Available since v19.2.0.

HTTP Request

GET /go/api/current_user/access_tokens

Returns

An array of access token objects.

Get one token for current user

$ curl 'https://ci.example.com/go/api/current_user/access_tokens/42' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_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
}

Gets a token by its unique identifier (id).

Available since v19.2.0.

HTTP Request

GET /go/api/current_user/access_tokens/:id

Returns

An access token object.

Create token for current user

$ curl 'https://ci.example.com/go/api/current_user/access_tokens' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{
        "description": "my first token"
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_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"
}

Creates a token.

Available since v19.2.0.

HTTP Request

POST /go/api/current_user/access_tokens/:id

Returns

An access token object.

Revoke token for current user

$ curl 'https://ci.example.com/go/api/current_user/access_tokens/42' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{
        "revoke_cause": "token was compromised"
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_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
}

Revokes a token so it cannot be reused again.

Available since v19.2.0.

HTTP Request

POST /go/api/current_user/access_tokens/:id/revoke

Returns

An access token object.

Get all tokens for all users

$ curl 'https://ci.example.com/go/api/admin/access_tokens?filter=all' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links" : {
    "self" : {
      "href" : "https://ci.example.com/go/api/admin/access_tokens"
    },
    "doc" : {
      "href" : "https://api.gocd.org/19.2.0/#access-token"
    }
  },
  "_embedded" : {
    "access_tokens" : [ {
      "_links" : { ... },
      "id" : 42,
      "description" : "dummy access token",
      "username" : "username",
      "revoked" : false,
      "revoke_cause" : null,
      "revoked_by" : null,
      "revoked_at" : null,
      "created_at" : "2019-03-06T05:02:24Z",
      "last_used_at" : null,
      "revoked_because_user_deleted" : false
    },
    {
      "_links" : { ... },
      "id" : 43,
      "description" : "another access token",
      "username" : "username",
      "revoked" : true,
      "revoke_cause" : "revoke cause",
      "revoked_by" : "username",
      "revoked_at" : "2019-03-07T05:02:45Z",
      "created_at" : "2019-03-06T05:02:34Z",
      "last_used_at" : null,
      "revoked_because_user_deleted" : false
    }]
  }
}
$ curl 'https://ci.example.com/go/api/admin/access_tokens' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links" : {
    "self" : {
      "href" : "https://ci.example.com/go/api/admin/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/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" : "dummy access token",
      "username" : "username",
      "revoked" : false,
      "revoke_cause" : null,
      "revoked_by" : null,
      "revoked_at" : null,
      "created_at" : "2019-03-06T05:02:24Z",
      "last_used_at" : null,
      "revoked_because_user_deleted" : false
    }]
  }
}
$ curl 'https://ci.example.com/go/api/admin/access_tokens?filter=revoked' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links" : {
    "self" : {
      "href" : "https://ci.example.com/go/api/admin/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/admin/access_tokens/43"
        },
        "doc" : {
          "href" : "https://api.gocd.org/19.2.0/#access-token"
        },
        "find" : {
          "href" : "https://ci.example.com/go/api/admin/access_tokens/:id"
        }
      },
      "id" : 43,
      "description" : "another access token",
      "username" : "username",
      "revoked" : true,
      "revoke_cause" : "revoke cause",
      "revoked_by" : "username",
      "revoked_at" : "2019-03-07T05:02:45Z",
      "created_at" : "2019-03-06T05:02:34Z",
      "last_used_at" : null,
      "revoked_because_user_deleted" : false
    } ]
  }
}

Allows system administrators to list the tokens belonging to all users.

Available since v19.2.0.

HTTP Request

GET /go/api/admin/access_tokens

Returns

An array of access token objects.

The following filters are supported by the API. In case of no filter, only the active tokens will be send.

Query String Description
all returns all the tokens for all the users
active returns only the active tokens for all the users
revoked returns only the revoked tokens for all the users

Get one token for any user

$ curl 'https://ci.example.com/go/api/admin/access_tokens/42' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_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
}

Allows system administrators to view tokens belonging to any user.

Available since v19.2.0.

HTTP Request

GET /go/api/admin/access_tokens/:id

Returns

An access token object.

Revoke token for any user

$ curl 'https://ci.example.com/go/api/admin/access_tokens/42' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{
        "revoke_cause": "token was compromised"
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_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.

Available since v19.2.0.

HTTP Request

POST /go/api/admin/access_tokens/:id/revoke

Returns

An access token object.

Agent Health

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

Check agent-server connectivity

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

The above command returns a plain text response:

HTTP/1.1 200 OK
Content-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:

The endpoint will return status 503 in any other cases.

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

Agents

The agents API allows users with administrator role to manage agents.

The agent object

Available since v15.2.0.

Attribute Type Description
uuid String The identifier of this agent.
hostname String The hostname of the agent.
elastic_agent_id String The elastic agent identifier of this agent. This attribute is only available if the agent is an elastic agent. Since v16.8.0.
elastic_plugin_id String The identifier of the elastic agent plugin that manages this agent instance. This attribute is only available if the agent is an elastic agent. Since v16.8.0.
ip_address String The IP address of the agent.
sandbox String The path where the agent will perform its builds.
operating_system String The operating system as reported by the agent.
free_space Integer The amount of free space in bytes.
agent_config_state String Whether an agent is enabled or not. Can be one of Pending, Enabled, Disabled. Since v15.3.0.
agent_state String The state an agent is in. Can be one of Idle, Building, LostContact, Missing, Building, Unknown. Since v15.3.0.
agent_version String The version of the agent. Since v20.5.0.
agent_bootstrapper_version String The version of the (installed) agent bootstrapper. Since v20.5.0.
resources Array The set of resources that this agent is tagged with. This attribute is only available if the agent is NOT an elastic agent.
environments Array The set of environments that this agent belongs to. Updated in v19.9.0.
build_state String If the agent is running a build, the state of the build on the agent. Can be one of Idle, Building, Cancelled, Unknown. Since v15.3.0.
build_details Object The build details provides information like pipeline, stage and job if the build_state of the agent is Building. Since v16.10.0.

The Environment object

{
  "name": "uat",
  "origin": {
    "type": "gocd",
    "_links": {
      "self": {
        "href": "http://test.host/go/admin/config_xml"
      },
      "doc": {
        "href": "https://api.gocd.org/19.3.0/#get-configuration"
      }
    }
  }
}

Attribute Type Description
name String The name of the environment.
origin Object Where the environment was defined.

The Environment Origin object

{
  "type": "gocd",
  "_links": {
    "self": {
      "href": "http://test.host/go/admin/config_xml"
    },
    "doc": {
      "href": "https://api.gocd.org/19.3.0/#get-configuration"
    }
  }
}

Attribute Type Description
type String The origin type of the environment:
  • gocd : The environment is defined in GoCD cruise-config.xml.
  • config-repo: The environment is defined via an external config-repo.
  • unknown: The environment is neither defined in cruise-config.xml nor via config-repo.
.

Get all agents

$ curl 'https://ci.example.com/go/api/agents' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v7+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/agents"
    },
    "doc": {
      "href": "https://api.gocd.org/#agents"
    }
  },
  "_embedded": {
    "agents": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da"
          },
          "doc": {
            "href": "https://api.gocd.org/#agents"
          },
          "find": {
            "href": "https://ci.example.com/go/api/agents/:uuid"
          }
        },
        "uuid": "adb9540a-b954-4571-9d9b-2f330739d4da",
        "hostname": "agent01.example.com",
        "ip_address": "10.12.20.47",
        "sandbox": "/Users/ketanpadegaonkar/projects/gocd/gocd/agent",
        "operating_system": "Mac OS X",
        "free_space": 84983328768,
        "agent_config_state": "Enabled",
        "agent_state": "Idle",
        "agent_version": "20.5.0",
        "agent_bootstrapper_version": "20.5.0",
        "resources": [
          "java",
          "linux",
          "firefox"
        ],
        "environments": [
          {
            "name": "perf",
            "origin": {
              "type": "gocd",
              "_links": {
                "self": {
                  "href": "https://ci.example.com/go/admin/config_xml"
                },
                "doc": {
                  "href": "https://api.gocd.org/#get-configuration"
                }
              }
            }
          },
          {
            "name": "UAT",
            "origin": {
              "type": "config-repo",
              "_links": {
                "self": {
                  "href": "https://ci.example.com/go/api/admin/config_repos/foo"
                },
                "doc": {
                  "href": "https://api.gocd.org/#config-repos"
                },
                "find": {
                  "href": "https://ci.example.com/go/api/admin/config_repos/:id"
                }
              }
            }
          },
          {
            "name": "test",
            "origin": {
              "type": "unknown"
            }
          }
        ],
        "build_state": "Idle"
      }
    ]
  }
}

Lists all available agents, registered as well as agents that are in Pending state awaiting registration.

Updated to version v6 since v19.9.0.

Available since v14.3.0.

HTTP Request

GET /go/api/agents

Returns

An array of agent objects.

Get one agent

$ curl 'https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v7+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da"
    },
    "doc": {
      "href": "https://api.gocd.org/#agents"
    },
    "find": {
      "href": "https://ci.example.com/go/api/agents/:uuid"
    }
  },
  "uuid": "adb9540a-b954-4571-9d9b-2f330739d4da",
  "hostname": "ketanpkr.corporate.thoughtworks.com",
  "ip_address": "10.12.20.47",
  "sandbox": "/Users/ketanpadegaonkar/projects/gocd/gocd/agent",
  "operating_system": "Mac OS X",
  "free_space": 85890146304,
  "agent_config_state": "Enabled",
  "agent_state": "Building",
  "agent_version": "20.5.0",
  "agent_bootstrapper_version": "20.5.0",
  "resources": ["java", "linux", "firefox"],
  "environments": [
    {
      "name": "perf",
      "origin": {
        "type": "gocd",
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/admin/config_xml"
          },
          "doc": {
            "href": "https://api.gocd.org/#get-configuration"
          }
        }
      }
    },
    {
      "name": "UAT",
      "origin": {
        "type": "config-repo",
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/config_repos/foo"
          },
          "doc": {
            "href": "https://api.gocd.org/#config-repos"
          },
          "find": {
            "href": "https://ci.example.com/go/api/admin/config_repos/:id"
          }
        }
      }
    }
  ],
  "build_state": "Building",
  "build_details": {
    "_links": {
      "job": {
        "href": "https://ci.example.com/go/tab/build/detail/up42/1/up42_stage/1/up42_job"
      },
      "stage": {
        "href": "https://ci.example.com/go/pipelines/up42/1/up42_stage/1"
      },
      "pipeline": {
        "href": "https://ci.example.com/go/tab/pipeline/history/up42"
      }
    },
    "pipeline_name": "up42",
    "stage_name": "up42_stage",
    "job_name": "up42_job"
  }
}

Gets an agent by its unique identifier (uuid)

Updated to version v6 since v19.9.0.

Available since v15.2.0.

HTTP Request

GET /go/api/agents/:uuid

Returns

An agent object.

Update an agent

$ curl 'https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v7+json' \
      -H 'Content-Type: application/json' \
      -X PATCH \
      -d '{
        "hostname": "agent02.example.com",
        "agent_config_state": "Enabled",
        "resources": ["Java","Linux"],
        "environments": ["Dev"]
        }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da"
    },
    "doc": {
      "href": "https://api.gocd.org/#agents"
    },
    "find": {
      "href": "https://ci.example.com/go/api/agents/:uuid"
    }
  },
  "uuid": "adb9540a-b954-4571-9d9b-2f330739d4da",
  "hostname": "agent02.example.com",
  "ip_address": "10.12.20.47",
  "sandbox": "/Users/ketanpadegaonkar/projects/gocd/gocd/agent",
  "operating_system": "Mac OS X",
  "free_space": 84834283520,
  "agent_config_state": "Enabled",
  "agent_state": "Idle",
  "resources": ["Java","Linux"],
  "environments": [
  {
    "name": "Dev",
    "origin": {
      "type": "gocd",
      "_links": {
        "self": {
          "href": "https://ci.example.com/go/admin/config_xml"
        },
        "doc": {
          "href": "https://api.gocd.org/#get-configuration"
        }
      }
    }
  }],
  "build_state": "Idle"
}

Update some attributes of an agent.

Updated to version v6 since v19.9.0.

Available since v14.3.0.

HTTP Request

PATCH /go/api/agents/:uuid

Atleast one of the following properties must be specified, not specifying the property will leave it unchanged.

Attribute Type Description
hostname String The new hostname.
resources String | Array A comma separated strings of resources, or an array of string resources. Updating of resources is NOT supported by elastic agents.
environments String | Array A comma separated strings of environments, or an array of string environments. The agent will be associated to an environment only if an environment exists in GoCD for the given name, else will be ignored.
agent_config_state String Whether an agent should be enabled. In case of agents awaiting approval, setting this will approve the agents. Can be one of Enabled, Disabled.

Returns

The updated agent object.

Delete an agent

$ curl 'https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v7+json' \
      -X DELETE

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
{
  "message": "Deleted 1 agent(s)."
}

Deletes an agent.

Updated to version v6 since v19.9.0.

Available since v14.3.0.

HTTP Request

DELETE /go/api/agents/:uuid

Returns

A message confirmation if the agent was deleted.

Bulk update agents

curl 'https://ci.example.com/go/api/agents' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v7+json' \
      -H 'Content-Type: application/json' \
      -X PATCH \
      -d '{
            "uuids": [
              "adb9540a-b954-4571-9d9b-2f330739d4da",
              "adb528b2-b954-1234-9d9b-b27ag4h568e1"
            ],
            "operations": {
              "environments": {
                "add": ["Dev", "Test"],
                "remove": ["Production"]
              },
              "resources": {
                "add": ["Linux", "Firefox"],
                "remove": ["Chrome"]
              }
            },
            "agent_config_state" : "enabled"
          }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
{
  "message": "Updated agent(s) with uuid(s): [adb9540a-b954-4571-9d9b-2f330739d4da, adb528b2-b954-1234-9d9b-b27ag4h568e1]."
}

Updates a list of agents.

Updated to version v6 since v19.9.0.

Available since v16.7.0.

HTTP Request

PATCH /go/api/agents

Atleast one of the following properties must be specified, not specifying the property will leave it unchanged.

Attribute Type Description
operations Object The bulk update operations performed on the set of agents.
agent_config_state String Whether an agent should be enabled. In case of agents awaiting approval, setting this will approve the agents. Can be one of Enabled, Disabled.

Returns

A message confirmation if the agents were updated successfully.

The bulk update operation attributes

{
  "environments": {
    "add": [
      "Dev",
      "Test"
    ],
    "remove": [
      "Production"
    ]
  },
  "resources": {
    "add": [
      "Linux",
      "Firefox"
    ],
    "remove": [
      "Chrome"
    ]
  }
}

Attribute Type Description
environments Object The environments update operation to be performed on the set of agents.
resources Object The resources update operation to be performed on the set of agents. Updating of resources is NOT supported by elastic agents.

The environment update operation attributes

{
  "add": [
    "Dev",
    "Test"
  ],
  "remove": [
    "Production"
  ]
}

Attribute Type Description
add Array The list of environments to which the specified agents needs to be added. If the said environment is present, the agent will be mapped to the same.
remove Array The list of environments from which the specified agents needs to be removed.

The resources update operation attributes

{
  "add": [
    "Linux",
    "Firefox"
  ],
  "remove": [
    "Chrome"
  ]
}

Attribute Type Description
add Array The list of resources that the agents needs to be tagged with.
remove Array The list of resources that the agents needs to be removed from.

Bulk delete agents

curl 'https://ci.example.com/go/api/agents' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v7+json' \
      -H 'Content-Type: application/json' \
      -X DELETE \
      -d '{
            "uuids": [
              "adb9540a-b954-4571-9d9b-2f330739d4da",
              "adb528b2-b954-1234-9d9b-b27ag4h568e1"
            ]
          }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
{
  "message": "Deleted 2 agent(s)."
}

Deletes a list of agents.

Updated to version v6 since v19.9.0.

Available since v16.7.0.

HTTP Request

DELETE /go/api/agents

Returns

A message confirmation if the agents were deleted.

Agent job run history

$ curl 'https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da/job_run_history' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links" : {
    "doc" : {
      "href" : "https://api.gocd.org/19.11.0/#agent-job-run-history"
    },
    "self" : {
      "href" : "https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da/job_run_history"
    },
    "find" : {
      "href" : "https://ci.example.com/go/api/agents/:uuid"
    }
  },
  "uuid" : "adb9540a-b954-4571-9d9b-2f330739d4da",
  "jobs" : [ {
    "job_state_transitions" : [ {
      "state_change_time" : "2019-11-12T00:20:56Z",
      "state" : "Scheduled"
    }, {
      "state_change_time" : "2019-11-12T00:21:06Z",
      "state" : "Assigned"
    }, {
      "state_change_time" : "2019-11-12T00:21:17Z",
      "state" : "Preparing"
    }, {
      "state_change_time" : "2019-11-12T00:22:19Z",
      "state" : "Building"
    }, {
      "state_change_time" : "2019-11-12T00:37:42Z",
      "state" : "Rescheduled"
    } ],
    "job_name" : "jasmine",
    "stage_name" : "build-non-server",
    "stage_counter" : "1",
    "pipeline_name" : "build-windows-PR",
    "pipeline_counter" : 5282,
    "result" : "Unknown",
    "rerun" : false
  } ],
  "pagination" : {
    "page_size" : 50,
    "offset" : 812,
    "total" : 813
  }
}

Lists the jobs that have executed on an agent.

Updated to version v1 since v19.12.0.

Available since v14.3.0.

HTTP Request

GET /go/api/agents/:uuid/job_run_history

With pagination

GET /go/api/agents/:uuid/job_run_history?offset=:offset&page_size=:page_size&sort_column=:sort_column&sort_order=:sort_order

The following query string parameters are supported by the API.

Attribute Type Description
offset Number The number of records to skip.
page_size Number The number of records per page of this response. Must be between 10 and 100. Defaults to 50.
sort_column String The sort order of records. Can be one of pipeline, stage, job, result, completed. Defaults to completed.
sort_order String The order of sorting of the column specified by sort_column. Can be one of ASC, DESC. Defaults to DESC.

Returns

An array of job objects along with the job transitions.

The build details object

{
  "build_details": {
    "_links": {
      "job": {
        "href": "https://ci.example.com/go/tab/build/detail/pipelineName/pipelineCounter/stageName/stageCounter/jobName"
      },
      "stage": {
        "href": "https://ci.example.com/go/pipelines/pipelineName/pipelineCounter/stageName/stageCounter"
      },
      "pipeline": {
        "href": "https://ci.example.com/go/tab/pipeline/history/pipelineName"
      }
    },
    "pipeline_name": "pipelineName",
    "stage_name": "stageName",
    "job_name": "jobName"
  }
}

Attribute Type Description
pipeline String Name of the pipeline, whose job the agent is building.
stage String Name of the stage, whose job the agent is building.
job String Name of the job the agent is building.

Kill running tasks

$ curl 'https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da/kill_running_tasks' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v7+json'
      -H 'X-GoCD-Confirm: true' \
      -X POST

The above command would return a HTTP status 202 without a response body.

When a job is cancelled, the agent tries to safely terminate all the running tasks for the job. If a running tasks fails to terminate the agent gets into a Building(Cancelled) state. Use this API to force kill all running tasks on an agent stuck in Building(Cancelled).

Available since v20.5.0.

HTTP Request

POST /go/api/agents/:uuid/kill_running_tasks

Returns

No Content

Artifacts

The artifacts API allows users to query and create artifacts of a job.

The artifact object

Available since v14.3.0.

Attribute Type Description
name String The basename of the file/folder.
url String The URL to the artifact.
type String The type of the artifact. Can be one of file, folder.
files Array If the artifact is of type folder then this property will contain files/folders inside this folder.

Get all artifacts

$ curl 'https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName.json' \
      -u 'username:password'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "name": "cruise-output",
    "url": "https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName/cruise-output",
    "type": "folder",
    "files": [
      {
        "name": "console.log",
        "url": "https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName/cruise-output/console.log",
        "type": "file"
      },
      {
        "name": "md5.checksum",
        "url": "https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName/cruise-output/md5.checksum",
        "type": "file"
      }
    ]
  }

Lists all available artifacts in a job.

Available since v14.3.0.

HTTP Request

GET /go/files/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/:job_name.json

Returns

An array of artifact objects.

Get artifact file

$ curl 'https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName/path/to/file' \
      -u 'username:password'

The above command returns the contents of the file you requested

Gets an artifact file 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_file

Returns

An the contents of the requested file.

Get artifact directory

$ curl 'https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName/path/to/directory.zip' \
      -u 'username:password'

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

Returns

One of -

Create artifact

$ curl 'https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName/pkg/foobar-widgets-1.2.3.jar' \
      -u 'username:password' \
      -H 'Confirm:true' \
      -X POST \
      -F 'file=@target/dist/foobar-widgets-1.2.3.jar'

The above command uploads the file target/dist/foobar-widgets-1.2.3.jar to the specified job at the remote path pkg/foobar-widgets-1.2.3.jar and returns the following response:

HTTP/1.1 201 Created
Content-Type: text/plain; charset=UTF-8

File pkg/foobar-widgets-1.2.3.jar was created successfully

Uploads a local file as an artifact.

Available since v14.3.0.

HTTP Request

POST /go/files/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/:job_name/*path_to_file

The following form parameter must be specified

Attribute Type Description
file String The contents file to be uploaded as multipart/form-data.

Returns

An acknowledgement that the file was created.

Create multiple artifacts

$ curl 'https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName/path/in/destination' \
      -u 'username:password' \
      -H 'Confirm: true' \
      -X POST \
      -F 'zipfile=@target/dist/zip-of-files.zip'

The above command uploads the contents of the zip file target/dist/zip-of-files.zip to the specified job at the remote directory path/in/destination/ and returns the following response:

HTTP/1.1 201 Created
Content-Type: text/plain; charset=UTF-8

File path/in/destination was created successfully

Example:

$ unzip -l /location/of/test.zip
Archive:  location/of/test.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
        0  04-06-2018 10:28   x/
        0  04-06-2018 10:29   x/y/
        6  04-06-2018 10:29   x/y/z.txt
        6  04-06-2018 10:29   x/y/a.txt
---------                     -------
       12                     4 files

$ pwd
/location/of/gocd/artifacts/pipelines/PipelineName/541/StageName/1/JobName

$ ls
cruise-output/


$ curl 'https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName/path/in/destination' \
      ... \
      -F 'zipfile=@/location/of/test.zip'

$ ls
cruise-output/   path/

$ find path
path
path/in
path/in/destination
path/in/destination/x
path/in/destination/x/y
path/in/destination/x/y/z.txt
path/in/destination/x/y/a.txt

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.

Available since v14.3.0.

HTTP Request

POST /go/files/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/:job_name/*path_to_directory

The following form parameter must be specified

Attribute Type Description
zipfile String The zip file to be uploaded as multipart/form-data.

Returns

An acknowledgement that the directory was created.

Append to artifact

$ curl 'https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName/logs/operations.log' \
      -u 'username:password' \
      -T logs/production.log

The above command appends the file logs/production.log to the specified job at the remote path logs/operations.log and returns the following response:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8

File logs/operations.log was appended successfully

Appends a local file to an existing artifact.

Available since v14.3.0.

HTTP Request

PUT /go/files/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/:job_name/*path_to_file

Returns

An acknowledgement that the file was appended to.

Backups

The backups API allows users with administrator role to manage GoCD server backups.

The Backup Object

Available since v19.3.0.

Attribute Type Description
time DateTime The time of the backup.
path String The filesystem location where the backed up files are stored.
user Object The user that performed this backup.
status String Status of the backup. Possible values are COMPLETED, IN_PROGRESS, ERROR, ABORTED.
progress_status String If the status of the backup is IN_PROGRESS, then this field gives more granular details about the back up in progress. Possible values are STARTING, CREATING_DIR, BACKUP_VERSION_FILE, BACKUP_CONFIG, BACKUP_CONFIG_REPO, BACKUP_DATABASE, POST_BACKUP_SCRIPT_START, POST_BACKUP_SCRIPT_COMPLETE.
message String The detailed message corresponding to the ‘status’ or ‘progress_status’ fields.

Schedule Backup

$ curl 'https://ci.example.com/go/api/backups' \
      -i \
      -u 'username:password' \
      -H 'X-GoCD-Confirm: true' \
      -H 'Accept: application/vnd.go.cd.v2+json' \
      -X POST

The above command returns an empty response body with a response code of 202 (Accepted) to indicate that request to backup is accepted and is scheduled asynchronously. It returns location header in the response that can be used for polling the status of the backup.

HTTP/1.1 202 Accepted
Content-Type: application/vnd.go.cd.v2+json;charset=utf-8
Location: /go/api/backups/:backup_id
Retry-After: 5
$ curl 'https://ci.example.com/go/api/backups/:backup_id' \
      -i \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json' \
      -X GET

The above command is used to poll the status of the backup that was scheduled previously. It returns JSON structured like this:

{
  "_links": {
    "doc": {
      "href": "https://api.gocd.org/#backups"
    }
  },
  "time": "2015-08-07T10:07:19.868Z",
  "path": "/var/lib/go-server/serverBackups/backup_20150807-153719",
  "status" : "COMPLETED",
  "progress_status" : "BACKUP_DATABASE",
  "message" : "Backup was generated successfully.",
  "user": {
    "_links": {
      "doc": {
        "href": "https://api.gocd.org/#users"
      },
      "self": {
        "href": "https://ci.example.com/go/api/users/username"
      },
      "find": {
        "href": "https://ci.example.com/go/api/users/:login_name"
      },
      "current_user" : {
        "href" : "https://ci.example.com/go/api/users/current_user"
      }
    },
    "login_name": "username"
  }
}

Available since v19.3.0.

HTTP Request

POST /go/api/backups

Returns an empty response body with a response code 202 (Accepted) and location header containing the link to be polled for checking the status of the backup.

Get Backup

$ curl 'https://ci.example.com/go/api/backups/:backup_id' \
      -i \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json' \
      -X GET

The above command is used to poll the status of the backup that was scheduled previously. It returns JSON structured like this:

{
  "_links": {
    "doc": {
      "href": "https://api.gocd.org/#backups"
    }
  },
  "time": "2015-08-07T10:07:19.868Z",
  "path": "/var/lib/go-server/serverBackups/backup_20150807-153719",
  "status" : "COMPLETED",
  "progress_status" : "BACKUP_DATABASE",
  "message" : "Backup was generated successfully.",
  "user": {
    "_links": {
      "doc": {
        "href": "https://api.gocd.org/#users"
      },
      "self": {
        "href": "https://ci.example.com/go/api/users/username"
      },
      "find": {
        "href": "https://ci.example.com/go/api/users/:login_name"
      },
      "current_user" : {
        "href" : "https://ci.example.com/go/api/users/current_user"
      }
    },
    "login_name": "username"
  }
}

Available since v19.3.0.

GET /go/api/backups/:backup_id

Returns

A new backup object.

Current User

The current user API allows any authenticated user to manage certain aspects of their profile.

Get current user

$ curl 'https://ci.example.com/go/api/current_user' \
      -u 'jdoe:password' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "doc": {
      "href": "https://api.gocd.org/#users"
    },
    "self": {
      "href": "https://ci.example.com/go/api/users/jdoe"
    },
    "find": {
      "href": "https://ci.example.com/go/api/users/:login_name"
    }
  },
  "login_name": "jdoe",
  "display_name": "John Doe",
  "enabled": true,
  "email": null,
  "email_me": false,
  "checkin_aliases": [

  ]
}

Gets the current user

Available since v17.5.0.

HTTP Request

GET /go/api/current_user

Returns

A user object.

Update current user

$ curl 'https://ci.example.com/go/api/current_user' \
      -u 'jdoe:password' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -H 'Content-Type: application/json' \
      -X PATCH \
      -d '{
            "email": "jdoe@example.com",
            "email_me": true,
            "checkin_aliases": ["jdoe", "johndoe"]
          }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "doc": {
      "href": "https://api.gocd.org/#users"
    },
    "self": {
      "href": "https://ci.example.com/go/api/users/jdoe"
    },
    "find": {
      "href": "https://ci.example.com/go/api/users/:login_name"
    }
  },
  "login_name": "jdoe",
  "display_name": "jdoe",
  "enabled": false,
  "email": "jdoe@example.com",
  "email_me": true,
  "checkin_aliases": [
    "jdoe",
    "johndoe"
  ]
}

Update some attributes of the current user.

Available since v17.5.0.

HTTP Request

PATCH /go/api/current_user

Atleast one of the following properties must be specified, not specifying the property will leave it unchanged.

Attribute Type Description
email String The user’s email address.
email_me Boolean Boolean indicating if the user should be signed up for email notifications.
checkin_aliases Array A list of SCM checkin aliases to map users to SCM commits.

Returns

The updated user object.

Dashboard

The Dashboard API allows users to view dashboard information.

Dashboard object

Available since v18.12.0.

Attribute Type Description
pipelines Object The list of pipelines.
environments Object The list of environments.
pipeline_groups Object The list of dashboard pipeline groups.

Dashboard pipeline object

Attribute Type Description
name String The name of the pipeline.
last_updated_timestamp Number The dashboard pipeline instance’s last updated timestamp.
locked Boolean Whether the current pipeline instance is locked.
pause_info Object The pause information of the pipeline.
can_operate Boolean Whether the current user has permission to trigger the pipeline.
can_administer Boolean Whether the current user has permission to edit the pipeline configurations.
can_unlock Boolean Whether the current user has permission to unlock a locked pipeline isntance.
can_pause Boolean Whether the current user has permission to pause the pipeline.
from_config_repo Boolean Whether the pipeline’s configuration is defined using pipeline as code.
instances Object The list of pipeline instances.

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"
          }
        ]
      }
    }
  ]
}

Attribute Type Description
label String The label of the current pipeline instance.
counter Number The pipeline counter of the current pipeline instance.
triggered_by String The name of the user who triggered the current pipeline instance.
scheduled_at Date The schedule time of the current pipeline instance.
stages Object The list of stages of the current pipeline instance.

Dashboard pipeline’s stage object

{
  "stages": [
    {
      "name": "up42_stage",
      "counter": "1",
      "status": "Cancelled",
      "approved_by": "changes",
      "cancelled_by": "bob",
      "scheduled_at": "2018-11-21T09:43:07Z"
    }
  ]
}

Attribute Type Description
name String The name of the stage.
counter Number The stage counter of the current stage instance.
status String The status of the current stage instance. Can be one of Building, Cancelled, Passed, Failed.
approved_by String The approver of the current stage instance.
cancelled_by String Indicates who cancelled the stage if stage status is Cancelled.
scheduled_at Date The schedule time of the current stage instance.

Dashboard environment object

{
  "environments": [
    {
      "name": "QA",
      "pipelines": [
        "up42"
      ],
      "can_administer": true
    }
  ]
}

Attribute Type Description
name String The name of the environment.
pipelines Object The list of pipelines which belongs to the current environment.
can_administer Boolean Whether the current has permission to edit the environment configurations.

Dashboard Pipeline Group object

{
  "pipeline_groups": [
    {
      "name": "UAT",
      "pipelines": [
        "up42"
      ],
      "can_administer": true
    }
  ]
}

Attribute Type Description
name String The name of the pipeline group.
pipelines Object The list of pipelines which belongs to the current pipeline group.
can_administer Boolean Whether the current user have permissions to edit the pipeline group configurations.

Get Dashboard

$ curl 'https://ci.example.com/go/api/dashboard' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v3+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
  "_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