NAV Navbar
Logo
shell
Switch version:

Introduction

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

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

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

Current version

By default, all requests receive Version 1 of the API. It is recommended to explicitly request this version via the Accept header.

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

If you specify an unsupported, Accept header, GoCD will respond with the current default JSON representation of the resource.

Authentication

All APIs require you to authenticate yourself using your username and password. 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, Go may return status codes 401, 403 or 404.

Basic authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
$ curl 'https://ci.example.com/go/api/agents' \
      -u 'username:password' \
      -H 'Accept: application/vnd.go.cd.v2+json' \

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

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": {
    "self": {
      "href": "https://ci.example.com/go/api/agents"
    },
    "doc": {
      "href": "https://api.gocd.io/#agents"
    }
  },
  "_embedded": {
    "agents": []
  }
}

To use Basic Authentication with the Go 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 go is authenticating against an external source like LDAP.

$ curl 'https://ci.example.com/go/api'
      -b 'JSESSIONID=15kvus1kdrec46vk2a6jmtmo' \
      -H 'Accept: application/vnd.go.cd.v1+json'

The above command returns the following response

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": {
    "self": {
      "href": "https://ci.example.com/go/api/agents"
    },
    "doc": {
      "href": "https://api.gocd.io/#agents"
    }
  },
  "_embedded": {
    "agents": []
  }
}

Agents

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

The agent object

Available since v15.2.0.

Attribute Type Description
uuid String The identifier of this agent.
hostname String The hostname of the agent.
elastic_agent_id String The elastic agent identifier of this agent. This attribute is only available if the agent is an elastic agent. Since v16.8.0.
elastic_plugin_id String The identifier of the elastic agent plugin that manages this agent instance. This attribute is only available if the agent is an elastic agent. Since v16.8.0.
ip_address String The IP address of the agent.
sandbox String The path where the agent will perform its builds.
operating_system String The operating system as reported by the agent.
free_space Integer The amount of free space in bytes.
agent_config_state String Whether an agent is enabled or not. Can be one of Pending, Enabled, Disabled. Since v15.3.0.
agent_state String The state an agent is in. Can be one of Idle, Building, LostContact, Missing, Building, Unknown. Since v15.3.0.
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.
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.

Get all agents

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

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/agents"
    },
    "doc": {
      "href": "https://api.gocd.io/#agents"
    }
  },
  "_embedded": {
    "agents": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da"
          },
          "doc": {
            "href": "https://api.gocd.io/#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": ["perf", "UAT"],
        "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.

Available since v15.2.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.v4+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da"
    },
    "doc": {
      "href": "https://api.gocd.io/#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": ["perf", "UAT"],
  "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)

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.v4+json' \
      -H 'Content-Type: application/json' \
      -X PATCH \
      -d '{
        "hostname": "agent02.example.com",
        "agent_config_state": "Enabled",
        "resources": ["Java","Linux"],
        "environments": ["Dev"]
        }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da"
    },
    "doc": {
      "href": "https://api.gocd.io/#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": ["Dev"],
  "build_state": "Idle"
}

Update some attributes of an agent.

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

The above command returns JSON structured like this:

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

Deletes an agent.

Available since v15.2.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.v4+json' \
      -H 'Content-Type: application/json' \
      -X PATCH \
      -d '{
            "uuids": [
              "adb9540a-b954-4571-9d9b-2f330739d4da",
              "adb528b2-b954-1234-9d9b-b27ag4h568e1"
            ],
            "operations": {
              "environments": {
                "add": ["Dev", "Test"],
                "remove": ["Production"]
              },
              "resources": {
                "add": ["Linux", "Firefox"],
                "remove": ["Chrome"]
              }
            },
            "agent_config_state" : "enabled"
          }'

The above command returns JSON structured like this:

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

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.v4+json' \
      -H 'Content-Type: application/json' \
      -X DELETE \
      -d '{
            "uuids": [
              "adb9540a-b954-4571-9d9b-2f330739d4da",
              "adb528b2-b954-1234-9d9b-b27ag4h568e1"
            ]
          }'

The above command returns JSON structured like this:

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

Deletes a list of agents.

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'

The above command returns JSON structured like this:

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.

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]

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.

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.

