Introduction

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

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

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

API versions

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

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

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

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

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

Authentication

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

Bearer token authentication

Available since v19.2.0.

# 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'

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
Set-Cookie: JSESSIONID=15kvus1kdrec46vk2a6jmtmo;Path=/go;Expires=Mon, 15-Jun-2015 10:16:20 GMT

{
  "_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

# 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'

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
Set-Cookie: JSESSIONID=15kvus1kdrec46vk2a6jmtmo;Path=/go;Expires=Mon, 15-Jun-2015 10:16:20 GMT

{
  "_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.

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

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

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
Set-Cookie: JSESSIONID=15kvus1kdrec46vk2a6jmtmo;Path=/go;Expires=Mon, 15-Jun-2015 10:16:20 GMT

{
  "_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": []
}

Server Health

The server health API allows users to monitor if the GoCD server is up and running. Usually used for health checks in Docker and Kubernetes.

Check Server Health

$ curl 'https://ci.example.com/go/api/v1/health'

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

This API will indicate if the server is up.

Available since v17.11.0.

HTTP Request

GET /go/api/v1/health

Agents

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

Important: Please note that this API requires using v5 of the API using application/vnd.go.cd.v5+json

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.
`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.3.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. Can be one of `gocd`, `config-repo`.

Get all agents

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

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v5+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",
        "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": "Idle"
      }
    ]
  }
}

Lists all available agents, these are agents that are present in the <agents/> tag inside cruise-config.xml and also agents that are in Pending state awaiting registration.

Updated to version v5 since v19.3.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.v5+json'

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v5+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",
  "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 v5 since v19.3.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.v5+json' \
      -H 'Content-Type: application/json' \
      -X PATCH \
      -d '{
        "hostname": "agent02.example.com",
        "agent_config_state": "Enabled",
        "resources": ["Java","Linux"],
        "environments": ["Dev"]
        }'

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v5+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 v5 since v19.3.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.
`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.v5+json' \
      -X DELETE

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v5+json; charset=utf-8

{
  "message": "Deleted 1 agent(s)."
}

Deletes an agent.

You must first disable an agent and ensure that its status is not Building, before attempting to deleting it.

Updated to version v5 since v19.3.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.v5+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"
          }'

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v5+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 v5 since v19.3.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. Updating of resources is NOT supported by elastic agents.
`resources`	Object	The resources update operation to be performed on the set of 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.
`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.v5+json' \
      -H 'Content-Type: application/json' \
      -X DELETE \
      -d '{
            "uuids": [
              "adb9540a-b954-4571-9d9b-2f330739d4da",
              "adb528b2-b954-1234-9d9b-b27ag4h568e1"
            ]
          }'

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v5+json; charset=utf-8

{
  "message": "Deleted 2 agent(s)."
}

Deletes a list of agents.

You must first disable the agents and ensure that their status is not Building, before attempting to deleting them.

Updated to version v5 since v19.3.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'

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "jobs": [
    {
      "agent_uuid": "5c5c318f-e6d3-4299-9120-7faff6e6030b",
      "name": "upload",
      "job_state_transitions": [
        {
          "state_change_time": 1435631497131,
          "id": 539906,
          "state": "Scheduled"
        },
        ...
      ],
      "scheduled_date": 1435631497131,
      "original_job_id": null,
      "pipeline_counter": 251,
      "rerun": false,
      "pipeline_name": "distributions-all",
      "result": "Passed",
      "state": "Completed",
      "id": 100129,
      "stage_counter": "1",
      "stage_name": "upload-installers"
    }
  ],
  "pagination": {
    "offset": 0,
    "total": 1292,
    "page_size": 10
  }
}

Lists the jobs that have executed on an agent.

Updated to version v5 since v19.3.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]

Note: :offset is an optional parameter indicating the number of jobs to be skipped.

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.

Access Tokens

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

Important: Please note that this API requires using v1 of the API using application/vnd.go.cd.v1+json

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'

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'

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

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

Revokes a token so it cannot be reused again.

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

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'

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'

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'

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'

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

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.

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

Check agent-server connectivity

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

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:

able to establish HTTP(s) contact with the server
is authorized by the server (by an admin, or by auto-registration)

The endpoint will return status 503 in any other cases.

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

Users

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

The user object

Available since v15.2.0.

Attribute	Type	Description
`login_name`	String	The user’s login name.
`display_name`	String	The user’s display name.
`enabled`	Boolean	Boolean indicating if the user is enabled (can login in).
`email`	String	The user’s email address.
`email_me`	Boolean	Boolean indicating if the user has signed up for email notifications.
`checkin_aliases`	Array	A list of SCM checkin aliases to map users to SCM commits.
`admin`	Boolean	Boolean indicating if the user is an admin. Since v19.1.0.
`roles`	Array	List of user roles that the user has been assigned. Since v19.1.0.

Get all users

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

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/users"
    },
    "doc": {
      "href": "https://api.gocd.org/#users"
    }
  },
  "_embedded": {
    "users": [
      {
        "_links": {
          "doc": {
            "href": "https://api.gocd.org/#users"
          },
          "self": {
            "href": "https://ci.example.com/go/api/users/admin"
          },
          "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,
        "admin": false,
        "roles": [{
          "name": "role name",
          "type": "gocd"
        }],
        "checkin_aliases": [
          "jdoe",
          "johndoe"
        ]
      }
    ]
  }
}

Lists all available users.

Available since v15.2.0.

HTTP Request

GET /go/api/users

Returns

An array of user objects.

Get one user

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

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+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": true,
  "email": null,
  "email_me": false,
  "admin": true,
  "roles": [{
    "name": "role name",
    "type": "gocd"
  }],
  "checkin_aliases": [

  ]
}

Gets a user by its login name

Available since v15.2.0.

HTTP Request

GET /go/api/users/:login_name

Returns

A user object.

Create a user

$ curl 'https://ci.example.com/go/api/users' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v3+json' \
      -H 'Content-Type: application/json' \
      -X POST \
      -d '{
            "email": "jdoe@example.com",
            "login_name": "jdoe"
          }'

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+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": true,
  "email": null,
  "email_me": false,
  "admin": false,
  "roles": [{
    "name": "role name",
    "type": "gocd"
  }],
  "checkin_aliases": [

  ]
}

Creates a user

Available since v15.3.0.

HTTP Request

POST /go/api/users

The following properties may be specified:

Attribute	Type	Description
`login_name`	String	The user’s login name. This attribute MUST be specified.
`enabled`	Boolean	Boolean indicating if the user is enabled (can login in).
`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

A user object.

Update a user

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

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+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,
  "admin": false,
  "roles": [{
    "name": "role name",
    "type": "gocd"
  }],
  "checkin_aliases": [
    "jdoe",
    "johndoe"
  ]
}

Update some attributes of a user.

Available since v15.2.0.

HTTP Request

PATCH /go/api/users/:login_name

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

Attribute	Type	Description
`enabled`	Boolean	Boolean indicating if the user is enabled (can log in).
`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.

Delete a user

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

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

{
  "message": "User 'jdoe' was deleted successfully."
}

Deletes a user.

Available since v15.2.0.

HTTP Request

DELETE /go/api/users/:login_name

Returns

A message confirmation if the user was deleted.

Bulk Delete Users

$ curl 'https://ci.example.com/go/api/users' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v3+json' \
      -H 'Content-Type: application/json' \
      -X DELETE \
      -d '{"users": ["jez", "tez"]}'

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

{
  "message": "Users '[\"jez\", \"tez\"]' were deleted successfully."
}

Deletes multiple users.

Available since v17.11.0.

HTTP Request

DELETE /go/api/users

Returns

A message confirming if the users were deleted.

Bulk Enable/Disable Users

$ curl 'https://ci.example.com/go/api/admin/operations/state' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v3+json' \
      -H 'Content-Type: application/json' \
      -X PATCH \
      -d '{
            "users": ["jez", "tez"],
            "operations": {
              "enable": true
            }
          }'

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

{
  "message": "Users '[\"jez\", \"tez\"]' were enabled successfully."
}

Enables/Disables multiple users.

Available since v19.1.0.

HTTP Request

PATCH /go/api/users/operations/state

Returns

A message confirming if the users were enabled/disabled.

The user role object

Available since v19.1.0.

Attribute	Type	Description
`type`	String	The type of role (plugin \| gocd).
`Name`	String	Name of the role.

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'

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

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.

Notification Filters

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

The notification filter object

Available since v17.5.0.

Attribute	Type	Description
`id`	Number	The internal ID of the notification filter.
`pipeline`	String	The pipeline name to which the notification filter should match.
`stage`	String	The stage name to which the notification filter should match.
`event`	String	The event to which the notification filter should match.
`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.v1+json'

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

{
  "filters": [
    {
      "id": 10,
      "pipeline": "my_pipeline",
      "stage": "[Any Stage]",
      "event": "Breaks",
      "match_commits": true
    }
  ]
}

Lists all notification filters for the authenticated user.

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.v1+json' \
      -H 'Content-Type: application/json' \
      -X POST \
      -d '{
            "pipeline": "my_pipeline",
            "stage": "my_stage",
            "event": "Breaks",
            "match_commits": true
          }'

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

{
  "filters": [
    {
      "id": 1,
      "pipeline": "already_existed",
      "stage": "[Any Stage]",
      "event": "All",
      "match_commits": true
    },
    {
      "id": 2,
      "pipeline": "my_pipeline",
      "stage": "my_stage",
      "event": "Breaks",
      "match_commits": true
    }
  ]
}

Creates a notification filter for the authenticated user.

Available since v17.5.0.

HTTP Request

POST /go/api/notification_filters

The following properties may be specified:

Attribute	Type	Description
`pipeline`	String	The pipeline name to match. Can also be “[Any Pipeline]”. This attribute MUST be specified.
`stage`	String	The stage name to match. Can also be “[Any Stage]”. This attribute MUST be specified.
`event`	String	The event to match. Can be one of: “All”, “Passes”, “Fails”, “Breaks”, “Fixed”, “Cancelled”. This attribute MUST be specified.
`match_commits`	Boolean	Should the filter only match the user’s commits?.

Returns

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

Delete a notification filter

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

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

{
  "filters": [
  ]
}

Deletes a notification filter for the authenticated user.

Available since v17.5.0.

HTTP Request

DELETE /go/api/notification_filters/:id

Returns

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

Materials

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

The material object

Available since v14.3.0.

Attribute	Type	Description
`description`	String	The description of the material.
`fingerprint`	String	The fingerprint of the material.
`type`	String	The type of a material. Can be one of `Git`, `Mercurial`, `Perforce`, `Subversion`, `Tfs`, `Pipeline`, `SCM`.

