IBM Cloud API Docs

Introduction

Last updated: 2023-02-17

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

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

go get -u github.com/IBM/continuous-delivery-go-sdk/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/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>0.1.3</version>
</dependency>

Gradle example:

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

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.

  • Dallas: https://api.us-south.devops.cloud.ibm.com/toolchain/v2
  • Washington DC: https://api.us-east.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
  • Sydney: https://api.au-syd.devops.cloud.ibm.com/toolchain/v2
  • Tokyo: https://api.jp-tok.devops.cloud.ibm.com/toolchain/v2
  • Osaka: https://api.jp-osa.devops.cloud.ibm.com/toolchain/v2
  • Toronto: https://api.ca-tor.devops.cloud.ibm.com/toolchain/v2
  • São Paulo: https://api.br-sao.devops.cloud.ibm.com/toolchain/v2
  • Madrid: https://api.eu-es.devops.cloud.ibm.com/toolchain/v2

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/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
integer		 The HTTP response code.
trace
string		 The unique ID that is used to trace an error.
errors
ErrorDetail[]		 The collection of error details that is encountered in the request.

ErrorDetail

Name Description
code
string		 An indicator that describes a specific error.
message
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

Methods

Get a list of toolchains

Returns a list of toolchains that the caller is authorized to access and that meets the provided query parameters.

GET /toolchains

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • resource-controller.instance.retrieve

Request

Query Parameters

  • resource_group_id
    Required*
    string

    The resource group ID where the toolchains exist

    Possible values: length = 32, Value must match regular expression ^[0-9a-f]{32}$

    Example: 6a9a01f2cff54a7f966f803d92877123

  • limit
    integer

    Limit the number of results

    Possible values: 1 ≤ value ≤ 200

    Default: 20

  • start
    string

    Pagination token

    Possible values: 0 ≤ length ≤ 100, Value must match regular expression ^([a-zA-Z0-9+=/])+$

  • name
    string

    Exact name of toolchain to look up. This parameter is case sensitive

    Possible values: 0 ≤ length ≤ 128, Value must match regular expression ^([^\x00-\x7F]|[a-zA-Z0-9-._ ])+$

    Example: TestToolchainV2

  • curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --get --data "resource_group_id={resource_group_id}" --data "limit={limit}"   "{base_url}/toolchains"
  • listToolchainsOptions := toolchainClient.NewListToolchainsOptions(resourceGroupId)
listToolchainsOptions.SetLimit(limit)

toolchains, response, err := toolchainClient.ListToolchains(listToolchainsOptions)
  • const response = await toolchainService.listToolchains({
    resourceGroupId: resourceGroupId
});
  • response = toolchain_service.list_toolchains(
    resource_group_id = resource_group_id
)
  • ListToolchainsOptions listToolchainsOptions = new ListToolchainsOptions.Builder()
    .resourceGroupId(resourceGroupId)
    .build();
Response<ToolchainCollection> listToolchainsResponse = service.listToolchains(listToolchainsOptions).execute();
ToolchainCollection toolchainCollection = listToolchainsResponse.getResult();

Response

Response Body

ToolchainCollection

Response structure for GET toolchains

Status Code

  • 200

    Successful request

  • 400

    Missing toolchain parameters or unsupported toolchain

  • 401

    Invalid authentication credentials

  • 404

    Resource group with the provided ID is not found or accessible

  • 500

    Internal system error encountered