Get all users

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

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/users"
    },
    "doc": {
      "href": "https://api.gocd.io/#users"
    }
  },
  "_embedded": {
    "users": [
      {
        "_links": {
          "doc": {
            "href": "https://api.gocd.io/#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,
        "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.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "doc": {
      "href": "https://api.gocd.io/#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,
  "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.v1+json' \
      -H 'Content-Type: application/json' \
      -X POST \
      -d '{
            "email": "jdoe@example.com",
            "login_name": "jdoe"
          }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "doc": {
      "href": "https://api.gocd.io/#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,
  "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.v1+json' \
      -H 'Content-Type: application/json' \
      -X PATCH \
      -d '{
            "email": "jdoe@example.com",
            "email_me": true,
            "checkin_aliases": ["jdoe", "johndoe"]
          }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "doc": {
      "href": "https://api.gocd.io/#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 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 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

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

The above command returns JSON structured like this:

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

Materials

The materials API allows users to query and notify materials in the Go 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'

The above command returns JSON structured like this:

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'

The above command returns JSON structured like this:

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

Gets an agent by its unique identifier (uuid)

Available since v14.3.0.

HTTP Request

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

With pagination

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

Returns

A list of modification objects.

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'

The above command returns the following response:

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 Go Server when a commit has been made in Version Control and Go needs to trigger relevant pipelines.

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

The above command returns the following response:

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 Go Server when a commit has been made in Version Control and Go needs to trigger relevant pipelines.

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

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"

The above command returns the following response:

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 Go Server when a commit has been made in Version Control and Go needs to trigger relevant pipelines.

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

Backups

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

The backup object

Available since v15.2.0.

Attribute Type Description
time DateTime The time of the backup.
path String The filesystem location of the backup.
user Object The user that performed this backup.

Create a backup

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

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "doc": {
      "href": "https://api.gocd.io/#backups"
    }
  },
  "time": "2015-08-07T10:07:19.868Z",
  "path": "/var/lib/go-server/serverBackups/backup_20150807-153719",
  "user": {
    "_links": {
      "doc": {
        "href": "https://api.gocd.io/#users"
      },
      "self": {
        "href": "https://ci.example.com/go/api/users/username"
      },
      "find": {
        "href": "https://ci.example.com/go/api/users/:login_name"
      }
    },
    "login_name": "username"
  }
}

Create a server backup.

Available since v15.2.0.

HTTP Request

POST /go/api/backups

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'

The above command returns JSON structured like this:

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'

The above command returns JSON structured like this:

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

Lists all available artifacts in a job.

Available since v14.3.0.

HTTP Request

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

Returns

An array of artifact objects.

Get artifact file

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

The above command returns the contents of the file you requested

Gets an artifact file by its path.

Available since v14.3.0.

HTTP Request

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

Returns

An the contents of the requested file.

Get artifact directory

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

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

Gets an artifact directory by its path.

Available since v14.3.0.

HTTP Request

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

Returns

One of -

Create artifact

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

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

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

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

Uploads a local file as an artifact.

Available since v14.3.0.

HTTP Request

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

The following form parameter must be specified

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

Returns

An acknowledgement that the file was created.

Append to artifact

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

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

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

File logs/operations.log was appended successfully

Appends a local file to an existing artifact.

Available since v14.3.0.

HTTP Request

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

Returns

An acknowledgement that the file was appended to.

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'

The above command returns JSON structured like this:

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'

The above command returns JSON structured like this:

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]

Returns

An array of pipeline instances.

Get pipeline status


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

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "locked": false,
  "paused": true,
  "schedulable": 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 'Confirm: true' \
      -X POST \
      -d 'pauseCause=take some rest'

The above command returns the following response:

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

Pause the specified pipeline.

Available since v14.3.0.

HTTP Request

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

The following post parameters must be specified.

Attribute Type Description
pauseCause String Reason for pausing the pipeline.

Returns

Nothing.

Unpause a pipeline

$ curl 'https://ci.example.com/go/api/pipelines/pipeline1/unpause' \
      -u 'username:password' \
      -H 'Confirm: true' \
      -X POST

The above command returns the following response:

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

Unpause the specified pipeline.

Available since v14.3.0.

HTTP Request

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

Returns

Nothing.

Releasing a pipeline lock


$ curl 'http://ci.example.com/go/api/pipelines/pipeline1/releaseLock' \
       -u 'username:password' \
       -H 'Confirm: true' \
       -X POST

The above command returns the following response:

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
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 v14.3.0.

HTTP Request

POST /go/api/pipelines/:pipeline_name/releaseLock

Returns

A text confirmation.

Scheduling pipelines


$ curl 'http://ci.example.com/go/api/pipelines/pipeline1/schedule' \
       -u 'username:password' \
       -H 'Confirm: true' \
       -X POST

The above command returns the following response:

HTTP/1.1 202 Accepted
Content-Type: text/html; charset=utf-8
Request to schedule pipeline pipeline1 accepted

Scheduling allows user to trigger a specific pipeline.

Available since v14.3.0.

HTTP Request

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

You may optionally submit specific materials information and environment variables in order to schedule the pipeline with the specified set of materials and parameterize it with the specified environment variables.

Post Data Desciption
no parameter Triggers a new instance of the specified pipeline with the latest revision of all materials.
materials[svn_material]=3456 Triggers a new instance of the specified pipeline with revision 3456 of the material whose materialName attribute is svn_version.
materials[repo-name:pkg-name]=gcc-4.4.7-3.el6.x86_64 Triggers a new instance of the specified pipeline with revision gcc-4.4.7-3.el6.x86_64 of the rpm package material.
materials[svn_material]=3456&materials[upstream_foo]=upstream_foo/2/dist/1 Triggers a new instance of the specified pipeline by specifying multiple materials.
variables[ENV_VAR_1]=value1 Triggers a new instance of the specified pipeline with a parameterized environment variable. Pipeline-level environment variable ENV_VAR_1 will be set to value1.
materials[svn_material]=3456&variables[ENV_VAR_1]=value1&variables[ENV_VAR_2]=value2 Triggers a new instance of the specified pipeline with revision 3456 of the material and two parameterized environment variables, ENV_VAR_1 and ENV_VAR_2.
secure_variables[PASSWORD]=new_password Triggers a new instance of the specified pipeline with a parameterized secure environment variable. Pipeline-level secure environment variable PASSWORD will be set to new_password.

Returns

A text confirmation.

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

The above command returns the following response:

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'

The above command returns the following response:

HTTP/1.1 200 OK
Content-Type: application/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": "Passed",
      "state": "Completed",
      "id": 1,
      "stage_counter": null,
      "stage_name": null
    }
  ],
  "pipeline_counter": 1,
  "pipeline_name": "mypipeline",
  "approval_type": "success",
  "result": "Passed",
  "counter": 1,
  "id": 1,
  "rerun_of_counter": null,
  "fetch_materials": true,
  "artifacts_deleted": false
}