Get all materials

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "description": "URL: https://github.com/gocd/gocd, Branch: master",
    "fingerprint": "03c8d2a131154436b6ef2d621c6f773837481aaea8c5c1bb9c0cb9b5bc64a2f1",
    "type": "Git"
  }
]

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

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'

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "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

Available since v14.3.0.

HTTP Request

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

With pagination

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

Note: :offset is an optional parameter indicating the number of jobs to be skipped.

Returns

A list of modification objects.

Notify SVN materials

$ curl 'https://ci.example.com/go/api/material/notify/svn' \
      -u 'username:password' \
      -H 'Confirm: true' \
      -X POST \
      -d 'uuid=svn-repository-uuid'

HTTP/1.1 202 Accepted
Content-Type: text/plain; charset=UTF-8

The material is now scheduled for an update. Please check relevant pipeline(s) for status.

APIs that notify GoCD Server when a commit has been made in Version Control and GoCD needs to trigger relevant pipelines.

When using this feature, uncheck Poll for new changes or set autoUpdate flag in cruise configuration to false for the relevant material.

Available since v14.3.0.

HTTP Request

POST /go/api/material/notify/svn

The following post parameters must be specified.

Attribute	Type	Description
`uuid`	String	The subversion repository UUID.

Returns

A text confirmation.

Notification script

To notify GoCD via a SVN post commit hook, you may use the following post commit hook in your subversion repository.

The post commit hook is located at /path/to/repository/hooks/post-commit.

#!/bin/sh

REPOS="$1"
REV="$2"
UUID=$(svnlook uuid $1)

curl 'https://ci.example.com/go/api/material/notify/svn' \
    -u 'username:password' \
    -H 'Confirm: true' \
    -X POST \
    -d "uuid=$UUID"

Notify git materials

$ curl 'https://ci.example.com/go/api/material/notify/git' \
      -u 'username:password' \
      -H 'Confirm: true' \
      -X POST \
      -d "repository_url=git://git.example.com/git/funky-widgets.git"

HTTP/1.1 202 Accepted
Content-Type: text/plain; charset=UTF-8

The material is now scheduled for an update. Please check relevant pipeline(s) for status.

APIs that notify GoCD Server when a commit has been made in Version Control and GoCD needs to trigger relevant pipelines.

When using this feature, uncheck Poll for new changes or set autoUpdate flag in cruise configuration to false for the relevant material.

Available since v14.3.0.

HTTP Request

POST /go/api/material/notify/git

The following post parameters must be specified.

Attribute	Type	Description
`repository_url`	String	The git repository url as defined in `cruise-config.xml`.

Returns

A text confirmation.

Notification script

To notify GoCD via a Git post commit hook, you may use the following post commit hook in your git repository.

The post commit hook is located at /path/to/repository.git/hooks/post-receive.

#!/bin/sh

curl 'https://ci.example.com/go/api/material/notify/git' \
    -u 'username:password' \
    -H 'Confirm: true' \
    -X POST \
    -d "repository_url=git://git.example.com/git/funky-widgets.git"

Hosting your repository on BitBucket?

Available since v17.11.0.

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

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

https://{webhookSecret}:x@gocd.example.com:8154/go/api/webhooks/bitbucket/notify

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

Returns

A text confirmation, with the http status 202 Accepted.

Hosting your repository on GitHub, or GitHub Enterprise?

Available since v17.6.0.

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

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

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

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

Returns

A text confirmation, with the http status 202 Accepted.

Hosting your repository on GitLab?

Available since v17.11.0.

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

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

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

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

Returns

A text confirmation, with the http status 202 Accepted.

Notify Mercurial materials

$ curl 'https://ci.example.com/go/api/material/notify/hg' \
      -u 'username:password' \
      -H 'Confirm: true' \
      -X POST \
      -d "repository_url=ssh://hg.example.com//hg/repos/funky-widgets"

HTTP/1.1 202 Accepted
Content-Type: text/plain; charset=UTF-8

The material is now scheduled for an update. Please check relevant pipeline(s) for status.

APIs that notify GoCD Server when a commit has been made in Version Control and GoCD needs to trigger relevant pipelines.

When using this feature, uncheck Poll for new changes or set autoUpdate flag in cruise configuration to false for the relevant material.

Available since v14.3.0.

HTTP Request

POST /go/api/material/notify/hg

The following post parameters must be specified.

Attribute	Type	Description
`repository_url`	String	The Mercurial repository URL as defined in `cruise-config.xml`.

Returns

A text confirmation.

Notification script

To notify GoCD via a Mercurial changegroup hook, you may use the following in your Mercurial repository.

The hook goes into the hgrc file, located at /path/to/hg/repository/.hg/hgrc.

[hooks]
changegroup = curl -sSL 'https://ci.example.com/go/api/material/notify/hg' \
    -u 'username:password' \
    -H 'Confirm: true' \
    -X POST \
    -d "repository_url=ssh://hg.example.com//hg/repos/funky-widgets"

Notify other scm materials

$ curl 'https://ci.example.com/go/api/material/notify/scm' \
      -u 'username:password' \
      -H 'Confirm: true' \
      -X POST \
      -d "scm_name=material_name"

HTTP/1.1 202 Accepted
Content-Type: text/plain; charset=UTF-8

The material is now scheduled for an update. Please check relevant pipeline(s) for status.

APIs that notify GoCD Server when a commit has been made in Version Control and GoCD needs to trigger relevant pipelines.

When using this feature, uncheck Poll for new changes or set autoUpdate flag in cruise configuration to false for the relevant material.

Available since v14.3.0.

HTTP Request

POST /go/api/material/notify/scm

The following post parameters must be specified.

Attribute	Type	Description
`scm_name`	String	The scm_name is the material name as defined in pipeline material page.

Returns

A text confirmation.

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

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

{
  "_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

{
  "_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.

Pipeline Groups

The pipeline groups allows users to list pipeline groups along with the pipelines, stages and materials for each pipeline.

Config listing

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "pipelines": [
      {
        "stages": [
          {
            "name": "up42_stage"
          }
        ],
        "name": "up42",
        "materials": [
          {
            "description": "URL: https://github.com/gocd/gocd, Branch: master",
            "fingerprint": "2d05446cd52a998fe3afd840fc2c46b7c7e421051f0209c7f619c95bedc28b88",
            "type": "Git"
          }
        ],
        "label": "${COUNT}"
      }
    ],
    "name": "first"
  }
]

This API is built primarily to support rendering of value stream mapping. As such the information rendered in the configuration is kept to a minimum.

Available since v14.3.0.

HTTP Request

GET /go/api/config/pipeline_groups

Returns

A list of pipeline groups, pipelines in each group, stages and materials in each pipeline.

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'

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'

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

The path_to_file can be a nested file for e.g. dist/foobar-widgets-1.2.0.jar

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'

Gets an artifact directory by its path.

Available since v14.3.0.

HTTP Request

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

The path_to_directory can be a nested directory for e.g. target/dist.zip

Since it may take an undetermined amount of time to compress a directory, the server may return a 202 Accepted code to indicate that it is compressing the requested directory.

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

Returns

One of -

A status code 202 Accepted to acknowledge your request to compress the contents of the requested directory.
The requested directory contents in the form of a zip file.

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'

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'

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

File path/in/destination was created successfully

$ 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

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.

Pipelines

The pipelines API allows users to view pipeline information and operate on it.

Get pipeline instance

$ curl 'http://ci.example.com/go/api/pipelines/PipelineName/instance/1' \
      -u 'username:password'

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "build_cause": {
    "approver": "",
    "material_revisions": [
      {
        "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"
          }
        ],
        "material": {
          "description": "URL: https://github.com/gocd/gocd, Branch: master",
          "fingerprint": "61e2da369d0207a7ef61f326eed837f964471b35072340a03f8f55d993afe01d",
          "type": "Git",
          "id": 4
        },
        "changed": true
      }
    ],
    "trigger_forced": false,
    "trigger_message": "modified by Pick E Reader <pick.e.reader@example.com>"
  },
  "name": "PipelineName",
  "natural_order": 1,
  "can_run": false,
  "comment": null,
  "stages": [
    {
      "name": "stage1",
      "approved_by": "changes",
      "jobs": [
        {
          "name": "jsunit",
          "result": "Passed",
          "state": "Completed",
          "id": 1,
          "scheduled_date": 1398332981981
        }
      ],
      "can_run": false,
      "result": "Passed",
      "approval_type": "success",
      "counter": "1",
      "id": 1,
      "operate_permission": false,
      "rerun_of_counter": null,
      "scheduled": true
    }
  ],
  "counter": 1,
  "id": 1,
  "preparing_to_schedule": false,
  "label": "14.1.0.1-b14a81825d081411993853ea5ea45266ced578b4"
}

Gets pipeline instance object.

Available since v15.1.0.

HTTP Request

GET /go/api/pipelines/:pipeline_name/instance/:pipeline_counter

Returns

A pipeline instance object.

Get pipeline history