Example responses
  • {
  "limit": 3,
  "total_count": 12,
  "first": {
    "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains?resource_group_id=6a9a01f2cff54a7f966f803d92877123&limit=3"
  },
  "next": {
    "start": "eyJ0b29sY2hhaW5fZ3VpZCI6ImVhZGVmNGYzLThlMzktNDY2OS04NmY0LWU1NTA1MWExMjMzOCJ9",
    "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains?resource_group_id=6a9a01f2cff54a7f966f803d92877123&limit=3&start=eyJ0b29sY2hhaW5fZ3VpZCI6ImVhZGVmNGYzLThlMzktNDY2OS04NmY0LWU1NTA1MWExMjMzOCJ9"
  },
  "previous": {
    "start": "eyJ0b29sY2hhaW5fZ3VpZCI6IjA4NDFlYTMxLTEzMDMtNDJiZC1hYmMyLTQzMjYzZDg0YmU0OSJ9",
    "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains?resource_group_id=6a9a01f2cff54a7f966f803d92877123&limit=3&start=eyJ0b29sY2hhaW5fZ3VpZCI6IjA4NDFlYTMxLTEzMDMtNDJiZC1hYmMyLTQzMjYzZDg0YmU0OSJ9"
  },
  "last": {
    "start": "eyJ0b29sY2hhaW5fZ3VpZCI6ImYxNTI3ZjkyLTQyOTAtNGUzZi1iMmIzLTc3ODg5YTE0NDkzOCJ9",
    "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains?resource_group_id=6a9a01f2cff54a7f966f803d92877123&limit=3&start=eyJ0b29sY2hhaW5fZ3VpZCI6ImYxNTI3ZjkyLTQyOTAtNGUzZi1iMmIzLTc3ODg5YTE0NDkzOCJ9"
  },
  "toolchains": [
    {
      "id": "62935028-0202-48fe-b877-7e99c817b856",
      "name": "TestToolchainV2-2",
      "description": "A second sample toolchain",
      "account_id": "f2337426699b4041bc50f1d45042f777",
      "location": "us-south",
      "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
      "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:62935028-0202-48fe-b877-7e99c817b856::",
      "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains/62935028-0202-48fe-b877-7e99c817b856",
      "created_at": "2021-05-05T17:07:09.354Z",
      "updated_at": "2022-01-01T13:13:07.968Z",
      "created_by": "IBMid-123456AB7C"
    },
    {
      "id": "a8334cb6-87a2-4308-8bf0-681f7b418f37",
      "name": "TestToolchainV2-3",
      "description": "A third sample toolchain",
      "account_id": "f2337426699b4041bc50f1d45042f777",
      "location": "us-south",
      "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
      "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:a8334cb6-87a2-4308-8bf0-681f7b418f37::",
      "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains/a8334cb6-87a2-4308-8bf0-681f7b418f37",
      "created_at": "2021-05-05T17:07:09.354Z",
      "updated_at": "2022-01-01T13:13:07.968Z",
      "created_by": "IBMid-123456AB7C"
    },
    {
      "id": "eadef4f3-8e39-4669-86f4-e55051a12338",
      "name": "TestToolchainV2-1",
      "description": "A sample toolchain",
      "account_id": "f2337426699b4041bc50f1d45042f777",
      "location": "us-south",
      "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
      "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:eadef4f3-8e39-4669-86f4-e55051a12338::",
      "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains/eadef4f3-8e39-4669-86f4-e55051a12338",
      "created_at": "2021-05-05T17:07:09.354Z",
      "updated_at": "2022-01-01T13:13:07.968Z",
      "created_by": "IBMid-123456AB7C"
    }
  ]
}
  • {
  "status_code": 400,
  "errors": [
    {
      "code": "invalid_request",
      "message": "The request contained an invalid body or one or more invalid parameters"
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 401,
  "errors": [
    {
      "code": "authentication_error",
      "message": "An error occured during authentication. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 404,
  "errors": [
    {
      "code": "not_found_or_accessible",
      "message": "The requested resource was not found or is not accessible."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 500,
  "errors": [
    {
      "code": "unknown",
      "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}

Create a toolchain

Creates a new toolchain based off the provided parameters in the body

POST /toolchains

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • resource-controller.instance.create

Auditing

Calling this method generates the following auditing event.

  • toolchain.instance.create

Request

Request Body

Required*
ToolchainPrototype

Body structure for creating a toolchain.

  • curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "name": "{toolchain_name}", "resource_group_id": "{resource_group_id}", "description": "{toolchain_description}" }'   "{base_url}/toolchains"
  • createToolchainOptions := toolchainClient.NewCreateToolchainOptions(toolchainName, resourceGroupId)
createToolchainOptions.SetDescription(toolchainDescription)

toolchain, response, err := toolchainClient.CreateToolchain(createToolchainOptions)
  • const toolchainPrototypeModel = {
    description: toolchainDescription,
    name: toolchainName,
    resourceGroupId: resourceGroupId
};

const response = await toolchainService.createToolchain(toolchainPrototypeModel);
  • response = toolchain_service.create_toolchain(
    description = description,
    name = name,
    resource_group_id = resource_group_id
)
  • CreateToolchainOptions createToolchainOptions = new CreateToolchainOptions.Builder()
    .description(description)
    .name(name)
    .resourceGroupId(resourceGroupId)
    .build();
Response<ToolchainPost> createToolchainResponse = service.createToolchain(createToolchainOptions).execute();
ToolchainPost createdToolchain = createToolchainResponse.getResult();

Response

Response Body

ToolchainPost

Response structure for POST toolchain

Status Code

  • 201

    Toolchain successfully created

  • 400

    Missing required toolchain properties, or reached the maximum number of toolchains allowed in the resource group

  • 401

    Invalid authentication credentials

  • 500

    Internal system error encountered

Example responses
  • {
  "id": "ec58a911-c217-4e56-a40b-93482cd18706",
  "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:ec58a911-c217-4e56-a40b-93482cd18706::",
  "location": "us-south",
  "account_id": "f2337426699b4041bc50f1d45042f777",
  "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
  "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains/ec58a911-c217-4e56-a40b-93482cd18706",
  "name": "TestToolchainV2",
  "description": "A sample toolchain to test the API",
  "created_at": "2021-05-05T17:07:09.354Z",
  "created_by": "IBMid-123456AB7C",
  "updated_at": "2021-05-05T17:07:09.354Z"
}
  • {
  "status_code": 400,
  "errors": [
    {
      "code": "invalid_request",
      "message": "The request contained an invalid body or one or more invalid parameters"
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 401,
  "errors": [
    {
      "code": "authentication_error",
      "message": "An error occured during authentication. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 500,
  "errors": [
    {
      "code": "unknown",
      "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}

Get a toolchain

Returns data for a single toolchain identified by its ID

GET /toolchains/{toolchain_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • resource-controller.instance.retrieve

Request

Path Parameters

  • toolchain_id
    Required*

    ID of the toolchain

  • curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/toolchains/{toolchain_id}"
  • getToolchainByIDOptions := toolchainClient.NewGetToolchainByIDOptions(toolchainId)

toolchain, response, err := toolchainClient.GetToolchainByID(getToolchainByIDOptions)
  • const response = await toolchainService.getToolchainById({
    toolchainId: toolchainId
});
  • response = toolchain_service.get_toolchain_by_id(
    toolchain_id = toolchain_id
)
  • GetToolchainByIdOptions getToolchainByIdOptions = new GetToolchainByIdOptions.Builder()
    .toolchainId(toolchainId)
    .build();
Response<Toolchain> getToolchainByIdResponse = service.getToolchainById(getToolchainByIdOptions).execute();
Toolchain toolchain = getToolchainByIdResponse.getResult();

Response

Response Body

Toolchain

Response structure for GET toolchains

Status Code

  • 200

    Successful request

  • 400

    Missing toolchain parameters or unsupported toolchain

  • 401

    Invalid authentication credentials

  • 404

    Toolchain with the provided ID was not found or is not accessible

  • 500

    Internal system error encountered

Example responses
  • {
  "id": "ec58a911-c217-4e56-a40b-93482cd18706",
  "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:ec58a911-c217-4e56-a40b-93482cd18706::",
  "location": "us-south",
  "account_id": "f2337426699b4041bc50f1d45042f777",
  "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
  "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains/ec58a911-c217-4e56-a40b-93482cd18706",
  "name": "TestToolchainV2",
  "description": "A sample toolchain to test the API",
  "created_at": "2021-05-05T17:07:09.354Z",
  "created_by": "IBMid-123456AB7C",
  "updated_at": "2021-05-05T17:07:09.354Z"
}
  • {
  "status_code": 400,
  "errors": [
    {
      "code": "invalid_request",
      "message": "The request contained an invalid body or one or more invalid parameters"
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 401,
  "errors": [
    {
      "code": "authentication_error",
      "message": "An error occured during authentication. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 404,
  "errors": [
    {
      "code": "not_found_or_accessible",
      "message": "The requested resource was not found or is not accessible."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 500,
  "errors": [
    {
      "code": "unknown",
      "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}

Delete a toolchain

Delete the toolchain with the specified ID

DELETE /toolchains/{toolchain_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • resource-controller.instance.delete

Auditing

Calling this method generates the following auditing event.

  • toolchain.instance.delete

Request

Path Parameters

  • toolchain_id
    Required*

    ID of the toolchain

  • curl -X DELETE --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/toolchains/{toolchain_id}"
  • deleteToolchainOptions := toolchainClient.NewDeleteToolchainOptions(toolchainId)

response, err := toolchainClient.DeleteToolchain(deleteToolchainOptions)
  • const response = await toolchainService.deleteToolchain({
    toolchainId: toolchainId
});
  • response = toolchain_service.delete_toolchain(
    toolchain_id = toolchain_id
)
  • DeleteToolchainOptions deleteToolchainOptions = new DeleteToolchainOptions.Builder()
    .toolchainId(toolchainId)
    .build();
Response<Void> deleteToolchainResponse = service.deleteToolchain(deleteToolchainOptions).execute();

Response

Status Code

  • 204

    Toolchain successfully deleted

  • 400

    Missing or invalid path parameters

  • 401

    Invalid authentication credentials

  • 404

    Toolchain with the provided ID was not found or is not accessible, or unsupported toolchain

  • 500

    Internal system error encountered

Example responses
  • {
  "status_code": 400,
  "errors": [
    {
      "code": "invalid_request",
      "message": "The request contained an invalid body or one or more invalid parameters"
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 401,
  "errors": [
    {
      "code": "authentication_error",
      "message": "An error occured during authentication. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 404,
  "errors": [
    {
      "code": "not_found_or_accessible",
      "message": "The requested resource was not found or is not accessible."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 500,
  "errors": [
    {
      "code": "unknown",
      "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}

Update a toolchain

Update the toolchain with the specified ID

PATCH /toolchains/{toolchain_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • resource-controller.instance.update

Auditing

Calling this method generates the following auditing event.

  • toolchain.instance.update

Request

Path Parameters

  • toolchain_id
    Required*

    ID of the toolchain

Request Body

Required*
application/merge-patch+jsonToolchainPrototypePatch

Body structure for the update toolchain PATCH request.

  • curl -X PATCH --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/merge-patch+json"   --data '{ "name": "{new_toolchain_name}", "description": "{new_toolchain_description}" }'   "{base_url}/toolchains/{toolchain_id}"
  • toolchainPatchModel := map[string]interface{}{
    "name": newToolchainName,
    "description": newToolchainDescription,
}
updateToolchainOptions := toolchainClient.NewUpdateToolchainOptions(toolchainId, toolchainPatchModel)
toolchain, response, err := toolchainClient.UpdateToolchain(updateToolchainOptions)
  • const toolchainPatchModel = {
    description: toolchainDescription,
    name: toolchainName
};

const response = await toolchainService.updateToolchain(toolchainPatchModel);
  • toolchain_prototype_patch = {}
toolchain_prototype_patch["description"] = updated_description
toolchain_prototype_patch["name"] = updated_name

response = toolchain_service.update_toolchain(
    toolchain_id = toolchain_id,
    toolchain_prototype_patch = toolchain_prototype_patch,
)
  • HashMap<String, Object> toolchainPrototypePatch = new HashMap<>();
toolchainPrototypePatch.put("name", toolchainName);
toolchainPrototypePatch.put("description", toolchainDescription);
UpdateToolchainOptions updateToolchainOptions = new UpdateToolchainOptions.Builder()
    .toolchainId(toolchainId)
    .toolchainPrototypePatch(toolchainPrototypePatch)
    .build();
Response<ToolchainPatch> toolchainPatchResponse = service.updateToolchain(updateToolchainOptions).execute();
ToolchainPatch updatedToolchain = toolchainPatchResponse.getResult();

Response

Response Body

ToolchainPatch

Response structure for PATCH toolchain

Status Code

  • 200

    Toolchain successfully updated

  • 400

    Missing toolchain parameters or unsupported toolchain

  • 401

    Invalid authentication credentials

  • 403

    Not authorized to modify the toolchain

  • 404

    Toolchain with the provided ID was not found or is not accessible

  • 500

    Internal system error encountered

Example responses
  • {
  "id": "ec58a911-c217-4e56-a40b-93482cd18706",
  "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:ec58a911-c217-4e56-a40b-93482cd18706::",
  "location": "us-south",
  "account_id": "f2337426699b4041bc50f1d45042f777",
  "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
  "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains/ec58a911-c217-4e56-a40b-93482cd18706",
  "name": "newToolchainName",
  "description": "New toolchain description",
  "created_at": "2021-05-05T17:07:09.354Z",
  "created_by": "IBMid-123456AB7C",
  "updated_at": "2022-01-01T13:13:07.968Z"
}
  • {
  "status_code": 400,
  "errors": [
    {
      "code": "invalid_request",
      "message": "The request contained an invalid body or one or more invalid parameters"
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 401,
  "errors": [
    {
      "code": "authentication_error",
      "message": "An error occured during authentication. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 403,
  "errors": [
    {
      "code": "insufficient_permissions",
      "message": "You do not have the necessary permissions to complete this action. To request permissions for a resource group, contact the administrator of the resource or resource group."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 404,
  "errors": [
    {
      "code": "not_found_or_accessible",
      "message": "The requested resource was not found or is not accessible."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 500,
  "errors": [
    {
      "code": "unknown",
      "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}

Create a toolchain event

Creates and sends a custom event to each Event Notifications instance configured as a tool in the toolchain. This operation will fail if no Event Notifications instances are configured in the toolchain.

POST /toolchains/{toolchain_id}/events

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • toolchain.event.send

Auditing

Calling this method generates the following auditing event.

  • toolchain.event.send

Request

Path Parameters

  • toolchain_id
    Required*

    ID of the toolchain to send events from

Request Body

Required*
ToolchainEventPrototype

Body structure for creating a toolchain event.

  • curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "title": "My event title", "description": "My event description", "content_type": "text/plain", "data": { "text_plain": "My event details" } }'   "{base_url}/toolchains/{toolchain_id}/events"
  • createToolchainEventOptions := toolchainClient.NewCreateToolchainEventOptions(toolchainId, eventTitle, eventDescription, "text/plain")
eventDetails := "My event details"
createToolchainEventOptions.SetData(&cdtoolchainv2.ToolchainEventPrototypeData{ TextPlain: &eventDetails })

event, response, err := toolchainClient.CreateToolchainEvent(createToolchainEventOptions)
  • const response = await toolchainService.createToolchainEvent({
    toolchainId: toolchainId,
    title: eventTitle,
    description: eventDescription,
    contentType: "text/plain",
    data: {
        text_plain: eventDetails
    }
})
  • response = toolchain_service.create_toolchain_event(
    toolchain_id = toolchain_id,
    title = event_title,
    description = event_description,
    content_type = "text/plain",
    data = {
        "text_plain": event_details
    }
)
  • ToolchainEventPrototypeData eventDetails = new ToolchainEventPrototypeData.Builder()
    .textPlain("My event details")
    .build();
CreateToolchainEventOptions createToolchainEventOptions = new CreateToolchainEventOptions.Builder()
    .toolchainId(toolchainId)
    .title(eventTitle)
    .description(eventDescription)
    .contentType("text/plain")
    .data(eventDetails)
    .build();
Response<ToolchainEventPost> createToolchainEventResponse = service.createToolchainEvent(createToolchainEventOptions).execute();
ToolchainEventPost createdEvent = createToolchainEventResponse.getResult();

Response

Response Body

ToolchainEventPost

Response structure for POST toolchain event

Status Code

  • 200

    Request acknowledged and successfully processed

  • 400

    Missing or incorrect required toolchain event properties

  • 401

    Invalid authentication credentials

  • 403

    Unauthorized to send events from toolchain

  • 404

    Toolchain with provided ID was not found or is not accessible

  • 413

    Exceeded maximum allowed size for the event payload

  • 429

    Too many requests have been made within a given time window

  • 500

    Internal system error encountered

Example responses
  • {
  "id": "59ed5e54-93c0-4c24-964a-400c9fd4e7bb"
}
  • {
  "status_code": 400,
  "errors": [
    {
      "code": "invalid_request",
      "message": "The request contained an invalid body or one or more invalid parameters"
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 401,
  "errors": [
    {
      "code": "authentication_error",
      "message": "An error occured during authentication. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 403,
  "errors": [
    {
      "code": "insufficient_permissions",
      "message": "You do not have the necessary permissions to complete this action. To request permissions for a resource group, contact the administrator of the resource or resource group."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 404,
  "errors": [
    {
      "code": "not_found_or_accessible",
      "message": "The requested resource was not found or is not accessible."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 413,
  "errors": [
    {
      "code": "exceeded_max_payload",
      "message": "The request body exceeded the maximum size."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 429,
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests have been made within a given time window."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 500,
  "errors": [
    {
      "code": "unknown",
      "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}

Get a list of tools bound to a toolchain

Returns a list of tools bound to a toolchain that the caller is authorized to access and that meet the provided query parameters

GET /toolchains/{toolchain_id}/tools

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • resource-controller.instance.retrieve

Auditing

Calling this method generates the following auditing event.

  • toolchain.tool-instance.read

Request

Path Parameters

  • toolchain_id
    Required*

    ID of the toolchain that tools are bound to

Query Parameters

  • limit
    integer

    Limit the number of results

    Possible values: 1 ≤ value ≤ 150

    Default: 20

  • start
    string

    Pagination token

    Possible values: 0 ≤ length ≤ 100, Value must match regular expression ^([a-zA-Z0-9+=/])+$

  • curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --get --data "limit={limit}"   "{base_url}/toolchains/{toolchain_id}/tools"
  • listToolsOptions := toolchainClient.NewListToolsOptions(toolchainId)
listToolsOptions.SetLimit(limit)

tools, response, err := toolchainClient.ListTools(listToolsOptions)
  • const response = await toolchainService.listTools({
    toolchainId: toolchainId
});
  • response = toolchain_service.list_tools(
    toolchain_id = toolchain_id
)
  • ListToolsOptions listToolsOptions = new ListToolsOptions.Builder()
    .toolchainId(toolchainId)
    .build();
Response<ToolchainToolCollection> listToolsResponse = service.listTools(listToolsOptions).execute();
ToolchainToolCollection toolCollection = listToolsResponse.getResult();

Response

Response Body

ToolchainToolCollection

Response structure for GET tools

Status Code

  • 200

    Successful request

  • 400

    Missing or invalid path or required query parameters, or unsupported toolchain

  • 401

    Invalid authentication credentials

  • 404

    Resource group with provided ID was not found or is not accessible

  • 500

    Internal system error encountered

Example responses
  • {
  "limit": 3,
  "total_count": 12,
  "first": {
    "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools?limit=3"
  },
  "previous": {
    "start": "eyJpbnN0YW5jZV9pZCI6IjEzODgxYTZkLWI1ZDktNDQwNi05MzFmLWM4NTc1NDc0MmQ1NSJ9",
    "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools?limit=3&start=eyJpbnN0YW5jZV9pZCI6IjEzODgxYTZkLWI1ZDktNDQwNi05MzFmLWM4NTc1NDc0MmQ1NSJ9"
  },
  "next": {
    "start": "eyJpbnN0YW5jZV9pZCI6IjlkZDBjNDc3LWYxNzMtNGMzZi1hN2NmLWQyNzAyNmFjZTM3OSJ9",
    "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools?limit=3&start=eyJpbnN0YW5jZV9pZCI6IjlkZDBjNDc3LWYxNzMtNGMzZi1hN2NmLWQyNzAyNmFjZTM3OSJ9"
  },
  "last": {
    "start": "eyJpbnN0YW5jZV9pZCI6ImQzYzkxMDYwLTcwOWMtNGZmZi1hODUwLTllZDFkZWMwMGYxYiJ9",
    "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools?limit=3&start=eyJpbnN0YW5jZV9pZCI6ImQzYzkxMDYwLTcwOWMtNGZmZi1hODUwLTllZDFkZWMwMGYxYiJ9"
  },
  "tools": [
    {
      "id": "2983b160-fc37-4c45-8a8f-e616ad7e470b",
      "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e:tool:2983b160-fc37-4c45-8a8f-e616ad7e470b",
      "name": "MyTool-1",
      "toolchain_id": "d02d29f1-e7bb-4977-8a6f-26d7b7bb893e",
      "toolchain_crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e::",
      "tool_type_id": "slack",
      "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
      "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools/2983b160-fc37-4c45-8a8f-e616ad7e470b",
      "referent": {
        "ui_href": "https://team-one.slack.com/messages/channel-one"
      },
      "updated_at": "2022-01-01T13:13:07.968Z",
      "parameters": {
        "label": "#channel-one",
        "channel_name": "channel-one",
        "team_url": "team-one",
        "apikey": "hash:SHA3-512:5bad9f13ac3580162ddb2980909fe3375a64e61b5c3d78d819cc02e84f98810dc5f8b848e07babedeaaabf78cfcbb71fe6098ea294b702a9deff904836322bd2"
      },
      "state": "configured"
    },
    {
      "id": "93f7a2b1-a1cb-46f2-9ab7-dc2e3443dd3e",
      "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e:tool:93f7a2b1-a1cb-46f2-9ab7-dc2e3443dd3e",
      "name": "MyTool-3",
      "toolchain_id": "d02d29f1-e7bb-4977-8a6f-26d7b7bb893e",
      "toolchain_crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e::",
      "tool_type_id": "slack",
      "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
      "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools/93f7a2b1-a1cb-46f2-9ab7-dc2e3443dd3e",
      "referent": {
        "ui_href": "https://team-three.slack.com/messages/channel-three"
      },
      "updated_at": "2022-01-01T13:13:07.968Z",
      "parameters": {
        "label": "#channel-three",
        "channel_name": "channel-three",
        "team_url": "team-three",
        "apikey": "hash:SHA3-512:44c285cc194a392cb55bae8f306a8a2778477bff07759a75739d00d24a8a3d41ef1acfa88571075b67afc53cc1ec37cb4ee1e2589debc99b4e7b4d283ede06ce"
      },
      "state": "configured"
    },
    {
      "id": "9dd0c477-f173-4c3f-a7cf-d27026ace379",
      "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e:tool:9dd0c477-f173-4c3f-a7cf-d27026ace379",
      "name": "MyTool-2",
      "toolchain_id": "d02d29f1-e7bb-4977-8a6f-26d7b7bb893e",
      "toolchain_crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e::",
      "tool_type_id": "slack",
      "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
      "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools/9dd0c477-f173-4c3f-a7cf-d27026ace379",
      "referent": {
        "ui_href": "https://team-two.slack.com/messages/channel-two"
      },
      "updated_at": "2022-01-01T13:13:07.968Z",
      "parameters": {
        "label": "#channel-two",
        "channel_name": "channel-two",
        "team_url": "team-two",
        "apikey": "hash:SHA3-512:3c0ec55cc85421e41aeffcdd2c94a637af1f189deb5f0e8682d2c339ee7e72ed287648ce0a5f529bae5dce36c0e80669ceadf9ea495a4350f70a12fa58d1a4fe"
      },
      "state": "configured"
    }
  ]
}
  • {
  "status_code": 400,
  "errors": [
    {
      "code": "invalid_request",
      "message": "The request contained an invalid body or one or more invalid parameters"
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 401,
  "errors": [
    {
      "code": "authentication_error",
      "message": "An error occured during authentication. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 404,
  "errors": [
    {
      "code": "not_found_or_accessible",
      "message": "The requested resource was not found or is not accessible."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 500,
  "errors": [
    {
      "code": "unknown",
      "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}

Create a tool

Provisions a new tool based off the provided parameters in the body and binds it to the specified toolchain

POST /toolchains/{toolchain_id}/tools

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • toolchain.instance.create-bindings

Auditing

Calling this method generates the following auditing events.

  • toolchain.tool-instance.create

  • toolchain.tool-instance.deploy

Request

Path Parameters

  • toolchain_id
    Required*

    ID of the toolchain to bind the tool to

Request Body

Required*
ToolchainToolPrototype

Details on the new tool

  • curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "name": "{tool_name}", "tool_type_id": "{tool_type_id}", "parameters": {json_parameters_object} }'   "{base_url}/toolchains/{toolchain_id}/tools"
  • createToolOptions := toolchainClient.NewCreateToolOptions(toolchainId, toolTypeId)
createToolOptions.SetName(toolName)
createToolOptions.SetParameters(toolParameters)

tool, response, err := toolchainClient.CreateTool(createToolOptions)
  • const toolParameters = {};

const toolPrototypeModel = {
    toolchainId: toolchainId,
    toolTypeId: toolTypeId,
    name: toolName,
    parameters: toolParameters
};

const response = await toolchainService.createTool(toolPrototypeModel);
  • tool_parameters = {}

response = toolchain_service.create_tool(
    name = name,
    toolchain_id = toolchain_id,
    tool_type_id = tool_type_id,
    parameters = tool_parameters
)

  • HashMap<String, Object> toolParameters = new HashMap<>();
CreateToolOptions createToolOptions = new CreateToolOptions.Builder()
    .name(name)
    .parameters(toolParameters)
    .toolchainId(toolchainId)
    .toolTypeId(toolTypeId)
    .build();
Response<ToolchainToolPost> createToolResponse = service.createTool(createToolOptions).execute();
ToolchainToolPost createdTool = createToolResponse.getResult();

Response

Response Body

ToolchainToolPost

POST tool response body

Status Code

  • 201

    Tool successfully created

  • 400

    Missing required tool properties, or reached the maximum number of tools allowed in toolchain

  • 401

    Invalid authentication credentials

  • 500

    Internal system error encountered

Example responses
  • {
  "id": "ec58a911-c217-4e56-a40b-93482cd18706",
  "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e:tool:ec58a911-c217-4e56-a40b-93482cd18706",
  "name": "MyTool",
  "toolchain_id": "d02d29f1-e7bb-4977-8a6f-26d7b7bb893e",
  "toolchain_crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e::",
  "tool_type_id": "slack",
  "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
  "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools/ec58a911-c217-4e56-a40b-93482cd18706",
  "referent": {
    "ui_href": "https://my-team.slack.com/messages/my-channel"
  },
  "updated_at": "2022-01-01T13:13:07.968Z",
  "parameters": {
    "label": "#my-channel",
    "channel_name": "my-channel",
    "team_url": "my-team",
    "apikey": "hash:SHA3-512:5bad9f13ac3580162ddb2980909fe3375a64e61b5c3d78d819cc02e84f98810dc5f8b848e07babedeaaabf78cfcbb71fe6098ea294b702a9deff904836322bd2"
  },
  "state": "configured"
}
  • {
  "status_code": 400,
  "errors": [
    {
      "code": "invalid_request",
      "message": "The request contained an invalid body or one or more invalid parameters"
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 401,
  "errors": [
    {
      "code": "authentication_error",
      "message": "An error occured during authentication. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 500,
  "errors": [
    {
      "code": "unknown",
      "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}

Get a tool

Returns a tool that is bound to the provided toolchain

GET /toolchains/{toolchain_id}/tools/{tool_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • resource-controller.instance.retrieve

Auditing

Calling this method generates the following auditing event.

  • toolchain.tool-instance.read

Request

Path Parameters

  • toolchain_id
    Required*

    ID of the toolchain

  • tool_id
    Required*

    ID of the tool bound to the toolchain

  • curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/toolchains/{toolchain_id}/tools/{tool_id}"
  • getToolByIDOptions := toolchainClient.NewGetToolByIDOptions(toolchainId, toolId)

tool, response, err := toolchainClient.GetToolByID(getToolByIDOptions)
  • const response = await toolchainService.getToolById({
    toolchainId: toolchainId,
    toolId: toolId
});
  • response = toolchain_service.get_tool_by_id(
    toolchain_id = toolchain_id,
    tool_id = tool_id
)
  • GetToolByIdOptions getToolByIdOptions = new GetToolByIdOptions.Builder()
    .toolchainId(toolchainId)
    .toolId(toolId);
    .build();
Response<ToolchainTool> getToolByIdResponse = service.getToolById(getToolByIdOptions).execute();
ToolchainTool tool = getToolByIdResponse.getResult();

Response

Response Body

ToolchainTool

Response structure for GET tool

Status Code

  • 200

    Successful request

  • 400

    Missing or invalid path parameters

  • 401

    Invalid authentication credentials

  • 404

    Tool with provided ID was not found or is not accessible

  • 500

    Internal system error encountered

Example responses
  • {
  "id": "ec58a911-c217-4e56-a40b-93482cd18706",
  "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e:tool:ec58a911-c217-4e56-a40b-93482cd18706",
  "name": "MyTool",
  "toolchain_id": "d02d29f1-e7bb-4977-8a6f-26d7b7bb893e",
  "toolchain_crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e::",
  "tool_type_id": "slack",
  "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
  "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools/ec58a911-c217-4e56-a40b-93482cd18706",
  "referent": {
    "ui_href": "https://my-team.slack.com/messages/my-channel"
  },
  "updated_at": "2022-01-01T13:13:07.968Z",
  "parameters": {
    "label": "#my-channel",
    "channel_name": "my-channel",
    "team_url": "my-team",
    "apikey": "hash:SHA3-512:5bad9f13ac3580162ddb2980909fe3375a64e61b5c3d78d819cc02e84f98810dc5f8b848e07babedeaaabf78cfcbb71fe6098ea294b702a9deff904836322bd2"
  },
  "state": "configured"
}
  • {
  "status_code": 400,
  "errors": [
    {
      "code": "invalid_request",
      "message": "The request contained an invalid body or one or more invalid parameters"
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 401,
  "errors": [
    {
      "code": "authentication_error",
      "message": "An error occured during authentication. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 404,
  "errors": [
    {
      "code": "not_found_or_accessible",
      "message": "The requested resource was not found or is not accessible."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 500,
  "errors": [
    {
      "code": "unknown",
      "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}

Delete a tool

Delete the tool with the specified ID

DELETE /toolchains/{toolchain_id}/tools/{tool_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • toolchain.instance.delete-bindings

Auditing

Calling this method generates the following auditing events.

  • toolchain.tool-instance.delete

  • toolchain.tool-instance.undeploy

Request

Path Parameters

  • toolchain_id
    Required*

    ID of the toolchain

  • tool_id
    Required*

    ID of the tool bound to the toolchain

  • curl -X DELETE --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/toolchains/{toolchain_id}/tools/{tool_id}"
  • deleteToolOptions := toolchainClient.NewDeleteToolOptions(toolchainId, toolId)

response, err := toolchainClient.DeleteTool(deleteToolOptions)
  • const response = await toolchainService.deleteTool({
    toolchainId: toolchainId,
    toolId: toolId
});
  • response = toolchain_service.delete_tool(
    toolchain_id = toolchain_id,
    tool_id = tool_id
)
  • DeleteToolOptions deleteToolOptions = new DeleteToolOptions.Builder()
    .toolchainId(toolchainId)
    .toolId(toolId)
    .build();
Response<Void> deleteToolResponse = service.deleteTool(deleteToolOptions).execute();

Response

Status Code

  • 204

    Tool successfully deleted

  • 400

    Missing or invalid path parameters

  • 401

    Invalid authentication credentials

  • 404

    Tool with the provided ID was not found or is not accessible, or unsupported toolchain

  • 500

    Internal system error encountered

Example responses
  • {
  "status_code": 400,
  "errors": [
    {
      "code": "invalid_request",
      "message": "The request contained an invalid body or one or more invalid parameters"
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 401,
  "errors": [
    {
      "code": "authentication_error",
      "message": "An error occured during authentication. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 404,
  "errors": [
    {
      "code": "not_found_or_accessible",
      "message": "The requested resource was not found or is not accessible."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 500,
  "errors": [
    {
      "code": "unknown",
      "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}

Update a tool

Update the tool with the specified ID

PATCH /toolchains/{toolchain_id}/tools/{tool_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • resource-controller.instance.update

Auditing

Calling this method generates the following auditing event.

  • toolchain.tool-instance.update

Request

Path Parameters

  • toolchain_id
    Required*

    ID of the toolchain

  • tool_id
    Required*

    ID of the tool bound to the toolchain

Request Body

Required*
application/merge-patch+jsonToolchainToolPrototypePatch

Details on the new tool

  • curl -X PATCH --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/merge-patch+json"   --data '{ "name": "{new_tool_name}", "parameters": {new_json_parameters_object} }'   "{base_url}/toolchains/{toolchain_id}/tools/{tool_id}"
  • toolPatchModel := map[string]interfact{}{
    "name": "newToolName",
    "parameters": "newToolParameters",
}
updateToolOptions := toolchainClient.NewUpdateToolOptions(toolchainId, toolId, toolPatchModel)
tool, response, err := toolchainClient.UpdateTool(updateToolOptions)
  • const newToolParameters = {};

const toolPatchModel = {
    toolchainId: toolchainId,
    toolId: toolId,
    name: newToolName,
    parameters: newToolParameters
};

const response = await toolchainService.updateTool(toolPatchModel);
  • updated_tool_parameters = {}

tool_prototype_patch = {}
tool_prototype_patch["name"] = updated_name
tool_prototype_patch["parameters"] = updated_tool_parameters

response = toolchain_service.update_tool(
    toolchain_id = toolchain_id,
    tool_id = tool_id,
    toolchain_tool_prototype_patch = tool_prototype_patch
)
  • HashMap<String, Object> toolPrototypePatch = new HashMap<>();
toolPrototypePatch.put("name", toolName);
toolPrototypePatch.put("parameters", toolParameters);
UpdateToolOptions updateToolOptions = new UpdateToolOptions.Builder()
    .toolId(toolId)
    .toolchainId(toolchainId)
    .toolchainToolPrototypePatch(toolPrototypePatch)
    .build();
Response<ToolchainToolPatch> updateToolResponse = service.updateTool(updateToolOptions).execute();
ToolchainToolPatch updatedTool = updateToolResponse.getResult();

Response

Response Body

ToolchainToolPatch

Response structure for PATCH tool

Status Code

  • 200

    Tool successfully updated

  • 400

    Missing or invalid path parameters

  • 401

    Invalid authentication credentials

  • 403

    Not authorized to modify the tool

  • 409

    Conflicting tool type IDs in the body and the target tool

  • 500

    Internal system error encountered

Example responses
  • {
  "id": "ec58a911-c217-4e56-a40b-93482cd18706",
  "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e:tool:ec58a911-c217-4e56-a40b-93482cd18706",
  "name": "MyTool",
  "toolchain_id": "d02d29f1-e7bb-4977-8a6f-26d7b7bb893e",
  "toolchain_crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e::",
  "tool_type_id": "slack",
  "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
  "href": "https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools/ec58a911-c217-4e56-a40b-93482cd18706",
  "referent": {
    "ui_href": "https://my-team.slack.com/messages/my-channel"
  },
  "updated_at": "2022-01-01T13:13:07.968Z",
  "parameters": {
    "label": "#my-channel",
    "channel_name": "my-channel",
    "team_url": "my-team",
    "apikey": "hash:SHA3-512:5bad9f13ac3580162ddb2980909fe3375a64e61b5c3d78d819cc02e84f98810dc5f8b848e07babedeaaabf78cfcbb71fe6098ea294b702a9deff904836322bd2"
  },
  "state": "configured"
}
  • {
  "status_code": 400,
  "errors": [
    {
      "code": "invalid_request",
      "message": "The request contained an invalid body or one or more invalid parameters"
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 401,
  "errors": [
    {
      "code": "authentication_error",
      "message": "An error occured during authentication. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 403,
  "errors": [
    {
      "code": "insufficient_permissions",
      "message": "You do not have the necessary permissions to complete this action. To request permissions for a resource group, contact the administrator of the resource or resource group."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 409,
  "errors": [
    {
      "code": "conflict",
      "message": "The target resource is already in the requested state."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
  • {
  "status_code": 500,
  "errors": [
    {
      "code": "unknown",
      "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
    }
  ],
  "trace": "3KADyw3zCjKvP5LkC1L3wM"
}
id=curlclassName=tab-item-selected