Gets stage instance object.

Available since v15.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'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "stages": [
    {
      "name": "defaultStage",
      "approved_by": "admin",
      "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",
      "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.

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]

Returns

An array of stage instances.

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'

The above command returns XML structured like this:

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'

The above command returns JSON structured like this:

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]

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'

The above command returns CSV structure like this (indented for readability):

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'

The above command returns CSV structure like this:

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'

The above command returns CSV structure like this:

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

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'

The above command defines a property ‘PropertyName’ for ‘PipelineName/541/StageName/1/JobName’ and returns the following response:

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'

The above command returns JSON structured like this:

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'

The above command returns the following response:

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'

The above command returns the contents of the config file

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

Gets the current configuration file.

Available since v14.3.0.

HTTP Request

GET /go/api/admin/config.xml

Other convenience APIs

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

or

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

Returns

The contents of the configuration file.

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'

The above command returns XML structured like this:

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'

The above command returns XML structured like this:

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'

The above command returns XML structured like this:

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'

The above command returns XML structured like this:

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

or

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

Returns

A stage object.

Get job

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

The above command returns XML structured like this:

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.

Get Dashboard

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

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/dashboard"
    },
    "doc": {
      "href": "https://api.gocd.io/current/#dashboard"
    }
  },
  "_embedded": {
    "pipeline_groups": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/config/pipeline_groups"
          },
          "doc": {
            "href": "https://api.gocd.io/current/#pipeline-groups"
          }
        },
        "name": "first",
        "_embedded": {
          "pipelines": [
            {
              "_links": {
                "self": {
                  "href": "https://ci.example.com/go/api/pipelines/first/history"
                },
                "doc": {
                  "href": "https://api.gocd.io/current/#pipelines"
                },
                "settings_path": {
                  "href": "https://ci.example.com/go/admin/pipelines/first/general"
                },
                "trigger": {
                  "href": "https://ci.example.com/go/api/pipelines/first/schedule"
                },
                "trigger_with_options": {
                  "href": "https://ci.example.com/go/api/pipelines/first/schedule"
                },
                "pause": {
                  "href": "https://ci.example.com/go/api/pipelines/first/pause"
                },
                "unpause": {
                  "href": "https://ci.example.com/go/api/pipelines/first/unpause"
                }
              },
              "name": "first",
              "locked": true,
              "pause_info": {
                "paused": false,
                "paused_by": null,
                "pause_reason": null
              },
              "_embedded": {
                "instances": [
                  {
                    "_links": {
                      "self": {
                        "href": "https://ci.example.com/go/api/pipelines/first/instance/2"
                      },
                      "doc": {
                        "href": "https://api.gocd.io/current/#get-pipeline-instance"
                      },
                      "history_url": {
                        "href": "https://ci.example.com/go/api/pipelines/first/history"
                      },
                      "vsm_url": {
                        "href": "https://ci.example.com/go/pipelines/value_stream_map/first/2"
                      },
                      "compare_url": {
                        "href": "https://ci.example.com/go/compare/first/1/with/2"
                      },
                      "build_cause_url": {
                        "href": "https://ci.example.com/go/pipelines/first/2/build_cause"
                      }
                    },
                    "label": "2",
                    "schedule_at": "2015-09-18T11:11:36.378Z",
                    "triggered_by": "admin",
                    "_embedded": {
                      "stages": [
                        {
                          "_links": {
                            "self": {
                              "href": "https://ci.example.com/go/api/stages/first/2/stage1/2"
                            },
                            "doc": {
                              "href": "https://api.gocd.io/current/#get-stage-instance"
                            }
                          },
                          "name": "stage1",
                          "status": "Building",
                          "previous_stage": {
                            "_links": {
                              "self": {
                                "href": "https://ci.example.com/go/api/stages/first/1/stage1/2"
                              },
                              "doc": {
                                "href": "https://api.gocd.io/current/#get-stage-instance"
                              }
                            },
                            "name": "stage1",
                            "status": "Passed"
                          }
                        },
                        {
                          "_links": {
                            "self": {
                              "href": "https://ci.example.com/go/api/stages/first/2/stage2/1"
                            },
                            "doc": {
                              "href": "https://api.gocd.io/current/#get-stage-instance"
                            }
                          },
                          "name": "stage2",
                          "status": "Passed"
                        }
                      ]
                    }
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }
}

Lists pipelines on Dashboard.

Available since v15.3.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.

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

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "http://ci.example.com/go/api/admin/encrypt"
    },
    "doc": {
      "href": "https://api.gocd.io/#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.

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. If not specified, label_template defaults to ${COUNT}.
enable_pipeline_locking Boolean Whether pipeline is locked to run single instance or not.
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.
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",
        "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.
branch String The git branch to build.
destination String The directory (relative to the pipeline directory) in which source code will be checked out.
auto_update Boolean Whether to poll for new changes or not.
filter Object The filter specifies files in changesets that should not trigger a pipeline automatically.
invert_filter Boolean Invert filter to enable whitelist. Since v16.7.0.
submodule_folder String The git submodule in the git repository.
shallow_clone Boolean Clone with -n (–depth) option if set to true. Since v16.3.0.

The subversion material attributes

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

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

The mercurial material attributes

{
  "materials": [
    {
      "type": "hg",
      "attributes": {
        "name": "api-docs",
        "url": "http://username:password@hg.example.com/hg/api.go.cd",
        "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.
destination String The directory (relative to the pipeline directory) in which source code will be checked out.
filter Object The filter specifies files in changesets that should not trigger a pipeline automatically.
invert_filter Boolean Invert filter to enable whitelist. Since v16.7.0.
auto_update Boolean Whether to poll for new changes or not.

The perforce material attributes

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

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

The tfs material attributes

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

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

The dependency material attributes

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

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 go 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 Go 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. If not specified, the path 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": {
        "run_if": [
          "passed"
        ],
        "pipeline": "upstream",
        "stage": "upstream_stage",
        "job": "upstream_job",
        "is_source_a_file": false,
        "source": "result",
        "destination": "test"
      }
    }
  ]
}

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.
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.
is_source_a_file Boolean Whether source is a file or directory.
destination String The path of the directory where the artifact is fetched to.
on_cancel Object The task specifies a task to execute when a stage is cancelled.

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

Attribute Type Description
type String The type of the artifact. Can be one of test, build.
source String The file or folder to publish to the server.
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.

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.

Get pipeline config

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

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "e064ca0fe5d8a39602e19666454b8d77"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/pipelines/my_pipeline"
    },
    "doc": {
      "href": "https://api.gocd.io/#pipeline-config"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/pipelines/:name"
    }
  },
  "label_template": "${COUNT}",
  "enable_pipeline_locking": false,
  "name": "my_pipeline",
  "template": null,
  "params": [],
  "environment_variables": [],
  "materials": [
    {
      "type": "git",
      "attributes": {
        "url": "git@github.com:example/sample_repo.git",
        "destination": "code",
        "filter": {
            "ignore": [
                    "**/*.*",
                    "**/*.html"
            ]
        },
        "invert_filter": false,
        "name": "git",
        "auto_update": true,
        "branch": "master",
        "submodule_folder": null,
        "shallow_clone": true
      }
    }
  ],
  "stages": [
    {
      "name": "my_stage",
      "fetch_materials": true,
      "clean_working_directory": false,
      "never_cleanup_artifacts": false,
      "approval": {
        "type": "success",
        "authorization": {
          "roles": [],
          "users": []
        }
      },
      "environment_variables": [],
      "jobs": [
        {
          "name": "my_job",
          "run_instance_count": null,
          "timeout": 0,
          "environment_variables": [],
          "resources": [
                "Linux",
                "Java"
          ],
          "tasks": [
            {
              "type": "exec",
              "attributes": {
                "run_if": [
                  "passed"
                ],
                "on_cancel": {
                  "type": "exec",
                  "attributes": {
                    "command": "ls",
                    "working_directory": null
                  }
                },
                "command": "sleep",
                "arguments": [
                  "10"
                ],
                "working_directory": null
              }
            }
         ],
          "tabs": [
            {
              "name": "cobertura",
              "path": "target/site/cobertura/*.xml"
            }
          ],
          "artifacts": [
            {
              "source": "target",
              "destination": "result",
              "type": "build"
            },
            {
              "source": "test",
              "destination": "res1",
              "type": "test"
            }
          ],
          "properties": null
        }
      ]
    }
  ],
  "tracking_tool": null,
  "timer": null
}

Gets pipeline config for specified pipeline name.

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.v3+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "e064ca0fe5d8a39602e19666454b8d77"' \
      -X PUT \
      -d '{
            "label_template": "${COUNT}",
            "enable_pipeline_locking": true,
            "name": "my_pipeline",
            "template": null,
            "materials": [
              {
                "type": "git",
                "attributes": {
                  "url": "git@github.com:sample_repo/example.git",
                  "destination": "destination1",
                  "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
                        }
                      }
                    ]
                  }
                ]
              }
            ]
          }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "e89135b38ddbcd9380c83eb524647bdd"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/pipelines/my_pipeline"
    },
    "doc": {
      "href": "https://api.gocd.io/#pipeline-config"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/pipelines/:name"
    }
  },
  "label_template": "${COUNT}",
  "enable_pipeline_locking": true,
  "name": "my_pipeline",
  "template": null,
  "params": [],
  "environment_variables": [],
  "materials": [
    {
      "type": "git",
      "attributes": {
        "url": "git@github.com:sample_repo/example.git",
        "destination": "destination1",
        "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
              }
            }
          ],
          "tabs": [],
          "artifacts": [],
          "properties": null
        }
      ]
    }
  ],
  "tracking_tool": null,
  "timer": null
}