$ curl 'http://ci.example.com/go/api/pipelines/pipeline1/history/0' \
       -u 'username:password'

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "pipelines": [
    {
      "build_cause": {
        "approver": "anonymous",
        "material_revisions": [
          {
            "modifications": [
              {
                "email_address": null,
                "id": 1,
                "modified_time": 1434957613000,
                "user_name": "Pick E Reader <pick.e.reader@example.com>",
                "comment": "my hola mundo changes",
                "revision": "c194b49db102b705ebc13e604e490ae13ac92d96"
              }
            ],
            "material": {
              "description": "URL: https://github.com/gocd/gocd, Branch: master",
              "fingerprint": "f6e7a3899c55e1682ffb00383bdf8f882bcee2141e79a8728254190a1fddcf4f",
              "type": "Git",
              "id": 1
            },
            "changed": false
          }
        ],
        "trigger_forced": true,
        "trigger_message": "Forced by anonymous"
      },
      "name": "pipeline1",
      "natural_order": 11,
      "can_run": true,
      "comment": null,
      "stages": [
        {
          "name": "stage1",
          "approved_by": "admin",
          "jobs": [
            {
              "name": "job1",
              "result": "Failed",
              "state": "Completed",
              "id": 13,
              "scheduled_date": 1436172201081
            }
          ],
          "can_run": true,
          "result": "Failed",
          "approval_type": "success",
          "counter": "1",
          "id": 13,
          "operate_permission": true,
          "rerun_of_counter": null,
          "scheduled": true
        }
      ],
      "counter": 11,
      "id": 13,
      "preparing_to_schedule": false,
      "label": "11"
    },
    {
      "build_cause": {
        "approver": "anonymous",
        "material_revisions": [
          {
            "modifications": [
              {
                "email_address": null,
                "id": 1,
                "modified_time": 1434957613000,
                "user_name": "Pick E Reader <pick.e.reader@example.com>",
                "comment": "my hola mundo changes",
                "revision": "c194b49db102b705ebc13e604e490ae13ac92d96"
              }
            ],
            "material": {
              "description": "URL: https://github.com/gocd/gocd, Branch: master",
              "fingerprint": "f6e7a3899c55e1682ffb00383bdf8f882bcee2141e79a8728254190a1fddcf4f",
              "type": "Git",
              "id": 1
            },
            "changed": false
          }
        ],
        "trigger_forced": true,
        "trigger_message": "Forced by anonymous"
      },
      "name": "pipeline1",
      "natural_order": 10,
      "can_run": true,
      "comment": null,
      "stages": [
        {
          "name": "stage1",
          "approved_by": "admin",
          "jobs": [
            {
              "name": "job1",
              "result": "Passed",
              "state": "Completed",
              "id": 12,
              "scheduled_date": 1436172122024
            }
          ],
          "can_run": true,
          "result": "Passed",
          "approval_type": "success",
          "counter": "1",
          "id": 12,
          "operate_permission": true,
          "rerun_of_counter": null,
          "scheduled": true
        }
      ],
      "counter": 10,
      "id": 12,
      "preparing_to_schedule": false,
      "label": "10"
    }
  ],
  "pagination": {
    "offset": 0,
    "total": 2,
    "page_size": 10
  }
}

The pipeline history allows users to list pipeline instances. Supports pagination using offset which tells the API how many instances to skip.

Available since v14.3.0.

HTTP Request

GET /go/api/pipelines/:pipeline_name/history

With pagination

GET /go/api/pipelines/:pipeline_name/history[/:offset]

Note: :offset is an optional parameter indicating the number of pipeline instances to be skipped.

Returns

An array of pipeline instances.

Get pipeline status


$ curl 'http://ci.example.com/go/api/pipelines/pipeline1/status' \
       -u 'username:password'

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "pausedCause": "Reason for pausing this pipeline",
  "pausedBy": "admin",
  "paused": true,
  "schedulable": false,
  "locked": false
}

The pipeline status allows users to check if the pipeline is paused, locked and schedulable.

Available since v14.3.0.

HTTP Request

GET /go/api/pipelines/:pipeline_name/status

Returns

JSON containing information about pipeline state.

Pause a pipeline

$ curl 'https://ci.example.com/go/api/pipelines/pipeline1/pause' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -H 'Content-Type: application/json' \
      -X POST \
      -d '{
            "pause_cause": "Investigating build failures"
          }'

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

{
  "message" : "Pipeline 'pipeline1' paused successfully."
}

Pause the specified pipeline.

Available since v18.2.0.

HTTP Request

POST /go/api/pipelines/:pipeline_name/pause

The following properties may be specified.

Attribute	Type	Description
`pause_cause`	String	Reason for pausing the pipeline.

If you do not specify a JSON request body, you MUST set the http request header X-GoCD-Confirm with any random string. This is done to force the browser to perform a CORS preflight check.

Returns

A message confirming that the pipeline was paused.

Unpause a pipeline

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

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

{
  "message" : "Pipeline 'pipeline1' unpaused successfully."
}

Unpause the specified pipeline.

Available since v18.2.0.

HTTP Request

POST /go/api/pipelines/:pipeline_name/unpause

Returns

A message confirming that the pipeline was unpaused.

Releasing a pipeline lock

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

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

{
  "message" : "Pipeline lock released for pipeline1."
}

Release a lock on a pipeline so that you can start up a new instance without having to wait for the earlier instance to finish.

Available since v18.2.0.

HTTP Request

POST /go/api/pipelines/:pipeline_name/unlock

Returns

A message confirming that the pipeline was unlocked.

Scheduling pipelines


$ curl 'https://ci.example.com/go/api/pipelines/pipeline1/schedule' \
       -u 'username:password' \
       -H 'Accept: application/vnd.go.cd.v1+json' \
       -H 'Content-Type: application/json' \
       -X POST \
       -d '{
             "environment_variables": [
               {
                 "name": "USERNAME",
                 "secure": false,
                 "value": "bob"
               },
               {
                 "name": "SSH_PASSPHRASE",
                 "value": "some passphrase",
                 "secure": true,
               },
               {
                 "name": "PASSWORD",
                 "encrypted_value": "YEepp1G0C05SpP0fcp4Jh+kPmWwXH5Nq",
                 "secure": true,
               }
             ],
             "materials": [
               {
                 "fingerprint": "b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c",
                 "revision": "123"
               },
               {
                 "fingerprint": "7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730",
                 "revision": "1058e75b18e8a645dd71702851994a010789f450"
               }
             ],
             "update_materials_before_scheduling": true
           }'

HTTP/1.1 202 Accepted
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8

{
  "message" : "Request to schedule pipeline pipeline1 accepted"
}

Scheduling allows user to trigger a specific pipeline.

Available since v18.2.0.

HTTP Request

POST /go/api/pipelines/:pipeline_name/schedule

The following properties may be specified.

Attribute	Type	Description
`environment_variables`	Array	A list of environment variables that can be overridden while scheduling the pipeline.
`materials`	Array	A list of materials that must be used to trigger a new instance of the pipeline. Defaults to triggering with the latest revision of all pipelines.
`update_materials_before_scheduling`	Boolean	Whether a material update should be updated before scheduling. Defaults to true.

If you do not specify a JSON request body, you MUST set the http request header X-GoCD-Confirm with any random string. This is done to force the browser to perform a CORS preflight check.

Returns

A message indicating if the request was accepted.

The scheduling material object

{
  "materials": [
    {
      "fingerprint": "5ae0ad30a5daf288a5d5ad0779f5599e18628079db282b9979a5a1647e7d6064",
      "revision": "123"
    },
    {
      "fingerprint": "06cd91c5bae482aef5b26d48e22e6f2e2dd7c9e880e02d55ce16e5aafc3c0c4b",
      "revision": "ccfbcd41f7d9dd2f10323d9a4f19c7f0aa5f6fe0"
    },
    {
      "fingerprint": "bc3f161b22bef8b027446e0fb56a1c6dda5d02c14bbbe1415b428fcf949aaa09",
      "revision": "upstream_foo/2/dist/1"
    },
    {
      "fingerprint": "29f7131be1c8475331e17dbde34df03483d17c711ecbc36427ead6ec6408666f",
      "revision": "gcc-4.4.7-3.el6.x86_64"
    }
  ]
}

Attribute	Type	Description
`fingerprint`	String	The fingerprint of the material object.
`revision`	String	The revision of the material that should be used to trigger the pipeline: For git and hg repositories, this will be the SHA of the commit. For subversion repositories, this will be the integer revision. For perforce repositories, this will be the changelist number. For TFS repositories, this will be the changeset ID. For pipeline dependency materials, this will be the pipeline identifier in the form `:pipeline_name/:pipeline_counter/:stage_name/:stage_counter`. For package materials, this will be the revision identifier of the package as specified by the package material plugin. .

Stages

The stages API allows users to view stage information and operate on it.

Cancel stage

$ curl 'https://ci.example.com/go/api/stages/myPipeline/myStages/cancel' \
      -u 'username:password' \
      -H 'Confirm: true' \
      -X POST

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8

Stage cancelled successfully.

Cancel an active stage of a specified stage.

Available since v14.3.0.

HTTP Request

POST /go/api/stages/:pipeline_name/:stage_name/cancel

Returns

A text confirmation.

Get stage Instance

$ curl 'https://ci.example.com/go/api/stages/myPipeline/myStages/instance/1/1' \
  -u 'username:password' \
  -H 'Accept: application/vnd.go.cd.v1+json'

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

{
  "name": "defaultStage",
  "clean_working_directory": false,
  "approved_by": "changes",
  "jobs": [
    {
      "agent_uuid": "278fb0b6-d3b8-47e1-9443-67f26bfb5c15",
      "name": "defaultJob",
      "job_state_transitions": [
        {
          "state_change_time": 1436509518752,
          "id": 1,
          "state": "Scheduled"
        },
        {
          "state_change_time": 1436509524491,
          "id": 2,
          "state": "Assigned"
        },
        {
          "state_change_time": 1436509534639,
          "id": 3,
          "state": "Preparing"
        },
        {
          "state_change_time": 1436509542522,
          "id": 4,
          "state": "Building"
        },
        {
          "state_change_time": 1436509642582,
          "id": 5,
          "state": "Completing"
        },
        {
          "state_change_time": 1436509642631,
          "id": 6,
          "state": "Completed"
        }
      ],
      "scheduled_date": 1436509518752,
      "original_job_id": null,
      "pipeline_counter": null,
      "rerun": false,
      "pipeline_name": null,
      "result": "Cancelled",
      "state": "Completed",
      "id": 1,
      "stage_counter": null,
      "stage_name": null
    }
  ],
  "pipeline_counter": 1,
  "pipeline_name": "mypipeline",
  "approval_type": "success",
  "result": "Cancelled",
  "cancelled_by": "user",
  "counter": 1,
  "id": 1,
  "rerun_of_counter": null,
  "fetch_materials": true,
  "artifacts_deleted": false
}

Gets stage instance object.

Available since v19.1.0.

HTTP Request

GET /go/api/stages/:pipeline_name/:stage_name/instance/:pipeline_counter/:stage_counter

Returns

A stage instance object.

Get stage history

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "stages": [
    {
      "name": "defaultStage",
      "approved_by": "admin",
      "cancelled_by": "GoCD",
      "jobs": [
        {
          "name": "defaultJob",
          "result": "Cancelled",
          "state": "Completed",
          "id": 3,
          "scheduled_date": 1436509881002
        }
      ],
      "pipeline_counter": 3,
      "pipeline_name": "mypipeline",
      "result": "Cancelled",
      "approval_type": "success",
      "id": 3,
      "counter": "1",
      "rerun_of_counter": null
    },
    {
      "name": "defaultStage",
      "approved_by": "admin",
      "cancelled_by": "admin",
      "jobs": [
        {
          "name": "defaultJob",
          "result": "Cancelled",
          "state": "Completed",
          "id": 2,
          "scheduled_date": 1436509783931
        }
      ],
      "pipeline_counter": 2,
      "pipeline_name": "mypipeline",
      "result": "Cancelled",
      "approval_type": "success",
      "id": 2,
      "counter": "1",
      "rerun_of_counter": null
    },
    {
      "name": "defaultStage",
      "approved_by": "changes",
      "jobs": [
        {
          "name": "defaultJob",
          "result": "Passed",
          "state": "Completed",
          "id": 1,
          "scheduled_date": 1436509518752
        }
      ],
      "pipeline_counter": 1,
      "pipeline_name": "mypipeline",
      "result": "Passed",
      "approval_type": "success",
      "id": 1,
      "counter": "1",
      "rerun_of_counter": null
    }
  ],
  "pagination": {
    "offset": 0,
    "total": 3,
    "page_size": 10
  }
}

