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.

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

Authentication

All APIs require you to authenticate yourself using your username and password. 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.v1+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.

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

The agent object

Available since v15.2.0.

Attribute	Type	Description
`uuid`	String	The identifier of this agent.
`hostname`	String	The hostname of the agent.
`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.
`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.
`resources`	Array	The set of resources that this agent is tagged with.
`environments`	Array	The set of environments that this agent belongs to.

Get all agents

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

The above command returns JSON structured like this:

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

{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/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",
        "build_state": "Idle",
        "resources": ["java", "linux", "firefox"],
        "environments": ["perf", "UAT"]
      }
    ]
  }
}

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

The above command returns JSON structured like this:

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

{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/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": "Idle",
  "build_state": "Idle",
  "resources": ["java", "linux", "firefox"],
  "environments": ["perf", "UAT"]
}

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.v2+json' \
      -H 'Content-Type: application/json' \
      -X PATCH \
      -d '{
            "hostname": "agent02.example.com"
          }'

The above command returns JSON structured like this:

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

{
  "_links": {
    "self": {
      "href": "https://ci.example.com/go/api/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",
  "build_state": "Idle",
  "resources": ["java","linux"],
  "environments": []
}

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

The above command returns JSON structured like this:

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

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

Deletes an agent.

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

Available since v15.2.0.

HTTP Request

DELETE /go/api/agents/:uuid

Returns

A message confirmation if the agent was 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]

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

Returns

An array of job objects along with the job transitions.

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": "[email protected]",
            "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": "[email protected]",
            "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": "[email protected]",
  "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 <[email protected]>",
      "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]

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

Returns

A list of modification objects.

Notify SVN materials

$ curl 'https://ci.example.com/go/api/material/notify/svn' \
      -u 'username:password' \
      -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.

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

Available since v14.3.0.

HTTP Request

POST /go/api/material/notify/svn

The following post parameters must be specified.

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

Returns

A text confirmation.

Notification script

To notify 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' \
    -X POST \
    -d "uuid=$UUID"

Notify git materials

$ curl 'https://ci.example.com/go/api/material/notify/git' \
      -u 'username:password' \
      -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.

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

Available since v14.3.0.

HTTP Request

POST /go/api/material/notify/git

The following post parameters must be specified.

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

Returns

A text confirmation.

Notification script

To notify 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' \
    -X POST \
    -d "repository_url=git://git.example.com/git/funky-widgets.git"

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

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

Returns

An the contents of the requested file.

Get artifact directory

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

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

Gets an artifact directory by its path.

Available since v14.3.0.

HTTP Request

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

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

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

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

Returns

One of -

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

Create artifact

$ curl 'https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName/pkg/foobar-widgets-1.2.3.jar' \
      -u 'username:password'
      -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 <[email protected]>",
             "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 <[email protected]>"
  },
  "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 <[email protected]>",
                "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 <[email protected]>",
                "comment": "my hola mundo changes",
                "revision": "c194b49db102b705ebc13e604e490ae13ac92d96"
              }
            ],
            "material": {
              "description": "URL: https://github.com/gocd/gocd, Branch: master",
              "fingerprint": "f6e7a3899c55e1682ffb00383bdf8f882bcee2141e79a8728254190a1fddcf4f",
              "type": "Git",
              "id": 1
            },
            "changed": false
          }
        ],
        "trigger_forced": true,
        "trigger_message": "Forced by anonymous"
      },
      "name": "pipeline1",
      "natural_order": 10,
      "can_run": true,
      "comment": null,
      "stages": [
        {
          "name": "stage1",
          "approved_by": "admin",
          "jobs": [
            {
              "name": "job1",
              "result": "Passed",
              "state": "Completed",
              "id": 12,
              "scheduled_date": 1436172122024
            }
          ],
          "can_run": true,
          "result": "Passed",
          "approval_type": "success",
          "counter": "1",
          "id": 12,
          "operate_permission": true,
          "rerun_of_counter": null,
          "scheduled": true
        }
      ],
      "counter": 10,
      "id": 12,
      "preparing_to_schedule": false,
      "label": "10"
    }
  ],
  "pagination": {
    "offset": 0,
    "total": 2,
    "page_size": 10
  }
}

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

Available since v14.3.0.

HTTP Request

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

With pagination

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

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

Returns

An array of pipeline instances.

Get pipeline status


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

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' \
      -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'
      -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'
       -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'
       -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' \
      -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]

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

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]

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

Returns

An array of jobs instances.

Properties

The properties API allows managing of job properties.

Get all job properties

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

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

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

Returns

Job properties as CSV.

Create property

$ curl 'http://ci.example.com/go/properties/PipelineName/541/StageName/1/JobName/PropertyName' \
        -u 'username:password' \
        -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

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

Returns

The contents of the configuration file.

Create pipeline

$ curl 'https://ci.example.com/go/tab/admin/pipelines/mypipeline.json' \
      -u 'username:password' \
      -X POST \
      -d 'url=http://svnrepo.com/mysvn/trunk'

The above command returns the following response:

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

{
  "isValid": "true",
  "error": "",
  "messageId": "Pipeline successfully created."
}

Creates a pipeline.

Available since v14.3.0.

HTTP Request

POST /go/tab/admin/pipelines/:pipeline_name.json

