Introduction

A toolchain is a set of tools that supports development, deployment, and operational tasks. A tool is an instance that represents its corresponding tool, such as a GitHub tool, a Slack tool, and so on. For more information about the tools that are supported in Continuous Delivery, see Continuous Delivery integrations. Each toolchain is associated with a resource group, where you can manage user access control by using IBM Cloud Identity and Access Management (IAM).

The Toolchain API provides the following functions, based on the user's IAM permissions:

Read a toolchain
Create a toolchain
Update a toolchain
Delete a toolchain and its tools
Read a tool
Provision a tool
Update a tool
De-provision a tool

For more information about toolchains, see Creating toolchains.

toolchain-go-sdk is the official toolchain SDK for the Go programming language.

Run the go get command to retrieve the toolchain SDK and add it to the GOPATH workspace or to the project's Go module dependencies.

go get github.com/IBM/continuous-delivery-go-sdk/v2/cdtoolchainv2

To retrieve the latest version of the SDK, type go get -u:

go get -u github.com/IBM/continuous-delivery-go-sdk/v2/cdtoolchainv2

To use the toolchain SDK within a program, import the package by running the go build or go mod tidy commands to load the package.

import (
	"github.com/IBM/continuous-delivery-go-sdk/v2/cdtoolchainv2"
)

The code examples on this tab use the client library that is provided for Node.

Installation:

npm install @ibm-cloud/continuous-delivery

For more information, view the project on GitHub: https://github.com/IBM/continuous-delivery-node-sdk. See also Using the SDK.

The code examples on this tab use the client library that is provided for Node.

Installation:

pip install "ibm-continuous-delivery"

For more information, view the project on GitHub: https://github.com/IBM/continuous-delivery-python-sdk. See also the Python client library for IBM Cloud Continuous Delivery https://pypi.org/project/ibm-continuous-delivery/ and Using the SDK.

The code examples on this tab use the client library that is provided for Java.

Maven example:

<dependency>
    <groupId>com.ibm.cloud</groupId>
    <artifactId>cd-toolchain</artifactId>
    <version>2.0.1</version>
</dependency>

Gradle example:

compile 'com.ibm.cloud:cd-toolchain:2.0.1'

For more information, view the project on GitHub: https://github.com/IBM/continuous-delivery-java-sdk. See also Using the SDK.

Endpoint URL

The toolchain API uses the following regional endpoint URLs. When you call the API, add the path for each method to form the complete API endpoint for your requests.

Continuous Delivery will be discontinued in the following regions on 12 February 2027: au-syd, ca-mon, ca-tor, us-east. On 12 June 2026, customers will no longer be able to create new resources in the affected regions. However, if a region has no active usage, the region may be discontinued earlier and stop accepting new instances. Learn more.

Dallas: https://api.us-south.devops.cloud.ibm.com/toolchain/v2
London: https://api.eu-gb.devops.cloud.ibm.com/toolchain/v2
Frankfurt: https://api.eu-de.devops.cloud.ibm.com/toolchain/v2
Tokyo: https://api.jp-tok.devops.cloud.ibm.com/toolchain/v2
São Paulo: https://api.br-sao.devops.cloud.ibm.com/toolchain/v2
Montreal (deprecated, limited availability region): https://api.ca-mon.devops.cloud.ibm.com/toolchain/v2
Sydney (deprecated): https://api.au-syd.devops.cloud.ibm.com/toolchain/v2
Toronto (deprecated): https://api.ca-tor.devops.cloud.ibm.com/toolchain/v2
Washington DC (deprecated): https://api.us-east.devops.cloud.ibm.com/toolchain/v2

Note: The following regions have been discontinued and are no longer available:

Osaka (jp-osa)
Madrid (eu-es)

Example request to the Toolchain API (Dallas):

curl -X <HTTP_METHOD> "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/<ENDPOINT_PATH>"

Where <HTTP_METHOD> is the appropriate HTTP method, such as GET or POST, and <ENDPOINT_PATH> is an endpoint that is provided by the Toolchain API.

Example of constructing the toolchain service client pointed at a specific region.

First construct the toolchain client:

import (
	"github.com/IBM/continuous-delivery-go-sdk/v2/cdtoolchainv2"
)
...
toolchainClientOptions := &cdtoolchainv2.CdToolchainV2Options{}
toolchainClient, err := cdtoolchainv2.NewCdToolchainV2UsingExternalConfig(toolchainClientOptions)

By default, the SDK points at the Dallas URL. A different target region can be set using SetServiceURL:

toolchainClient.SetServiceURL(endpointUrl)

Default service URL:

https://api.us-south.devops.cloud.ibm.com/toolchain/v2

Example to change the service URL to the Frankfurt region:

const options = {
  authenticator: new IamAuthenticator({
    apikey: '{iam_api_key}'
  }),
  serviceUrl: 'https://api.eu-de.devops.cloud.ibm.com/toolchain/v2'
};
const toolchainService = new CdToolchainV2(options);

Alternatively, the service URL can be set through environment variables:

export CD_TOOLCHAIN_URL=https://api.eu-de.devops.cloud.ibm.com/toolchain/v2

For more information, see Using the SDK.

Default service URL:

https://api.us-south.devops.cloud.ibm.com/toolchain/v2

Example to change the service URL to the Frankfurt region:

from ibm_continuous_delivery.cd_toolchain_v2 import CdToolchainV2
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{iam_api_key}')
service = CdToolchainV2(authenticator=authenticator)
service.set_service_url('https://api.eu-de.devops.cloud.ibm.com/toolchain/v2')

Alternatively, the service URL can be set through environment variables:

export CD_TOOLCHAIN_URL=https://api.eu-de.devops.cloud.ibm.com/toolchain/v2

For more information, see Using the SDK.

Default service URL:

https://api.us-south.devops.cloud.ibm.com/toolchain/v2

Example to change the service URL to the Frankfurt region:

import com.ibm.cloud.continuous_delivery.cd_toolchain.v2;
import com.ibm.cloud.sdk.core.security.Authenticator;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

Authenticator authenticator = new IamAuthenticator.Builder()
  .apikey("{api_key}")
  .build();
CdToolchain service = new CdToolchain(CdToolchain.DEFAULT_SERVICE_NAME, authenticator);
service.setServiceUrl("https://api.eu-de.devops.cloud.ibm.com/toolchain/v2");

Alternatively, the service URL can be set through environment variables:

export CD_TOOLCHAIN_URL=https://api.eu-de.devops.cloud.ibm.com/toolchain/v2

For more information, see Using the SDK.

Authentication

Authentication to the toolchain API is enforced by using an IBM Cloud Identity and Access Management (IAM) access token. This token determines the actions that a user or service ID can access when they use the API.

For more information about obtaining an IAM token for an authenticated user or service ID, see the IAM Identity Services API documentation.

To use the toolchain API, add a valid IAM token to the HTTP Authorization request header, for example, -H "Authorization: Bearer <IAM_TOKEN>".

Example request to generate an access token:

curl -X POST
https://iam.cloud.ibm.com/identity/token
  -H "Content-Type: application/x-www-form-urlencoded"
  -H "Accept: application/json"
  -d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=<API_KEY>"

Where <API_KEY> is your IBM Cloud API Key. Use the resulting IAM token value prefixed by Bearer to authenticate into the Toolchain API.

Example Authorization header value:

Bearer poJraWQiOiIyMDIxMTAzMDE1MTQiLCJhbGciiuJSUzI1NiJ9.eyJpYW1fdWQiOiJJQk1pZC0xMTAwMDBCS1VWIiwiaWQiOiJJQk1pZC0xMTAwMDBCS1VWIiwicmVhbG1pZCI6IklCTWlkIiwianRpIjoiMjgzMDE3MWItYmY1MC00ZGEyLWE4MjAtMjFmNGVjYWQ0NDE0IiwiaWRlbnRkj

To authenticate into the toolchain service through the Go SDK, an IAM API key. To obtain an API key, access the IBM Cloud API keys page and create an API key.

The IAM API key can be passed to the toolchain Go SDK through environment variables:

export CD_TOOLCHAIN_AUTHTYPE=iam
export CD_TOOLCHAIN_APIKEY=<IAM_API_KEY>

Setting client options programmatically

Construct the service client programmatically, where {iam_api_key} is your hardcoded IAM API key.

const CdToolchainV2 = require('@ibm-cloud/continuous-delivery/cd-toolchain/v2');
const { IamAuthenticator } = require('@ibm-cloud/continuous-delivery/auth');

// Create an IAM authenticator.
const authenticator = new IamAuthenticator({
  apikey: '{iam_api_key}'
});

// Construct the service client.
const toolchainService = new CdToolchainV2({
  authenticator,                                                    // required
  serviceUrl: 'https://api.eu-de.devops.cloud.ibm.com/toolchain/v2' // optional
});

Setting client options through environment variables

Export environment variables to implement service client options, where {service_url} is an endpoint URL for the service and {iam_api_key} is an IAM API key.

export CD_TOOLCHAIN_AUTH_TYPE=iam
export CD_TOOLCHAIN_APIKEY={iam_api_key}
export CD_TOOLCHAIN_URL={service_url}

Construct the service client using external configuration. CdToolchainV2.newInstance() initializes the client with the environment variables, using them for subsequent authentication.

const CdToolchainV2 = require('@ibm-cloud/continuous-delivery/cd-toolchain/v2');
const toolchainService = CdToolchainV2.newInstance();

Setting client options through a credentials file

Store credentials in a file such as my-credentials.env, where {service_url} is an endpoint URL for the service and {iam_api_key} is an IAM API key.

CD_TOOLCHAIN_AUTH_TYPE=iam
CD_TOOLCHAIN_APIKEY={iam_api_key}
CD_TOOLCHAIN_URL={service_url}

Export the name of the file with an environment variable, where {credential_file_path} is the absolute path to your credentials file, such as "$HOME/secrets/my-credentials.env".

export IBM_CREDENTIALS_FILE={credential_file_path}

Construct the service client using external configuration. CdToolchainV2.newInstance() initializes with the defined credential file, using it for subsequent authentication.

const CdToolchainV2 = require('@ibm-cloud/continuous-delivery/cd-toolchain/v2');
const toolchainService = CdToolchainV2.newInstance();

Setting client options programmatically

Construct the service client programmatically, where {iam_api_key} is your hardcoded IAM API key.

from ibm_continuous_delivery.cd_toolchain_v2 import CdToolchainV2
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

## Create an IAM authenticator.
authenticator = IAMAuthenticator('{iam_api_key}')
## Construct the service client.
service = CdToolchainV2(authenticator=authenticator)
## Set custom service URL (optional)
service.set_service_url('https://api.eu-de.devops.cloud.ibm.com/toolchain/v2')

Setting client options through environment variables

Export environment variables to implement service client options, where {service_url} is an endpoint URL for the service and {iam_api_key} is an IAM API key.

export CD_TOOLCHAIN_AUTH_TYPE=iam
export CD_TOOLCHAIN_APIKEY={iam_api_key}
export CD_TOOLCHAIN_URL={service_url}

Construct the service client using external configuration. CdToolchainV2.new_instance() initializes the client with the environment variables, using them for subsequent authentication.

from ibm_continuous_delivery.cd_toolchain_v2 import CdToolchainV2
service = CdToolchainV2.new_instance()

Setting client options through a credentials file

Store credentials in a file such as my-credentials.env, where {service_url} is an endpoint URL for the service and {iam_api_key} is an IAM API key.

CD_TOOLCHAIN_AUTH_TYPE=iam
CD_TOOLCHAIN_APIKEY={iam_api_key}
CD_TOOLCHAIN_URL={service_url}

Export the name of the file with an environment variable, where {credential_file_path} is the absolute path to your credentials file, such as "$HOME/secrets/my-credentials.env".

export IBM_CREDENTIALS_FILE={credential_file_path}

Construct the service client using external configuration. CdToolchainV2.new_instance() initializes with the defined credential file, using it for subsequent authentication.

from ibm_continuous_delivery.cd_toolchain_v2 import CdToolchainV2
service = CdToolchainV2.new_instance()