The stage history allows users to list stage instances of specified stage. Supports pagination using offset which tells the API how many instances to skip.

Updated to version v1 since v19.3.0.

Available since v14.3.0.

HTTP Request

GET /go/api/stages/:pipeline_name/:stage_name/history

With pagination

GET /go/api/stages/:pipeline_name/:stage_name/history[/:offset]

Note: :offset is an optional parameter indicating the number of stages to be skipped.

Returns

An array of stage instances.

Run stage

$ curl 'https://ci.example.com/go/api/stages/myPipeline/myPipelineRunCounter/myStages/run' \
      -u 'username:password' \
      -H 'X-GoCD-Confirm: true' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -X POST

HTTP/1.1 202 Accepted
Content-Type: application/vnd.go.cd.v1+json;charset=utf-8

{
  "message" : "Request to schedule stage testAPI/1/defaultStage accepted"
}

Runs a specified stage.

Available since v18.11.0.

HTTP Request

POST /go/api/stages/:pipeline_name/:pipeline_counter/:stage_name/run

Returns

A text confirmation.

Run failed jobs

$ curl 'https://ci.example.com/go/api/stages/myPipeline/myPipelineRunCounter/myStage/myStageCounter/run-failed-jobs' \
      -u 'username:password' \
      -H 'X-GoCD-Confirm: true' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -X POST

HTTP/1.1 202 Accepted
Content-Type: application/vnd.go.cd.v1+json;charset=utf-8

{
  "message" : "Request to rerun jobs accepted"
}

Runs failed jobs in a completed stage.

Available since v18.11.0.

HTTP Request

POST /go/api/stages/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/run-failed-jobs

Returns

A text confirmation.

Run selected jobs

$ curl 'https://ci.example.com/go/api/stages/myPipeline/myPipelineRunCounter/myStage/myStageCounter/run-selected-jobs' \
      -u 'username:password' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/vnd.go.cd.v1+json' \
      -X POST \
      -d '{
            jobs: ["job1", "job2"]
      }'

HTTP/1.1 202 Accepted
Content-Type: application/vnd.go.cd.v1+json;charset=utf-8

{
  "message" : "Request to rerun jobs accepted"
}

Runs specified jobs in a completed stage.

Available since v18.11.0.

HTTP Request

POST /go/api/stages/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/run-selected-jobs

Following property must be specified:

Attribute	Type	Description
`jobs`	Array	A list job names that needs to be triggered again. This attribute MUST be specified.

Returns

A text confirmation.

Jobs

The jobs API allows users to view job information.

Get scheduled jobs

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

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<scheduledJobs>
  <job name="job1" id="6">
    <link rel="self" href="https://ci.example.com/go/tab/build/detail/mypipeline/5/defaultStage/1/job1"/>
    <buildLocator>mypipeline/5/defaultStage/1/job1</buildLocator>
  </job>
  <job name="job2" id="7">
    <link rel="self" href="https://ci.example.com/go/tab/build/detail/mypipeline/5/defaultStage/1/job2"/>
    <buildLocator>mypipeline/5/defaultStage/1/job2</buildLocator>
  </job>
</scheduledJobs>

Lists all the current job instances which are scheduled but not yet assigned to any agent.

Available since v14.3.0.

HTTP Request

GET /go/api/jobs/scheduled.xml

Returns

An array of scheduled job instances.

Get job history

$ curl 'https://ci.example.com/go/api/jobs/mypipeline/defaultStage/job1/history' \
      -u 'username:password'

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "jobs": [
    {
      "agent_uuid": null,
      "name": "job1",
      "job_state_transitions": [],
      "scheduled_date": 1436519914378,
      "original_job_id": null,
      "pipeline_counter": 5,
      "rerun": false,
      "pipeline_name": "mypipeline",
      "result": "Unknown",
      "state": "Scheduled",
      "id": 6,
      "stage_counter": "1",
      "stage_name": "defaultStage"
    },
    {
      "agent_uuid": "278fb0b6-d3b8-47e1-9443-67f26bfb5c15",
      "name": "job1",
      "job_state_transitions": [],
      "scheduled_date": 1436519733253,
      "original_job_id": null,
      "pipeline_counter": 4,
      "rerun": false,
      "pipeline_name": "mypipeline",
      "result": "Passed",
      "state": "Completed",
      "id": 4,
      "stage_counter": "1",
      "stage_name": "defaultStage"
    }
  ],
  "pagination": {
    "offset": 0,
    "total": 2,
    "page_size": 10
  }
}

The job history allows users to list job instances of specified job. Supports pagination using offset which tells the API how many instances to skip.

Available since v14.3.0.

HTTP Request

GET /go/api/jobs/:pipeline_name/:stage_name/:job_name/history

With pagination

GET /go/api/jobs/:pipeline_name/:stage_name/:job_name/history[/:offset]

Note: :offset is an optional parameter indicating the number of jobs to be skipped.

Returns

An array of jobs instances.

Properties

The properties API allows managing of job properties.

Get all job properties

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

cruise_agent,   cruise_timestamp_01_scheduled,  cruise_timestamp_02_assigned
myLocalAgent, 2015-07-09T11:59:08+05:30,      2015-07-09T11:59:16+05:30

Lists all job properties.

Available since v14.3.0.

HTTP Request

GET /go/properties/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/:job_name

Returns

CSV list containing property names and their corresponding value.

Get one property

$ curl 'http://ci.example.com/go/properties/PipelineName/541/StageName/1/JobName/cruise_agent' \
      -u 'username:password'

Gets a property by its name.

cruise_agent
myLocalAgent

Available since v14.3.0.

HTTP Request

GET /go/properties/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/:job_name/:property_name

Returns

Property name and its value.

Get historical properties

$ curl 'http://ci.example.com/go/properties/search?pipelineName=PipelineName&stageName=StageName&jobName=JobName&limitPipeline=latest&limitCount=2' \
        -u 'username:password'

cruise_agent,cruise_job_duration,cruise_job_id,cruise_job_result,cruise_pipeline_counter,cruise_pipeline_label,cruise_stage_counter,cruise_timestamp_01_scheduled,cruise_timestamp_02_assigned,cruise_timestamp_03_preparing,cruise_timestamp_04_building,cruise_timestamp_05_completing,cruise_timestamp_06_completed

myLocalAgent,0,13,Passed,8,4f9e580347b2e259fe030a775771359cdc984346,1,2015-07-07T09:44:27+05:30,2015-07-07T09:44:34+05:30,2015-07-07T09:44:44+05:30,2015-07-07T09:44:46+05:30,2015-07-07T09:44:46+05:30,2015-07-07T09:44:46+05:30

myLocalAgent,0,14,Passed,9,4f9e580347b2e259fe030a775771359cdc984346,1,2015-07-07T10:17:37+05:30,2015-07-07T10:17:45+05:30,2015-07-07T10:17:55+05:30,2015-07-07T10:17:56+05:30,2015-07-07T10:17:56+05:30,2015-07-07T10:17:56+05:30

Available since v14.3.0.

HTTP Request

GET /go/properties/search?pipelineName=:pipeline_name&stageName=:stage_name&jobName=:job_name&limitPipeline=:pipeline_counter&limitCount=:number

Note: limitPipeline and limitCount are optional parameters. The default value of limitPipeline is latest pipeline instance’s counter. The default value of limitCount is 100.

Returns

Job properties as CSV.

Create property

$ curl 'http://ci.example.com/go/properties/PipelineName/541/StageName/1/JobName/PropertyName' \
        -u 'username:password' \
        -H 'Confirm: true' \
        -X POST \
        -d 'value=PropertyValue'

Property 'PropertyName' created with value 'PropertyValue'

Available since v14.3.0.

Defines a property on a specific job instance.

HTTP Request

POST /go/properties/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/:job_name/:property_name

The following post parameter must be specified :

Attribute	Type	Description
`value`	String	The value of property.

Returns

An acknowledgement that the property was created.

Configuration

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

List all modifications

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "md5": "893d30ab646489d882f2350b10f47d0e",
    "commitSHA": "d2f9091145e2e4b3b22d938c4819610467ae20c1",
    "username": "admin",
    "goEdition": "OpenSource",
    "time": 1436253610465,
    "schemaVersion": 75,
    "goVersion": "N/A"
  },
  {
    "md5": "a2285d3304a51508c88e5479e327553c",
    "commitSHA": "f27b48594645c9f15f55bb56d0100dd60e4cbacc",
    "username": "admin",
    "goEdition": "OpenSource",
    "time": 1436253595701,
    "schemaVersion": 75,
    "goVersion": "N/A"
  }
 ]

Lists the config repository modifications.

Available since v14.3.0.

HTTP Request

GET /go/api/config/revisions

Returns

An array of repository modifications.

Get repository modification diff

$ curl 'https://ci.example.com/go/api/config/diff/d2f9091145e2e4b3b22d938c4819610467ae20c1/f27b48594645c9f15f55bb56d0100dd60e4cbacc' \
      -u 'username:password'

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

@@ -29,7 +29,7 @@
           <job name="up42_job">
             <tasks>
               <exec command="sleep">
-                <arg>40000</arg>
+                <arg>100</arg>
                 <runif status="passed" />
               </exec>
             </tasks>

Gets the diff between two config repository modifications.

Available since v14.3.0.

HTTP Request

GET /go/api/config/diff/:from_commit_sha/:to_commit_sha

Returns

The diff between two config repo modifications.

Get configuration

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

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

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

Returns

The contents of the configuration file.

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.

Feeds

The feed API allows users to view feed information.

Get all pipelines

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

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<pipelines>
 <link rel="self" href="https://ci.example.com/go/api/pipelines.xml"/>
    <pipeline href="https://ci.example.com/go/api/pipelines/pipeline1/stages.xml" />
    <pipeline href="https://ci.example.com/go/api/pipelines/pipeline2/stages.xml" />