Update pipeline config for specified pipeline name.

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.v3+json' \
      -H 'Content-Type: application/json' \
      -X POST -d '{ "group": "first",
                    "pipeline": {
                    "label_template": "${COUNT}",
                    "enable_pipeline_locking": true,
                    "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
                                }
                              }
                            ]
                          }
                        ]
                      }
                    ]
                }
              }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/pipelines/new_pipeline"
    },
    "doc": {
      "href": "https://api.gocd.io/#pipeline-config"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/pipelines/:name"
    }
  },
  "label_template": "${COUNT}",
  "enable_pipeline_locking": true,
  "name": "new_pipeline",
  "template": null,
  "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": 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": "never",
          "environment_variables": [],
          "resources": [],
          "tasks": [
            {
              "type": "exec",
              "attributes": {
                "run_if": [
                  "passed"
                ],
                "command": "ls",
                "working_directory": null
              }
            }
          ],
          "tabs": [],
          "artifacts": [],
          "properties": null
        }
      ]
    }
  ],
  "tracking_tool": null,
  "timer": null
}

Create a pipeline.

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

The above command returns JSON structured like this:

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

Deletes a pipeline from the config XML.

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.

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.

Get all templates

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

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/templates"
    },
    "doc": {
      "href": "https://api.gocd.io/#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.io/#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.io/#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.v3+json'
      -i

The above command returns JSON structured like this:

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

{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/templates/template.name"
    },
    "doc": {
      "href": "https://api.gocd.io/#template-config"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/templates/:template_name"
    }
  },
  "name": "template.name",
  "stages": [
    {
      "name": "up42_stage",
      "fetch_materials": true,
      "clean_working_directory": false,
      "never_cleanup_artifacts": false,
      "approval": {
        "type": "success",
        "authorization": {
          "roles": [

          ],
          "users": [

          ]
        }
      },
      "environment_variables": [

      ],
      "jobs": [
        {
          "name": "up42_job",
          "run_instance_count": null,
          "timeout": "never",
          "elastic_profile_id": "docker",
          "environment_variables": [

          ],
          "resources": [

          ],
          "tasks": [
            {
              "type": "exec",
              "attributes": {
                "run_if": [

                ],
                "on_cancel": null,
                "command": "ls",
                "working_directory": null
              }
            }
          ],
          "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.v3+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": {
                      "command": "ls",
                      "working_directory": null
                    }
                  }
                ]
              }
            ]
          }
        ]
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/templates/template"
    },
    "doc": {
      "href": "https://api.gocd.io/#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,
          "elastic_profile_id": "elastic_profile_id",
          "timeout": "never",
          "environment_variables": [

          ],
          "resources": [

          ],
          "tasks": [
            {
              "type": "exec",
              "attributes": {
                "run_if": [

                ],
                "on_cancel": null,
                "command": "ls",
                "working_directory": null
              }
            }
          ],
          "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.v3+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,
                "timeout": 0,
                "environment_variables": [],
                "resources": [],
                "tasks": [
                  {
                    "type": "exec",
                    "attributes": {
                      "command": "sleep",
                      "working_directory": null
                    }
                  }
                ]
              }
            ]
          }
        ]
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "e89135b38ddbcd9380c83eb524647bdd"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/templates/template"
    },
    "doc": {
      "href": "https://api.gocd.io/#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": "never",
          "environment_variables": [

          ],
          "resources": [

          ],
          "tasks": [
            {
              "type": "exec",
              "attributes": {
                "run_if": [

                ],
                "on_cancel": null,
                "command": "sleep",
                "working_directory": null
              }
            }
          ],
          "tabs": [

          ],
          "artifacts": [

          ],
          "properties": null
        }
      ]
    }
  ]
}