Setting client options programmatically

Construct the service client programmatically, where {iam_api_key} is your hardcoded IAM API key.

import com.ibm.cloud.continuous_delivery.cd_toolchain.v2;
import com.ibm.cloud.sdk.core.security.Authenticator;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;
// Create an IAM authenticator
Authenticator authenticator = new IamAuthenticator.Builder()
  .apikey("{api_key}")
  .build();
// Construct the service client
CdToolchain service = new CdToolchain(CdToolchain.DEFAULT_SERVICE_NAME, authenticator);

Setting client options through environment variables

Export environment variables to implement service client options, where {service_url} is an endpoint URL for the service and {iam_api_key} is an IAM API key.

export CD_TOOLCHAIN_AUTH_TYPE=iam
export CD_TOOLCHAIN_APIKEY={iam_api_key}
export CD_TOOLCHAIN_URL={service_url}

Construct the service client using external configuration. CdToolchain.newInstance() initializes the client with the environment variables, using them for subsequent authentication.

import com.ibm.cloud.continuous_delivery.cd_toolchain.v2;
CdToolchain service = CdToolchainV2.newInstance()

Setting client options through a credentials file

Store credentials in a file such as my-credentials.env, where {service_url} is an endpoint URL for the service and {iam_api_key} is an IAM API key.

CD_TOOLCHAIN_AUTH_TYPE=iam
CD_TOOLCHAIN_APIKEY={iam_api_key}
CD_TOOLCHAIN_URL={service_url}

Export the name of the file with an environment variable, where {credential_file_path} is the absolute path to your credentials file, such as "$HOME/secrets/my-credentials.env".

export IBM_CREDENTIALS_FILE={credential_file_path}

Construct the service client using external configuration. CdToolchain.newInstance() initializes with the defined credential file, using it for subsequent authentication.

import com.ibm.cloud.continuous_delivery.cd_toolchain.v2;
CdToolchain service = CdToolchainV2.newInstance()

Error handling

The toolchain API uses standard HTTP response codes to indicate whether a method completed successfully. HTTP response codes in the 2xx range indicate success. A response in the 4xx range indicates a failure, and a response in the 5xx range typically indicates an internal system error that cannot be resolved by the user. The following tables show the response codes and methods.

ErrorResponse | Name | Description | |------------------------------|-------------------------------------------------------------------------| | status_code \n integer | The HTTP response code. | | trace \n string | The unique ID that is used to trace an error. | | errors \n ErrorDetail[] | The collection of error details that is encountered in the request. |

ErrorDetail | Name | Description | |------------------------|-------------------------------------------------| | code \n string | An indicator that describes a specific error. | | message \n string | The short description of a specific error. |

Versioning

All toolchain API requests are prefixed with a segment that represents the API version. The latest version of the toolchain API is v2. The versions of individual components of Continuous Delivery, such as toolchain and pipeline, may change independently of each other.

Pagination

Some API requests may return multiple results. To avoid performance problems, these results are returned one page at a time, with a limited number of results in each page. GET requests for the following resources use pagination:

/toolchains
/toolchains/{toolchain_id}/tools

The fields first, previous, next, and last are included in the collection response as needed, depending on the number of the results. The href property for these fields contains a URL reference to the appropriate page of results from the collection resource.

The default page size is 20 items, and the maximum size is 200 toolchains and 150 tools. To control the page size, use the limit query parameter.

Token based pagination is used to traverse through the pages. The start query parameter, which corresponds to a pagination token, can be used to traverse to a specific section in the collection. The response will return results from the beginning of the collection and will provide the appropriate start values to traverse through the rest of the collection.

A total_count is also included in the response, indicating how many results exist in the collection.

Rate limiting

Rate limits for API requests are enforced on this service. If the number of requests reaches the request limit within the specified time window, no further requests are accepted until after the time window. Clients that are blocked by rate limited should wait and try the request again later.

An HTTP status code of 429 indicates that the rate limit has been exceeded.

Related APIs

Tekton Pipeline

Continuous Delivery Toolchain v2 | IBM Cloud API Docs