</pipelines>

Lists all pipelines.

Available since v14.3.0.

HTTP Request

GET /go/api/pipelines.xml

Returns

An array of pipelines.

Get feed of all stages

$ curl 'https://ci.example.com/go/api/pipelines/mypipeline/stages.xml' \
      -u 'username:password'

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:go="http://www.thoughtworks-studios.com/ns/go">
    <title><![CDATA[mypipeline]]></title>
    <id>https://ci.example.com/go/api/pipelines/mypipeline/stages.xml</id>
    <author>
        <name>Go</name>
    </author>
    <updated>2015-07-13T10:59:49+05:30</updated>
    <link rel="self" href="https://ci.example.com/go/api/pipelines/mypipeline/stages.xml"/>
        <link rel="next" href="https://ci.example.com/go/api/pipelines/mypipeline/stages.xml?before=6"/>

        <entry>
            <title><![CDATA[mypipeline(2) stage defaultStage(1) Cancelled]]></title>
            <updated>2015-07-10T12:00:04+05:30</updated>
            <id>https://ci.example.com/go/pipelines/mypipeline/2/defaultStage/1</id>

            <author>
                <name><![CDATA[Pick E Reader <pick.e.reader@example.com>]]></name>
            </author>

            <link title="defaultStage Stage Detail" href="https://ci.example.com/go/api/stages/2.xml" rel="alternate" type="application/vnd.go+xml"/>
            <link title="defaultStage Stage Detail" href="https://ci.example.com/go/pipelines/mypipeline/2/defaultStage/1" rel="alternate" type="text/html"/>
            <link title="mypipeline Pipeline Detail" href="https://ci.example.com/go/api/pipelines/mypipeline/2.xml" rel="http://www.thoughtworks-studios.com/ns/relations/go/pipeline" type="application/vnd.go+xml"/>
            <link title="mypipeline Pipeline Detail" href="https://ci.example.com/go/pipelines/mypipeline/2/defaultStage/1/pipeline" rel="http://www.thoughtworks-studios.com/ns/relations/go/pipeline" type="text/html"/>

            <category scheme="http://www.thoughtworks-studios.com/ns/categories/go" term="stage" label="Stage" />
            <category scheme="http://www.thoughtworks-studios.com/ns/categories/go" term="completed" label="Completed" />
            <category scheme="http://www.thoughtworks-studios.com/ns/categories/go" term="cancelled" label="Cancelled" />
        </entry>
        <entry>
            <title><![CDATA[mypipeline(1) stage defaultStage(1) Passed]]></title>
            <updated>2015-07-10T11:57:22+05:30</updated>
            <id>https://ci.example.com/go/pipelines/mypipeline/1/defaultStage/1</id>

            <author>
                <name><![CDATA[Pick E Reader <pick.e.reader@example.com>]]></name>
            </author>

            <link title="defaultStage Stage Detail" href="https://ci.example.com/go/api/stages/1.xml" rel="alternate" type="application/vnd.go+xml"/>
            <link title="defaultStage Stage Detail" href="https://ci.example.com/go/pipelines/mypipeline/1/defaultStage/1" rel="alternate" type="text/html"/>
            <link title="mypipeline Pipeline Detail" href="https://ci.example.com/go/api/pipelines/mypipeline/1.xml" rel="http://www.thoughtworks-studios.com/ns/relations/go/pipeline" type="application/vnd.go+xml"/>
            <link title="mypipeline Pipeline Detail" href="https://ci.example.com/go/pipelines/mypipeline/1/defaultStage/1/pipeline" rel="http://www.thoughtworks-studios.com/ns/relations/go/pipeline" type="text/html"/>

            <category scheme="http://www.thoughtworks-studios.com/ns/categories/go" term="stage" label="Stage" />
            <category scheme="http://www.thoughtworks-studios.com/ns/categories/go" term="completed" label="Completed" />
            <category scheme="http://www.thoughtworks-studios.com/ns/categories/go" term="passed" label="Passed" />
        </entry>
</feed>

Gets feed of all stages for the specified pipeline with links to the pipeline and stage details.

Available since v14.3.0.

HTTP Request

GET /go/api/pipelines/:pipeline_name/stages.xml

Returns

An array of feed of stages.

Get pipeline

$ curl 'https://ci.example.com/go/api/pipelines/mypipeline/1.xml' \
      -u 'username:password'

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<pipeline name="mypipeline" counter="1" label="1">
  <link rel="self" href="https://ci.example.com/go/api/pipelines/mypipeline/1.xml"/>
  <id><![CDATA[urn:x-go.studios.thoughtworks.com:job-id:mypipeline:1]]></id>
  <scheduleTime>2015-07-10T11:55:18+05:30</scheduleTime>
  <materials>
    <material materialUri="https://ci.example.com/go/api/materials/405.xml" type="GitMaterial" url="URL: https://github.com/gocd/gocd" branch="master">
      <modifications>
        <changeset changesetUri="https://ci.example.com/go/api/materials/405/changeset/c194b49db102b705ebc13e604e490ae13ac92d96.xml">
          <user><![CDATA[Pick E Reader <pick.e.reader@example.com>]]></user>
          <checkinTime>2015-06-22T12:50:13+05:30</checkinTime>
          <revision><![CDATA[c194b49db102b705ebc13e604e490ae13ac92d96]]></revision>
          <message><![CDATA[Update README]]></message>
          <file name="README" action="modified"/>
        </changeset>
      </modifications>
    </material>
  </materials>
  <stages>
    <stage href="https://ci.example.com/go/api/stages/1.xml"/>
  </stages>
  <approvedBy><![CDATA[changes]]></approvedBy>
</pipeline>

Gets XML representation of pipeline.

Available since v14.3.0.

HTTP Request

GET /go/api/pipelines/:pipeline_name/:pipeline_id.xml

Returns

A pipeline object.

Get stage

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

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<stage name="defaultStage" counter="1">
  <link rel="self" href="https://ci.example.com/go/api/stages/2.xml"/>
  <id><![CDATA[urn:x-go.studios.thoughtworks.com:stage-id:mypipeline:2:defaultStage:1]]></id>
  <pipeline name="mypipeline" counter="2" label="2" href="https://ci.example.com/go/api/pipelines/mypipeline/2.xml"/>
  <updated>2015-07-10T12:00:04+05:30</updated>
  <result>Cancelled</result>
  <state>Completed</state>
  <approvedBy><![CDATA[admin]]></approvedBy>
  <jobs>
    <job href="https://ci.example.com/go/api/jobs/2.xml"/>
  </jobs>
</stage>

Gets XML representation of stage.

Available since v14.3.0.

HTTP Request

GET /go/api/stages/:stage_id.xml

Alternate APIs

GET /go/pipelines/:pipeline:name/:pipeline_counter/:stage_name/:stage_counter.xml

Returns

A stage object.

Get job

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

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<job name="defaultJob">
  <link rel="self" href="https://ci.example.com/go/api/jobs/2.xml"/>
  <id><![CDATA[urn:x-go.studios.thoughtworks.com:job-id:mypipeline:2:defaultStage:1:defaultJob]]></id>
  <pipeline name="mypipeline" counter="2" label="2"/>
  <stage name="defaultStage" counter="1" href="https://ci.example.com/go/api/stages/2.xml"/>
  <result>Cancelled</result>
  <state>Completed</state>
  <properties>
    <property name="cruise_agent"><![CDATA[INpicke.local]]></property>
    <property name="cruise_job_duration"><![CDATA[0]]></property>
    <property name="cruise_job_id"><![CDATA[2]]></property>
    <property name="cruise_job_result"><![CDATA[Cancelled]]></property>
    <property name="cruise_pipeline_counter"><![CDATA[2]]></property>
    <property name="cruise_pipeline_label"><![CDATA[2]]></property>
    <property name="cruise_stage_counter"><![CDATA[1]]></property>
    <property name="cruise_timestamp_01_scheduled"><![CDATA[2015-07-10T11:59:43+05:30]]></property>
    <property name="cruise_timestamp_02_assigned"><![CDATA[2015-07-10T11:59:52+05:30]]></property>
    <property name="cruise_timestamp_03_preparing"><![CDATA[2015-07-10T12:00:02+05:30]]></property>
    <property name="cruise_timestamp_06_completed"><![CDATA[2015-07-10T12:00:04+05:30]]></property>
  </properties>
  <agent uuid="278fb0b6-d3b8-47e1-9443-67f26bfb5c15"/>
  <artifacts baseUri="https://ci.example.com/go/files/mypipeline/2/defaultStage/1/defaultJob" pathFromArtifactRoot="pipelines/mypipeline/2/defaultStage/1/defaultJob"/>
  <resources/>
  <environmentvariables/>
</job>

Gets XML representation of job.

Available since v14.3.0.

HTTP Request

GET /go/api/jobs/:job_id.xml

Returns

A job 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'

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 with any administrator privilege to get the cipher text(encrypted text) corresponding to any plain text value. You may use this cipher text in other APIs that allow you to configure the pipelines and templates.

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

Encrypt a plain text value

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

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

{
  "_links": {
    "self": {
      "href": "http://ci.example.com/go/api/admin/encrypt"
    },
    "doc": {
      "href": "https://api.gocd.org/#encryption"
    }
  },
  "encrypted_value": "aSdiFgRRZ6A="
}

Returns the encrypted value for the plain text passed.

Available since v17.1.0.

HTTP Request

POST /go/api/admin/encrypt

Returns

The encrypted value of the plain text.

Pipeline Config

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

Important: Please note that this API requires using v6 of the API using Accept: application/vnd.go.cd.v7+json

The pipeline config object

Available since v15.3.0.