Update template config for specified template name.

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

The above command returns JSON structured like this:

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

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'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://build.go.cd/go/api/version"
    },
    "doc": {
      "href": "https://api.gocd.io/#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.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "3924a894cf0e5bef02abe9de0df3bb84"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/environments"
    },
    "doc": {
      "href": "https://api.gocd.io/#environment-config"
    }
  },
  "_embedded": {
    "environments": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/environments/foobar"
          },
          "doc": {
            "href": "https://api.gocd.io/#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.io/#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.io/#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.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "4167e3ec81fdac0fb29d854b36ceb981"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/environments/my_environment"
    },
    "doc": {
      "href": "https://api.gocd.io/#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.io/#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.io/#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.v1+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
          }
        ]
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "d3b07384d113edec49eaa6238ad5ff00"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/environments/new_environment"
    },
    "doc": {
      "href": "https://api.gocd.io/#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.io/#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.io/#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.v1+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "26b227605daf6f2d7768c8edaf61b861"' \
      -X PUT \
      -d '{
        "name" : "new_environment",
        "pipelines" : [ { "name" : "pipeline1" } ]
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "4167e3ec81fdac0fb29d854b36ceb981"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/environments/new_environment"
    },
    "doc": {
      "href": "https://api.gocd.io/#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.io/#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.

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

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

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "4167e3ec81fdac0fb29d854b36ceb981"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/environments/new_environment"
    },
    "doc": {
      "href": "https://api.gocd.io/#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.io/#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.io/#agents"
        },
        "find": {
          "href": "https://ci.example.com/go/api/agents/:uuid"
        }
      },
      "uuid": "12345678-e2f6-4c78-123456789012"
    }
  ],
  "environment_variables": [

  ]
}