Creating pipeline supports following parameters.

General parameters

Parameter name	Example value	Required	Description
pipelineGroup	defaultGroup	No	The name of the Pipeline Group to add the new pipeline to. The pipeline group will be created if it does not already exist.
builder	ant	No	Can be one of `ant`, `nant`, `rake` or `exec`.
buildfile	build.xml	No	Not allowed for exec
target	all	No	Not allowed for exec
command	unittest.sh arg1 arg2	No	Required for exec
source	pkg	No	no default value
dest	installer	No	no default value

Subversion

Parameter name	Example value	Required	Description
scm	svn	No	Default value is `svn`
url	http://svnrepo.com/mysvn/trunk	Yes	The URL of the Subversion repository
username	checkout_username	No	The SVN username
password	checkout_password	No	The SVN password

Mercurial

Parameter name	Example value	Required	Description
scm	hg	Yes	-
url	http://hgrepo.com/hg/my_project	Yes	The URL of the repository

Git

Parameter name	Example value	Required	Description
scm	git	Yes	-
url	git://github.com/foo/bar.git	Yes	The URL of the repository

Perforce

Parameter name	Example value	Required	Description
scm	p4	Yes	-
url	p4server.foo.com:1666	Yes	The P4PORT of the repository
username	checkout_username	No	The P4USER to connect to the repository
password	checkout_password	No	The P4PASSWD to connect to the repository
useTickets	true or false	No	-
view	//depot/… //something/…	Yes	-

Team Foundation Server

Parameter name	Example value	Required	Description
scm	tfs	Yes	-
url	http://tfs.host.com:8080/tfs/DefaultCollection	Yes	The url of your TFS collection
domain	COMPANYNAME	No	Domain name that the given user belong to
username	tfsuser	Yes	Username used to connect to the collection
password	tfspassword	No	Password for the given user name
projectPath	$/MyProject	Yes	Project path in the given collection

Returns

A text confirmation.

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 <[email protected]>]]></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 <[email protected]>]]></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 <[email protected]>]]></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

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.

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 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"
          ]
        },
        "submodule_folder": null
      }
    }
  ]
}

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.
`submodule_folder`	String	The git submodule in the git repository.

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,
        "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.
`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:[email protected]/hg/api.go.cd",
        "destination": "api-docs",
        "filter": null,
        "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.
`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,
        "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.
`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
      }
    }
  ]
}

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.

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

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.

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": [

      ]
    }
  ]
}

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

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": {
      "link": "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": {
    "link": "https://github.com/gocd/api.go.cd/issues/${ID}",
    "regex": "##(d+)"
  }
}

Attribute	Type	Description
`link`	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.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: "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": "[email protected]:example/sample_repo.git",
        "destination": "code",
        "filter": {
            "ignore": [
                    "**/*.*",
                    "**/*.html"
            ]
        },
        "name": "git",
        "auto_update": true,
        "branch": "master",
        "submodule_folder": null
      }
    }
  ],
  "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.v1+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": "[email protected]:sample_repo/example.git",
                  "destination": "destination1",
                  "filter": null,
                  "name": null,
                  "auto_update": true,
                  "branch": "master",
                  "submodule_folder": null
                }
              }
            ],
            "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.v1+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": "[email protected]:sample_repo/example.git",
        "destination": "destination1",
        "filter": null,
        "name": null,
        "auto_update": true,
        "branch": "master",
        "submodule_folder": null
      }
    }
  ],
  "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.

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

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

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.v1+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": "[email protected]:sample_repo/example.git",
                          "destination": "dest",
                          "filter": null,
                          "name": null,
                          "auto_update": true,
                          "branch": "master",
                          "submodule_folder": null
                        }
                      }
                    ],
                    "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.v1+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": "[email protected]:sample_repo/example.git",
        "destination": "dest",
        "filter": null,
        "name": null,
        "auto_update": true,
        "branch": "master",
        "submodule_folder": null
      }
    }
  ],
  "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.

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.

Introduction

Current version

Authentication

Basic authentication

Cookie/Session authentication

Agents

The agent object

Get all agents

Get one agent

Update an agent

Delete an agent

Agent job run history

Users

The user object

Get all users

Get one user

Create a user

Update a user

Delete a user

Materials

The material object

Get all materials

Get material modifications

Notify SVN materials

Notification script

Notify git materials

Notification script

Backups

The backup object

Create a backup

Pipeline Groups

Config listing

Artifacts

The artifact object

Get all artifacts

Get artifact file

Get artifact directory

Create artifact

Append to artifact

Pipelines

Get pipeline instance

Get pipeline history

Get pipeline status

Pause a pipeline

Unpause a pipeline

Releasing a pipeline lock

Scheduling pipelines

Stages

Cancel stage

Get stage Instance

Get stage history

Jobs

Get scheduled jobs

Get job history

Properties

Get all job properties

Get one property

Get historical properties

Create property

Configuration

List all modifications

Get repository modification diff

Get configuration

Create pipeline

General parameters

Subversion

Mercurial

Git

Perforce

Team Foundation Server

Feeds

Get all pipelines

Get feed of all stages

Get pipeline

Get stage

Get job

Dashboard

Get Dashboard

Pipeline Config

The pipeline config object