Attribute	Type	Description
`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.

Note: Credentials for git materials can be provided either in url or in username/password attributes. For security reasons it is recommended to provide the credentials in username/password attributes.

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.

Note: Credentials for mercurial materials can be provided either in url or in username/password attributes. For security reasons it is recommended to provide the credentials in username/password attributes.

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

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.

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 svn 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. Since v16.7.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",
    "authorization": {
      "roles": [

      ],
      "users": [

      ]
    }
  }
}

Attribute	Type	Description
`type`	String	The type of the approval on which stage will trigger. Can be one of `success`, `manual`.
`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.
`properties`	Array	The list of properties of the build from XML files or artifacts created during your build.
`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 property object

{
  "properties": [
    {
      "name": "coverage.class",
      "source": "target/emma/coverage.xml",
      "xpath": "substring-before(//report/data/all/coverage[starts-with(@type,'class')]/@value, '%')"
    }
  ]
}

Attribute	Type	Description
`name`	String	The name of the property.
`source`	String	The relative path to the XML file containing the data that you want to use to create the property.
`xpath`	String	The xpath that will be used to create property.

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. Can be one of `mingle`, `generic`.
`attributes`	Object	The attributes of the tracking tool. See attributes for generic and mingle tracking tools.

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 mingle tracking tool object

{
  "attributes": {
    "base_url": "https://mingle.example.com",
    "project_identifier": "foobar_widgets",
    "mql_grouping_conditions": "status > 'In Dev'"
  }
}

Attribute	Type	Description
`base_url`	String	The base URL of the Mingle server.
`project_identifier`	String	The project identfier can be found under the mingle project’s Project admin tab in the section titled Basic Information.
`mql_grouping_conditions`	String	The MQL string that determines the ‘passing criteria’ for cards displayed.

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.v7+json' \
      -i

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+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,
  "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}"
        }]
      } ],
      "properties" : null
    } ]
  }, {
    "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" : [ ],
      "properties" : null
    } ]
  } ],
  "tracking_tool" : null,
  "timer" : null
}

Gets pipeline config for specified pipeline name.

Updated to version v7 since v19.4.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.v7+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "e064ca0fe5d8a39602e19666454b8d77"' \
      -X PUT \
      -d '{
            "label_template": "${COUNT}",
            "lock_behavior": "unlockWhenFinished",
            "name": "my_pipeline",
            "template": null,
            "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"
                        }
                      }
                    ]
                  }
                ]
              }
            ]
          }'

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/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,
  "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}"
        }]
      } ],
      "properties" : null
    } ]
  }, {
    "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" : [ ],
      "properties" : null
    } ]
  } ],
  "tracking_tool" : null,
  "timer" : null
}

Update pipeline config for specified pipeline name.

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

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

Updated to version v7 since v19.4.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.v7+json' \
      -H 'Content-Type: application/json' \
      -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"
                                }
                              }
                            ]
                          }
                        ]
                      }
                    ]
                }
              }'

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/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,
  "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}"
        }]
      } ],
      "properties" : null
    } ]
  }, {
    "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" : [ ],
      "properties" : null
    } ]
  } ],
  "tracking_tool" : null,
  "timer" : null
}

Create a pipeline.

Updated to version v7 since v19.4.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.v7+json' \
      -X DELETE

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

{
  "message": "Pipeline 'my_pipeline' was deleted successfully."
}

Deletes a pipeline from the config XML.

Updated to version v7 since v19.4.0.

Available since v16.6.0.

HTTP Request

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

Returns

A message confirmation if the pipeline was deleted.

Template Config

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

Important: Please note that this API requires using v4 of the API using Accept: application/vnd.go.cd.v4+json

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.v4+json'

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

Lists all available templates with the associated pipelines’ names.

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.v4+json' \
      -i

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/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}"
        } ]
      } ],
      "properties" : null
    } ]
  }, {
    "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" : [ ],
      "properties" : null
    } ]
  } ]
}

Gets template config for specified template name.

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.v4+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"
                    }
                  }
                ]
              }
            ]
          }
        ]
      }'

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/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}"
        } ]
      } ],
      "properties" : null
    } ]
  }, {
    "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" : [ ],
      "properties" : null
    } ]
  } ]
}

Creates a template config object.

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.v4+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"
                    }
                  }
                ]
              }
            ]
          }
        ]
      }'

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/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}"
        } ]
      } ],
      "properties" : null
    } ]
  }, {
    "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" : [ ],
      "properties" : null
    } ]
  } ]
}

Update template config for specified template name.

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

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

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.v4+json' \
      -X DELETE

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+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.

Available since v16.10.0.

HTTP Request

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

Returns

A message confirmation if the template was deleted.

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'

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

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.

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

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

Available since v18.2.0.

HTTP Request

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

Returns

The template authorization 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'

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'

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

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

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

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

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

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

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.

Version

The Version API allows users to get the GoCD server version details.

The version object

Available since v16.6.0.

Attribute	Type	Description
`version`	String	The GoCD server version.
`build_number`	Integer	The GoCD server build number.
`git_sha`	String	The git SHA from which this server version was built.
`full_version`	String	The GoCD server full version.
`commit_url`	String	TThe GitHub url to the `git_sha`.

Get version

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

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

{
  "_links": {
    "self": {
      "href": "https://build.go.cd/go/api/version"
    },
    "doc": {
      "href": "https://api.gocd.org/#version"
    }
  },
  "version": "16.6.0",
  "build_number": "3348",
  "git_sha": "a7a5717cbd60c30006314fb8dd529796c93adaf0",
  "full_version": "16.6.0 (3348-a7a5717cbd60c30006314fb8dd529796c93adaf0)",
  "commit_url": "https://github.com/gocd/gocd/commits/a7a5717cbd60c30006314fb8dd529796c93adaf0"
}

Gets the current GoCD server details

Available since v16.6.0.

HTTP Request

GET /go/api/version

Returns

The version object.

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.
`agents`	Array	List of agent uuids 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.v2+json'

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+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"
          }
        ],
        "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": "12345678-e2f6-4c78-123456789012"
          }
        ],
        "environment_variables": [
          {
            "secure": false,
            "name": "username",
            "value": "admin"
          },
          {
            "secure": true,
            "name": "password",
            "encrypted_value": "LSd1TI0eLa+DjytHjj0qjA=="
          }
        ]
      }
    ]
  }
}

Lists all available environments.

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.v2+json'

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+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"
    }
  ],
  "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": "12345678-e2f6-4c78-123456789012"
    }
  ],
  "environment_variables": [
    {
      "secure": false,
      "name": "username",
      "value": "admin"
    },
    {
      "secure": true,
      "name": "password",
      "encrypted_value": "LSd1TI0eLa+DjytHjj0qjA=="
    }
  ]
}

Gets environment config for specified environment name.

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.v2+json' \
      -H 'Content-Type: application/json' \
      -X POST -d '{
        "name" : "new_environment",
        "pipelines" : [
          {
          "name" : "up2"
          }
        ],
        "agents" : [
          {
            "uuid" : "12345678-e2f6-4c78-123456789012"
          }
        ],
        "environment_variables" : [
          {
            "name" : "username",
            "value" : "admin",
            "secure" : false
          }
        ]
      }'

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+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"
    }
  ],
  "agents": [
    {
      "_links": {
        "self": {
          "href": "https://ci.example.com/go/api/agents/12345678-e2f6-4c78-123456789012"
        },
        "doc": {
          "href": "https://api.gocd.org/#agents"
        },
        "find": {
          "href": "https://ci.example.com/go/api/agents/:uuid"
        }
      },
      "uuid": "12345678-e2f6-4c78-123456789012"
    }
  ],
  "environment_variables": [
    {
      "secure": false,
      "name": "username",
      "value": "admin"
    },
    {
      "secure": true,
      "name": "password",
      "encrypted_value": "LSd1TI0eLa+DjytHjj0qjA=="
    }
  ]
}

Creates an environment

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.
`agents`	Array	The list of agent uuids 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.v2+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "26b227605daf6f2d7768c8edaf61b861"' \
      -X PUT \
      -d '{
        "name" : "new_environment",
        "pipelines" : [ { "name" : "pipeline1" } ]
      }'

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+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"
    }
  ],
  "agents": [

  ],
  "environment_variables": [

  ]
}

Update some attributes of an environment.

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

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

Available since v16.7.0.

HTTP Request

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

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

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

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.v2+json' \
      -H 'Content-Type: application/json' \
      -X PATCH \
      -d '{
      "pipelines": {
        "add": ["up42"],
        "remove": ["sample"]
      },
      "agents": {
        "add": ["12345678-e2f6-4c78-123456789012"],
        "remove": ["87654321-e2f6-4c78-123456789012"]
      },
      "environment_variables": {
          "add": [
            {
              "name": "GO_SERVER_URL",
              "value": "https://ci.example.com/go"
            }
          ],
          "remove": ["URL"]
      }
}'

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+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"
    }
  ],
  "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": "12345678-e2f6-4c78-123456789012"
    }
  ],
  "environment_variables": [
    {
      "name": "GO_SERVER_URL",
      "value": "https://ci.example.com/go",
      "secure": false
    }
  ]
}

Update some attributes of an environment.

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"
    ]
  },
  "agents": {
    "add": [
      "agent05",
      "agent02"
    ],
    "remove": [
      "agent01"
    ]
  },
  "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.
`agents`	Object	The agents update operation to be performed on the set of agents.
`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 agent-update operation attributes

{
  "add": [
    "agent05",
    "agent02"
  ],
  "remove": [
    "agent01"
  ]
}

Attribute	Type	Description
`add`	Array	The list of agents which needs to be added to the specified environment.
`remove`	Array	The list of agents 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.v2+json' \
      -X DELETE

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

{
  "message": "Environment 'my_environment' was deleted successfully."
}

Deletes an environment.

Available since v16.7.0.

HTTP Request

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

Returns

A message confirmation if the environment was deleted.

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'

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'

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

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

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.

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

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

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

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.

Plugin Info

The plugin info API allows users with administrator role to fetch information about installed plugins.

The plugin info object

Available since v19.3.0.

Attribute	Type	Description
`id`	String	Plugin unique identifier.
`status`	Object	The status of the plugin.
`plugin_file_location`	String	The location where the plugin is installed.
`bundled_plugin`	Boolean	Indicates whether the plugin is bundled with GoCD.
`about`	Object	Additional details about the plugin.
`extensions`	Array	A list of extension information pertaining to the list of extensions the plugin implements.

The plugin status object

{
  "state": "invalid",
  "messages": [
    "Plugin not supported"
  ]
}

Attribute	Type	Description
`state`	String	Status of the plugin. Can be one of `active`, `invalid`.
`messages`	Array	Array of messages stating the reason why the plugin isn’t loaded. The messages are shown only if the status is invalid.

The plugin vendor object

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

Attribute	Type	Description
`name`	String	Name of the plugin author.
`url`	String	Link to know more details about the plugin author.

The plugin about object