Update some attributes of an environment.

Available since v16.10.0.

HTTP Request

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

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

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.

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.

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

The above command returns JSON structured like this:

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

Attribute Type Description
id String The identifier of the elastic agent profile.
plugin_id String The plugin identifier of the elastic agent profile.
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.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "32628084ef10b0c82a55f8f2f867d8d0"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/elastic/profiles"
    },
    "doc": {
      "href": "https://api.gocd.io/#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.io/#elastic-profiles"
          },
          "find": {
            "href": "https://ci.example.com/go/api/elastic/profiles/:profile_id"
          }
        },
        "id": "unit-tests",
        "plugin_id": "cd.go.contrib.elastic-agent.docker"
      }
    ]
  }
}

Lists all available elastic agent profiles.

Available since v16.11.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.v1+json'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/elastic/profiles/unit-tests"
    },
    "doc": {
      "href": "https://api.gocd.io/#elastic-agent-profiles"
    },
    "find": {
      "href": "https://ci.example.com/go/api/elastic/profiles/:profile_id"
    }
  },
  "id": "unit-tests",
  "plugin_id": "cd.go.contrib.elastic-agent.docker",
  "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 v16.11.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.v1+json' \
      -H 'Content-Type: application/json' \
      -X POST -d '{
        "id": "unit-tests",
        "plugin_id": "cd.go.contrib.elastic-agent.docker",
        "properties": [
          {
            "key": "Image",
            "value": "gocdcontrib/gocd-dev-build"
          },
          {
            "key": "Environment",
            "value": "JAVA_HOME=/opt/java\nMAKE_OPTS=-j8"
          }
        ]
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/elastic/profiles/unit-tests"
    },
    "doc": {
      "href": "https://api.gocd.io/#elastic-profiles"
    },
    "find": {
      "href": "https://ci.example.com/go/api/elastic/profiles/:profile_id"
    }
  },
  "id": "unit-tests",
  "plugin_id": "cd.go.contrib.elastic-agent.docker",
  "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 v16.11.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.v1+json' \
      -H 'Content-Type: application/json' \
      -H 'If-Match: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"' \
      -X PUT \
      -d '{
        "plugin_id": "cd.go.contrib.elastic-agent.docker",
        "properties": [
          {
            "key": "Image",
            "value": "gocdcontrib/gocd-dev-build:1.0.0"
          },
          {
            "key": "Environment",
            "value": "JAVA_HOME=/opt/java\nMAKE_OPTS=-j8"
          }
        ]
      }'

The above command returns JSON structured like this:

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

Update some attributes of an elastic agent profile.

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

The above command returns JSON structured like this:

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

Deletes the profile.

Available since v16.11.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 v16.7.0.

Attribute Type Description
id String Plugin unique identifier.
name String Name of the plugin.
display_name String Plugin display name to be used in views.
version String The version of the plugin.
type String The type of the plugin. Can be one of authentication, notification, package-repository, task, scm, elastic.
pluggable_instance_settings Object List of pluggable_instance_settings settings required to configure a pluggable instance e.g PluggableTask, PluggableSCM.
image Object The plugin icon for the specific plugin. This is currently only supported by elastic agent plugins. Since v16.12.0.

The pluggable_instance_settings object

{
  "pluggable_instance_settings": {
    "configurations": [
      {
        "key": "url",
        "metadata": {
          "secure": false,
          "required": true,
          "part_of_identity": false
        }
      }
    ],
    "view": {
      "template": "<div>Plugin view template</div>"
    }
  }
}

Attribute Type Description
configurations Array List of configurations required to configure a pluggable instance.
view Object The view contains the Angular view template.

The Image Object

{
  "content_type": "image/svg+xml",
  "data": "...."
}

Attribute Type Description
content_type String A valid content type for the image. Please make sure the content type is supported by most browsers.
data String A base-64 encoded (single-line non-chunking) byte array of the byte-sequence that composes the image.

The plugin info configurations object

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

Attribute Type Description
key String Describes the configuration key.
metadata Object Metadata for the configuration property. For plugins of types authentication, notification, task and scm, the metadata consists of attributes secure, required and part_of_identity. The attributes for package-repository and elastic 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 elastic configurations object

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

Attribute Type Description
key String Describes the configuration key for a elastic agent 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.

Get all plugin info

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

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "3924a894cf0e5bef02abe9de0df3bb84"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/plugin_info"
    },
    "doc": {
      "href": "https://api.gocd.io/#plugin-info"
    }
  },
  "_embedded": {
    "plugin_info": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/plugin_info/plugin_id"
          },
          "doc": {
            "href": "https://api.gocd.io/#plugin-info"
          },
          "find": {
            "href": "https://ci.example.com/go/api/admin/plugin_info/:id"
          }
        },
        "id": "plugin_id",
        "name": "SCM Plugin",
        "display_name": "SCM Plugin For HG",
        "version": "1.2.3",
        "type": "scm"
      }
    ]
  }
}

Lists all available plugin info.

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

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "4167e3ec81fdac0fb29d854b36ceb981"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/plugin_info/my_plugin"
    },
    "doc": {
      "href": "https://api.gocd.io/#plugin-info"
    },
    "find": {
      "href": "https://ci.example.com/go/api/admin/plugin_info/:id"
    }
  },
  "id": "my_plugin",
  "name": "My SCM Plugin",
  "display_name": "SCM Plugin For HG",
  "version": "1.2.3",
  "type": "scm",
  "pluggable_instance_settings": {
    "configurations": [
      {
        "key": "url",
        "metadata": {
          "secure": false,
          "required": true,
          "part_of_identity": true
        }
      },
      {
        "key": "username",
        "metadata": {
          "secure": false,
          "required": false,
          "part_of_identity": false
        }
      },
      {
        "key": "password",
        "metadata": {
          "secure": true,
          "required": false,
          "part_of_identity": false
        }
      }
    ],
    "view": {
    "template": "<div>Plugin view template </div>"
    }
  }
}