{
  "name": "GitHub Pull Requests Builder",
  "version": "1.3.3",
  "target_go_version": "15.1.0",
  "description": "Plugin that polls a GitHub repository for pull requests and triggers a build for each of them",
  "target_operating_systems": [

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

Attribute	Type	Description
`name`	String	Name of the plugin.
`version`	String	Version of the plugin that’s installed.
`target_go_version`	String	Minimal version of GoCD required for the plugin to work.
`description`	String	Short description about what the plugin does.
`target_operating_systems`	Array	List of operating systems on which the plugin is expected to work.
`vendor`	Object	Details about the plugin author.

Extension information object: Config repo

{
  "extensions": [
    {
      "type": "configrepo",
      "plugin_settings": {
        "configurations": [
          {
            "key": "url",
            "metadata": {
              "secure": false,
              "required": true
            }
          }
        ],
        "view": {
          "template": "<div>Plugin view template</div>"
        }
      },
      "capabilities": {
        "supports_pipeline_export": true,
        "supports_parse_content": true
      }
    }
  ]
}

Attribute	Type	Description
`type`	String	The type of the extension, which is `configrepo`.
`plugin_settings`	Object	The html view for the plugin and the list of properties required to be configured.
`capabilities`	Object	The capabilities object indicates the enhancements that a plugin provides.

Extension information object: Elastic agent

{
  "extensions": [
    {
      "type": "elastic",
      "elastic_agent_profile_settings": {
        "configurations": [
          {
            "key": "Image",
            "metadata": {
              "secure": false,
              "required": true
            }
          }
        ],
        "view": {
          "template": "<div>Elastic agent profile template</div>"
        }
      },
      "supports_cluster_profiles": true,
      "cluster_profile_settings": {
        "configurations": [
          {
            "key": "EfsDnsOrIP",
            "metadata": {
              "secure": false,
              "required": true
            }
          }
        ],
        "view": {
          "template": "<div>Cluster Profile view template</div>"
        }
      },
      "capabilities": {
        "supports_plugin_status_report": true,
        "supports_agent_status_report": true,
        "supports_cluster_status_report": true
      }
    },
    {
      "type": "elastic",
      "elastic_agent_profile_settings": {
        "configurations": [
          {
            "key": "Image",
            "metadata": {
              "secure": false,
              "required": true
            }
          }
        ],
        "view": {
          "template": "<div>Elastic agent profile template</div>"
        }
      },
      "supports_cluster_profiles": false,
      "plugin_settings": {
        "configurations": [
          {
            "key": "EfsDnsOrIP",
            "metadata": {
              "secure": false,
              "required": true
            }
          }
        ],
        "view": {
          "template": "<div>Plugin view template</div>"
        }
      },
      "capabilities": {
        "supports_plugin_status_report": true,
        "supports_agent_status_report": true,
        "supports_cluster_status_report": false
      }
    }
  ]
}

Attribute	Type	Description
`type`	String	The type of the extension, which is `elastic`.
`plugin_settings`	Object	The html view for the plugin and the list of properties required to be configured. Present in case of plugin supports plugin settings. .
`supports_cluster_profiles`	Boolean	Boolean indicating whether plugin supports defining cluster profiles.
`elastic_agent_profile_settings`	Object	The html view for the elastic agent profile and the list of properties required to be configured.
`cluster_profile_settings`	Object	The html view for the cluster profile and the list of properties required to be configured. Present in case of plugin supports defining cluster profiles.
`capabilities`	Object	The capabilities object indicates the enhancements that a plugin provides.

Extension information object: Authorization

{
  "extensions": [
    {
      "type": "authorization",
      "auth_config_settings": {
        "configurations": [
          {
            "key": "Id",
            "metadata": {
              "secure": false,
              "required": true
            }
          }
        ],
        "view": {
          "template": "<div>Auth view template</div>"
        }
      },
      "role_settings": {
        "configurations": [
          {
            "key": "Name",
            "metadata": {
              "secure": false,
              "required": true
            }
          }
        ],
        "view": {
          "template": "<div>Role view template</div>"
        }
      },
      "capabilities": {
        "can_search": true,
        "supported_auth_type": "password",
        "can_authorize": true
      }
    }
  ]
}

Attribute	Type	Description
`type`	String	The type of the extension, which is `authorization`.
`auth_config_settings`	Object	The html view for auth config and the list of properties that can be used to configure auth configs.
`role_settings`	Object	The html view for role config and the list of properties that can be used to configure role configs.
`capabilities`	Object	The capabilities object indicates the enhancements that a plugin provides.

Extension information object: SCM

{
  "extensions": [
    {
      "type": "scm",
      "display_name": "Github",
      "scm_settings": {
        "configurations": [
          {
            "key": "url",
            "metadata": {
              "secure": false,
              "required": true,
              "part_of_identity": true
            }
          }
        ],
        "view": {
          "template": "<div>Scm view template</div>"
        }
      }
    }
  ]
}

Attribute	Type	Description
`type`	String	The type of the extension, which is `scm`.
`display_name`	String	The descriptive name of the plugin.
`scm_settings`	Object	The html view for pluggable scm and the list of properties that can be used to configure the pluggable scm material.

Extension information object: Task

{
  "extensions": [
    {
      "type": "task",
      "display_name": "Task",
      "task_settings": {
        "configurations": [
          {
            "key": "script",
            "metadata": {
              "secure": false,
              "required": true
            }
          }
        ],
        "view": {
          "template": "<div>task view template</div>"
        }
      }
    }
  ]
}

Attribute	Type	Description
`type`	String	The type of the extension, which is `task`.
`display_name`	String	The descriptive name of the plugin.
`task_settings`	Object	The html view for pluggable task and the list of properties that can be used to configure the pluggable task.

Extension information object: Package repo

{
  "extensions": [
    {
      "type": "package-repository",
      "package_settings": {
        "configurations": [
          {
            "key": "PACKAGE_SPEC",
            "metadata": {
              "secure": false,
              "display_order": 0,
              "required": true,
              "part_of_identity": false,
              "display_name": "Package Spec"
            }
          }
        ]
      },
      "repository_settings": {
        "configurations": [
          {
            "key": "REPO_URL",
            "metadata": {
              "secure": false,
              "display_order": 0,
              "required": true,
              "part_of_identity": false,
              "display_name": "Repository URL"
            }
          }
        ]
      }
    }
  ]
}

Attribute	Type	Description
`type`	String	The type of the extension, which is `package-repository`.
`package_settings`	Object	The list of properties that can be used to configure a package material. A form is created for the user based on these properties. No request is currently made to fetch the view for package settings.
`repository_settings`	Object	The list of properties that can be used to configure package repositories. A form is created for the user based on these properties. No request is currently made to fetch the view for repository settings.

Extension information object: Notification

{
  "extensions": [
    {
      "type": "notification",
      "plugin_settings": {
        "configurations": [
          {
            "key": "url",
            "metadata": {
              "secure": false,
              "required": true
            }
          }
        ],
        "view": {
          "template": "<div>Plugin view template</div>"
        }
      }
    }
  ]
}

Attribute	Type	Description
`type`	String	The type of the extension, which is `notification`.
`plugin_settings`	Object	The html view for the plugin and the list of properties required to be configured.

Extension information object: Analytics

{
  "extensions": [
    {
      "type": "analytics",
      "plugin_settings": {
        "configurations": [
          {
            "key": "analytics_source_url",
            "metadata": {
              "secure": false,
              "required": true
            }
          }
        ],
        "view": {
          "template": "<div>Plugin view template</div>"
        }
      },
      "capabilities": {
        "supported_analytics": [
          {
            "type": "pipeline",
            "id": "pipeline_duration",
            "title": "Pipeline Duration"
          }
        ]
      }
    }
  ]
}

Attribute	Type	Description
`type`	String	The type of the extension, which is `analytics`.
`plugin_settings`	Object	The html view for the plugin and the list of properties required to be configured.
`capabilities`	Object	The capabilities object indicates the enhancements that a plugin provides.

Extension information object: Artifact

{
  "extensions": [
    {
      "type": "artifact",
      "store_config_settings": {
        "configurations": [
          {
            "key": "RegistryURL",
            "metadata": {
              "secure": false,
              "required": true
            }
          }
        ],
        "view": {
          "template": "<div>Plugin view template</div>"
        }
      },
      "artifact_config_settings": {
        "configurations": [
          {
            "key": "BuildFile",
            "metadata": {
              "secure": false,
              "required": false
            }
          }
        ],
        "view": {
          "template": "<div>Plugin view template</div>"
        }
      },
      "fetch_artifact_settings": {
        "configurations": [
          {
            "key": "EnvironmentVariablePrefix",
            "metadata": {
              "secure": false,
              "required": false
            }
          }
        ],
        "view": {
          "template": "<div>Plugin view template</div>"
        }
      }
    }
  ]
}

Attribute	Type	Description
`type`	String	The type of the extension, which is `artifact`.
`store_config_settings`	Object	The html view to configure the artifact store and the list of properties that can be used to configure the artifact store.
`artifact_config_settings`	Object	The html view to configure the publish artifact configs and the list of properties that can be used to configure publish artifact config.
`fetch_artifact_settings`	Object	The html view to configure the fetch artifact config and the list of properties that can be used to configure fetch artifact config.

The plugin info configurations object

{
  "configurations": [
    {
      "key": "url",
      "metadata": {
        "secure": false,
        "required": true
      }
    }
  ]
}

Attribute	Type	Description
`key`	String	Describes the configuration key.
`metadata`	Object	Metadata for the configuration property. The metadata consists of attributes `secure`, `required`. The attributes for package-repository and scm plugins are given below.

The package repository configurations object

{
  "configurations": [
    {
      "key": "REPO_URL",
      "metadata": {
        "secure": false,
        "display_order": 0,
        "required": true,
        "part_of_identity": false,
        "display_name": "Repository URL"
      }
    }
  ]
}

Attribute	Type	Description
`key`	String	Describes the configuration key for a repository configuration property.
`metadata`	Object	Metadata for the configuration property.

The scm configurations object

{
  "configurations": [
    {
      "key": "REPO_URL",
      "metadata": {
        "secure": false,
        "required": true,
        "part_of_identity": false
      }
    }
  ]
}

Attribute	Type	Description
`key`	String	Describes the configuration key for a repository configuration property.
`metadata`	Object	Metadata for the configuration property.

The plugin info view object

{
  "view": {
    "template": "<div>Plugin view template</div>"
  }
}

Attribute	Type	Description
`template`	String	The plugin Angular.js view template.

The Config Repo Capabilities object

{
  "capabilities": {
    "supports_pipeline_export": true,
    "supports_parse_content": true
  }
}

Attribute	Type	Description
`supports_pipeline_export`	Boolean	Indicates if plugin supports pipeline configuration export.
`supports_parse_content`	Boolean	Indicates if plugin supports parse content.

The Elastic Agents Capabilities object

{
  "capabilities": {
    "supports_plugin_status_report": true,
    "supports_agent_status_report": true,
    "supports_cluster_status_report": true
  }
}

Attribute	Type	Description
`supports_plugin_status_report`	Boolean	Indicates if plugin supports plugin level status report.
`supports_agent_status_report`	Boolean	Indicates if plugin supports elastic agent status report for a specific agent.
`supports_cluster_status_report`	Boolean	Indicates if plugin supports cluster profile status report for a specific agent.

The Authorization Capabilities object

{
  "capabilities": {
    "can_search": true,
    "supported_auth_type": "password",
    "can_authorize": true
  }
}

Attribute	Type	Description
`can_search`	Boolean	Indicates if plugin supports user search.
`supported_auth_type`	String	Specifies the type of authentication supported, can be one of `password` or `web`.
`can_authorize`	Boolean	Indicates if plugin supports authorization.

The Analytics Capabilities object

The analytics capablities contains a list of supported_analytics, with the following attributes.

{
  "capabilities": {
    "supported_analytics": [
      {
        "type": "pipeline",
        "id": "pipeline_duration",
        "title": "Pipeline Duration"
      }
    ]
  }
}

Attribute	Type	Description
`id`	String	Unique identifier for an analytics.
`title`	String	Title for the analytics.
`type`	String	The type of the analytics.

Get all plugin info

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

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v5+json; charset=utf-8
ETag: "3924a894cf0e5bef02abe9de0df3bb84"

{
  "_links": {
    "self": {
      "href": "http://localhost:8153/go/api/admin/plugin_info"
    },
    "find": {
      "href": "http://localhost:8153/go/api/admin/plugin_info/:plugin_id"
    },
    "doc": {
      "href": "https://api.gocd.org/#plugin-info"
    }
  },
  "_embedded": {
    "plugin_info": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/plugin_info/json.config.plugin"
          },
          "doc": {
            "href": "https://api.gocd.org/#plugin-info"
          },
          "find": {
            "href": "https://ci.example.com/go/api/admin/plugin_info/:id"
          }
        },
        "id": "json.config.plugin",
        "status": {
          "state": "active"
        },
        "plugin_file_location": "/Users/varshavs/gocd/server/plugins/bundled/gocd-json-config-plugin.jar",
        "bundled_plugin": true,
        "about": {
          "name": "JSON Configuration Plugin",
          "version": "0.2",
          "target_go_version": "16.1.0",
          "description": "Configuration plugin that supports GoCD configuration in JSON",
          "target_operating_systems": [

          ],
          "vendor": {
            "name": "Tomasz Setkowski",
            "url": "https://github.com/tomzo/gocd-json-config-plugin"
          }
        },
        "extensions": [
          {
            "type": "configrepo",
            "plugin_settings": {
              "configurations": [
                {
                  "key": "pipeline_pattern",
                  "metadata": {
                    "secure": false,
                    "required": false
                  }
                },
                {
                  "key": "environment_pattern",
                  "metadata": {
                    "secure": false,
                    "required": false
                  }
                }
              ],
              "view": {
                "template": "Some view"
              }
            }
          }
        ]
      }
    ]
  }
}