Gets plugin info for a specified plugin id.

Available since v16.7.0.

HTTP Request

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

Returns

The plugin info 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'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/scms"
    },
    "doc": {
      "href": "https://api.gocd.io/#scms"
    }
  },
  "_embedded": {
    "scms": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/scms/scmName"
          },
          "doc": {
            "href": "https://api.gocd.io/#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

The above command returns JSON structured like this:

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

{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/scms/pluggable.scm.material.name"
    },
    "doc": {
      "href": "https://api.gocd.io/#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="
    }
  ]
 }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/scms/scmName"
    },
    "doc": {
      "href": "https://api.gocd.io/#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="
            }
            ]
          }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "e89135b38ddbcd9380c83eb524647bdd"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/scms/scmName"
    },
    "doc": {
      "href": "https://api.gocd.io/#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.

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'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/repositories"
    },
    "doc": {
      "href": "https://api.gocd.io/#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.io/#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.io/#packages"
                },
                "find": {
                  "href": "https://ci.example.com/go/api/admin/packages/:package_id"
                }
              },
              "name": "package",
              "id": "6bba891e-2675-49af-b16d-200bd6c6801e"
            }
          ]
        }
      }
    ]
  }
}

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

Available since v16.12.0.

HTTP Request

GET /go/api/admin/repositories

Returns

A list of repository objects

Get a Repository

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

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/repositories/dd8926c0-3b4a-4c9e-8012-957b179cec5b"
    },
    "doc": {
      "href": "https://api.gocd.io/#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.io/#packages"
          },
          "find": {
            "href": "https://ci.example.com/go/api/admin/packages/:package_id"
          }
        },
        "name": "package",
        "id": "6bba891e-2675-49af-b16d-200bd6c6801e"
      }
    ]
  }
}

Get a repository for a specified id

Available since v16.12.0.

HTTP Request

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

Returns

A repository object

Create a Repository

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

The above command returns JSON structured like this:

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

    ]
  }
}

Create the repository configuration in cruise-config.xml.

Available since v16.12.0.

HTTP Request

POST /go/api/admin/repositories

Returns

A new repository object.

Edit a repository

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

The above command returns JSON structured like this:

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

    ]
  }
}

Update package repository for specified repository id.

Available since v16.12.0.

HTTP Request

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

Returns

The updated repository object.

Delete a repository

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

The above command returns JSON structured like this:

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

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

Available since v16.12.0.

HTTP Request

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

Returns

A message confirmation if the repository was deleted.

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'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/packages"
    },
    "doc": {
      "href": "https://api.gocd.io/#packages"
    }
  },
  "_embedded": {
    "packages": [
      {
        "_links": {
          "self": {
            "href": "https://ci.example.com/go/api/admin/packages/f579bb13-bed3-4ad1-a547-ff9d9bcf56d4"
          },
          "doc": {
            "href": "https://api.gocd.io/#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.io/#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.io/#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.io/#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

The above command returns JSON structured like this:

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

{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/packages/package.id"
    },
    "doc": {
      "href": "https://api.gocd.io/#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.io/#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"
    }
  ]
}'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/packages/package-id"
    },
    "doc": {
      "href": "https://api.gocd.io/#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.io/#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 "http://localhost:8153/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"
  }]
}'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "e89135b38ddbcd9380c83eb524647bdd"
{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/admin/packages/f579bb13-bed3-4ad1-a547-ff9d9bcf56d4"
    },
    "doc": {
      "href": "https://api.gocd.io/#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.io/#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.

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

The above command returns JSON structured like this:

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

Errors

Go CD uses the following HTTP status codes to indicate errors.

Error Code Meaning
400 Bad Request – The request could not be understood. The client SHOULD NOT repeat the request without modifications.
401 Unauthorized – Your username or password is incorrect or you are not authorized to perform this action.
403 Forbidden – The resource requested is hidden for administrators only.
404 Not Found – The specified resource could not be found.
405 Method Not Allowed – You tried to access a resource with an invalid method.
406 Not Acceptable – You requested a format that isn’t json.
409 Conflict – The request could not be completed due to a conflict with the current state of the resource.
410 Gone – The resource requested has been removed from our servers.
422 Unprocessible Entity – The server understood the request, but the request is semantically erroneous.
500 Internal Server Error – We had a problem with our server. Try again later.
501 Not implemented – The server does not support the functionality required to fulfill the request.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.