Lists all available plugin info.

Available since v19.3.0.

HTTP Request

GET /go/api/admin/plugin_info

Returns

An array of plugin info objects.

Get plugin info

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

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v5+json; charset=utf-8
ETag: "4167e3ec81fdac0fb29d854b36ceb981"

{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/plugin_info/my_plugin"
    },
    "doc": {
      "href": "https://api.gocd.org/#plugin-info"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/plugin_info/:id"
    }
  },
  "id": "my_plugin",
  "status": {
    "state": "active"
  },
  "plugin_file_location": "/path/to/server/plugins/external/my_plugin.jar",
  "bundled_plugin": false,
  "about": {
    "name": "My Plugin",
    "version": "0.2",
    "target_go_version": "16.1.0",
    "description": "Short desc",
    "target_operating_systems": [

    ],
    "vendor": {
      "name": "GoCD contributors",
      "url": "https://github.com/tomzo/gocd-json-config-plugin"
    }
  },
  "extensions": [
    {
      "type": "configrepo",
      "plugin_settings": {
        "configurations": [
          {
            "key": "pipeline_pattern",
            "metadata": {
              "secure": false,
              "required": false
            }
          },
          {
            "key": "environment_pattern",
            "metadata": {
              "secure": false,
              "required": false
            }
          }
        ],
        "view": {
          "template": "Some view"
        }
      }
    }
  ]
}

Gets plugin info for a specified plugin id.

Available since v19.3.0.

HTTP Request

GET /go/api/admin/plugin_info/:id

Returns

The plugin info object.

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

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.

Available since v17.9.0.

HTTP Request

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

Returns

A Plugin Settings object

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

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.

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

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.

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

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

Available since v17.9.0.

HTTP Request

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

Returns

The updated Plugin Settings object.

SCMs

The pluggable SCM API 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.v1+json'

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.

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.v1+json'
      -i

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

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.v1+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="
    }
  ]
 }'

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

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.v1+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="
            }
            ]
          }'

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

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

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

Available since v16.7.0.

HTTP Request

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

Returns

The updated SCM object.

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'

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

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

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

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.

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

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

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

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.

Packages

The package definition API 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.v1+json'

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

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.v1+json'
      -i

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+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.

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.v1+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"
    }
  ]
}'

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

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.v1+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"
  }]
}'

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

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

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

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.v1+json' \
      -X DELETE

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+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.

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.
`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.v1+json'

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/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",
        "properties": [
          {
            "key": "Url",
            "value": "ldap://ldap.server.url"
          }
        ]
      }
    ]
  }
}

Lists all available authorization configurations.

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.v1+json'

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/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",
  "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.

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.v1+json' \
      -H 'Content-Type: application/json' \
      -X POST -d '{
        "id": "ldap",
        "plugin_id": "cd.go.authentication.ldap",
        "properties": [
          {
            "key": "Url",
            "value": "ldap://ldap.server.url:389"
          },
          ...
        ]
      }'

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/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",
  "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

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.v1+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"' \
      -X PUT \
      -d '{
        "plugin_id": "cd.go.authentication.ldap",
        "properties": [
          {
            "key": "Url",
            "value": "ldap://ldap.server.url:10389"
          },
          {
            "key": "SearchBase",
            "value": "ou=users,ou=system"
          },
          {
            "key": "ManagerDN",
            "value": "uid=admin,ou=system"
          }
          ...
        ]
      }'

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/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",
  "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.

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

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

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.v1+json' \
      -X DELETE

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

{
  "message": "The security auth config 'ldap' was deleted successfully."
}

Deletes the authorization configuration.

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.

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.

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.v2+json'

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/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"]
        }
      },
      {
        "_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"
            }
          ]
        }
      }
    ]
  }
}

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

Available since v17.5.0.

HTTP Request

GET /go/api/admin/security/roles

Returns

An array of role object.

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.v2+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"]
        }
      }
    ]
  }
}

List all available roles of specified type.

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.v2+json'

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

Gets role for specified role name.

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.v2+json' \
      -H 'Content-Type: application/json' \
      -X POST -d '{
         "name": "new-role",
         "type": "gocd",
         "attributes" : {
          "users": ["bob"]
         }
        }'

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

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

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.v2+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"
            }
          ]
        }
      }'

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

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

Prerequisite to create plugin role,

Install authorization plugin with can_authorize capability.
Create authorization configuration.

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.v2+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"' \
      -X PUT \
      -d '{
        "name": "spacetiger",
        "type": "gocd",
        "attributes": {
          "users": ["alice"]
        }
      }'

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

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

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

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.v2+json' \
      -X DELETE

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

{
  "message": "The plugin role config 'blackbird' was deleted successfully."
}

Deletes the role.

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.v2+json' \
      -X PATCH \
      -d '{
      "operations": [
        {
          "role": "role1",
          "users": {
            "add": [
              "user1",
              "user2"
            ],
            "remove": [
              "user3",
              "user4"
            ]
          }
        },
        {
          "role": "role2",
          "users": {
            "add": [
              "user2"
            ]
          }
        }
      ]
    }'

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

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.

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.

The config repository material object

Attribute	Type	Description
`type`	String	The type of a material. Can be one of `git`, `svn`, `hg`, `p4`, `tfs`, `scm`.
`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.

The package material attributes

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

Attribute	Type	Description
`ref`	String	The unique package repository id.

Get all Config repos

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

HTTP/1.1 200 OK
Content-Type: application/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": [
        ]
      }
    ]
  }
}

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

Updated to version v2 since v19.4.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.v2+json' \
      -i

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+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": [

  ]
}

Gets the config repo object for a specified id.

Updated to version v2 since v19.4.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.v2+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"
     }
    ]
  }'

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

Create a config repo object.

Updated to version v2 since v19.4.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.v2+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "e064ca0fe5d8a39602e19666454b8d77"' \
      -X PUT \
      -d '{
            "id": "repo-1",
            "plugin": "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"
             }
            ]
          }'

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

Update config repos for specified config repo id.

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

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

Updated to version v2 since v19.4.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.v2+json' \
      -X DELETE

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

{
  "message": "The config repo 'repo-1' was deleted successfully."
}

Deletes the config repo.

Updated to version v2 since v19.4.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' \

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'

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

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 th

Introduction

API versions

Authentication

Bearer token authentication

Basic authentication

Cookie/Session authentication

Server Health

Check Server Health

Agents

The agent object

The Environment object

The Environment Origin object

Get all agents

Get one agent

Update an agent

Delete an agent

Bulk update agents

The bulk update operation attributes

The environment update operation attributes

The resources update operation attributes

Bulk delete agents

Agent job run history

The build details object

Access Tokens

The access token object

Get all tokens for current user

Get one token for current user

Create token for current user

Revoke token for current user

Get all tokens for all users

Get one token for any user

Revoke token for any user

Agent Health

Check agent-server connectivity

Users

The user object

Get all users

Get one user

Create a user

Update a user

Delete a user

Bulk Delete Users

Bulk Enable/Disable Users

The user role object

Current User

Get current user

Update current user

Notification Filters

The notification filter object

Show all notification filters

Create a notification filter

Delete a notification filter

Materials

The material object

Get all materials

Get material modifications

Notify SVN materials

Notification script

Notify git materials

Notification script

Hosting your repository on BitBucket?

Returns

Hosting your repository on GitHub, or GitHub Enterprise?

Returns

Hosting your repository on GitLab?

Returns

Notify Mercurial materials

Notification script

Notify other scm materials

Backups

The Backup Object

Schedule Backup

Get Backup

Pipeline Groups

Config listing

Artifacts

The artifact object

Get all artifacts

Get artifact file

Get artifact directory