IBM Cloud API Docs

Introduction

Last updated: 2020-04-14

IBM Cloud Schematics delivers Terraform so that you can use a high-level scripting language to model the resources that you want in your IBM Cloud environment, and enable Infrastructure as Code (IaC). Terraform is an open source software that is developed by HashiCorp that enables predictable and consistent resource provisioning to rapidly build complex, multitier cloud environments.

IBM Cloud Schematics and Ansible are the complementary solutions, where Ansible helps you to provision use case, config management, and deploy a secured application. IBM Cloud Schematics also supports Ansible Galaxy to streamline your automation tasks by using roles and collections.

The following list provides the detailed documentation.

The code examples on this tab use the IBM Cloud Schematics SDK for Java.

Gradle

compile group: 'com.ibm.cloud', name: 'schematics', version: '0.+'

Maven

Maven installation instructions

GitHub

https://github.com/ibm/schematics-java-sdk

The code examples on this tab use the IBM Cloud Schematics SDK for Node.js.

Installation

npm install --save @ibm-cloud/ibm-schematics

GitHub

https://github.com/ibm/schematics-node-sdk

The code examples on this tab use the IBM Cloud Schematics SDK for Python.

Installation

pip3 install ibm-schematics

GitHub

https://github.com/ibm/schematics-python-sdk

The code examples on this tab use the IBM Cloud Schematics SDK for Go.

Installation

go get -u github.com/IBM/schematics-go-sdk

GitHub

https://github.com/ibm/schematics-go-sdk

Before you begin

Authentication

The IBM Cloud Schematics API uses Identity and Access Management (IAM) to authenticate requests. Pass a bearer token in an Authorization header or an apikey. Tokens support authenticated requests without embedding service credentials in every call. API keys use basic authentication. For more information, see IAM access.

Authentication with external configuration

In this scenario, configuration is defined with an external credentials file and authenticator that is constructed by SDK's authenticator factory during client initialization. It avoids hardcoding credentials within application code.

The default name of the credentials file is ibm-credentials.env. It is expected to be located in either the current directory or in the user's home directory. The path and name of the file can be controlled by using the IBM_CREDENTIALS_FILE environment variable.

The name of each configuration property contains the service name along with the actual attribute name in the form <service-name>_<attribute-name>.

It is not necessary to use a .env file, these properties can be set by using environment variables with the same name in the environment where the applications ran.

Variable guide for the authentication code samples

`{apikey}` IAM API key
`{url}` URL of Schematics instance

SDK managing the IAM token. Replace {apikey} and {url}.

IBM_SCHEMATICS_URL={url}
IBM_SCHEMATICS_APIKEY={apikey}

import com.ibm.cloud.schematics.v1.Schematics;

Schematics service = Schematics.newInstance("ibm-schematics");

const SchematicsV1 = require('@ibm-cloud/ibm-schematics/schematics/v1');

const service = SchematicsV1.newInstance({
    serviceName: 'ibm-schematics'
});

from ibm_schematics.schematics_v1 import SchematicsV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

service = SchematicsV1.new_instance(service_name="ibm-schematics")

import (
    "github.com/IBM/schematics-go-sdk/schematicsv1"
)
schematicsService, err := schematicsv1.NewSchematicsV1UsingExternalConfig(&schematicsv1.SchematicsV1Options{
    ServiceName: "ibm-schematics",
})

Programmatic authentication

In this scenario authentication that is configured by constructing an authenticator instance provides the configuration attributes programmatically and then passing this instance to a client instantiation.

SDK managing the IAM token.

import com.ibm.cloud.schematics.v1.Schematics;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

IamAuthenticator authenticator = new IamAuthenticator("{apikey}");

Schematics service = new Schematics(Schematics.DEFAULT_SERVICE_NAME, authenticator);

service.setServiceUrl("{url}");

const SchematicsV1  = require('@ibm-cloud/ibm-schematics/schematics/v1');
const { IamAuthenticator } = require('ibm-cloud-sdk-core');

const authenticator = new IamAuthenticator({
    apikey: '{apikey}'
});

const service = new SchematicsV1({
    authenticator: authenticator
});

service.setServiceUrl('{url}');

from ibm_schematics.schematics_v1 import SchematicsV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')

service = SchematicsV1(authenticator=authenticator)

service.set_service_url('{url}')

import (
    "github.com/IBM/go-sdk-core/v4/core"
    "github.com/IBM/schematics-go-sdk/schematicsv1"
)
authenticator := &core.IamAuthenticator{
    ApiKey: "{apikey}",
}
schematicsv1.NewSchematicsV1(
    &schematicsv1.SchematicsV1Options{
        URL:           "{url}",
        Authenticator: authenticator,
    }
)

Authorization

To use the IBM Cloud Schematics API, you must be authorized to work with IBM Cloud Schematics. Schematics uses service access roles in Identity and Access Management (IAM) to determine the permissions that you have in Schematics. For more information about needed permissions, see Managing user access.

If you are assigned an IBM Cloud Schematics service access role, you can view, create, update, delete, or run an action against your Workspaces in Schematics. To provision the IBM Cloud resources that you defined in your Terraform template, you must be assigned the IAM platform or service access role that is needed to provision the individual resource. For example, to provision an IBM Cloud Kubernetes Service cluster, you must have the Administrator platform role and the Manager service access role for IBM Cloud Kubernetes Service in addition to the permissions in IBM Cloud Schematics. Refer to the documentation for your resource to determine the access policies that you need to provision and work with your resource.

API endpoints

IBM Cloud Schematics provides different APIs that you can use to create and work with Workspaces in specific locations. The API endpoint determines where your Schematics actions run and where your Workspace data is stored. By default, the information that is stored in Schematics is encrypted in transit and at rest. To ensure disaster recovery, your data is replicated to another location within the same region. Make sure that your data can be stored in these regions before you start by using Schematics.

The GetServiceURLForRegion function with the x-ibm-region parameters in the API returns the service URL to be used for the specified region. Following table lists the servers object in the API definition.

API endpoint
Location API endpoint Location where Schematics actions run Data is stored in Data is replicated to
North America Public: https://us.schematics.cloud.ibm.com
IBM Cloud Schematics actions that are run in either the us-south or us-east location. Workspaces that are created with this endpoint and all associated data are stored in the US. Data is replicated between two locations in the US.
Dallas Public: https://us-south.schematics.cloud.ibm.com

Private: https://private-us-south.schematics.cloud.ibm.com		 All IBM Cloud Schematics actions run in the Dallas (us-south) location. All Workspaces are stored in the Dallas (us-south) location. Data is replicated between two locations in the US for disaster recovery purposes.
Washington Public: https://us-east.schematics.cloud.ibm.com

Private: https://private-us-east.schematics.cloud.ibm.com		 All IBM Cloud Schematics actions run in the Washington (us-east) location. All workspaces are stored in the Washington (us-east) location. Data is replicated between two locations in the US for disaster recovery purposes.
Europe Public: https://eu.schematics.cloud.ibm.com
IBM Cloud Schematics actions that are run in either the eu-de or eu-gb location. Workspaces that are created with this endpoint and all associated data are stored in Europe. Data is replicated between two locations in Europe.
Frankfurt Public: https://eu-de.schematics.cloud.ibm.com

Private: https://private-eu-de.schematics.cloud.ibm.com		 All IBM Cloud Schematics actions run in the Frankfurt (eu-de) location. All Workspaces are stored in the Frankfurt (eu-de) location. Data is replicated between two locations in Europe for disaster recovery purposes.
London Public: https://eu-gb.schematics.cloud.ibm.com

Private: https://private-eu-gb.schematics.cloud.ibm.com		 All IBM Cloud Schematics actions run in the London (eu-gb) location. All Workspaces are stored in the London (eu-gb) location. Data is replicated between two locations in Europe for disaster recovery purposes.

Versioning

All API requests require a major version in the path (/v1/).

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

Error handling code
HTTP error code Description Recovery
200 Success The request was successful.
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all needed parameters in your request.
401 Unauthorized You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized to access '{workspace}'. Check that you have the correct access credentials and permissions.
404 Not Found The requested resource might not be found.
408 Request Timeout The connection to the server timed out. Wait a few minutes, then try again.
409 Conflict The entity is already in the requested state.
429 Too Many Requests Too many requests are made within a time window. Wait and then call the API again.
500 Internal Server Error IBM Cloud Schematics is disabled. Your request might not be processed. Wait few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
503 Service Temporarily Unavailable IBM Cloud Schematics might not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

Code example

If an error response from the server endpoint the Java SDK throws an exception from the com.ibm.cloud.sdk.core.service.exception package. The base class for all exception classes is ServiceResponseException - that derives from unchecked RuntimeException - to handle any error response from the server. The list provides predefined exceptions and their corresponding statusCode and message content.

Exception handling
Exception Status Code and default error message
ServiceResponseException Base class for all exceptions
BadRequestException 400 Bad Request
UnauthorizedException 401 Unauthorized
ForbiddenException 403 Forbidden
NotFoundException 404 Not found
ConflictException 409 Conflict
UnsupportedException 415 Unsupported media type
InternalServerErrorException 500 Internal server error
IllegalArgumentException An invalid argument was passed to the method.

All service exceptions contain the following fields:

Java exception fields
Field Description
statusCode HTTP response status code
message the error message returned in the response
debuggingInfo a Map<String, Object> that contains the unmarshalled error response object when a JSON error response is returned.
It provides more information beyond the error message.

Example error handling

import com.ibm.cloud.sdk.core.service.exception.BadRequestException;
import com.ibm.cloud.sdk.core.service.exception.NotFoundException;
import com.ibm.cloud.sdk.core.service.exception.ServiceResponseException;
import com.ibm.cloud.sdk.core.service.exception.UnauthorizedException;

try {
  // Invoke a Schematics method request
} catch (BadRequestException e) {
  // Handle Bad Request (400) exception
} catch (UnauthorizedException e) {
  // Handle Unauthorized (401) exception
} catch (NotFoundException e) {
  // Handle Not Found (404) exception
} catch (ServiceResponseException se) {
  System.out.println("Service returned status code "
    + se.getStatusCode() + ": " + se.getMessage());
  System.out.println("Detailed error info: " + se.getDebuggingInfo().getOrDefault("reason", "")););
} catch (RuntimeException re) {
  // Handle other error conditions
  System.out.println("Unexpected Exception: \n" + re.getMessage());
}

Code example

If an error response from the server endpoint the Node SDK creates an Error object that contains either the HTTP response error message or a generic error message. If the network problems the axios package generates an Error object. This Error object is passed as the first parameter to the callback function, its failure describes the content as shown in the following table.

Node exception fields
Field Description
status HTTP response status code
statusText a text description of the status code
message generic error message
body the error response body as text

Example error handling

service.<Schematics API Method Request>(params)
  .then((response) => {
    // ...handle successful response...
  })
  .catch(error => {
    console.log("Error status code: " + error.status);
    console.log("Error status text: " + error.statusText);
    console.log("Error message:     " + error.message);
    console.log("Error details:     " + error.body)
  });

Code example

If an error response from the server endpoint the Python SDK throws an ApiException that includes more information about the cause of the failure. It provides the following details:

Python exception fields
Field Description
code HTTP response status code
message the error message returned in the response
reason a more detailed description about the cause of the failure

Example error handling

from ibm_cloud_sdk_core import ApiException

try:
  # Invoke a Schematics method request
except ApiException as ae:
  print("Method failed")
  print(" - status code: " + str(ae.code))
  print(" - error message: " + ae.message)
  if ("reason" in ae.http_response.json()):
    print(" - reason: " + ae.http_response.json()["reason"])


from requests import ConnectionError, ReadTimeout, RequestException

try:
  # Invoke a Schematics method request
except ConnectionError as cerr:
  print("Connection error occurred:")
  print(cerr)
except ReadTimeout as rt:
  # The server did not send any data in the allotted amount of time.
  print("Read timed out:")
  print(rt)
except RequestException as re:
  # Handle other request failures
  print("Request Exception:")
  print(re)

Code example

If an error response from the server endpoint the Go SDK creates an error object that contains either the HTTP response error message or a generic error message.

An extra detailedResponse is returned by the service that contains the following fields:

Go exception fields
Field Description
StatusCode HTTP response status code
Result JSON error response object that is unmarshalled as map[string]interface{}
RawResult raw non-JSON error response object as []byte

Example error handling

_, detailedResponse, err := // Invoke a Schematics method request
if err != nil {
    if (detailedResponse != nil) {
      fmt.Println("Error status code: ", detailedResponse.StatusCode)
      fmt.Println("Error message:     ", err.Error())
      errorMap, ok := detailedResponse.GetResultAsMap(); if ok {
        fmt.Println("Reason:          ", errorMap["reason"])
      }
    } else {
      // Handle other error conditions
      fmt.Println("Error message: ", err.Error())
    }
  }

Methods

List supported schematics locations

Retrieve a list of IBM Cloud locations where you can create the Schematics workspace or action. workspaces.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v1/locations

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • curl -X GET https://schematics.cloud.ibm.com/v1/locations -H "Authorization: <iam_token>"
  • getSchematicsLocationOptions := schematicsService.NewListSchematicsLocationOptions()

locations, detailedResponse, err := schematicsService.ListSchematicsLocation(getSchematicsLocationOptions)

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(locations, "", "  ")
fmt.Println(string(w))
  • schematicsService.listSchematicsLocation({})
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • list_schematics_locations = schematics_service.list_schematics_location().get_result()

print(json.dumps(list_schematics_locations, indent=2))
  • ListSchematicsLocationOptions listSchematicsLocationOptions = new ListSchematicsLocationOptions();

Response<List<SchematicsLocations>> response = service.listSchematicsLocation(listSchematicsLocationOptions).execute();
List<SchematicsLocations> listSchematicsLocations = response.getResult();

System.out.println(listSchematicsLocations);

Response

Response Body

SchematicsLocations[]

A list of the IBM Cloud locations where you can create the Schematics workspace or action.

Status Code

  • 200

    Successfully returned the location information.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

Example responses
  • {
  "ID": "us",
  "Name": "us",
  "Country": "",
  "Geography": "na",
  "Kind": "country",
  "Metro": "",
  "MultizoneMetro": ""
}

List supported locations

Retrieve a list of IBM Cloud locations where you can work with the Schematics objects.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v2/locations

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • curl --location --request GET  https://schematics.cloud.ibm.com/v2/locations --header "Authorization: <access_token> " --header "Content-Type: application/json" --header "X-Feature-Region-Visibility: true"
  • schematics_locations_list = schematics_service.list_locations(headers={'X-Feature-Region-Visibility' : 'true'}).get_result()
print(json.dumps(schematics_locations_list, indent=2))

  • ListLocationsOptions listLocationsOptions = new ListLocationsOptions();
service.setDefaultHeaders(Collections.singletonMap("X-Feature-Region-Visibility", "true"));
Response<SchematicsLocationsList> response3 = service.listLocations(listLocationsOptions).execute();
SchematicsLocationsList schematicsLocationsList = response3.getResult();
System.out.println(schematicsLocationsList);

  • const header = {
"X-Feature-Region-Visibility":"true",
}
const params = {
headers : header
};
schematicsService.listLocations(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});

  • listLocationsOptions := schematicsService.NewListLocationsOptions()
schematicsLocationsList, response, err := schematicsService.ListLocations(listLocationsOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(schematicsLocationsList, "", "  ")
fmt.Println(string(b))
fmt.Println(response)

Response

Response Body

SchematicsLocationsList

The list of locations details.

Status Code

  • 200

    Successfully listed all the locations.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "locations": [
    {
      "region": "eu-de",
      "metro": "Frankfurt",
      "geography_code": "eu",
      "geography": "Europe",
      "country": "Germany",
      "type": "mzr",
      "paired_region": [
        "eu-gb"
      ],
      "restricted": true
    },
    {
      "region": "eu-gb",
      "metro": "London",
      "geography_code": "eu",
      "geography": "Europe",
      "country": "United Kingdom",
      "type": "mzr",
      "paired_region": [
        "eu-de"
      ],
      "restricted": true
    },
    {
      "region": "us-east",
      "metro": "Washington DC",
      "geography_code": "NA",
      "geography": "North America",
      "country": "United States",
      "type": "mzr",
      "paired_region": [
        "us-south"
      ],
      "restricted": false
    },
    {
      "region": "us-south",
      "metro": "Dallas",
      "geography_code": "NA",
      "geography": "North America",
      "country": "United States",
      "type": "mzr",
      "paired_region": [
        "us-east"
      ],
      "restricted": false
    }
  ]
}

List resource groups

Retrieve a list of IBM Cloud resource groups that your account has access to.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v1/resource_groups

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • curl -X GET https://schematics.cloud.ibm.com/v1/resource_groups -H "Authorization: <iam_token>"
  • listResourceGroupOptions := schematicsService.NewListResourceGroupOptions()

resourceGroups, detailedResponse, err := schematicsService.ListResourceGroup(listResourceGroupOptions)

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(resourceGroups, "", "  ")
fmt.Println(string(w))
  • schematicsService.listResourceGroup({})
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • list_resource_group_response = schematics_service.list_resource_group().get_result()

print(json.dumps(list_resource_group_response, indent=2))
  • ListResourceGroupOptions listResourceGroupOptions = new ListResourceGroupOptions();

Response<List<ResourceGroupResponse>> response = service.listResourceGroup(listResourceGroupOptions).execute();
List<ResourceGroupResponse> listResourceGroupResponse = response.getResult();

System.out.println(listResourceGroupResponse);

Response

Response Body

ResourceGroupResponse[]

A list of resource groups that your account has access to.

Status Code

  • 200

    Successfully returned resource groups information.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

No Sample Response

This method does not specify any sample responses.

Get Schematics API information

Retrieve detailed information about the IBM Cloud Schematics API version and the version of the provider plug-ins that the API uses.

GET /v1/version

Request

No Request Parameters

This method does not accept any request parameters.

  • curl -X GET https://schematics.cloud.ibm.com/v1/version
  • schematicsVersion, detailedResponse, err := schematicsService.GetSchematicsVersion(&schematicsv1.GetSchematicsVersionOptions{})
if err != nil {
  panic(err)
}

b, _ := json.MarshalIndent(schematicsVersion, "", "  ")
fmt.Println(string(b))

  • schematicsService.getSchematicsVersion({})
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • version_response = schematics_service.get_schematics_version().get_result()

print(json.dumps(version_response, indent=2))
  • GetSchematicsVersionOptions getSchematicsVersionOptions = new GetSchematicsVersionOptions();

Response<VersionResponse> response = service.getSchematicsVersion(getSchematicsVersionOptions).execute();
VersionResponse versionResponse = response.getResult();

System.out.println(versionResponse);

Response

Response Body

VersionResponse

Successful response when you retrieve detailed information about the IBM Cloud Schematics API.

Status Code

  • 200

    Successfully returned version information.

Example responses
  • {
  "commitsha": "f905818892a0fa73d6b74792cfeabd0b49aeb930",
  "builddate": "2019-11-01T07:06:27Z",
  "buildno": "3230",
  "terraform_version": "v0.12.24",
  "terraform_provider_version": "v0.18.0",
  "helm_version": "v2.14.2",
  "helm_provider_version": "v0.10.0"
}

Get variable metadata by parsing the template

Get the variable metadata from the template. This metadata can be passed in the payload during Schematics workspace create or update API call.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

POST /v2/template_metadata_processor

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • X-Github-token
    string

    The personal access token to authenticate with your private GitHub or GitLab repository and access your Terraform template.

Request Body

Required*
TemplateMetaDataRequest

Create template metadata request.

  • curl --location --request POST https://schematics.cloud.ibm.com/v2/template_metadata_processor --header "Authorization: <access_token> " --header " Content-Type: application/json" --data-raw "{"region":"us-east","template_type": "terraform_v0.15","source": [{"source_type": "git_hub",[{"git": "computed_git_repo_url": "string", "git_repo_url": "https://github.com/IBM-Cloud/terraform-provider-ibm/tree/master/examples/ibm-vsi","git_repo_folder": ".", "git_release": "latest", "git_branch": "master"}]}] "source_type": "git_hub"
  • external_source_model = {
'source_type': 'git_hub',
'git' : {
'computed_git_repo_url': 'string',
'git_repo_url': 'https://github.com/IBM-Cloud/terraform-provider-ibm/tree/master/examples/ibm-vsi',
},
}
template_meta_data_response = schematics_service.process_template_meta_data(
template_type='terraform_v0.15',
source=external_source_model
).get_result()
print(json.dumps(template_meta_data_response, indent=2))

  • ExternalSource externalSourceModel = new ExternalSource.Builder()
.sourceType("git_hub")
.git(new ExternalSourceGit.Builder().gitRepoUrl("https://github.com/IBM-Cloud/terraform-provider-ibm/tree/master/examples/ibm-vsi").build())
.build();
ProcessTemplateMetaDataOptions processTemplateMetaDataOptions = new ProcessTemplateMetaDataOptions.Builder()
.templateType("terraform_v0.12")
.source(externalSourceModel)
.region("us-east")
.build();
Response<TemplateMetaDataResponse> response = service.processTemplateMetaData(processTemplateMetaDataOptions).execute();
TemplateMetaDataResponse templateMetaDataResponse = response.getResult();
System.out.println(templateMetaDataResponse);

  • const params = {
templateType: 'terraform_v0.15',
source:{
source_type: "git_hub",
git:{
computed_git_repo_url: "string",
git_repo_url: "https://github.com/IBM-Cloud/terraform-provider-ibm/tree/master/examples/ibm-vsi",
git_repo_folder: ".",
git_release: "latest",
git_branch: "master"
}
},
source_type: "git_hub"
};
schematicsService.processTemplateMetaData(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});

  • externalSourceModel := &schematicsv1.ExternalSource{
SourceType: core.StringPtr("local"),
}
processTemplateMetaDataOptions := schematicsService.NewProcessTemplateMetaDataOptions(
"testString",
externalSourceModel,
)
processTemplateMetaDataOptions.SetTemplateType("terraform_v0.12")
source := &schematicsv1.ExternalSource{
SourceType: core.StringPtr("git_hub"),
Git: &schematicsv1.ExternalSourceGit{
ComputedGitRepoURL: core.StringPtr("string"),
GitRepoURL:         core.StringPtr("https://github.com/IBM-Cloud/terraform-provider-ibm/tree/master/examples/ibm-vsi"),
},
}
processTemplateMetaDataOptions.SetSource(source)
processTemplateMetaDataOptions.SetRegion("us-east")
processTemplateMetaDataOptions.SetSourceType("git_hub")
templateMetaDataResponse, response, err := schematicsService.ProcessTemplateMetaData(processTemplateMetaDataOptions)
if err != nil {
fmt.Println(err)
}
b, _ := json.MarshalIndent(templateMetaDataResponse, "", "  ")
fmt.Println(string(b))
fmt.Println(response)

Response

Response Body

TemplateMetaDataResponse

Template metadata response

Status Code

  • 200

    Successfully processed the template.

  • 400

    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "type": "terraform_v0.15",
  "variables": [
    {
      "name": "softlayer_username",
      "metadata": {
        "type": "string",
        "description": "Enter your IBM Infrastructure (SoftLayer) full username, you can get this using: https://control.bluemix.net/account/user/profile"
      }
    },
    {
      "name": "softlayer_api_key",
      "metadata": {
        "type": "string",
        "description": "Enter your IBM Infrastructure (SoftLayer) API key, you can get this using: https://control.bluemix.net/account/user/profile"
      }
    }
  ]
}

List workspaces

Retrieve a list of Schematics workspaces from your IBM Cloud account that you have access to. The list of workspaces that is returned depends on the API endpoint that you use. For example, if you use an API endpoint for a geography, such as North America, only workspaces that are created in us-south or us-east are returned.

For more information about supported API endpoints, see API endpoints.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v1/workspaces

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.list

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Query Parameters

  • offset
    integer

    The starting position of the item in the list of items. For example, if you have three workspaces in your account, the first workspace is assigned position number 0, the second workspace is assigned position number 1, and so forth. If you have 6 workspaces and you want to list the details for workspaces 2-6, enter 1. To limit the number of workspaces that is returned, use the limit option in addition to the offset option. Negative numbers are not supported and are ignored.

    Possible values: value ≥ 0

  • limit
    integer

    The maximum number of items that you want to list. The number must be a positive integer between 1 and 2000. If no value is provided, 100 is used by default.

    Possible values: 1 ≤ value ≤ 2000

    Default: 100

  • profile
    string

    Level of details returned by the get method

    Allowable values: [ids,summary]

  • resource_group
    string

    The resource group (by default, fetch from all resource groups) name or ID

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces -H "Authorization: <iam_token>"    
  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces?profile=summary -H "Authorization: <iam_token>"
  • listWorkspacesOptions := schematicsService.NewListWorkspacesOptions()

workspaceList, detailedResponse, err := schematicsService.ListWorkspaces(listWorkspacesOptions)

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(workspaceList, "", "  ")
fmt.Println(string(w))
  • schematicsService.listWorkspaces({})
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • workspace_response_list = schematics_service.list_workspaces().get_result()

print(json.dumps(workspace_response_list, indent=2))
  • ListWorkspacesOptions listWorkspacesOptions = new ListWorkspacesOptions.Builder()
.build();

Response<WorkspaceResponseList> response = service.listWorkspaces(listWorkspacesOptions).execute();
WorkspaceResponseList workspaceResponseList = response.getResult();

System.out.println(workspaceResponseList);

Response

Response Body

WorkspaceResponseList

List of workspaces

Status Code

  • 200

    Successfully listed the workspaces that you have access to.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "offset": 0,
  "limit": 1,
  "count": 6,
  "workspaces": [
    {
      "id": "us-east.workspace.testWorkspaceApi.bb026f5e",
      "name": "testWorkspaceApi",
      "crn": "crn:v1:staging:public:schematics:us-south:a/0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0:00000000-0000-0000-0000-00000000000:workspace:us-east.workspace.testWorkspaceApi.bb026f5e",
      "type": [
        "terraform_v1.0"
      ],
      "description": "terraform workspace",
      "resource_group": "",
      "location": "us-east",
      "tags": [
        "department:HR",
        "application:compensation",
        "environment:staging"
      ],
      "created_at": "2021-09-28T11:34:22.88125945Z",
      "created_by": "schematics@ibm.com",
      "status": "DRAFT",
      "failure_reason": "",
      "workspace_status_msg": {
        "status_code": "",
        "status_msg": ""
      },
      "workspace_status": {
        "frozen": true,
        "frozen_by": "schematics@ibm.com",
        "frozen_at": "2021-09-28T11:34:22.306393108Z",
        "locked": false
      },
      "template_repo": {
        "url": "https://github.com/ptaube/tf_cloudless_sleepy",
        "commit_id": "",
        "full_url": "https://github.com/ptaube/tf_cloudless_sleepy",
        "has_uploadedgitrepotar": false
      },
      "template_data": [
        {
          "id": "6fef745e-dfaa-42",
          "folder": ".",
          "compact": false,
          "type": "terraform_v1.0",
          "values_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/template_data/6fef745e-dfaa-42/values",
          "values": "",
          "variablestore": [
            {
              "name": "sample_var",
              "secure": false,
              "value": "THIS IS IBM CLOUD TERRAFORM CLI DEMO",
              "type": "",
              "description": "Description of sample_var"
            },
            {
              "name": "sleepy_time",
              "secure": false,
              "value": "15",
              "type": "",
              "description": ""
            }
          ],
          "has_githubtoken": false
        }
      ],
      "runtime_data": [
        {
          "id": "6fef745e-dfaa-42",
          "engine_name": "terraform",
          "engine_version": "v0.12.31",
          "state_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/runtime_data/6fef745e-dfaa-42/state_store",
          "log_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/runtime_data/6fef745e-dfaa-42/log_store"
        }
      ],
      "shared_data": {
        "resource_group_id": ""
      },
      "applied_shareddata_ids": null,
      "updated_at": "0001-01-01T00:00:00Z",
      "last_health_check_at": "0001-01-01T00:00:00Z",
      "cart_id": ""
    }
  ]
}

Create a workspace

Create an IBM Cloud Schematics workspace that points to the source repository where your Terraform template or the IBM Cloud software template is stored. You can decide to create your workspace without connecting it to a GitHub or GitLab repository. Your workspace is then created with a Draft state. To later connect your workspace to a GitHub or GitLab repository, you must use the PUT /v1/workspaces/{id} API to update the workspace or use the /v1/workspaces/{id}/templates/{template_id}/template_repo_upload API to upload a TAR file instead.

Getting API endpoint:-

  • The Schematics API endpoint that you use to create the workspace determines where your Schematics actions run and your data is stored. See API endpoints for more information.
  • If you use the API endpoint for a geography and not a specific location, such as North America, you can specify the location in your API request body.
  • If you do not specify the location in the request body, Schematics determines your workspace location based on availability.
  • If you use an API endpoint for a specific location, such as Frankfurt, the location that you enter in your API request body must match your API endpoint.
  • You also have the option to not specify a location in your API request body if you use a location-specific API endpoint.

Getting IAM access token :-

  • Before you create Schematics workspace, you need to create the IAM access token for your IBM Cloud Account.
  • To create IAM access token, use export IBMCLOUD_API_KEY=<ibmcloud_api_key> and execute curl -X POST "https://iam.cloud.ibm.com/identity/token" -H "Content-Type= application/x-www-form-urlencoded" -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$IBMCLOUD_API_KEY" -u bx:bx. For more information, about creating IAM access token and API Docs, see IAM access token and Create API key.
  • You can set the environment values export ACCESS_TOKEN=<access_token> and export REFRESH_TOKEN=<refresh_token>.
  • You can use the obtained IAM access token in create workspace curl command.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

POST /v1/workspaces

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.create

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • X-Github-token
    string

    The personal access token to authenticate with your private GitHub or GitLab repository and access your Terraform template.

Request Body

Required*
WorkspaceCreateRequest

Input parameter to create the IBM Cloud Schematics workspace.

  • curl --request POST --url https://schematics.cloud.ibm.com/v1/workspaces -H "Authorization: Bearer <access_token>" -d '{"name":"<workspace_name>","type": ["terraform_v1.0"],"location": "<location>","description": "<workspace_description>","resource_group": "<resource_group_ID>","tags": [],"template_repo": {"url": "<source_repo_url>"},"template_data": [{"folder": ".","type": "terraform_v1.0","variablestore": [{"name": "variable_name1","value": "variable_value1"},{"name": "variable_name2","value": "variable_value2"}]}]}'
  • curl --request POST --url https://schematics.cloud.ibm.com/v1/workspaces -H "Authorization: Bearer <access_token>" -d '{"name":"<workspace_name>","type": ["terraform_v1.0"],"location": "<location>","description": "<workspace_description>","resource_group": "<resource_group_ID>","tags": [],"template_repo": {"url": ""},"template_data": [{"folder": ".","type": "terraform_v1.0","variablestore": [{"name": "variable_name1","value": "variable_value1"},{"name": "variable_name2","value": "variable_value2"}]}]}'
  • curl --request POST --url https://schematics.cloud.ibm.com/v1/workspaces -H  Content-Type: application/json Authorization: Bearer <access_token>" -d '{"name":"<workspace_name>","type": ["terraform_v1.0"],"description": "terraform workspace","tags":[  "department:HR", "application:compensation","environment:staging"], "template_repo":{"url":"https://github.com/ptaube/tf_cloudless_sleepy" },"workspace_status":{"frozen":true},"template_data":[{   "folder":".","type":"terraform_v1.0","variablestore":[ {"name":"sample_var","secure":false,"value":"THIS IS IBM CLOUD TERRAFORM CLI DEMO", "description":"Description of sample_var"},{   "name":"sleepy_time","value":"15"}]}]}'
  • curl --request POST --url https://schematics.cloud.ibm.com/v1/workspaces -H 'authorization: Bearer <access_token>' \ 'cache-control: no-cache' \ 'content-type: application/json' \ 'postman-token: dc2ea316-12a3-597b-4353-3150078d5d5e' \ '{"name": "<workspace_name>","shared_data": {"region": "us-south"}, "type": ["terraform_v1.0"], "description": "terraform workspace", "template_repo": {"url": "https://github.com/msundeep4/test-template-private-module"}, "template_data": [ {"folder": ".","type": "terraform_v1.0", "env_values": [{"__netrc__":"[['github.com','msundeep4','<githubtoken>']]"}] }]}'                
  • templateSourceDataRequestModel := &schematicsv1.TemplateSourceDataRequest{
    Folder: core.StringPtr("."),
    Type:   core.StringPtr("terraform_v1.0"),
    Variablestore: []schematicsv1.WorkspaceVariableRequest{
        {
            Name:  core.StringPtr("<variable_name1>"),
            Value: core.StringPtr("<variable_value1>"),
        },
        {
            Name:  core.StringPtr("<variable_name2>"),
            Value: core.StringPtr("<variable_value2>"),
        },
    },
}

templateRepoRequestModel := &schematicsv1.TemplateRepoRequest{
    URL: core.StringPtr("<source_repo_url>"),
}

createWorkspaceOptions := &schematicsv1.CreateWorkspaceOptions{
    Description:   core.StringPtr("<description>"),
    Name:          core.StringPtr("<workspace_name>"),
    TemplateData:  []schematicsv1.TemplateSourceDataRequest{*templateSourceDataRequestModel},
    TemplateRepo:  templateRepoRequestModel,
    Type:          []string{"terraform_v1.0"},
    Location:      core.StringPtr("<location>"),
    ResourceGroup: core.StringPtr("<resource_group>"),
    Tags:          []string{"<tags>"},
}

workspaceResponse, detailedResponse, err := schematicsService.CreateWorkspace(createWorkspaceOptions)

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(workspaceResponse, "", "  ")
fmt.Println(string(w))

  • const templateSourceDataRequestModel = {
  folder: '.',
  type: 'terraform_v1.0',
  variablestore: [
    {
      name: '<variable_name1>',
      value: '<variable_value1>',
    },
    {
      name: '<variable_name2>',
      value: '<variable_value2>',
    }
  ]
};

const templateRepoRequestModel = {
  url: '<source_repo_url>,
};

const params = {
  description: '<description>',
  name: '<workspace_name>',
  templateData: [templateSourceDataRequestModel],
  templateRepo: templateRepoRequestModel,
  type: ['terraform_v1.0'],
  location: '<location>',
  resourceGroup: '<resource_group>'
  tags: ['<tags>'],
};

schematicsService.createWorkspace(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • workspace_variable_request_model = {}
workspace_variable_request_model['name'] = 'variable_name1'
workspace_variable_request_model['value'] = 'variable_value1'

template_source_data_request_model = {}
template_source_data_request_model['env_values'] = [{ 'foo': 'bar' }]
template_source_data_request_model['folder'] = 'testString'
template_source_data_request_model['type'] = 'terraform_v1.0'
template_source_data_request_model['variablestore'] = [workspace_variable_request_model]

template_repo_request_model = {}
template_repo_request_model['url'] = '<source_repo_url>'


workspace_response = schematics_service.create_workspace(
    description="<description>", 
    name="<workspace_name>",
    template_data=[template_source_data_request_model],
    template_repo=template_repo_request_model,
    type=['terraform_v1.0'],
    location="<location>",
    resource_group="<resource_group>",
    tags=['<tags>'],
).get_result()

print(json.dumps(workspace_response, indent = 2))
  • // Construct an instance of the WorkspaceVariableRequest model
WorkspaceVariableRequest workspaceVariableRequestModel = new WorkspaceVariableRequest.Builder()
.name("variable_name1")
.value("variable_value1")
.build();

// Construct an instance of the TemplateSourceDataRequest model
TemplateSourceDataRequest templateSourceDataRequestModel = new TemplateSourceDataRequest.Builder()
.folder(".")
.type("terraform_v1.0")
.variablestore(new java.util.ArrayList<WorkspaceVariableRequest>(java.util.Arrays.asList(workspaceVariableRequestModel)))
.build();

// Construct an instance of the TemplateRepoRequest model
TemplateRepoRequest templateRepoRequestModel = new TemplateRepoRequest.Builder()
.url("<source_repo_url>")
.build();

CreateWorkspaceOptions createWorkspaceOptions = new CreateWorkspaceOptions.Builder()
.description("<description>")
.name("<workspace_name>")
.templateData(new java.util.ArrayList<TemplateSourceDataRequest>(java.util.Arrays.asList(templateSourceDataRequestModel)))
.templateRepo(templateRepoRequestModel)
.type(new java.util.ArrayList<String>(java.util.Arrays.asList("terraform_v1.0")))
.location("<location>")
.resourceGroup("<resource_group>")
.tags(new java.util.ArrayList<String>(java.util.Arrays.asList("<tags>")))
.build();

Response<WorkspaceResponse> response = service.createWorkspace(createWorkspaceOptions).execute();
WorkspaceResponse workspaceResponse = response.getResult();

System.out.println(workspaceResponse);

Response

Response Body

WorkspaceResponse

Workspace details

Status Code

  • 201

    Successfully created the workspace in IBM Cloud Schematics. Your resources are not provisioned until you use the POST /workspaces/{id}/apply API.

  • 400

    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    The workspace already exists. To find a list of workspaces, use the GET /workspaces API.

  • 409

    The workspace is frozen and disabled. Unfreeze the workspace first before you retry the request. Or the Schematics create, update, delete action has not completed. Wait until the create, update, delete, plan, apply, destroy or refresh action completes before you try again.

  • 429

    Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

  • 503

    IBM Cloud Schematics could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "id": "us-east.workspace.testWorkspaceApi.bb026f5e",
  "name": "testWorkspaceApi",
  "crn": "crn:v1:staging:public:schematics:us-south:a/0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0:00000000-0000-0000-0000-00000000000:workspace:us-east.workspace.testWorkspaceApi.bb026f5e",
  "type": [
    "terraform_v1.0"
  ],
  "description": "terraform workspace",
  "resource_group": "",
  "location": "us-east",
  "tags": [
    "department:HR",
    "application:compensation",
    "environment:staging"
  ],
  "created_at": "2021-09-28T11:34:22.88125945Z",
  "created_by": "schematics@ibm.com",
  "status": "DRAFT",
  "failure_reason": "",
  "workspace_status_msg": {
    "status_code": "",
    "status_msg": ""
  },
  "workspace_status": {
    "frozen": true,
    "frozen_by": "schematics@ibm.com",
    "frozen_at": "2021-09-28T11:34:22.306393108Z",
    "locked": false
  },
  "template_repo": {
    "url": "https://github.com/ptaube/tf_cloudless_sleepy",
    "commit_id": "",
    "full_url": "https://github.com/ptaube/tf_cloudless_sleepy",
    "has_uploadedgitrepotar": false
  },
  "template_data": [
    {
      "id": "6fef745e-dfaa-42",
      "folder": ".",
      "compact": false,
      "type": "terraform_v1.0",
      "values_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/template_data/6fef745e-dfaa-42/values",
      "values": "",
      "variablestore": [
        {
          "name": "sample_var",
          "secure": false,
          "value": "THIS IS IBM CLOUD TERRAFORM CLI DEMO",
          "type": "",
          "description": "Description of sample_var"
        },
        {
          "name": "sleepy_time",
          "secure": false,
          "value": "15",
          "type": "",
          "description": ""
        }
      ],
      "has_githubtoken": false
    }
  ],
  "runtime_data": [
    {
      "id": "6fef745e-dfaa-42",
      "engine_name": "terraform",
      "engine_version": "v0.12.31",
      "state_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/runtime_data/6fef745e-dfaa-42/state_store",
      "log_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/runtime_data/6fef745e-dfaa-42/log_store"
    }
  ],
  "shared_data": {
    "resource_group_id": ""
  },
  "applied_shareddata_ids": null,
  "updated_at": "0001-01-01T00:00:00Z",
  "last_health_check_at": "0001-01-01T00:00:00Z",
  "cart_id": ""
}

Get workspace details

Retrieve detailed information for a workspace in your IBM Cloud account.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v1/workspaces/{w_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.read

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id} -H "Authorization: Bearer <iam_token>"
  • workspaceDetails, detailedResponse, err := schematicsService.GetWorkspace(&schematicsv1.GetWorkspaceOptions{
    WID: <workspace_id>,
})

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(workspaceDetails, "", "  ")
fmt.Println(string(w))
  • const params = {
  wId: '<workspace_id>',
};

schematicsService.getWorkspace(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • workspace_response = schematics_service.get_workspace(
    w_id='<workspace_id>'
).get_result()

print(json.dumps(workspace_response, indent=2))
  • GetWorkspaceOptions getWorkspaceOptions = new GetWorkspaceOptions.Builder()
.wId("<workspace_id>")
.build();

Response<WorkspaceResponse> response = service.getWorkspace(getWorkspaceOptions).execute();
WorkspaceResponse workspaceResponse = response.getResult();

System.out.println(workspaceResponse);

Response

Response Body

WorkspaceResponse

Workspace details

Status Code

  • 200

    Successfully retrieved details about your workspace.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    Not found. The specified workspace could not be found. Verify that the workspace ID is correct. To list workspaces in your IBM Cloud account, use the GET /v1/workspaces API.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "id": "us-east.workspace.testWorkspaceApi.bb026f5e",
  "name": "testWorkspaceApi",
  "crn": "crn:v1:staging:public:schematics:us-south:a/0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0:00000000-0000-0000-0000-00000000000:workspace:us-east.workspace.testWorkspaceApi.bb026f5e",
  "type": [
    "terraform_v1.0"
  ],
  "description": "terraform workspace",
  "resource_group": "",
  "location": "us-east",
  "tags": [
    "department:HR",
    "application:compensation",
    "environment:staging"
  ],
  "created_at": "2021-09-28T11:34:22.88125945Z",
  "created_by": "schematics@ibm.com",
  "status": "INACTIVE",
  "failure_reason": "",
  "workspace_status_msg": {
    "status_code": "200",
    "status_msg": ""
  },
  "workspace_status": {
    "frozen": true,
    "frozen_by": "schematics@ibm.com",
    "frozen_at": "2021-09-28T11:34:22.306393108Z",
    "locked": false
  },
  "template_repo": {
    "url": "<displays your Git repository URL>",
    "commit_id": "<displays the workspace version of the Git repository templates that are used by same repository>",
    "full_url": "<displays your Git repository URL with all the files.>",
    "has_uploadedgitrepotar": false
  },
  "template_data": [
    {
      "id": "6fef745e-dfaa-42",
      "folder": ".",
      "compact": false,
      "type": "terraform_v1.0",
      "values_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/template_data/6fef745e-dfaa-42/values",
      "values": "",
      "values_metadata": [
        {
          "default": "hello",
          "description": "A sample_var to pass to the template.",
          "name": "sample_var",
          "type": "string"
        },
        {
          "default": "0",
          "description": "How long our local-exec will take a nap.",
          "name": "sleepy_time",
          "type": "string"
        }
      ],
      "variablestore": [
        {
          "name": "sample_var",
          "secure": false,
          "value": "THIS IS IBM CLOUD TERRAFORM CLI DEMO",
          "type": "",
          "description": "Description of sample_var"
        },
        {
          "name": "sleepy_time",
          "secure": false,
          "value": "15",
          "type": "",
          "description": ""
        }
      ],
      "has_githubtoken": false
    }
  ],
  "runtime_data": [
    {
      "id": "6fef745e-dfaa-42",
      "engine_name": "terraform",
      "engine_version": "v0.12.31",
      "state_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/runtime_data/6fef745e-dfaa-42/state_store",
      "log_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/runtime_data/6fef745e-dfaa-42/log_store"
    }
  ],
  "shared_data": {
    "resource_group_id": ""
  },
  "applied_shareddata_ids": null,
  "updated_at": "0001-01-01T00:00:00Z",
  "last_health_check_at": "0001-01-01T00:00:00Z",
  "cart_id": ""
}

Update workspace

Use this API to update or replace the entire workspace, including the Terraform template (template_repo) or IBM Cloud catalog software template (catalog_ref) that your workspace points to.

Tip:- If you want to update workspace metadata, use the PATCH /v1/workspaces/{id} API. To update workspace variables, use the PUT /v1/workspaces/{id}/template_data/{template_id}/values API.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

PUT /v1/workspaces/{w_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.update

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • X-Github-token
    string

    The personal access token to authenticate with your private GitHub or GitLab repository and access your Terraform template.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

Request Body

Required*
WorkspaceUpdateRequest

Replace the Workspace definition.

  • curl --request PUT --url https://schematics.cloud.ibm.com/v1/workspaces/{id} -H  Authorization: <iam_token>" -d '{"name":"testWorkspaceApi","type":[   "terraform_v1.0"],"description":"terraform workspace updated", "tags":["department:HR","application:compensation","environment:staging"], "template_repo":{"url":"https://github.com/ptaube/tf_cloudless_sleepy"}, "workspace_status":{"frozen":true},"template_data":[{"folder":".", "type":"terraform_v1.0","variablestore":[{"name":"sample_var","secure":false,"value":"THIS IS IBM CLOUD TERRAFORM CLI DEMO", "description":"Description of sample_var"},{"name":"sleepy_time","value":"15"}]}]}'
  • templateRepoRequestUpdateModel := &schematicsv1.TemplateRepoUpdateRequest{
    URL: core.StringPtr("<source_repo_url>"),
    RepoURL: core.StringPtr("<catalog_repo_url>"),
}

replaceWorkspaceOptions := &schematicsv1.ReplaceWorkspaceOptions{
    WID:          ws.ID,
    TemplateRepo: templateRepoRequestUpdateModel,
    CatalogRef: &schematicsv1.CatalogRef{
        ItemID:          core.StringPtr("<item_id>"),
        ItemName:        core.StringPtr("<item_name>"),
        ItemURL:         core.StringPtr("<item_url>"),
        ItemReadmeURL:   core.StringPtr("<item_readme_url>"),
        ItemIconURL:     core.StringPtr("<item_icon_url>"),
        OfferingVersion: core.StringPtr("<offering_version>"),
        LaunchURL:       core.StringPtr("<launch_url>"),
    },
}

replaceResponse, detailedResponse, err := schematicsService.ReplaceWorkspace(replaceWorkspaceOptions)

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(replaceResponse, "", "  ")
fmt.Println(string(w))
  • const catalogRefModel = {
  item_icon_url: '<item_icon_url>',
  item_id: '<item_id>',
  item_name: '<item_name>',
  item_readme_url: '<item_readme_url>',
  item_url: '<item_url>',
  launch_url: '<launch_url>',
  offering_version: '<offering_version>',
};

const templateRepoUpdateRequestModel = {
  repo_url: '<catalog_repo_url>',
  url: '<source_repo_url>',
};

const params = {
  wId: '<workspace_id>',
  templateRepo: templateRepoUpdateRequestModel,
  catalogRef: catalogRefModel
};

schematicsService.replaceWorkspace(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • catalog_ref_model = {}
catalog_ref_model['item_icon_url'] = '<item_icon_url>'
catalog_ref_model['item_id'] = '<item_id>'
catalog_ref_model['item_name'] = '<item_name>'
catalog_ref_model['item_readme_url'] = '<item_readme_url>'
catalog_ref_model['item_url'] = '<item_url>'
catalog_ref_model['launch_url'] = '<launch_url>'
catalog_ref_model['offering_version'] = '<offering_version>'

workspace_variable_request_model = {}
workspace_variable_request_model['name'] = 'variable_name1'
workspace_variable_request_model['value'] = 'variable_value1'

template_source_data_request_model = {}
template_source_data_request_model['variablestore'] = [workspace_variable_request_model]

template_repo_request_model = {}
template_repo_request_model['url'] = '<source_repo_url>'

workspace_response = schematics_service.replace_workspace(
    w_id='<workspace_id>',
    description="<description>", 
    name="<workspace_name>",
    catalog_ref=catalog_ref_model,
    template_data=[template_source_data_request_model],
    template_repo=template_repo_request_model,
    type=['terraform_v0.12.20'],
    location="<location>",
    resource_group="<resource_group>",
    tags=['<tags>'],
).get_result()

print(json.dumps(workspace_response, indent = 2))
  • // Construct an instance of the CatalogRef model
CatalogRef catalogRefModel = new CatalogRef.Builder()
.itemIconUrl("<item_icon_url>")
.itemId("<item_id>")
.itemName("<item_name>")
.itemReadmeUrl("<item_readme_url>")
.itemUrl("<item_url>")
.launchUrl("<launch_url>")
.offeringVersion("<offering_version>")
.build();

// Construct an instance of the TemplateRepoUpdateRequest model
TemplateRepoUpdateRequest templateRepoUpdateRequestModel = new TemplateRepoUpdateRequest.Builder()
.repoUrl("<catalog_repo_url>")
.url("<source_repo_url>")
.build();

ReplaceWorkspaceOptions replaceWorkspaceOptions = new ReplaceWorkspaceOptions.Builder()
.wId("<workspace_id>")
.catalogRef(catalogRefModel)
.templateRepo(templateRepoUpdateRequestModel)
.build();

Response<WorkspaceResponse> response = service.replaceWorkspace(replaceWorkspaceOptions).execute();
WorkspaceResponse workspaceResponse = response.getResult();

Response

Response Body

WorkspaceResponse

Workspace details

Status Code

  • 200

    Successfully updated the workspace metadata.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    Not found. The specified workspace could not be found. Verify that the workspace ID is correct. To list workspaces in your IBM Cloud account, use the GET /v1/workspaces API.

  • 409

    The workspace is frozen and disabled. Unfreeze the workspace first before you retry the request. Or the Schematics create, update, delete action has not completed. Wait until the create, update, delete, plan, apply, destroy or refresh action completes before you try again.

  • 429

    Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

  • 503

    IBM Cloud Schematics could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "id": "us-east.workspace.testWorkspaceApi.bb026f5e",
  "name": "testWorkspaceApi",
  "crn": "crn:v1:staging:public:schematics:us-south:a/0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0:00000000-0000-0000-0000-00000000000:workspace:us-east.workspace.testWorkspaceApi.bb026f5e",
  "type": [
    "terraform_v1.0"
  ],
  "description": "terraform workspace updated",
  "resource_group": "",
  "location": "us-east",
  "tags": [
    "department:HR",
    "application:compensation",
    "environment:staging"
  ],
  "created_at": "2021-09-28T11:34:22.88125945Z",
  "created_by": "schematics@ibm.com",
  "status": "DRAFT",
  "failure_reason": "",
  "workspace_status_msg": {
    "status_code": "200",
    "status_msg": ""
  },
  "workspace_status": {
    "frozen": true,
    "frozen_by": "schematics@ibm.com",
    "frozen_at": "2021-09-28T14:36:08.58852336Z",
    "locked": false
  },
  "template_repo": {
    "url": "https://github.com/ptaube/tf_cloudless_sleepy",
    "commit_id": "c0a1dbc6e7afe4dad06de617a7fc35e22ddd4f95",
    "full_url": "https://github.com/ptaube/tf_cloudless_sleepy",
    "has_uploadedgitrepotar": false
  },
  "template_data": [
    {
      "id": "6fef745e-dfaa-42",
      "folder": ".",
      "compact": false,
      "type": "terraform_v1.0",
      "values_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/template_data/6fef745e-dfaa-42/values",
      "values": "",
      "values_metadata": [
        {
          "default": "hello",
          "description": "A sample_var to pass to the template.",
          "name": "sample_var",
          "type": "string"
        },
        {
          "default": "0",
          "description": "How long our local-exec will take a nap.",
          "name": "sleepy_time",
          "type": "string"
        }
      ],
      "variablestore": [
        {
          "name": "sample_var",
          "secure": false,
          "value": "THIS IS IBM CLOUD TERRAFORM CLI DEMO",
          "type": "",
          "description": "Description of sample_var"
        },
        {
          "name": "sleepy_time",
          "secure": false,
          "value": "15",
          "type": "",
          "description": ""
        }
      ],
      "has_githubtoken": false
    }
  ],
  "runtime_data": [
    {
      "id": "6fef745e-dfaa-42",
      "engine_name": "terraform",
      "engine_version": "v0.12.31",
      "state_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/runtime_data/6fef745e-dfaa-42/state_store",
      "log_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/runtime_data/6fef745e-dfaa-42/log_store"
    }
  ],
  "shared_data": {
    "resource_group_id": ""
  },
  "applied_shareddata_ids": null,
  "updated_by": "schematics@ibm.com",
  "updated_at": "2021-09-28T14:36:08.595317742Z",
  "last_health_check_at": "0001-01-01T00:00:00Z",
  "cart_id": ""
}

Delete a workspace

Deletes a workspace from IBM Cloud Schematics. Deleting a workspace does not automatically remove the IBM Cloud resources that the workspace manages. To remove all resources that are associated with the workspace, use the DELETE /v1/workspaces/{id}?destroy_resources=true API.

Note: If you delete a workspace without deleting the resources, you must manage your resources with the resource dashboard or CLI afterwards. You cannot use IBM Cloud Schematics anymore to manage your resources.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

DELETE /v1/workspaces/{w_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.delete

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • refresh_token
    Required*
    string

    The IAM refresh token for the user or service identity. The IAM refresh token is required only if you want to destroy the Terraform resources before deleting the Schematics workspace. If you want to delete the workspace only and keep all your Terraform resources, refresh token is not required.

    Retrieving refresh token:

    • Use export IBMCLOUD_API_KEY=<ibmcloud_api_key>, and execute curl -X POST "https://iam.cloud.ibm.com/identity/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$IBMCLOUD_API_KEY" -u bx:bx.
    • For more information, about creating IAM access token and API Docs, refer, IAM access token and Create API key.

    Limitation:

    • If the token is expired, you can use refresh token to get a new IAM access token.
    • The refresh_token parameter cannot be used to retrieve a new IAM access token.
    • When the IAM access token is about to expire, use the API key to create a new access token.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

Query Parameters

  • destroy_resources
    string

    If set to true, refresh_token header configuration is required to delete all the Terraform resources, and the Schematics workspace. If set to false, you can remove only the workspace. Your Terraform resources are still available and must be managed with the resource dashboard or CLI.

  • curl -X DELETE https://schematics.cloud.ibm.com/v1/workspaces/{id} -H "Authorization: <iam_token>"
  • _, detailedResponse, err := schematicsService.DeleteWorkspace(&schematicsv1.DeleteWorkspaceOptions{
    WID:          <workspace_id>,
    RefreshToken: core.StringPtr("<refresh_token>"),
})

if err != nil {
    panic(err)
}

  • const params = {
  wId: '<workspace_id>',
  refreshToken: "Refresh Token"
};

schematicsService.deleteWorkspace(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

  • workspace_delete_response = schematics_service.delete_workspace(
    w_id='<workspace_id>'
).get_result()

print(json.dumps(workspace_delete_response, indent=2))
  • DeleteWorkspaceOptions deleteWorkspaceOptions = new DeleteWorkspaceOptions.Builder()
.wId("<workspace_id>")
.build();

Response<String> response = service.deleteWorkspace(deleteWorkspaceOptions).execute();
String workspaceDeleteResponse = response.getResult();

System.out.println(workspaceDeleteResponse);

Response

Response Body

string

Response for workspace delete job

Status Code

  • 200

    Successfully deleted the workspace.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 409

    Deletion failed. Could not delete the workspace template information. The workspace is frozen and disabled for updates. Unfreeze the workspace first, before you try again. Or the Schematics create, update, delete action has not completed. Wait until the create, update, delete, plan, apply, destroy or refresh action completes before you try again.

  • 429

    Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

  • 503

    IBM Cloud Schematics could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Update workspace metadata

Use this API to update the following workspace metadata:

  • Workspace name (name) - Note: Updating the workspace name does not update the ID of the workspace.
  • Workspace description (description)
  • Tags (tags[])
  • Resource group (resource_group)
  • Workspace status (workspace_status.frozen)

Tip: If you want to update information about the Terraform template or IBM Cloud catalog software template that your workspace points to, use the PUT /v1/workspaces/{id} API. To update workspace variables, use the PUT /v1/workspaces/{id}/template_data/{template_id}/values API.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

PATCH /v1/workspaces/{w_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.update

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

Request Body

Required*
WorkspaceUpdateRequest

Input parameters to update workspace metadata.

  • curl --request PATCH --url https://schematics.cloud.ibm.com/v1/workspaces/{id} -H "Authorization: <iam_token>" -d '{"name":"<workspace_name>","description": "<workspace_description>","tags": ["<tag1>", "<tag2>"], "resource_group": "<resource_grou>", "workspace_status": {"frozen": <true_or_false>}}'
  • updateWorkspaceOptions := &schematicsv1.UpdateWorkspaceOptions{
    WID: <workspace_id>,
    Description:   core.StringPtr("<description>"),
    Name:          core.StringPtr("<workspace_name>"),
    ResourceGroup: core.StringPtr("<resource_group>"),
    Tags:          []string{"<tag1>", "<tag2>"},
    WorkspaceStatus: &schematicsv1.WorkspaceStatusUpdateRequest {
        Frozen: core.BoolPtr(<true_or_false>),
    },
}

workspaceUpdateResponse, detailedResponse, err := schematicsService.UpdateWorkspace(updateWorkspaceOptions)

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(workspaceUpdateResponse, "", "  ")
fmt.Println(string(w))
  • const workspaceStatusUpdateRequestModel = {
  frozen : '<true or false>'
}

const params = {
  wId: '<workspace_id>',
  description: '<description>',
  name: '<workspace_name>',
  type: ['terraform_v1.0'],
  resourceGroup: '<resource_group>',
  tags: ['<tags>'],
  workspaceStatus: workspaceStatusUpdateRequestModel
};

schematicsService.updateWorkspace(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • workspace_status_update_request_model = {}
workspace_status_update_request_model['frozen'] = <True or False>

workspace_response = schematics_service.update_workspace(
    w_id='<workspace_id>',
    description="<description>", 
    name="<workspace_name>",
    resource_group="<resource_group>",
    tags=['<tag1>', '<tag2>'],
    workspace_status=workspace_status_update_request_model
).get_result()

print(json.dumps(workspace_response, indent=2))
  • WorkspaceStatusUpdateRequest workspaceStatusUpdateRequestModel = new WorkspaceStatusUpdateRequest.Builder()
.frozen(<true_or_false>)
.build();

UpdateWorkspaceOptions updateWorkspaceOptions = new UpdateWorkspaceOptions.Builder()
.wId("testString")
.description("<description>")
.name("<workspace_name>")
.tags(new java.util.ArrayList<String>(java.util.Arrays.asList("<tag>")))
.workspaceStatus(workspaceStatusUpdateRequestModel)
.build();

Response<WorkspaceResponse> response = service.updateWorkspace(updateWorkspaceOptions).execute();
WorkspaceResponse workspaceResponse = response.getResult();

System.out.println(workspaceResponse);

Response

Response Body

WorkspaceResponse

Workspace details

Status Code

  • 200

    Successfully updated the workspace metadata.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    Not found. The specified workspace could not be found. Verify that the workspace ID is correct. To list workspaces in your IBM Cloud account, use the GET /v1/workspaces API.

  • 409

    Patch failed. The workspace is marked as frozen. Unfreeze the workspace before you retry the request.

  • 429

    Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

  • 503

    IBM Cloud Schematics could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "id": "myworkspace-123456",
  "name": "myworkspace",
  "type": [
    "terraform_v1.0"
  ],
  "description": "This is a workspace created with the API",
  "resource_group": "a1b23aa11bb22cc55",
  "location": "eu-de",
  "tags": [],
  "created_at": "2019-11-06T16:19:32.352418401Z",
  "created_by": "user@us.ibm.com",
  "status": "INACTIVE",
  "workspace_status_msg": {
    "status_code": "",
    "status_msg": ""
  },
  "workspace_status": {
    "frozen": false,
    "locked": false
  },
  "template_repo": {
    "url": "https://github.com/myorg/myrepo"
  },
  "template_data": [
    {
      "id": "d1369548-1bc2-4d",
      "folder": ".",
      "type": "terraform_v1.0",
      "values_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/template_data/a123456b/values\n            values: ''\n            values_metadata:\n              - name: variable1\n                type: value1\n              - name: variable2\n                type: value2\n            variablestore:\n              - name: variable1\n                secure: false\n                value: value1\n                type: ''\n                description: ''\n              - name: variable2\n                secure: false\n                value: value2\n                type: ''\n                description: ''\n        runtime_data:\n          - id: a123456b\n            engine_name: terraform\n            engine_version: v0.12.24\n            state_store_url: >-\n              https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a123456b/state_store\n            log_store_url: >-\n              https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a123456b/log_store\n        shared_data:\n          resource_group_id: ''\n        updated_at: '0001-01-01T00:00:00Z'\n        last_health_check_at: '0001-01-01T00:00:00Z'     "
    }
  ]
}

Show workspace template readme

Retrieve the README.md file of the Terraform of IBM Cloud catalog template that your workspace points to.

GET /v1/workspaces/{w_id}/templates/readme

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

Query Parameters

  • ref
    string

    The GitHub or GitLab branch where the README.md file is stored, or the commit ID or tag that references the README.md file that you want to retrieve. If you do not specify this option, the README.md file is retrieved from the master branch by default.

  • formatted
    string

    The format of the readme file. Value ''markdown'' will give markdown, otherwise html

    Allowable values: [markdown,html]

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/templates/readme -H "Authorization: <iam_token>"
  • readme, detailedResponse, err := schematicsService.GetWorkspaceReadme(&schematicsv1.GetWorkspaceReadmeOptions{
    WID: <workspace_id>,
})

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(readme, "", "  ")
fmt.Println(string(w))
  • const params = {
  wId: '<workspace_id>',
};

schematicsService.getWorkspaceReadme(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • template_readme = schematics_service.get_workspace_readme(
    w_id='<workspace_id>'
).get_result()

print(json.dumps(template_readme, indent=2))
  • GetWorkspaceReadmeOptions getWorkspaceReadmeOptions = new GetWorkspaceReadmeOptions.Builder()
.wId("<workspace_id>")
.build();

Response<TemplateReadme> response = service.getWorkspaceReadme(getWorkspaceReadmeOptions).execute();
TemplateReadme templateReadme = response.getResult();

System.out.println(templateReadme);

Response

Response Body

TemplateReadme

The README.md file for the template used by the workspace

Status Code

  • 200

    Successfully retrieved the README.md of the template that your workspace points to.

  • 400

    The source URL format is invalid, the source repository is not supported by Schematics, or the source repository API returns an HTTP error.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    The README.md file could not be retrieved, because an HTTP error was returned by Git.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "readme": "&lt;p&gt;This is my readme.&lt;/p&gt;  \n"
}

Upload a TAR file to your workspace

Provide your Terraform template by uploading a TAR file from your local machine. Before you use this API, you must create a workspace without a link to a GitHub or GitLab repository with the POST /v1/workspaces API.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

PUT /v1/workspaces/{w_id}/template_data/{t_id}/template_repo_upload

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.update

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace where you want to upload your .tar file. To find the workspace ID, use the GET /v1/workspaces API.

  • t_id
    Required*
    string

    The ID of the Terraform template in your workspace. When you create a workspace, a unique ID is assigned to your Terraform template, even if no template was provided during workspace creation. To find this ID, use the GET /v1/workspaces API and review the template_data.id value.

Form Parameters

  • file
    binary

    Template tar file

  • curl -X PUT https://schematics.cloud.ibm.com/v1/workspaces/{id}/template_data/{template_id}/template_repo_upload -H "Authorization: <iam_token>" -H "Content-Type: multipart/form-data" --form "file =@<file_path>/mytarfile.tar"
  • fileReader, _ := os.Open(<path_of_tar_file>)
fileReaderWrapper := ioutil.NopCloser(fileReader)

uploadTarOptions := &schematicsv1.UploadTemplateTarOptions{
    WID:             <workspace_id>,
    TID:             <template_id>,
    File:            fileReaderWrapper,
    FileContentType: core.StringPtr("multipart/form-data"),
}

uploadResult, httpResponse, err := schematicsService.UploadTemplateTar(uploadTarOptions)

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(uploadResult, "", "  ")
fmt.Println(string(w))
  • fileStream = fs.createReadStream('<path_of_tar_file>');

schematicsService.uploadTemplateTar({
    wId : '<workspace_id>',
    tId: '<template_id>',
    fileContentType: "multipart/form-data",
    file: fileStream
})
.then(res => {
  console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
  console.warn(err);
})
  • file = open("<path_of_tar_file>", "rb")

template_repo_tar_upload_response = schematics_service.upload_template_tar(
    w_id='<workspace_id>',
    t_id='<template_id>',
    file = file,
    file_content_type = 'multipart/form-data'
).get_result()

print(json.dumps(template_repo_tar_upload_response, indent=2))
  • UploadTemplateTarOptions uploadTemplateTarOptions = new UploadTemplateTarOptions.Builder()
.wId("<workspace_id>")
.tId("<template_id>")
.file(new File("<path_of_tar_file>"))
.fileContentType("multipart/form-data")
.build();

Response<TemplateRepoTarUploadResponse> response = service.uploadTemplateTar(uploadTemplateTarOptions).execute();
TemplateRepoTarUploadResponse templateRepoTarUploadResponse = response.getResult();

System.out.println(templateRepoTarUploadResponse);

Response

Response Body

TemplateRepoTarUploadResponse

Response after uploading Template in tar file format

Status Code

  • 200

    Successfully uploaded the TAR file to your workspace.

  • 400

    The tar file could not be read. Make sure that the tar file was created in the right format and try again.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    Not found. The specified workspace could not be found. Verify that the workspace ID is correct. To list workspaces in your IBM Cloud account, use the GET /v1/workspaces API.

  • 429

    Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

List workspace input variables

Retrieve a list of input variables that are declared in your Terraform or IBM Cloud catalog template.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v1/workspaces/{w_id}/template_data/{t_id}/values

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.template_values

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

  • t_id
    Required*
    string

    The ID of the Terraform template in your workspace. When you create a workspace, the Terraform template that your workspace points to is assigned a unique ID. Use the GET /v1/workspaces to look up the workspace IDs and template IDs or template_data.id in your IBM Cloud account.

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/template_data/{template_id}/values -H "Authorization: <iam_token>"      
  • inputValues, detailedResponse, err := schematicsService.GetWorkspaceInputs(&schematicsv1.GetWorkspaceInputsOptions{
    WID: <workspace_id>,
    TID: <template_id>,
})

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(inputValues, "", "  ")
fmt.Println(string(w))
  • const params = {
  wId: '<workspace_id>',
  tId: '<template_id>',
};

schematicsService.getWorkspaceInputs(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • template_values = schematics_service.get_workspace_inputs(
    w_id='<workspace_id>',
    t_id='<template_id>'
).get_result()

print(json.dumps(template_values, indent=2))
  • GetWorkspaceInputsOptions getWorkspaceInputsOptions = new GetWorkspaceInputsOptions.Builder()
.wId("<workspace_id>")
.tId("<template_id>")
.build();

Response<TemplateValues> response = service.getWorkspaceInputs(getWorkspaceInputsOptions).execute();
TemplateValues templateValues = response.getResult();
System.out.println(templateValues);

Response

Response Body

TemplateValues

Information about the input variables that are declared in the template that your workspace points to.

Status Code

  • 200

    Successfully retrieved a list of input variables that are declared in your template.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "values_metadata": [
    {
      "name": "variable_name",
      "type": "string"
    }
  ],
  "variablestore": [
    {
      "name": "variable_name",
      "secure": false,
      "value": "variable_value",
      "type": "",
      "description": ""
    }
  ]
}

Replace workspace input variables

Replace or Update the input variables for the template that your workspace points to.

PUT /v1/workspaces/{w_id}/template_data/{t_id}/values

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.template_values

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

  • t_id
    Required*
    string

    The ID of the Terraform template in your workspace. When you create a workspace, the Terraform template that your workspace points to is assigned a unique ID. Use the GET /v1/workspaces to look up the workspace IDs and template IDs or template_data.id in your IBM Cloud account.

Request Body

Required*
UserValuesRequest

Replace a Workspace input values

  • curl --location -g --request PUT https://schematics.cloud.ibm.com/v1/workspaces/{id}/template_data/{template_id}/values --header "Authorization: <iam_token>" --header "Content-Type: application/json" --data-raw "{"env_values": [{"name": "env_variable_name", "value": "env_variable_value" }], "values": "string", "variablestore": [{"description": "<variable_description>", "name": "<variable_name>", "secure": <true_or_false>, "use_default": <true_or_false>, "type": "<variable_datatype>", "value": "<variable_value>"}]}

Response

Response Body

UserValues

UserValues -

Status Code

  • 200

    Successfully updated input variables for the template that your workspace points to.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Get workspace template details

Retrieve detailed information about the Terraform template that your workspace points to.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v1/workspaces/{w_id}/templates/values

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.template_metadata_values

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace for which you want to retrieve input parameters and values. To find the workspace ID, use the GET /workspaces API.

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/templates/values -H "Authorization: <iam_token>"

Response

Response Body

WorkspaceTemplateValuesResponse

Response with the template details in your workspace

Status Code

  • 200

    Successfully retrieved details about the Terraform template that your workspace points to.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "template_data": [
    {
      "id": "1111aa2221-a11a-11",
      "folder": ".",
      "type": "terraform_v0.12",
      "values_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/template_data/71111aa2221-a11a-11/values",
      "values": "",
      "values_metadata": [
        {
          "name": "variable_name1",
          "type": "string"
        },
        {
          "name": "variable_name2",
          "type": "string"
        }
      ],
      "variablestore": [
        {
          "name": "variable_name1",
          "secure": false,
          "value": "variable_value1",
          "type": "",
          "description": ""
        },
        {
          "name": "variable_name2",
          "secure": false,
          "value": "variable_value2",
          "type": "",
          "description": ""
        }
      ]
    }
  ],
  "runtime_data": [
    {
      "id": "1111aa2221-a11a-11",
      "engine_name": "terraform",
      "engine_version": "v0.12.24",
      "state_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/1111aa2221-a11a-11/state_store",
      "log_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/1111aa2221-a11a-11/log_store"
    }
  ],
  "shared_data": {
    "cluster_id": null,
    "namespace": null,
    "region": "",
    "resource_group_id": ""
  }
}

List workspace variable metadata

Retrieve the metadata for all the workspace input variables that are declared in the template that your workspace points to.

GET /v1/workspaces/{w_id}/template_data/{t_id}/values_metadata

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace for which you want to retrieve the metadata of the input variables that are declared in the template. To find the workspace ID, use the GET /v1/workspaces API.

  • t_id
    Required*
    string

    The ID of the Terraform template for which you want to retrieve the metadata of your input variables. When you create a workspace, the Terraform template that your workspace points to is assigned a unique ID. To find this ID, use the GET /v1/workspaces API and review the template_data.id value.

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/template_data/{template_id}/values_metadata -H "Authorization: <iam_token>"

Response

Response Body

object[]

A list of input variables and its metadata for the workspace template.

Status Code

  • 200

    Successfully retrieved the metadata of the input variables for the template that your workspace points to.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "name": "variable_name",
  "type": "string"
}

List workspace output values

Retrieve a list of Terraform output variables. You define output values in your Terraform template to include information that you want to make accessible for other Terraform templates.

GET /v1/workspaces/{w_id}/output_values

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace for which you want to retrieve output parameters and values. To find the workspace ID, use the GET /workspaces API.

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/output_values -H "Authorization: <iam_token>"

Response

Response Body

OutputValues_inner[]

Terraform output values that are defined in the Terraform template or IBM Cloud software template.

Status Code

  • 200

    Successfully retrieved the output values in JSON format.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "id": "cef7da5d-dd7c-48",
  "folder": ".",
  "type": "terraform_v0.12",
  "output_values": [
    {
      "sshcommand": {
        "sensitive": false,
        "type": "string",
        "value": "ssh root@111.22.111.111"
      }
    }
  ]
}

List workspace resources

Retrieve a list of IBM Cloud resources that you created with your workspace.

GET /v1/workspaces/{w_id}/resources

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

  • curl --location --request GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/resources -H "Authorization: Bearer <access_token>" -H "refresh_token: <refresh_token>"--header "Content-Type: application/json" --data-raw '{"name": "testbranchReso","type": ["terraform_v0.12"],"description": "terraform workspace","tags": ["test:bbbranch"],"template_repo": {"url": "<source_repo_url>"},"template_data": [{"folder": ".","type": "terraform_v0.12","variablestore": [{"value": "variable_value1","name": "ibmcloud_api_key","type": "string","secure": true}],"env_values":[{"TF_LOG":"debug"}]}]}'
  • resourcesList, detailedResponse, err := schematicsService.GetWorkspaceResources(&schematicsv1.GetWorkspaceResourcesOptions{
    WID: <workspace_id>,
})

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(resourcesList, "", "  ")
fmt.Println(string(w))
  • const params = {
  wId: '<workspace_id>',
};

schematicsService.getWorkspaceResources(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • list_template_resources = schematics_service.get_workspace_resources(
    w_id='<workspace_id>'
).get_result()

print(json.dumps(list_template_resources, indent=2))
  • GetWorkspaceResourcesOptions getWorkspaceResourcesOptions = new GetWorkspaceResourcesOptions.Builder()
.wId("<workspace_id>")
.build();

Response<List<TemplateResources>> response = service.getWorkspaceResources(getWorkspaceResourcesOptions).execute();
List<TemplateResources> listTemplateResources = response.getResult();

System.out.println(listTemplateResources);

Response

Response Body

TemplateResources[]

Information about the resources provisioned by the workspace template.

Status Code

  • 200

    Successfully retrieved the resources in JSON format.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • [
  {
    "id": "445ec9f4-e157-41",
    "folder": ".",
    "type": "terraform_v0.12",
    "resources": null,
    "related_resources": [
      {
        "resource_id": "data.template_file.test",
        "resource_name": "vm1",
        "resource_type": "ibm_compute_vm_instance",
        "resource_crn": "",
        "resource_icon_url": "",
        "resource_controller_url": "https://cloud.ibm.com/gen1/infrastructure/virtual-server/120765732/details#main",
        "resource_group_name": "",
        "resource_status": "",
        "resource_tainted": false,
        "resource_extension": {
          "resource_name": "",
          "resource_data_array": null,
          "resource_type": ""
        }
      }
    ],
    "null_resources": [
      {
        "resource_id": "6776381372089043143",
        "resource_name": "null_resource.sleep",
        "resource_type": "null_resource",
        "resource_crn": "",
        "resource_icon_url": "",
        "resource_controller_url": "",
        "resource_group_name": "",
        "resource_status": "",
        "resource_tainted": false,
        "resource_extension": {
          "resource_name": "",
          "resource_data_array": null,
          "resource_type": ""
        }
      }
    ],
    "resources_count": 1
  }
]

Get Terraform statefile URL

This API is deprecated, and is replaced by the GET /v2/jobs/{job_id}/files, with file_type equal state_file. Retrieve the URL to the Terraform statefile (terraform.tfstate). You use the URL to access the Terraform statefile. The Terraform statefile includes detailed information about the IBM Cloud resources that you provisioned with IBM Cloud Schematics and Schematics uses the file to determine future create, modify, or delete actions for your resources. To show the content of the Terraform statefile, use the GET /v1/workspaces/{id}/runtime_data/{template_id}/state_store API.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v1/workspaces/{w_id}/state_stores

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.template_state_stores

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace for which you want to retrieve the Terraform statefile. To find the workspace ID, use the GET /v1/workspaces API.

  • curl -X GET  https://schematics.cloud.ibm.com/v1/workspaces/{workspace id}/state_stores/{activity id} -H  "Authorization: <iam_token>" Cache-Control: no-cache                      
  • curl -X GET <state_store_url> -H "Authorization: <iam_token>"
  • stateFile, detailedResponse, err := schematicsService.GetWorkspaceState(&schematicsv1.GetWorkspaceStateOptions{
    WID: <workspace_id>,
})

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(stateFile, "", "  ")
fmt.Println(string(w))
  • const params = {
  wId: '<workspace_id>',
};

schematicsService.getWorkspaceState(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • state_store_response_list = schematics_service.get_workspace_state(
    w_id='<workspace_id>'
).get_result()

print(json.dumps(state_store_response_list, indent=2))
  • GetWorkspaceStateOptions getWorkspaceStateOptions = new GetWorkspaceStateOptions.Builder()
.wId("<workspace_id>")
.build();

Response<StateStoreResponseList> response = service.getWorkspaceState(getWorkspaceStateOptions).execute();
StateStoreResponseList stateStoreResponseList = response.getResult();

System.out.println(stateStoreResponseList);

Response

Response Body

StateStoreResponseList

Information about the Terraform statefile URL.

Status Code

  • 200

    Successfully retrieved the URL to the Terraform statefile.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "version": 3,
  "terraform_version": "0.11.15",
  "serial": 1,
  "lineage": "8afcf3e5-a635-39ba-8b7a-930fc52d91c4",
  "modules": [
    {
      "path": [
        "root"
      ],
      "outputs": {
        "rendered_template": {
          "sensitive": false,
          "type": "string",
          "value": "Hello, I am a template. My sample_var value = THIS IS IBM CLOUD TERRAFORM CLI DEMO"
        }
      },
      "resources": {
        "data.template_file.test": {
          "type": "template_file",
          "depends_on": [],
          "primary": {
            "id": "a66b4e292bc3632041929666cc093a78bf8842030b165e38eca429d5561c51b2",
            "attributes": {
              "id": "a66b4e292bc3632041929666cc093a78bf8842030b165e38eca429d5561c51b2",
              "rendered": "Hello, I am a template. My sample_var value = THIS IS IBM CLOUD TERRAFORM CLI DEMO",
              "template": "Hello, I am a template. My sample_var value = ${sample_var}",
              "vars.%": "1",
              "vars.sample_var": "THIS IS IBM CLOUD TERRAFORM CLI DEMO"
            },
            "meta": {},
            "tainted": false
          },
          "deposed": [],
          "provider": "provider.template"
        },
        "null_resource.sleep": {
          "type": "null_resource",
          "depends_on": [],
          "primary": {
            "id": "6705893306070343458",
            "attributes": {
              "id": "6705893306070343458",
              "triggers.%": "1",
              "triggers.uuid": "eacbeee0-6710-f57c-76a1-5a1785d589d4"
            },
            "meta": {},
            "tainted": false
          },
          "deposed": [],
          "provider": "provider.null"
        }
      },
      "depends_on": []
    }
  ]
}

Show Terraform statefile content

This API is deprecated, and is replaced by the GET /v2/jobs/{job_id}/files, with file_type equal state_file. Show the content of the Terraform statefile (terraform.tfstate) that was created when your Terraform template was applied in IBM Cloud. The statefile holds detailed information about the IBM Cloud resources that were created by IBM Cloud Schematics and Schematics uses the file to determine future create, modify, or delete actions for your resources.

GET /v1/workspaces/{w_id}/runtime_data/{t_id}/state_store

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace for which you want to retrieve the Terraform statefile. To find the workspace ID, use the GET /v1/workspaces API.

  • t_id
    Required*
    string

    The ID of the Terraform template for which you want to retrieve the Terraform statefile. When you create a workspace, the Terraform template that your workspace points to is assigned a unique ID. To find this ID, use the GET /v1/workspaces API and review the template_data.id value.

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/runtime_data/{template_id}/state_store -H "Authorization: <iam_token>"
  • statefile, detailedResponse, err := schematicsService.GetWorkspaceTemplateState(&schematicsv1.GetWorkspaceTemplateStateOptions{
    WID: <workspace_id>,
    TID: <template_id>,
})

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(statefile, "", "  ")
fmt.Println(string(w))
  • const params = {
  wId: '<workspace_id>',
  tId: '<template_id>',
};

schematicsService.getWorkspaceTemplateState(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • template_state_store = schematics_service.get_workspace_template_state(
    w_id='<workspace_id>',
    t_id='<template_id>'
).get_result()

print(json.dumps(template_state_store, indent=2))
  • GetWorkspaceTemplateStateOptions getWorkspaceTemplateStateOptions = new GetWorkspaceTemplateStateOptions.Builder()
.wId("<workspace_id>")
.tId("<template_id>")
.build();

Response<TemplateStateStore> response = service.getWorkspaceTemplateState(getWorkspaceTemplateStateOptions).execute();
TemplateStateStore templateStateStore = response.getResult();

System.out.println(templateStateStore);

Response

Response Body

TemplateStateStore

The content of the Terraform statefile (terraform.tfstate).

Status Code

  • 200

    Successfully retrieved the information from the Terraform statefile.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "version": 3,
  "terraform_version": "0.11.14",
  "serial": 1,
  "lineage": "98aba884-11c1-7e45-f9d6-f895bbf80654",
  "modules": [
    {
      "path": [
        "root"
      ],
      "outputs": {},
      "resources": {
        "data.ibm_is_image.ubuntu": {
          "type": "ibm_is_image",
          "depends_on": [],
          "primary": {
            "id": "abc111-1111-1111-aaaa-123456789",
            "attributes": {
              "architecture": "amd64",
              "crn": "crn:v1:bluemix:public:is:us-south:::image:abc111-1111-1111-aaaa-123456789",
              "id": "abc111-1111-1111-aaaa-123456789",
              "name": "ubuntu-18.04-amd64",
              "os": "ubuntu-18-04-amd64",
              "status": "available",
              "visibility": "public"
            },
            "meta": {},
            "tainted": false
          },
          "deposed": [],
          "provider": "provider.ibm"
        },
        "data.ibm_is_ssh_key.ssh_key_id": {
          "type": "ibm_is_ssh_key",
          "depends_on": [],
          "primary": {
            "id": "111111-0000-0001-0000-0000001111a1",
            "attributes": {
              "fingerprint": "SHA256:A1B3aaaabbb3A/ABCDEaaAA",
              "id": "111111-0000-0001-0000-0000001111a1",
              "length": "2048",
              "name": "mykey",
              "type": "rsa"
            },
            "meta": {},
            "tainted": false
          },
          "deposed": [],
          "provider": "provider.ibm"
        }
      },
      "depends_on": []
    }
  ]
}

Get workspace job log URL

Get the Terraform log file URL for a workspace job. You can retrieve the log URL for jobs that were created with the PUT /v1/workspaces/{id}/apply, POST /v1/workspaces/{id}/plan, or DELETE /v1/workspaces/{id}/destroy API.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v1/workspaces/{w_id}/actions/{activity_id}/logs

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.log_stores

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace for which you want to retrieve the Terraform statefile. To find the workspace ID, use the GET /v1/workspaces API.

  • activity_id
    Required*
    string

    The ID of the activity or job, for which you want to retrieve details. To find the job ID, use the GET /v1/workspaces/{id}/actions API.

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/actions/{action_id}/logs -H "Authorization: <iam_token>"
  • curl -X GET <log_url> -H "Authorization: <access_token>"
  • activityLogResult, detailedResponse, err := schematicsService.GetWorkspaceActivityLogs(&schematicsv1.GetWorkspaceActivityLogsOptions{
    WID:        <workspace_id>,
    ActivityID: <activity_id>,
})

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(activityLogResult, "", "  ")
fmt.Println(string(w))
  • const params = {
  wId: '<workspace_id>',
  activityId: '<activity_id>',
};

schematicsService.getWorkspaceActivityLogs(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • workspace_activity_logs = schematics_service.get_workspace_activity_logs(
    w_id='<workspace_id>',
    activity_id='<activity_id>'
).get_result()

print(json.dumps(workspace_activity_logs, indent=2))
  • GetWorkspaceActivityLogsOptions getWorkspaceActivityLogsOptions = new GetWorkspaceActivityLogsOptions.Builder()
.wId("<workspace_id>")
.activityId("<activity_id>")
.build();

Response<WorkspaceActivityLogs> response = service.getWorkspaceActivityLogs(getWorkspaceActivityLogsOptions).execute();
WorkspaceActivityLogs workspaceActivityLogs = response.getResult();

System.out.println(workspaceActivityLogs);

Response

Response Body

WorkspaceActivityLogs

Workspace job logs for all the templates in the workspace

Status Code

  • 200

    Successfully retrieved the log file URL for your job.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    The specified workspace or action could not be found. Verify that you entered the correct workspace and action ID. To find the ID of your workspace, use the GET /v1/workspaces API. To find the ID of the action, use the GET /v1/workspaces/{id}/actions API.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "action_id": "123456ba12345b",
  "name": "APPLY",
  "templates": [
    {
      "template_id": "a1245319-b1235",
      "template_type": "terraform_v0.12",
      "log_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a1245319-b1235/log_store/actions/7123456ba12345b"
    }
  ]
}

Get latest workspace job log URL for all workspace templates

Retrieve the log file URL for the latest job of a template that ran against your workspace. You use this URL to retrieve detailed logs for the latest job.

GET /v1/workspaces/{w_id}/log_stores

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/log_stores -H "Authorization: <iam_token>"
  • curl -X GET <log_store_url> -H "Authorization: <iam_token>"
  • activityLogResult, detailedResponse, err := schematicsService.GetWorkspaceLogUrls(&schematicsv1.GetWorkspaceLogUrlsOptions{
    WID: <workspace_id>,
})

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(activityLogResult, "", "  ")
fmt.Println(string(w))
  • const params = {
  wId: '<workspace_id>',
};

schematicsService.getWorkspaceLogUrls(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • log_store_response_list = schematics_service.get_workspace_log_urls(
    w_id='<workspace_id>'
).get_result()

print(json.dumps(log_store_response_list, indent=2))
  • GetWorkspaceLogUrlsOptions getWorkspaceLogUrlsOptions = new GetWorkspaceLogUrlsOptions.Builder()
.wId("<workspace_id>")
.build();

Response<LogStoreResponseList> response = service.getWorkspaceLogUrls(getWorkspaceLogUrlsOptions).execute();
LogStoreResponseList logStoreResponseList = response.getResult();

System.out.println(logStoreResponseList);

Response

Response Body

LogStoreResponseList

List of log file URL that ran against your workspace.

Status Code

  • 200

    Successfully retrieved the log URL for the most recent job that ran against your workspace.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "runtime_data": [
    {
      "id": "a134567b24-12",
      "engine_name": "terraform",
      "engine_version": "terraformv0.12.24",
      "log_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a134567b24-12/log_store"
    }
  ]
}

Show latest logs for a workspace template

Show the Terraform logs for the most recent job of a template that ran against your workspace.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v1/workspaces/{w_id}/runtime_data/{t_id}/log_store

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.state_stores

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

  • t_id
    Required*
    string

    The ID of the Terraform template or IBM Cloud catalog software template in the workspace. Use the GET /v1/workspaces to look up the workspace IDs and template IDs or template_data.id

Query Parameters

  • log_tf_cmd
    boolean

    Enter false to replace the first line in each Terraform command section, such as Terraform INIT or Terraform PLAN, with Schematics INIT (Schematics PLAN) in your log output. In addition, the log lines Starting command: terraform init -input=false -no-color and Starting command: terraform apply -state=terraform.tfstate -var-file=schematics.tfvars -auto-approve -no-color are suppressed. All subsequent command lines still use the Terraform command prefix. To remove this prefix, use the log_tf_prefix option.

  • log_tf_prefix
    boolean

    false will hide all the terraform command prefix in the log statements

  • log_tf_null_resource
    boolean

    false will hide all the null resource prefix in the log statements

  • log_tf_ansible
    boolean

    true will format all logs to withhold the original format of ansible output in the log statements

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/runtime_data/{template_id}/log_store -H "Authorization: <iam_token>"
  • templateLogResult, detailedResponse, err := schematicsService.GetTemplateLogs(&schematicsv1.GetTemplateLogsOptions{
    WID: <workspace_id>,
    TID: <template_id>,
})

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(templateLogResult, "", "  ")
fmt.Println(string(w))
  • const params = {
  wId: '<workspace_id>',
  tId: '<template_id>',
};

schematicsService.getTemplateLogs(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • template_log_store_string = schematics_service.get_template_logs(
    w_id='<workspace_id>',
    t_id='<template_id>'
).get_result()

print(json.dumps(template_log_store_string, indent=2))
  • GetTemplateLogsOptions getTemplateLogsOptions = new GetTemplateLogsOptions.Builder()
.wId("<workspace_id>")
.tId("<template_id>")
.build();

Response<String> response = service.getTemplateLogs(getTemplateLogsOptions).execute();
String templateLogStoreString = response.getResult();

System.out.println(templateLogStoreString);

Response

Response Body

string

The Terraform logs for the most recent workspace job.

Status Code

  • 200

    Successfully retrieved the Terraform logs for the most recent workspace job.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Show logs for a workspace job

Show the Terraform logs for an job that ran against your workspace.

GET /v1/workspaces/{w_id}/runtime_data/{t_id}/log_store/actions/{activity_id}

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

  • t_id
    Required*
    string

    The ID of the Terraform template or IBM Cloud catalog software template in the workspace. Use the GET /v1/workspaces to look up the workspace IDs and template IDs or template_data.id

  • activity_id
    Required*
    string

    The ID of the activity or job, for which you want to retrieve details. To find the job ID, use the GET /v1/workspaces/{id}/actions API.

Query Parameters

  • log_tf_cmd
    boolean

    Enter false to replace the first line in each Terraform command section, such as Terraform INIT or Terraform PLAN, with Schematics INIT (Schematics PLAN) in your log output. In addition, the log lines Starting command: terraform init -input=false -no-color and Starting command: terraform apply -state=terraform.tfstate -var-file=schematics.tfvars -auto-approve -no-color are suppressed. All subsequent command lines still use the Terraform command prefix. To remove this prefix, use the log_tf_prefix option.

  • log_tf_prefix
    boolean

    false will hide all the terraform command prefix in the log statements

  • log_tf_null_resource
    boolean

    false will hide all the null resource prefix in the log statements

  • log_tf_ansible
    boolean

    true will format all logs to withhold the original format of ansible output in the log statements

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/runtime_data/{template_id}/log_store/actions/{action_id} -H "Authorization: <iam_token>"
  • activityLogResult, detailedResponse, err := schematicsService.GetTemplateActivityLog(&schematicsv1.GetTemplateActivityLogOptions{
    WID:        <workspace_id>,
    TID:        <template_id>,
    ActivityID: <activity_id>,
})

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(activityLogResult, "", "  ")
fmt.Println(string(w))
  • const params = {
  wId: '<workspace_id>',
  activityId: '<activity_id>',
  tId: '<template_id>',
};

schematicsService.getTemplateActivityLog(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • workspace_activity_template_log_string = schematics_service.get_template_activity_log(
    w_id='<workspace_id>',
    activity_id='<activity_id>',
    t_id='<template_id>'
).get_result()

print(json.dumps(workspace_activity_template_log_string, indent=2))
  • GetTemplateActivityLogOptions getTemplateActivityLogOptions = new GetTemplateActivityLogOptions.Builder()
.wId("<workspace_id>")
.activityId("<activity_id>")
.tId("<template_id>")
.build();

Response<String> response = service.getTemplateActivityLog(getTemplateActivityLogOptions).execute();
String workspaceActivityTemplateLogString = response.getResult();

System.out.println(workspaceActivityTemplateLogString);

Response

Response Body

string

Workspace template job log as a string

Status Code

  • 200

    Successfully retrieved the template activity logs as text (string).

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    The specified workspace, action, or template could not be found. Verify that you entered the correct workspace, action ID, and template ID. To find the ID of your workspace or template, use the GET /v1/workspaces API. To find the ID of the action, use the GET /v1/workspaces/{id}/actions API.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

List actions

Retrieve a list of all Schematics actions that depends on the API endpoint that you have access. For example, if you use an API endpoint for a geography, such as North America, only actions that are created in us-south or us-east are retrieved.

For more information, about supported API endpoints, see API endpoints.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v2/actions

Auditing

Calling this method generates the following auditing event.

  • schematics.action.list

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Query Parameters

  • offset
    integer

    The starting position of the item in the list of items. For example, if you have three workspaces in your account, the first workspace is assigned position number 0, the second workspace is assigned position number 1, and so forth. If you have 6 workspaces and you want to list the details for workspaces 2-6, enter 1. To limit the number of workspaces that is returned, use the limit option in addition to the offset option. Negative numbers are not supported and are ignored.

    Possible values: value ≥ 0

  • limit
    integer

    The maximum number of items that you want to list. The number must be a positive integer between 1 and 2000. If no value is provided, 100 is used by default.

    Possible values: 1 ≤ value ≤ 2000

    Default: 100

  • sort
    string

    Name of the field to sort-by; Use the '.' character to delineate sub-resources and sub-fields (eg. owner.last_name). Prepend the field with '+' or '-', indicating 'ascending' or 'descending' (default is ascending) Ignore unrecognized or unsupported sort field

  • profile
    string

    Level of details returned by the get method

    Allowable values: [ids,summary]

  • curl --location --request GET https://schematics.cloud.ibm.com/v2/actions/actions --header "Authorization:  <access_token>"
  • listActionsOptions := schematicsService.NewListActionsOptions()

actionList, response, err := schematicsService.ListActions(listActionsOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(actionList, "", "  ")
fmt.Println(string(b))

  • action_list = schematics_service.list_actions().get_result()
print (json.dumps(action_list, indent=2))
  • schematicsService.listActions({})
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});
  • ListActionsOptions listActionsOptions = new ListActionsOptions.Builder()
.build();
Response<ActionList> response = service.listActions(listActionsOptions).execute();
ActionList actionList = response.getResult();
System.out.println(actionList);

Response

Response Body

ActionList

List of Action definition response

Status Code

  • 200

    Successfully retrieved all actions.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "total_count": "xx total number of records",
  "limit": "xx records returned",
  "offset": "0 record skipped",
  "actions": [
    {
      "name": "Your action name",
      "description": "The description of the action",
      "id": "Your action ID",
      "location": "user location",
      "resource_group": "user resource group",
      "namespace": "target namespace name",
      "tags": [
        "string"
      ],
      "user_state": {
        "state": "live",
        "set_by": "user@in.ibm.com",
        "set_at": "2021-03-03T13:11:14.553280062Z"
      },
      "state": {
        "status_code": "normal",
        "status_message": "Action is ready for execution."
      },
      "sys_lock": {
        "sys_locked_at": "0001-01-01T00:00:00Z"
      },
      "created_at": "2021-03-03T13:11:14.558330723Z",
      "created_by": "user@in.ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    }
  ]
}

Create an action

Create an IBM Cloud Schematics action to run on a single target or groups of target hosts, roles, policies, or steps to deploy your resources in the target hosts. You can run the IBM Cloud resources the order in which you want to execute them. Note If your Git repository already contains a host file. Schematics does not overwrite the host file already present in your Git repository. For sample templates, see IBM Cloud Automation templates.

The Schematics action API now supports bastion host connection with non-root user, and bastion connection type is marked as optional, when inventory connection type is set as Windows Remote Management(winrm).

For more information, about the Schematics create action, see ibmcloud schematics action create. Note you cannot update the location and region once an action is created. Also, make sure your IP addresses are in the allowlist.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

POST /v2/actions

Auditing

Calling this method generates the following auditing event.

  • schematics.action.create

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • X-Github-token
    string

    The personal access token to authenticate with your private GitHub or GitLab repository and access your Terraform template.

Request Body

Required*
Action

Create Action request

  • curl --location --request POST https://schematics.cloud.ibm.com/v2/actions --header "Authorization: <access_token> " --header "Content-Type: application/json" --data-raw "{"name": "Example-12ab2",   "description": "<action_description>", "location": "<action_location>", "resource_group": "<resource_group>", "source": {"source_type": "git", "git": {"git_repo_url": "https://github.com/Cloud-Schematics/ansible-is-instance-actions"}}}
  • action_list = schematics_service.create_action(
name="mskpythonsamples-templates",
description="<short description>",
location="<location>",
resource_group="<resource_group>",
tags=["User environment,mytest"]
source={
‘git’:
{
‘git_repo_url’:“https://github.com/Cloud-Schematics/cli-demo”
}
}
).get_result()
print (json.dumps(action_list, indent=2))
  • CreateActionOptions createActionOptions = new CreateActionOptions.Builder()
.name("msksampletest-checkCreate")
 .build();

Response<Action> response = service.createAction(createActionOptions).execute();
Action actionList = response.getResult();

System.out.println(actionList);
  • const params = {
name:"Users action name",
description:"short description",
location:"us",
resource_group:"Users resource group",
tags:["env:prod", "mytest"],
source:{
"git":
{
'git_repo_url':"https://github.com/Cloud-Schematics/repo_name"
}
}

};

schematicsService.createAction(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});
  • createActionOptions := schematicsService.NewCreateActionOptions()
createActionOptions.SetName("set your name")
createActionOptions.SetDescription("short description")
tags := []string{"env:prod", "mytest1"}
createActionOptions.Tags = tags
createActionOptions.SetLocation("set your location")
createActionOptions.SetResourceGroup("set the resource group")
source := schematicsv1.ExternalSource{
SourceType: core.StringPtr("git"),
Git: &schematicsv1.ExternalSourceGit{
GitRepoURL: core.StringPtr("set your Git repository URL"),
},
}
createActionOptions.SetSource(&source)
actionList, response, err := schematicsService.CreateAction(createActionOptions)
if err != nil {
panic(err)
}

Response

Response Body

Action

Complete Action details with user inputs and system generated data

Status Code

  • 201

    Successfully created a new Action definition

  • 400

    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 409

    The specified resource already exists

  • 429

    Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "offset": 0,
  "limit": 1,
  "count": 6,
  "actions": [
    {
      "name": "Users action name",
      "description": "The description of the action",
      "location": "Users location",
      "resource_group": "Users resource group",
      "tags": [
        "string"
      ],
      "user_state": {
        "state": "live",
        "set_by": "user@.ibm.com",
        "set_at": "021-03-12T09:45:44.568286818Z"
      },
      "source": {
        "source_type": "git",
        "git": {
          "git_repo_url": "https://github.com/Cloud-Schematics/repo_name"
        },
        "catalog": {},
        "external_scm": {},
        "cos_bucket": {}
      },
      "source_type": "GitHub",
      "command_parameter": "user playbook name with the extension",
      "bastion": {
        "name": "bastionhost",
        "type": "string",
        "description": "string",
        "resource_query": "53.46.14.52",
        "credential_ref": "ssh_key",
        "created_at": "0001-01-01T00:00:00Z",
        "updated_at": "0001-01-01T00:00:00Z",
        "sys_lock": {
          "sys_locked_at": "0001-01-01T00:00:00Z"
        }
      },
      "targets_ini": "[webserverhost] \n 132.00.00.0",
      "credentials": [
        {
          "name": "ssh_key",
          "value": "*******",
          "metadata": {
            "type": "string",
            "secure": true
          }
        }
      ],
      "inputs": [
        {
          "name": "upassword",
          "value": "*******",
          "metadata": {
            "type": "string",
            "default_value": "user@123abc",
            "secure": true
          }
        },
        {
          "name": "dbname",
          "value": "dbfoo",
          "metadata": {
            "type": "string",
            "default_value": "foodb"
          }
        },
        {
          "name": "dbuser",
          "value": "xxx",
          "metadata": {
            "type": "string",
            "default_value": "xxx"
          }
        },
        {
          "name": "mysql_port",
          "value": "xxxx",
          "metadata": {
            "type": "string",
            "default_value": "xxxx"
          }
        },
        {
          "name": "httpd_port",
          "value": "xx",
          "metadata": {
            "type": "string",
            "default_value": "xx"
          }
        }
      ],
      "id": "Users action ID",
      "crn": "crn:v1::lalalalalallalallala::",
      "account": "0dlalalalalla",
      "source_created_at": "0001-01-01T00:00:00Z",
      "source_updated_at": "0001-01-01T00:00:00Z",
      "created_at": "2021-02-08T12:29:55.214763283Z",
      "created_by": "user@.ibm.com",
      "updated_at": "0001-01-01T00:00:00Z",
      "namespace": "Default",
      "state": {
        "status_code": "pending",
        "status_message": "Create Action is in queue, Please wait till action complete"
      },
      "sys_lock": {
        "sys_locked_at": "0001-01-01T00:00:00Z"
      }
    }
  ]
}

Get action details

Retrieve the detailed information of an actions from your IBM Cloud account. This API returns a URL to the log file that you can retrieve by using the GET /v2/actions/{action_id}/logs API.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v2/actions/{action_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.action.read

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • action_id
    Required*
    string

    Action Id. Use GET /actions API to look up the Action Ids in your IBM Cloud account.

Query Parameters

  • profile
    string

    Level of details returned by the get method

    Allowable values: [summary,detailed,ids]

  • curl --location --request GET https://schematics.cloud.ibm.com/v2/actions/{action_id} --header "Authorization:  <access_token> "
  • GetActionOptions getActionOptions = new GetActionOptions.Builder()
.actionId("set your action ID.")
.build();
Response<Action> response = service.getAction(getActionOptions).execute();
Action action = response.getResult();

System.out.println(action);
  • action = schematics_service.get_action(action_id="Users action ID").get_result()
print (json.dumps(action, indent=2))
  • const params = {
actionId: "Users action ID",
};

schematicsService.getAction(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});
  • getActionOptions := schematicsService.NewGetActionOptions("testString",)
getActionOptions.SetActionID("set your action ID")

action, response, err := schematicsService.GetAction(getActionOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(action, "", "  ")
fmt.Println(string(b))

Response

Response Body

Action

Complete Action details with user inputs and system generated data

Status Code

  • 200

    Successfully got the Action definition

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    Not found. The specified action could not be found. Verify that the action ID is correct. To list actions in your IBM Cloud account, use the GET /v2/actions API.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "name": "Users action name",
  "description": "The description of the action",
  "id": "Users action ID",
  "location": "Users location",
  "tags": [
    "environment details, for example env:test",
    "mytest"
  ],
  "user_state": {
    "state": "live",
    "set_by": "user@in.ibm.com",
    "set_at": "2021-03-12T09:45:44.568286818Z"
  },
  "state": {
    "status_code": "normal",
    "status_message": "Action is ready for execution."
  },
  "sys_lock": {
    "sys_locked_at": "0001-01-01T00:00:00Z"
  },
  "created_at": "2021-03-12T09:45:44.571913075Z",
  "created_by": "user@in.ibm.com",
  "updated_at": "0001-01-01T00:00:00Z"
}

Delete an action

Delete a Schematics action and specify the Ansible playbook that you want to run against your IBM Cloud resources. Note you cannot delete or stop the job activity from an ongoing execution of an action defined in the playbook. You can repeat the execution of same job, whenever you patch the actions. For more information, about the Schematics action state, see Schematics action state diagram.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

DELETE /v2/actions/{action_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.action.delete

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • force
    boolean

    Equivalent to -force options in the command line

  • propagate
    boolean

    Auto propagate the chaange or deletion to the dependent resources

Path Parameters

  • action_id
    Required*
    string

    Action Id. Use GET /actions API to look up the Action Ids in your IBM Cloud account.

  • curl --location --request DELETE https://schematics.cloud.ibm.com/v2/actions/{action_id} --header "Authorization:  <access_token> "
  • deleteActionOptions := schematicsService.NewDeleteActionOptions("set your deletion action options",)
deleteActionOptions.SetActionID("set your Action ID")

response, err := schematicsService.DeleteAction(deleteActionOptions)
if err != nil {
panic(err)
}
  • response = schematics_service.delete_action(
action_id="Set your action ID"
).get_result()

print(json.dumps(response, indent=2))
  • const params = {
actionId: "Users action ID",
};

schematicsService.deleteAction(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});
  • DeleteActionOptions deleteActionOptions = new DeleteActionOptions.Builder()
.actionId("Users action ID")
.build();

service.deleteAction(deleteActionOptions).execute();

Response

Status Code

  • 204

    Successfully initiated stopping of the job, and deleted the job record

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    Not found. The specified action could not be found. Verify that the action ID is correct. To list actions in your IBM Cloud account, use the GET /v2/actions API.

  • 409

    Failed to delete the specific resoure. If the resource is locked, try again after unlocking.

  • 429

    Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

  • 503

    IBM Cloud Schematics could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Update an action

Update or replace an action to change the action state from the critical state to normal state, or pending state to the normal state for a successful execution. For more information, about the Schematics action state, see Schematics action state diagram.

The Schematics action API now supports bastion host connection with non-root user, and bastion connection type is marked as optional, when inventory connection type is set as Windows Remote Management(winrm).

Note you cannot update the location and region once an action is created. Also, make sure your IP addresses are in the [allowlist](https://cloud.ibm.com/docs/schematics?topic=schematics-allowed-ipaddresses].

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

PATCH /v2/actions/{action_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.action.update

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • X-Github-token
    string

    The personal access token to authenticate with your private GitHub or GitLab repository and access your Terraform template.

Path Parameters

  • action_id
    Required*
    string

    Action Id. Use GET /actions API to look up the Action Ids in your IBM Cloud account.

Request Body

Required*
Action

Action

  • curl --location --request PATCH https://schematics.cloud.ibm.com/v2/actions/{action_id} --header "Authorization: <access_token>" --header "Content-Type: application/json" --data-raw "{"name": "<action_name>", "description": "<action_description>", "location": "<action_location>", "resource_group": "<resource_group>", "source": {"source_type": "git", "git": {"git_repo_url": "https://github.com/Cloud-Schematics/lamp-simple"}}, "command_parameter": "<YAML_or_YML file>", "tags": ["string"], "credentials": [{ "name": "ssh_key", "value": "<ssh_key>" 
,"metadata": { "string"}}], "bastion": {"name": "bastionhost", "type": "string", "description": "string", "resource_query": "<IP_address", "credential_ref": "ssh_key" }, "inputs": [{ "name": "string", "value": "string", "metadata": {"type": "string", "secure": <true_or_false>, "default_value": "string" }}, {"name": "string", "value": "string", "metadata": { "type": "string", "default_value": "string" }}, { "name": "dbuser", "value": "string", "metadata": {  "type": "string", "default_value": "string" }}, { "name": "mysql_port", "value": "string", "metadata": { "type": "string", "default_value": "string" }}, { "name": "httpd_port", "value": "string", "metadata": { "type": "string", "secure": <false_or_true>, "default_value": "string" } }], "source_type": "GitHub",   "targets_ini": "[hostgroupname] 
 "IP address" 
 host2 
 [hostgroupname] 
 "IP address" "}
  • updateActionOptions := schematicsService.NewUpdateActionOptions("teststring",)
updateActionOptions.SetActionID("us.ACTION.sundeepKumar-patchpart.44875f1b")
updateActionOptions.SetName("set your name")
updateActionOptions.SetDescription("short description")
tags := []string{"env:prod", "mytest1"}
updateActionOptions.Tags = tags
updateActionOptions.SetLocation("set your location")
updateActionOptions.SetResourceGroup("set your resource group name")
source := schematicsv1.ExternalSource{
SourceType: core.StringPtr("git"),
Git: &schematicsv1.ExternalSourceGit{
GitRepoURL: core.StringPtr("set your Git repository URL"),
},
}
updateActionOptions.SetSource(&source)
actionList, response, err := schematicsService.UpdateAction(updateActionOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(actionList, "", "v2/actions")
fmt.Println(string(b))
  • action = schematics_service.update_action(
action_id="Users action ID").get_result()
print (json.dumps(action, indent=2))
  • const params = {
actionId: "Users action ID",
xGithubToken: "Users Github token",
description:"Updated short description"
};

schematicsService.updateAction(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});
  • UpdateActionOptions updateActionOptions = new UpdateActionOptions.Builder()
.actionId("action ID")
.xGithubToken("testString")
.build();

Response<Action> response = service.updateAction(updateActionOptions).execute();
Action action = response.getResult();

System.out.println(action);

Response

Response Body

Action

Complete Action details with user inputs and system generated data

Status Code

  • 200

    Successfully updated an action.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    Not found. The specified action could not be found. Verify that the action ID is correct. To list actions in your IBM Cloud account, use the GET /v2/actions API.

  • 429

    Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "name": "Users action name",
  "description": "Updated short description",
  "location": "us",
  "tags": [
    "env:prod",
    "mytest"
  ],
  "user_state": {
    "state": "live",
    "set_by": "user@in.ibm.com",
    "set_at": "2021-03-12T09:45:44.568286818Z"
  },
  "source": {
    "source_type": "",
    "git": {
      "git_repo_url": "https://github.com/Cloud-Schematics/repo_name"
    },
    "catalog": {},
    "external_scm": {},
    "cos_bucket": {}
  },
  "bastion": {
    "created_at": "0001-01-01T00:00:00Z",
    "updated_at": "0001-01-01T00:00:00Z",
    "sys_lock": {
      "sys_locked_at": "0001-01-01T00:00:00Z"
    }
  },
  "id": "Users action ID",
  "crn": "crn:v1:lalalal.ACTION.actionname.97888799a",
  "account": "69999991919199191f",
  "source_created_at": "0001-01-01T00:00:00Z",
  "source_updated_at": "0001-01-01T00:00:00Z",
  "created_at": "2021-03-12T09:45:44.571913075Z",
  "created_by": "user@in.ibm.com",
  "updated_at": "2021-03-12T09:52:48.649631464Z",
  "state": {
    "status_code": "pending",
    "status_job_id": "Users job ID",
    "status_message": "Action is in queue. Wait until the action completes update."
  },
  "playbook_names": [
    "xx.yml",
    "errxx.yml"
  ],
  "sys_lock": {
    "sys_locked_at": "0001-01-01T00:00:00Z"
  }
}

Upload a TAR file to an action

Update your template by uploading tape archive file (.tar) file from your local machine. Before you use this API, you must create an action without a link to a GitHub or GitLab repository with the POST /v2/actions API.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

PUT /v2/actions/{action_id}/template_repo_upload

Auditing

Calling this method generates the following auditing event.

  • schematics.action.update

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • action_id
    Required*
    string

    Action Id. Use GET /actions API to look up the Action Ids in your IBM Cloud account.

Form Parameters

  • file
    binary

    Template tar file

Response

Response Body

TemplateRepoTarUploadResponse

Response after uploading Template in tar file format

Status Code

  • 200

    Successfully received the Git repository as input TAR file for the template.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    Not found. The specified action could not be found. Verify that the action ID is correct. To list actions in your IBM Cloud account, use the GET /v2/actions API.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

List workspace jobs

Retrieve a list of all jobs that ran against a workspace. Jobs are generated when you use the apply, plan, destroy, and refresh, command API.

GET /v1/workspaces/{w_id}/actions

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

Query Parameters

  • offset
    integer

    The starting position of the item in the list of items. For example, if you have three workspaces in your account, the first workspace is assigned position number 0, the second workspace is assigned position number 1, and so forth. If you have 6 workspaces and you want to list the details for workspaces 2-6, enter 1. To limit the number of workspaces that is returned, use the limit option in addition to the offset option. Negative numbers are not supported and are ignored.

    Possible values: value ≥ 0

  • limit
    integer

    The maximum number of items that you want to list. The number must be a positive integer between 1 and 2000. If no value is provided, 100 is used by default.

    Possible values: 1 ≤ value ≤ 2000

    Default: 100

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/actions -H "Authorization: <iam_token>"
  • listWorkspaceActivitiesOptions := &schematicsv1.ListWorkspaceActivitiesOptions{
    WID: <workspace_id>,
}

listWorkspaceActivitiesResult, detailedResponse, err := schematicsService.ListWorkspaceActivities(listWorkspaceActivitiesOptions)

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(listWorkspaceActivitiesResult, "", "  ")
fmt.Println(string(w))
  • const params = {
  wId: '<workspace_id>',
};

schematicsService.listWorkspaceActivities(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • workspace_activities = schematics_service.list_workspace_activities(
    w_id='<workspace_id>'
).get_result()

print(json.dumps(workspace_activities, indent=2))
  • ListWorkspaceActivitiesOptions listWorkspaceActivitiesOptions = new ListWorkspaceActivitiesOptions.Builder()
.wId("<workspace_id>")
.build();

Response<WorkspaceActivities> response = service.listWorkspaceActivities(listWorkspaceActivitiesOptions).execute();
WorkspaceActivities workspaceActivities = response.getResult();

System.out.println(workspaceActivities);

Response

Response Body

WorkspaceActivities

List of workspace jobs

Status Code

  • 200

    Successfully retrieved list of workspace jobs.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "workspace_name": "myworkspace",
  "workspace_id": "myworkspace-123456",
  "actions": [
    {
      "action_id": "a11223334b11224345",
      "name": "PLAN",
      "status": "COMPLETED",
      "message": [],
      "performed_by": "user@us.ibm.com",
      "performed_at": "2019-08-21T14:07:25.814722573Z",
      "templates": [
        {
          "template_id": "a1234b-2124",
          "template_type": "terraform_v0.12",
          "start_time": "2019-08-21T14:07:26.120106199Z",
          "end_time": "2019-08-21T14:07:30.088495607Z",
          "status": "COMPLETED",
          "message": "{\"messagekey\":\"M2001_ActivitySuccessful\",\"parms\":{},\"requestid\":\"1234b1234b123-1234n13\",\"timestamp\":\"2019-08-21T14:07:30.088498532Z\"}",
          "log_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a1234b-2124/log_store/actions/11223334b11224345                "
        }
      ]
    }
  ]
}

Get workspace job details

Get the details for a workspace job that ran against the workspace. This API returns the job status and a URL to the log file that you can retrieve by using the GET /v1/workspaces/{id}/actions/{action_id}/logs API.

GET /v1/workspaces/{w_id}/actions/{activity_id}

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

  • activity_id
    Required*
    string

    The ID of the activity or job, for which you want to retrieve details. To find the job ID, use the GET /v1/workspaces/{id}/actions API.

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/actions/{action_id} -H "Authorization: <iam_token>"
  • activityResponse, detailedResponse, err := schematicsService.GetWorkspaceActivity(&schematicsv1.GetWorkspaceActivityOptions{
    WID:        <workspace_id>,
    ActivityID: <activity_id>,
})

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(activityResponse, "", "  ")
fmt.Println(string(w))
  • const params = {
  wId: '<workspace_id>',
  activityId: '<activity_id>',
};

schematicsService.getWorkspaceActivity(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • workspace_activity = schematics_service.get_workspace_activity(
    w_id='<workspace_id>',
    activity_id='<activity_id>'
).get_result()

print(json.dumps(workspace_activity, indent=2))
  • GetWorkspaceActivityOptions getWorkspaceActivityOptions = new GetWorkspaceActivityOptions.Builder()
.wId("<workspace_id>")
.activityId("<activity_id>")
.build();

Response<WorkspaceActivity> response = service.getWorkspaceActivity(getWorkspaceActivityOptions).execute();
WorkspaceActivity workspaceActivity = response.getResult();

System.out.println(workspaceActivity);

Response

Response Body

WorkspaceActivity

Information about the workspace jobs.

Status Code

  • 200

    Successfully retrieved the workspace jobs details.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    Not found. The requested workspace or job cannot be located. Check that you have the correct workspace ID and job IDs in your request.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "action_id": "a11223334b11224345",
  "name": "PLAN",
  "status": "COMPLETED",
  "message": [],
  "performed_by": "user@us.ibm.com",
  "performed_at": "2019-08-21T14:07:25.814722573Z",
  "templates": [
    {
      "template_id": "a1234b-2124",
      "template_type": "terraform_v0.12",
      "start_time": "2019-08-21T14:07:26.120106199Z",
      "end_time": "2019-08-21T14:07:30.088495607Z",
      "status": "COMPLETED",
      "message": "{\"messagekey\":\"M2001_ActivitySuccessful\",\"parms\":{},\"requestid\":\"1234b1234b123-1234n13\",\"timestamp\":\"2019-08-21T14:07:30.088498532Z\"}",
      "log_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a1234b-2124/log_store/actions/11223334b11224345                "
    }
  ]
}

Stop the workspace job

Stop an ongoing schematics job that runs against your workspace. Note: If you remove the Schematics apply job that runs against your workspace, any changes to your IBM Cloud resources that are already applied are not reverted. If a creation, update, or deletion is currently in progress, Schematics waits for the job to be completed first. Then, any other resource creations, updates, or deletions that are included in your Terraform template file are ignored.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

DELETE /v1/workspaces/{w_id}/actions/{activity_id}

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

  • activity_id
    Required*
    string

    The ID of the activity or job, for which you want to retrieve details. To find the job ID, use the GET /v1/workspaces/{id}/actions API.

  • curl -X DELETE https://schematics.cloud.ibm.com/v1/workspaces/{id}/actions/{action_id} -H "Authorization: <iam_token>"
  • curl -X DELETE  https://schematics.cloud.ibm.com//v1/workspaces/{workspace_id}/actions/{job_id}?signal=interrupt  -H "Authorization: <iam_token>"
  • curl -X DELETE  https://schematics.cloud.ibm.com//v1/workspaces/{workspace_id}/actions/{job_id}?signal=force-stop  -H "Authorization: <iam_token>"
  • curl -X DELETE  https://schematics.cloud.ibm.com//v1/workspaces/{workspace_id}/actions/{job_id}?signal=terminate -H "Authorization: <iam_token>"
  • _, detailedResponse, err := schematicsService.DeleteWorkspaceActivity(&schematicsv1.DeleteWorkspaceActivityOptions{
    WID:        <workspace_id>,
    ActivityID: <activity_id>,
})

if err != nil {
    panic(err)
}
  • const params = {
  wId: '<workspace_id>',
  activityId: '<activity_id>',
};

schematicsService.deleteWorkspaceActivity(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • workspace_activity_apply_result = schematics_service.delete_workspace_activity(
    w_id='<workspace_id>',
    activity_id='<activity_id>'
).get_result()

print(json.dumps(workspace_activity_apply_result, indent=2))
  • DeleteWorkspaceActivityOptions deleteWorkspaceActivityOptions = new DeleteWorkspaceActivityOptions.Builder()
.wId("<workspace_id>")
.activityId("<activity_id>")
.build();

Response<WorkspaceActivityApplyResult> response = service.deleteWorkspaceActivity(deleteWorkspaceActivityOptions).execute();
WorkspaceActivityApplyResult workspaceActivityApplyResult = response.getResult();

System.out.println(workspaceActivityApplyResult);

Response

Response Body

WorkspaceActivityApplyResult

Response after successfully initiating a request to apply the Terraform template in IBM Cloud.

Status Code

  • 202

    Successfully initiated the stopping of workspace job.

  • 400

    The specified action cannot be stopped because the job completed successfully or a user in the account already requested to stop this action. Use the GET /v1/workspace/{id}/actions API to find the details for your job.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    Not found. The requested workspace or job cannot be located. Check that you have the correct workspace ID and job IDs in your request.

  • 409

    The specified resource is marked as frozen. Unfreeze the resource before you retry the request.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "requestid": "cf844c29-dc3e-4c34-af5e-c23d6a306c29",
  "timestamp": "2022-06-13T09:26:48.245448907Z",
  "messageid": "M1058",
  "message": "Cannot stop an activity that is already completed. Please check the activity details",
  "statuscode": 400
}

Run Terraform Commands

Run Terraform state commands to modify the workspace state file, by using the IBM Cloud Schematics API.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

PUT /v1/workspaces/{w_id}/commands

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • refresh_token
    Required*
    string

    The IAM refresh token for the user or service identity.

    Retrieving refresh token:

    • Use export IBMCLOUD_API_KEY=<ibmcloud_api_key>, and execute curl -X POST "https://iam.cloud.ibm.com/identity/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$IBMCLOUD_API_KEY" -u bx:bx.
    • For more information, about creating IAM access token and API Docs, refer, IAM access token and Create API key.

    Limitation:

    • If the token is expired, you can use refresh token to get a new IAM access token.
    • The refresh_token parameter cannot be used to retrieve a new IAM access token.
    • When the IAM access token is about to expire, use the API key to create a new access token.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

Request Body

Required*
TerraformCommands

command value

  • curl --location --request PUT 'https://schematics.cloud.ibm.com/v1/workspaces/<workspace_id>/commands' --header "refresh_token: <refresh_token>' --header 'Authorization: <iam_token>' --header 'Content-Type: application/json' --data-raw '{"commands": [{"command": "state show","command_params": "data.template_file.test","command_name": "Test1","command_desc": "Showing state","command_onerror": "continue"},{"command": "taint","command_params": "null_resource.sleep","command_name": "Test2", "command_desc": "Marking taint","command_onerror": "continue"},], "operation_name": "Workspace Command","description": "Executing command"}'
  • terraformCommandModel := &schematicsv1.TerraformCommand{
Command: core.StringPtr("<command_to_be_executed>"),
CommandParams: core.StringPtr("<command_parameters>"),
CommandName: core.StringPtr("<command_name>"),
CommandDesc: core.StringPtr("<command_description>"),
}

runWorkspaceCommandsOptions := schematicsService.NewRunWorkspaceCommandsOptions(
WID: core.StringPtr("<workspace_id>"),
RefreshToken: core.StringPtr("<refresh_token>"),
Commands: []schematicsv1.TerraformCommand{*terraformCommandModel},
OperationName: core.StringPtr("<operation_name>"),
Description: core.StringPtr("<operation_description>"),
)

workspaceActivityCommandResult, response, err := schematicsService.RunWorkspaceCommands(runWorkspaceCommandsOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(workspaceActivityCommandResult, "", ""),
fmt.Println(string(b))
  • const terraformCommandModel = {
  command: '<command_to_be_executed>',
  command_params: '<command_parameters>',
  command_name: '<command_name>',
  command_desc: '<command_description>',
};

const params = {
  wId: '<workspace_id>,'
  refreshToken: '<refresh_token>',
  commands: [terraformCommandModel],
  operationName: '<operation_name>',
  description: '<operation_description>',
};

schematicsService.runWorkspaceCommands(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • terraform_command_model = {
  'command': '<command_to_be_executed>',
  'command_params': '<command_parameters>',
  'command_name': '<command_name>',
  'command_desc': '<command_description>',
}

workspace_activity_command_result = schematics_service.run_workspace_commands(
w_id='<workspace_id>',
refresh_token='<refresh_token>',
commands=[terraform_command_model],
operation_name='<operation_name>',
description='<operation_description>'
).get_result()
print(json.dumps(workspace_activity_command_result, indent=2)),
  • TerraformCommand terraformCommandModel = new TerraformCommand.Builder()
.command("<command_to_be_executed>")
.commandParams("<command_parameters>")
.commandName("<command_name>")
.commandDesc("<command_description>")
.build();
RunWorkspaceCommandsOptions runWorkspaceCommandsOptions = new RunWorkspaceCommandsOptions.Builder()
.wId("<workspace_id>")
.refreshToken("<refresh_token>")
.commands(new java.util.ArrayList<TerraformCommand>(java.util.Arrays.asList(terraformCommandModel)))
.operationName("<operation_name>")
.description("<operation_description>")
.build();
Response<WorkspaceActivityCommandResult> response = service.runWorkspaceCommands(runWorkspaceCommandsOptions).execute();
WorkspaceActivityCommandResult workspaceActivityCommandResult = response.getResult();
System.out.println(workspaceActivityCommandResult);
Node.JS
const terraformCommandModel = {
command: '<command_to_be_executed>',
command_params: '<command_parameters>',
command_name: '<command_name>',
command_desc: '<command_description>',
};
const params = {
wId: '<workspace_id>',
refreshToken: '<refresh_token>',
commands: [terraformCommandModel],
operationName: '<operation_name>',
description: '<operation_description>',
};
schematicsService.runWorkspaceCommands(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});

Response

Response Body

WorkspaceActivityCommandResult

Response after successfully initiating a request to run a workspace command on the stack of resources provisioned using Terraform.

Status Code

  • 200

    Successfully updated the workspace metadata.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    Not found. The specified workspace could not be found. Verify that the workspace ID is correct. To list workspaces in your IBM Cloud account, use the GET /v1/workspaces API.

  • 409

    Workspace Command failed. The workspace is marked as frozen. Unfreeze the workspace before you retry the request.

  • 429

    Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

  • 503

    IBM Cloud Schematics could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "activityid": "223423423adfadf123456"
}

Perform a Schematics `apply` job

Run a Schematics apply job against your workspace. An apply job provisions, modifies, or removes the IBM Cloud resources that you described in the Terraform template that your workspace points to. Depending on the type and number of resources that you want to provision or modify, this process might take a few minutes, or even up to hours to complete. During this time, you cannot make changes to your workspace. After all updates are applied, the state of the files is persisted to determine what resources exist in your IBM Cloud account.

Important: Your workspace must be in an Inactive, Active, Failed, or Stopped state to perform a Schematics apply job. After all updates are applied, the state of the files is persisted to determine what resources exist in your IBM Cloud account.

Note: This API returns an activity or job ID that you use to retrieve the log URL with the GET /v1/workspaces/{id}/actions/{action_id}/logs API.

Important: Applying a template might incur costs. Make sure to review the pricing information for the resources that you specified in your templates before you apply the template in IBM Cloud. To find a summary of job that Schematics is about to perform, create a Terraform execution plan with the POST /v1/workspaces/{id}/plan API.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

PUT /v1/workspaces/{w_id}/apply

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace-resources.create

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • refresh_token
    Required*
    string

    The IAM refresh token for the user or service identity.

    Retrieving refresh token:

    • Use export IBMCLOUD_API_KEY=<ibmcloud_api_key>, and execute curl -X POST "https://iam.cloud.ibm.com/identity/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$IBMCLOUD_API_KEY" -u bx:bx.
    • For more information, about creating IAM access token and API Docs, refer, IAM access token and Create API key.

    Limitation:

    • If the token is expired, you can use refresh token to get a new IAM access token.
    • The refresh_token parameter cannot be used to retrieve a new IAM access token.
    • When the IAM access token is about to expire, use the API key to create a new access token.
  • delegated_token
    string

    The IAM delegated token for your IBM Cloud account. This token is required for requests that are sent via the UI only.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace for which you want to run a Schematics apply job. To find the workspace ID, use the GET /workspaces API.

Request Body

Required*
WorkspaceActivityOptions

Workspace 'apply' job options

  • curl -X PUT https://schematics.cloud.ibm.com/v1/workspaces/{id}/apply -H "Authorization: Bearer <iam_token>" -H "refresh_token: <refresh_token>"
  • curl -X GET <log_url> -H "Authorization: Bearer <iam_token>"
  • applyWorkspaceCommandOptions := &schematicsv1.ApplyWorkspaceCommandOptions{
    WID:          <workspace_id>,
    RefreshToken: core.StringPtr("refresh_token"),
}

applyResult, detailedResponse, err := schematicsService.ApplyWorkspaceCommand(applyWorkspaceCommandOptions)

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(applyResult, "", "  ")
fmt.Println(string(w))
  • const params = {
  wId: '<workspace_id>',
  refreshToken: '<refresh_token>'',
};

schematicsService.applyWorkspaceCommand(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
      console.warn(err)
  });
  • workspace_activity_apply_result = schematics_service.apply_workspace_command(
    w_id='<workspace_id>',
    refresh_token='<refresh_token>'
).get_result()

print(json.dumps(workspace_activity_apply_result, indent=2))
  • ApplyWorkspaceCommandOptions applyWorkspaceCommandOptions = new ApplyWorkspaceCommandOptions.Builder()
.wId("<workspace_id>")
.refreshToken("<refresh_token>")
.build();

Response<WorkspaceActivityApplyResult> response = service.applyWorkspaceCommand(applyWorkspaceCommandOptions).execute();
WorkspaceActivityApplyResult workspaceActivityApplyResult = response.getResult();

Response

Response Body

WorkspaceActivityApplyResult

Response after successfully initiating a request to apply the Terraform template in IBM Cloud.

Status Code

  • 202

    Successfully ran a Schematics apply job against your workspace.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    Not found. The specified workspace could not be found. Verify that the workspace ID is correct. To list workspaces in your IBM Cloud account, use the GET /v1/workspaces API.

  • 409

    Apply failed. Could not perform an apply job against the workspace. The workspace is frozen, or a Schematics create, update, plan, apply, destroy, delete, or refresh job has not completed yet. Unfreeze the workspace first or wait until the create, update, plan, apply, destroy, delete, or refresh job completes before you try again.

  • 429

    Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

  • 503

    IBM Cloud Schematics could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "activityid": "ec72d9e655e846bcbfbb840be49ef7bd"
}

Perform a Schematics `destroy` job

Run a Schematics destroy job against your workspace. A destroy job removes all IBM Cloud resources that are associated with your workspace. Removing your resources does not delete the Schematics workspace. To delete the workspace, use the DELETE /v1/workspaces/{id} API. This API returns an activity or job ID that you use to retrieve the URL to the log file with the GET /v1/workspaces/{id}/actions/{action_id}/logs API.

Important: Your workspace must be in an Active, Failed, or Stopped state to perform a Schematics destroy job.

Note: Deleting IBM Cloud resources cannot be undone. Make sure that you back up any required data before you remove your resources.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

PUT /v1/workspaces/{w_id}/destroy

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace-resources.delete

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • refresh_token
    Required*
    string

    The IAM refresh token for the user or service identity.

    Retrieving refresh token:

    • Use export IBMCLOUD_API_KEY=<ibmcloud_api_key>, and execute curl -X POST "https://iam.cloud.ibm.com/identity/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$IBMCLOUD_API_KEY" -u bx:bx.
    • For more information, about creating IAM access token and API Docs, refer, IAM access token and Create API key.

    Limitation:

    • If the token is expired, you can use refresh token to get a new IAM access token.
    • The refresh_token parameter cannot be used to retrieve a new IAM access token.
    • When the IAM access token is about to expire, use the API key to create a new access token.
  • delegated_token
    string

    The IAM delegated token for your IBM Cloud account. This token is required for requests that are sent via the UI only.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace for which you want to perform a Schematics destroy job. To find the workspace ID, use the GET /workspaces API.

Request Body

Required*
WorkspaceActivityOptions

Workspace destroy command options

  • curl -X PUT https://schematics.cloud.ibm.com/v1/workspaces/{id}/destroy -H "Authorization: Bearer <iam_token>" -H "refresh_token: <refresh_token>"
  • curl -X GET <log_url> -H "Authorization: Bearer <iam_token>"
  • destroyWorkspaceCommandOptions := &schematicsv1.DestroyWorkspaceCommandOptions{
    WID:          <workspace_id>,
    RefreshToken: core.StringPtr("refresh_token"),
}

destroyResult, detailedResponse, err := schematicsService.DestroyWorkspaceCommand(destroyWorkspaceCommandOptions)

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(destroyResult, "", "  ")
fmt.Println(string(w))
  • const params = {
  wId: '<workspace_id>',
  refreshToken: '<refresh_token>',
};

schematicsService.destroyWorkspaceCommand(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • workspace_activity_destroy_result = schematics_service.destroy_workspace_command(
    w_id='<workspace_id>',
    refresh_token='<refresh_token>'
).get_result()

print(json.dumps(workspace_activity_destroy_result, indent=2))
  • DestroyWorkspaceCommandOptions destroyWorkspaceCommandOptions = new DestroyWorkspaceCommandOptions.Builder()
.wId("<workspace_id>")
.refreshToken("<refresh_token>")
.build();

Response<WorkspaceActivityDestroyResult> response = service.destroyWorkspaceCommand(destroyWorkspaceCommandOptions).execute();
WorkspaceActivityDestroyResult workspaceActivityDestroyResult = response.getResult();

System.out.println(workspaceActivityDestroyResult);

Response

Response Body

WorkspaceActivityDestroyResult

Response after successfully initiating a request to destroy the stack of resources provisioned using Terraform.

Status Code

  • 202

    Successfully initiated a Schematics destroy job against your workspace.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    Not found. The requested workspace cannot be located. Check that you have the correct workspace ID in your request. Or the requested state-file cannot be located. Run apply action to create a state-file.

  • 409

    Could not perform a destroy job against the workspace. The workspace is frozen, or a Schematics create, update, plan, apply, delete, destroy, or refresh job has not completed yet. Unfreeze the workspace first or wait until the create, update, plan, apply, delete, destroy, or refresh job completes before you try again.

  • 429

    Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

  • 503

    IBM Cloud Schematics could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "activityid": "12a111a1aa1111aaaaa123a11112222a11ß"
}

Perform a Schematics `plan` job

Run a Schematics plan job against your workspace. The plan job creates a summary of IBM Cloud resources that must be created, modified, or deleted to achieve the state that is described in the Terraform or IBM Cloud catalog template that your workspace points to. During this time, you cannot make changes to your workspace. You can use the summary to verify your changes before you apply the template in IBM Cloud.

Important: Your workspace must be in an Inactive, Active, Failed, or Stopped state to perform a Schematics plan job.

Note: This API returns an activity or job ID that you use to retrieve the URL to the log file with the GET /v1/workspaces/{id}/actions/{action_id}/logs API.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

POST /v1/workspaces/{w_id}/plan

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace-resources.plan

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • refresh_token
    Required*
    string

    The IAM refresh token for the user or service identity.

    Retrieving refresh token:

    • Use export IBMCLOUD_API_KEY=<ibmcloud_api_key>, and execute curl -X POST "https://iam.cloud.ibm.com/identity/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$IBMCLOUD_API_KEY" -u bx:bx.
    • For more information, about creating IAM access token and API Docs, refer, IAM access token and Create API key.

    Limitation:

    • If the token is expired, you can use refresh token to get a new IAM access token.
    • The refresh_token parameter cannot be used to retrieve a new IAM access token.
    • When the IAM access token is about to expire, use the API key to create a new access token.
  • delegated_token
    string

    The IAM delegated token for your IBM Cloud account. This token is required for requests that are sent via the UI only.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace, for which you want to run a Schematics plan job. To find the ID of your workspace, use the GET /v1/workspaces API.

Request Body

Required*
WorkspaceActivityOptions

Workspace 'plan' job options

  • curl -X POST https://schematics.cloud.ibm.com/v1/workspaces/{id}/plan -H "Authorization: Bearer <iam_token>" -H "refresh_token: <refresh_token>"
  • curl -X GET <log_url> -H "Authorization: Bearer <iam_token>"
  • planWorkspaceCommandOptions := &schematicsv1.PlanWorkspaceCommandOptions{
    WID:          <workspace_id>,
    RefreshToken: core.StringPtr("refresh_token"),
}

planResult, detailedResponse, err := schematicsService.PlanWorkspaceCommand(planWorkspaceCommandOptions)

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(planResult, "", "  ")
fmt.Println(string(w))
  • const params = {
  wId: '<workspace_id>',
  refreshToken: '<refresh_token>',
};

schematicsService.planWorkspaceCommand(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • workspace_activity_plan_result = schematics_service.plan_workspace_command(
    w_id='<workspace_id>',
    refresh_token='<refresh_token>'
).get_result()

print(json.dumps(workspace_activity_plan_result, indent=2))
  • PlanWorkspaceCommandOptions planWorkspaceCommandOptions = new PlanWorkspaceCommandOptions.Builder()
.wId("<workspace_id>")
.refreshToken("<refresh_token>")
.build();

Response<WorkspaceActivityPlanResult> response = service.planWorkspaceCommand(planWorkspaceCommandOptions).execute();
WorkspaceActivityPlanResult workspaceActivityPlanResult = response.getResult();

System.out.println(workspaceActivityPlanResult);

Response

Response Body

WorkspaceActivityPlanResult

Response after successfully initiating a request to plan the Terraform template in IBM Cloud.

Status Code

  • 202

    Successfully performed a Schematics plan job.

  • 400

    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    Not found. The specified workspace could not be found. Verify that the workspace ID is correct. To list workspaces in your IBM Cloud account, use the GET /v1/workspaces API.

  • 409

    The workspace is frozen and disabled. Unfreeze the workspace first before you retry the request. Or the Schematics create, update, delete action has not completed. Wait until the create, update, delete, plan, apply, destroy or refresh action completes before you try again.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

  • 503

    IBM Cloud Schematics could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "activityid": "f4091a17707d0433a3f9307e8bcbc853"
}

Perform a Schematics `refresh` job

Run a Schematics refresh job against your workspace. A refresh job validates the IBM Cloud resources in your account against the state that is stored in the Terraform statefile of your workspace. If differences are found, the Terraform statefile is updated accordingly. This API returns an activity or job ID that you use to retrieve the URL to the log file with the GET /v1/workspaces/{id}/actions/{action_id}/logs API.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

PUT /v1/workspaces/{w_id}/refresh

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.refresh

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • refresh_token
    Required*
    string

    The IAM refresh token for the user or service identity.

    Retrieving refresh token:

    • Use export IBMCLOUD_API_KEY=<ibmcloud_api_key>, and execute curl -X POST "https://iam.cloud.ibm.com/identity/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$IBMCLOUD_API_KEY" -u bx:bx.
    • For more information, about creating IAM access token and API Docs, refer, IAM access token and Create API key.

    Limitation:

    • If the token is expired, you can use refresh token to get a new IAM access token.
    • The refresh_token parameter cannot be used to retrieve a new IAM access token.
    • When the IAM access token is about to expire, use the API key to create a new access token.
  • delegated_token
    string

    The IAM delegated token for your IBM Cloud account. This token is required for requests that are sent via the UI only.

Path Parameters

  • w_id
    Required*
    string

    The ID of the workspace, for which you want to run a Schematics refresh job. To find the ID of your workspace, use the GET /v1/workspaces API.

  • curl -X PUT https://schematics.cloud.ibm.com/v1/workspaces/{id}/refresh -H "Authorization: Bearer <iam_token>" -H "refresh_token: <refresh_token>"
  • curl -X GET <log_url> -H "Authorization: Bearer <iam_token>"
  • refreshWorkspaceCommandOptions := &schematicsv1.RefreshWorkspaceCommandOptions{
    WID:          <workspace_id>,
    RefreshToken: core.StringPtr("refresh_token"),
}

refreshResult, detailedResponse, err := schematicsService.RefreshWorkspaceCommand(refreshWorkspaceCommandOptions)

if err != nil {
    panic(err)
}

w, err := json.MarshalIndent(refreshResult, "", "  ")
fmt.Println(string(w))
  • const params = {
  wId: '<workspace_id>',
  refreshToken: '<refresh_token>',
};

schematicsService.refreshWorkspaceCommand(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • workspace_activity_refresh_result = schematics_service.refresh_workspace_command(
    w_id='<workspace_id>',
    refresh_token='<refresh_token>'
).get_result()

print(json.dumps(workspace_activity_refresh_result, indent=2))
  • RefreshWorkspaceCommandOptions refreshWorkspaceCommandOptions = new RefreshWorkspaceCommandOptions.Builder()
.wId("<workspace_id>")
.refreshToken("<refresh_token>")
.build();

Response<WorkspaceActivityRefreshResult> response = service.refreshWorkspaceCommand(refreshWorkspaceCommandOptions).execute();
WorkspaceActivityRefreshResult workspaceActivityRefreshResult = response.getResult();

System.out.println(workspaceActivityRefreshResult);

Response

Response Body

WorkspaceActivityRefreshResult

Response after successfully initiating a request to refresh the Terraform template in IBM Cloud.

Status Code

  • 202

    Successfully initiated a Schematics refresh job against your workspace.

  • 400

    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    Not found. The specified workspace could not be found. Verify that the workspace ID is correct. To list workspaces in your IBM Cloud account, use the GET /v1/workspaces API.

  • 409

    Could not perform a refresh job against the workspace. The workspace is frozen, or a Schematics create, update, plan, apply, delete, destroy, or refresh job has not completed yet. Unfreeze the workspace first or wait until the create, update, plan, apply, delete, destroy, or refresh job completes before you try again.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "activityid": "12a111a1aa1111aaaaa123a11112222a11"
}

List jobs

Retrieve a list of all Schematics jobs. The job displays a list of jobs with the status as pending, in_progess, success, or failed. Jobs are generated when you use the POST /v2/jobs, PUT /v2/jobs/{job_id}, or DELETE /v2/jobs/{job_id}.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v2/jobs

Auditing

Calling this method generates the following auditing event.

  • schematics.job.list

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Query Parameters

  • offset
    integer

    The starting position of the item in the list of items. For example, if you have three workspaces in your account, the first workspace is assigned position number 0, the second workspace is assigned position number 1, and so forth. If you have 6 workspaces and you want to list the details for workspaces 2-6, enter 1. To limit the number of workspaces that is returned, use the limit option in addition to the offset option. Negative numbers are not supported and are ignored.

    Possible values: value ≥ 0

  • limit
    integer

    The maximum number of items that you want to list. The number must be a positive integer between 1 and 2000. If no value is provided, 100 is used by default.

    Possible values: 1 ≤ value ≤ 2000

    Default: 100

  • sort
    string

    Name of the field to sort-by; Use the '.' character to delineate sub-resources and sub-fields (eg. owner.last_name). Prepend the field with '+' or '-', indicating 'ascending' or 'descending' (default is ascending) Ignore unrecognized or unsupported sort field

  • profile
    string

    Level of details returned by the get method

    Allowable values: [ids,summary]

  • resource
    string

    Name of the resource (workspaces, actions, environment or controls)

    Allowable values: [workspaces,action,actions,environment]

  • resource_id
    string

    The Resource Id. It could be an Action-id or Workspace-id.

  • action_id
    string

    Action Id

  • workspace_id
    string

    Workspace Id

  • list
    string

    list jobs

    Allowable values: [all]

  • curl --location --request GET https://schematics.cloud.ibm.com/v2/jobs?resource=actions&action_id=us-east.ACTION.Example-12a1b212.3287dc42  --header "Authorization: <access_token> " --header "Cookie: "
  • GetJobOptions getJobOptions = new GetJobOptions.Builder()
.jobId("job ID")
.build();

Response<Job> response = service.getJob(getJobOptions).execute();
Job job = response.getResult();

System.out.println(job);
  • job_list = schematics_service.list_jobs().get_result()
print(json.dumps(job_list, indent=2))
  • const params = {
resource:"resource group name",
actionId: "Users action ID"
};

schematicsService.listJobs(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});
  • listJobsOptions := schematicsService.NewListJobsOptions()
listJobsOptions.SetResource("set the action details")
listJobsOptions.SetActionID("set the action ID")
listJobsOptions.SetList("all")
jobList, response, err := schematicsService.ListJobs(listJobsOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(jobList, "", "/v2/jobs/")
fmt.Println(string(b))

Response

Response Body

JobList

List of Job details

Status Code

  • 200

    Successfully listed the jobs that you have access to.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "total_count": 2,
  "limit": 100,
  "offset": 0,
  "jobs": [
    {
      "id": "Users job ID",
      "name": "Users job name",
      "description": "Short description",
      "command_object": "Users resource action, for example, **action**",
      "command_object_id": "Users object ID",
      "command_name": "Users job command name, for example, **ansible_playbook_check**",
      "location": "Users location",
      "resource_group": "Users resource group name",
      "submitted_at": "2021-02-10T11:33:23.37852757Z",
      "duration": "57.243452S",
      "start_at": "2021-02-10T11:33:29.708025157Z",
      "end_at": "2021-02-10T11:34:26.951477114Z",
      "status": {
        "workspace_job_status": {
          "flow_status": {
            "updated_at": "0001-01-01T00:00:00Z"
          },
          "updated_at": "0001-01-01T00:00:00Z"
        },
        "action_job_status": {
          "action_name": "Users action name, for example, **00aaaa2222**",
          "status_code": "Job status ocde",
          "status_message": "Job status message",
          "updated_at": "0001-01-01T00:00:00Z"
        }
      },
      "log_summary": {
        "log_start_at": "0001-01-01T00:00:00Z",
        "log_analyzed_till": "0001-01-01T00:00:00Z",
        "repo_download_job": {},
        "workspace_job": {},
        "flow_job": {},
        "action_job": {
          "task_count": 3,
          "play_count": 1,
          "recap": {
            "unreachable": 1
          }
        }
      },
      "updated_at": "0001-01-01T00:00:00Z"
    }
  ]
}

Create a job

Create & launch the Schematics job. It can be used to launch an Ansible playbook against a target hosts. The job displays a list of jobs with the status as pending, in_progess, success, or failed.

POST /v2/jobs

Auditing

Calling this method generates the following auditing event.

  • schematics.job.create

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • refresh_token
    Required*
    string

    The IAM refresh token for the user or service identity.

    Retrieving refresh token:

    • Use export IBMCLOUD_API_KEY=<ibmcloud_api_key>, and execute curl -X POST "https://iam.cloud.ibm.com/identity/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$IBMCLOUD_API_KEY" -u bx:bx.
    • For more information, about creating IAM access token and API Docs, refer, IAM access token and Create API key.

    Limitation:

    • If the token is expired, you can use refresh token to get a new IAM access token.
    • The refresh_token parameter cannot be used to retrieve a new IAM access token.
    • When the IAM access token is about to expire, use the API key to create a new access token.

Request Body

Required*
Job

Create a Job Record and launch the Job

  • curl --location --request POST https://schematics.cloud.ibm.com/v2/jobs --header "Authorization: <access_token> "--header "Content-Type: application/json"--data-raw "{"command_object": "action","command_object_id": "us-east","command_name": "ansible_playbook_check","command_parameter": "site.yml"}"
  • CreateJobOptions createJobOptions = new CreateJobOptions.Builder()
.refreshToken("testString")
.commandObject("action")
.commandObjectId("set your action ID.")
.commandName("set command name")
.commandParameter("aj.yml")
.build();
Response<Job> response = service.createJob(createJobOptions).execute();
Job job = response.getResult();
System.out.println(job);
  • job = schematics_service.create_job().get_result()
object="action",
object_id="Users action ID",
name="ansible_playbook_run", parameter="test.yml"
).get_result()
print(json.dumps(job, indent=2))
  • const params = {"refreshToken":"testString",
"commandObject":"set your command object, [workspace or action]",
"commandObjectId":"set your action ID",
"commandName":"set your command, [ansible_playbook_run or ansible_playbook_check]",
"commandParameter":"set playbook name with the extension, [test.yml]"
};
schematicsService.createJob(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});
  • CreateJobOptions := schematicsService.NewCreateJobOptions("set your job options",)

CreateJobOptions.SetCommandObject("set your command object, [workspace or action]")
CreateJobOptions.SetCommandObjectID("set your action ID")
CreateJobOptions.SetCommandName("set your command name")
CreateJobOptions.SetCommandParameter("set your yml file as command parameter")

job, response, err := schematicsService.CreateJob(CreateJobOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(job, "", "/v2/jobs")
fmt.Println(string(b))

Response

Response Body

Job

Complete Job with user inputs and system generated data

Status Code

  • 201

    Successfully created the job in IBM Cloud Schematics.

  • 400

    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    The specified resource was not found

  • 409

    The specified resource already exists

  • 429

    Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

  • 503

    IBM Cloud Schematics could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "command_object": "Users resource action, for example, **action**",
  "command_object_id": "Users job ID",
  "command_name": "Users job command name, for example, **ansible_playbook_check**",
  "command_parameter": "Users playbook name",
  "id": "Users job ID",
  "name": "Users job name",
  "description": "This Action Run Lamp on multiple host xxxx",
  "location": "Users location",
  "resource_group": "Users resource group name",
  "submitted_at": "2021-02-09T05:38:52.933700022Z",
  "submitted_by": "schematics@ibm.com",
  "start_at": "2021-02-09T05:38:52.933698161Z",
  "end_at": "0001-01-01T00:00:00Z",
  "status": {
    "workspace_job_status": {
      "flow_status": {
        "updated_at": "0001-01-01T00:00:00Z"
      },
      "updated_at": "0001-01-01T00:00:00Z"
    },
    "action_job_status": {
      "action_name": "Example-12ab2",
      "status_code": "job_pending",
      "status_message": "Job created and pending to start",
      "updated_at": "2021-02-09T05:38:52.933701533Z"
    }
  },
  "data": {
    "job_type": "",
    "workspace_job_data": {
      "updated_at": "0001-01-01T00:00:00Z"
    },
    "action_job_data": {
      "inputs": [
        {
          "name": "upassword",
          "value": "Abc@123xxx",
          "metadata": {
            "type": "string",
            "default_value": "Abc@123xxx",
            "secure": true
          }
        },
        {
          "name": "dbname",
          "value": "Users DB name",
          "metadata": {
            "type": "string",
            "default_value": "xxxx"
          }
        },
        {
          "name": "dbuser",
          "value": "Users DB user value",
          "metadata": {
            "type": "string",
            "default_value": "root"
          }
        },
        {
          "name": "mysql_port",
          "value": "Users MySQL port number",
          "metadata": {
            "type": "string",
            "default_value": "3306"
          }
        },
        {
          "name": "httpd_port",
          "value": "Users HTTP port number",
          "metadata": {
            "type": "string",
            "default_value": "80"
          }
        }
      ],
      "updated_at": "0001-01-01T00:00:00Z"
    }
  },
  "bastion": {
    "name": "bastionhost",
    "type": "string",
    "description": "string",
    "resource_query": "100.100.100.100",
    "credential_ref": "ssh_key",
    "created_at": "0001-01-01T00:00:00Z",
    "updated_at": "0001-01-01T00:00:00Z",
    "sys_lock": {
      "sys_locked_at": "0001-01-01T00:00:00Z"
    }
  },
  "log_summary": {
    "log_start_at": "0001-01-01T00:00:00Z",
    "log_analyzed_till": "0001-01-01T00:00:00Z",
    "repo_download_job": {},
    "workspace_job": {},
    "flow_job": {},
    "action_job": {
      "recap": {}
    }
  },
  "updated_at": "0001-01-01T00:00:00Z"
}

Get a job

Retrieve the detailed information of Job

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v2/jobs/{job_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.job.read

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • job_id
    Required*
    string

    Job Id. Use GET /v2/jobs API to look up the Job Ids in your IBM Cloud account.

Query Parameters

  • profile
    string

    Level of details returned by the get method

    Allowable values: [summary,detailed,ids]

  • curl --location --request GET https://schematics.cloud.ibm.com/v2/jobs/jobid --header "Authorization:  <access_token> "
  • GetJobOptions getJobOptions = new GetJobOptions.Builder()
.jobId("set your job ID")
.build();

Response<Job> response = service.getJob(getJobOptions).execute();
Job job = response.getResult();

System.out.println(job);
  • job = schematics_service.get_job(job_id="us.JOB.keratinsample.08e45f87").get_result()
print (json.dumps(job, indent=2))
  • const params = {jobId: "Users job ID"};

schematicsService.getJob(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});
  • getJobOptions := schematicsService.NewGetJobOptions("set job options",)
getJobOptions.SetJobID("set your job ID")

job, response, err := schematicsService.GetJob(getJobOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(job, "", "")
fmt.Println(string(b))

Response

Response Body

Job

Complete Job with user inputs and system generated data

Status Code

  • 200

    Successfully retrieved details about your job record.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    The specified resource was not found

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "id": "Users job ID",
  "name": "Users Job name",
  "description": "Short description",
  "command_object": "Users resource action, for example, **action**",
  "command_object_id": "Users object ID",
  "command_name": "Users job command name, for example, **ansible_playbook_check**",
  "location": "Users location",
  "resource_group": "Users resource group",
  "submitted_at": "2021-02-09T05:38:52.933700022Z",
  "submitted_by": "users@test.com",
  "duration": "45.702379S",
  "start_at": "2021-02-09T05:38:58.338739558Z",
  "end_at": "2021-02-09T05:39:44.041118719Z",
  "status": {
    "workspace_job_status": {
      "flow_status": {
        "updated_at": "0001-01-01T00:00:00Z"
      },
      "updated_at": "0001-01-01T00:00:00Z"
    },
    "action_job_status": {
      "action_name": "Users action name",
      "status_code": "Users job status code",
      "status_message": "Users job execution status",
      "updated_at": "0001-01-01T00:00:00Z"
    }
  },
  "log_summary": {
    "log_start_at": "0001-01-01T00:00:00Z",
    "log_analyzed_till": "0001-01-01T00:00:00Z",
    "repo_download_job": {},
    "workspace_job": {},
    "flow_job": {},
    "action_job": {
      "task_count": 6,
      "play_count": 1,
      "recap": {
        "ok": 4,
        "failed": 1,
        "skipped": 1
      }
    }
  },
  "updated_at": "0001-01-01T00:00:00Z"
}

Update a job

Creates a copy of the Schematics job and relaunches an existing job by updating the information of an existing Schematics job.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

PUT /v2/jobs/{job_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.job.update

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • refresh_token
    Required*
    string

    The IAM refresh token for the user or service identity.

    Retrieving refresh token:

    • Use export IBMCLOUD_API_KEY=<ibmcloud_api_key>, and execute curl -X POST "https://iam.cloud.ibm.com/identity/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$IBMCLOUD_API_KEY" -u bx:bx.
    • For more information, about creating IAM access token and API Docs, refer, IAM access token and Create API key.

    Limitation:

    • If the token is expired, you can use refresh token to get a new IAM access token.
    • The refresh_token parameter cannot be used to retrieve a new IAM access token.
    • When the IAM access token is about to expire, use the API key to create a new access token.

Path Parameters

  • job_id
    Required*
    string

    Job Id. Use GET /v2/jobs API to look up the Job Ids in your IBM Cloud account.

Request Body

Required*
Job

Clone the Job-record, and relaunch the Job

  • curl --location --request PUT https://schematics.cloud.ibm.com/v2/jobs/us-east.JOB.Example-12a1b212.6f314758 --header "Authorization: <access_token> "--header "Content-Type: application/json "--header "Cookie: "--data-raw "{ "command_object": "action",  "command_object_id": "us-east.ACTION.Example-12a1b212.3287dc42",  "command_name": "ansible_playbook_run",  "command_parameter": "site.yml"}"
  • ReplaceJobOptions replaceJobOptions = new ReplaceJobOptions.Builder()
.refreshToken("testString")
.jobId("set your job ID")
.build();

Response<Job> response = service.replaceJob(replaceJobOptions).execute();
Job job = response.getResult();

System.out.println(job);
  • job = schematics_service.replace_job(refresh_token='testString',
job_id="set your job ID"
).get_result()
print (json.dumps(job, indent=2))
  • const params = {
refreshToken: 'testString',
jobId: "Users job ID",
description: "Very Huge short description",
};

schematicsService.replaceJob(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});
  • UpdatejobOptions := schematicsService.NewReplaceJobOptions("teststring","teststring",)
UpdatejobOptions.SetJobID("set the job ID")
UpdatejobOptions.SetCommandObject("set your command object, [workspace or action] ")
UpdatejobOptions.SetCommandObjectID("set your action ID")
UpdatejobOptions.SetCommandName("set the command name")
UpdatejobOptions.SetCommandParameter("set your yaml file for the command parameter")

job, response, err := schematicsService.ReplaceJob(UpdatejobOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(job, "", "")
fmt.Println(string(b))

Response

Response Body

Job

Complete Job with user inputs and system generated data

Status Code

  • 200

    Successfully relaunched the Job, returns a new Job Record

  • 400

    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    The specified resource was not found

  • 409

    The specified resource is locked, cannot be updated or deleted

  • 429

    Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

  • 503

    IBM Cloud Schematics could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

Example responses
  • {
  "command_object": "Users resource action, for example, **action**",
  "command_object_id": "Users object ID",
  "command_name": "Users job command name, for example, **ansible_playbook_check**",
  "command_parameter": "Users playbook name",
  "id": "Users job ID",
  "name": "Users job name",
  "description": "Short description for the update",
  "location": "Users location",
  "resource_group": "Users resource group name",
  "submitted_at": "2021-02-10T11:33:23.37852757Z",
  "start_at": "2021-02-10T11:33:23.378525569Z",
  "end_at": "2021-02-09T05:39:44.041118719Z",
  "duration": "45.702379S",
  "status": {
    "workspace_job_status": {
      "flow_status": {
        "updated_at": "0001-01-01T00:00:00Z"
      },
      "updated_at": "0001-01-01T00:00:00Z"
    },
    "action_job_status": {
      "action_name": "Users action name, for example, **12ab2**",
      "status_code": "job_pending",
      "status_message": "Job created and pending to start",
      "updated_at": "2021-02-10T11:33:23.378529139Z"
    }
  },
  "data": {
    "job_type": "",
    "workspace_job_data": {
      "updated_at": "0001-01-01T00:00:00Z"
    },
    "action_job_data": {
      "updated_at": "0001-01-01T00:00:00Z"
    }
  },
  "bastion": {
    "name": "bastionhost",
    "type": "string",
    "description": "string",
    "resource_query": "100.100.100.100",
    "credential_ref": "ssh_key",
    "created_at": "0001-01-01T00:00:00Z",
    "updated_at": "0001-01-01T00:00:00Z",
    "sys_lock": {
      "sys_locked_at": "0001-01-01T00:00:00Z"
    }
  },
  "log_summary": {
    "log_start_at": "0001-01-01T00:00:00Z",
    "log_analyzed_till": "0001-01-01T00:00:00Z",
    "repo_download_job": {},
    "workspace_job": {},
    "flow_job": {},
    "action_job": {
      "recap": {}
    }
  },
  "updated_at": "0001-01-01T00:00:00Z"
}

Stop the running Job, and delete the Job

Stop the running Job, and delete the Job. Note You cannot delete or stop the job activity from an ongoing execution of an action defined in the playbook. You can repeat the execution of same job, whenever you patch or update the action or workspace.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

DELETE /v2/jobs/{job_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.job.delete

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • refresh_token
    Required*
    string

    The IAM refresh token for the user or service identity.

    Retrieving refresh token:

    • Use export IBMCLOUD_API_KEY=<ibmcloud_api_key>, and execute curl -X POST "https://iam.cloud.ibm.com/identity/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$IBMCLOUD_API_KEY" -u bx:bx.
    • For more information, about creating IAM access token and API Docs, refer, IAM access token and Create API key.

    Limitation:

    • If the token is expired, you can use refresh token to get a new IAM access token.
    • The refresh_token parameter cannot be used to retrieve a new IAM access token.
    • When the IAM access token is about to expire, use the API key to create a new access token.
  • force
    boolean

    Equivalent to -force options in the command line

  • propagate
    boolean

    Auto propagate the chaange or deletion to the dependent resources

Path Parameters

  • job_id
    Required*
    string

    Job Id. Use GET /v2/jobs API to look up the Job Ids in your IBM Cloud account.

  • curl --location --request DELETE https://schematics.cloud.ibm.com/v2/jobs/{jobid} --header "Authorization: <access_token> "
  • DeleteJobOptions deleteJobOptions = new DeleteJobOptions.Builder()
.jobId("Set your job ID")
.refreshToken("<refresh token>")
.build();

service.deleteJob(deleteJobOptions).execute();
  • response = schematics_service.delete_job(
job_id="Set your job ID",
refresh_token="<refresh token>"
).get_result()

print(json.dumps(response, indent=2))
  • const params = {
refreshToken: "Users refresh token",
jobId: "Users job ID"
};
schematicsService.deleteJob(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});
  • deleteJobOptions := schematicsService.NewDeleteJobOptions("testString","testString",)
deleteJobOptions.SetJobID("set the job ID")
response, err := schematicsService.DeleteJob(deleteJobOptions)
if err != nil {
panic(err)
}

Response

Status Code

  • 204

    Successfully initiated stopping of the job, and deleted the job record.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 409

    Failed to delete the specific resoure. If the resource is locked, try again after unlocking.

  • 429

    Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

  • 503

    IBM Cloud Schematics could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Get job logs

Retrieve the job logs

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v2/jobs/{job_id}/logs

Auditing

Calling this method generates the following auditing event.

  • schematics.job.read

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • job_id
    Required*
    string

    Job Id. Use GET /v2/jobs API to look up the Job Ids in your IBM Cloud account.

  • curl --location --request GET https://schematics.cloud.ibm.com/v2/jobs/{job_id}/logs --header "Authorization: <access_token>"
  • ListJobLogsOptions listJobLogsOptions = new ListJobLogsOptions.Builder()
.jobId("job ID")
.build();

Response<JobLog> response = service.listJobLogs(listJobLogsOptions).execute();
JobLog jobLog = response.getResult();

System.out.println(jobLog);
  • job_log = schematics_service.list_job_logs(
job_id="Set your job ID"
).get_result()

print (job_log)
  • const params = {
jobId: "Users job ID"
};

schematicsService.listJobLogs(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});
  • listJobLogsOptions := schematicsService.NewListJobLogsOptions("testString",)
listJobLogsOptions.SetJobID("set the job ID")
jobLog, response, err := schematicsService.ListJobLogs(listJobLogsOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(jobLog, "", "")
fmt.Println(string(b))

Response

Response Body

JobLog

Job Log details

Status Code

  • 200

    Successfully lists the jobs logs that you have access to.

  • 401

    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • 403

    Unauthorized access. Check that you have the correct access credentials and permissions.

  • 404

    The specified resource was not found

  • 500

    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Get output files from the Job record

Get output files from the Job record. For more information, about the Schematics job status, download job logs, and download the output files, see Download Schematics Job.

GET /v2/jobs/{job_id}/files

Auditing

Calling this method generates the following auditing event.

  • schematics.job.read

Request

Custom Headers

  • Authorization
    Required*
    string

    The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • job_id
    Required*
    string

    Job Id. Use GET /v2/jobs API to look up the Job Ids in your IBM Cloud account.

Query Parameters

  • file_type
    Required*
    string

    The type of file you want to download eg.state_file, plan_json.

    Allowable values: [template_repo,readme_file,log_file,state_file,plan_json]

  • curl --location --request GET http://schematics.cloud.ibm.com/v2/jobs/{job_id}/files?file_type=plan_json   --header "Authorization: <access_token> " --header "Cookie: "
Response
Response Body
JobFileData
Output files from the Job record


Status Code
  • 200
    Successfully got the Job output files.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 404
    The specified resource was not found
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "job_id": "36521f0bb4d5754366e41349a53385f7",
  "file_type": "plan_json",
  "file_content": "{\"format_version\":\"0.1\",\"terraform_version\":\"0.15.5\",\"variables\":{\"TF_VERSION\":{\"value\":0.13},\"image_id\":{\"value\":\"ami-1234\"},\"sample_var\":{\"value\":\"hello\"},\"sleepy_time\":{\"value\":0}},\"planned_values\":{\"outputs\":{\"rendered_template\":{\"sensitive\":false,\"value\":\"Hello, I am a template. My sample_var value = hello\"}},\"root_module\":{\"resources\":[{\"address\":\"null_resource.sleep\",\"mode\":\"managed\",\"type\":\"null_resource\",\"name\":\"sleep\",\"provider_name\":\"registry.terraform.io/hashicorp/null\",\"schema_version\":0}]}},\"resource_changes\":[{\"address\":\"null_resource.sleep\",\"mode\":\"managed\",\"type\":\"null_resource\",\"name\":\"sleep\",\"provider_name\":\"registry.terraform.io/hashicorp/null\",\"change\":{\"actions\":[\"create\"],\"before\":null,\"after\":{},\"after_unknown\":{\"id\":true,\"triggers\":true},\"before_sensitive\":false,\"after_sensitive\":{\"triggers\":{}}}}],\"output_changes\":{\"rendered_template\":{\"actions\":[\"create\"],\"before\":null,\"after\":\"Hello, I am a template. My sample_var value = hello\",\"after_unknown\":false,\"before_sensitive\":false,\"after_sensitive\":false}},\"prior_state\":{\"format_version\":\"0.1\",\"terraform_version\":\"0.15.5\",\"values\":{\"outputs\":{\"rendered_template\":{\"sensitive\":false,\"value\":\"Hello, I am a template. My sample_var value = hello\"}},\"root_module\":{\"resources\":[{\"address\":\"data.template_file.test\",\"mode\":\"data\",\"type\":\"template_file\",\"name\":\"test\",\"provider_name\":\"registry.terraform.io/hashicorp/template\",\"schema_version\":0,\"values\":{\"filename\":null,\"id\":\"16e936de6b5ccd5a7ecf3ad558469e38d9b234c28ac93e8076008334797e11de\",\"rendered\":\"Hello, I am a template. My sample_var value = hello\",\"template\":\"Hello, I am a template. My sample_var value = ${sample_var}\",\"vars\":{\"sample_var\":\"hello\"}}}]}}},\"configuration\":{\"provider_config\":{\"ibm\":{\"name\":\"ibm\",\"version_constraint\":\"1.13.1\"}},\"root_module\":{\"outputs\":{\"rendered_template\":{\"expression\":{\"references\":[\"data.template_file.test\"]}}},\"resources\":[{\"address\":\"null_resource.sleep\",\"mode\":\"managed\",\"type\":\"null_resource\",\"name\":\"sleep\",\"provider_config_key\":\"null\",\"provisioners\":[{\"type\":\"local-exec\",\"expressions\":{\"command\":{\"references\":[\"var.sleepy_time\"]}}}],\"expressions\":{\"triggers\":{}},\"schema_version\":0},{\"address\":\"data.template_file.test\",\"mode\":\"data\",\"type\":\"template_file\",\"name\":\"test\",\"provider_config_key\":\"template\",\"expressions\":{\"template\":{\"constant_value\":\"Hello, I am a template. My sample_var value = ${sample_var}\"},\"vars\":{\"references\":[\"var.sample_var\"]}},\"schema_version\":0}],\"variables\":{\"TF_VERSION\":{\"default\":0.13,\"description\":\"terraform version.\"},\"image_id\":{\"description\":\"The id of the machine image (AMI) to use for the server.\"},\"sample_var\":{\"default\":\"hello\",\"description\":\"A sample_var to pass to the template.\"},\"sleepy_time\":{\"default\":0,\"description\":\"How long our local-exec will take a nap.\"}}}}}\n",
  "updated_at": "2022-03-30T07:17:57.50369681Z"
}
Delete one or more workspace
Delete one or multiple Schematics workspace. Deleting a workspace does not destroy the resources from the Schematics workspace.

   
Authorization


Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see
Schematics service access roles and required permissions.


POST /v1/workspace_jobs
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

  • refresh_token
    Required*
    string
    The IAM refresh token for the user or service identity.
    

    Retrieving refresh token:
    

      

    • Use export IBMCLOUD_API_KEY=<ibmcloud_api_key>, and execute curl -X POST "https://iam.cloud.ibm.com/identity/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$IBMCLOUD_API_KEY" -u bx:bx.
      • 

    • For more information, about creating IAM access token and API Docs, refer, IAM access token and Create API key.
      • 

    

    Limitation:
    

      

    • If the token is expired, you can use refresh token to get a new IAM access token.
      • 

    • The refresh_token parameter cannot be used to retrieve a new IAM access token.
      • 

    • When the IAM access token is about to expire, use the API key to create a new access token.
      • 

    

Request Body
Required*
WorkspaceBulkDeleteRequest
Create a workspace deletion job


  • curl --location --request POST  https://us-east.schematics.cloud.ibm.com/v1/workspace_jobs --header "Content-Type: application/json" --header "Authorization: <access_token> " --data-raw "{"workspaces": ["us-south.workspace.testWorkspace.a6010c37","us-south.workspace.teraformNewupdatedone.72011986","us-south.workspace.readterraform.400b427c","us-south.workspace.myworkspacesink.49745827","us-south.workspace.ReadTerraformTemp.c98c9774","us-south.workspace.SampleTest1.2a51c3a1"],"job": "delete"}"
  • workspace_bulk_delete_response = schematics_service.create_workspace_deletion_job(
new_workspaces=["us-south.workspace.bulkjob-wstesttestpart3.e64bbec8","us-south.workspace.bulkjob-wstesttestpart4.7982dc4a"],
refresh_token='testString'
).get_result()
print(json.dumps(workspace_bulk_delete_response, indent=2))

  • List list = new ArrayList();
list.add("us-south.workspace.bulkjob-wstesttestpart11.f70eba3e");
list.add(1,"us-south.workspace.bulkjob-wstesttestpart12.4a6a7fda");
CreateWorkspaceDeletionJobOptions createWorkspaceDeletionJobOptions = new CreateWorkspaceDeletionJobOptions.Builder()
.newWorkspaces(list)
.refreshToken("testString")
.build();
Response<WorkspaceBulkDeleteResponse> response = service.createWorkspaceDeletionJob(createWorkspaceDeletionJobOptions).execute();
WorkspaceBulkDeleteResponse workspaceBulkDeleteResponse = response.getResult();
System.out.println(workspaceBulkDeleteResponse);

  • const params = {
newWorkspaces:['us-south.workspace.bulkjob-wstesttestpart7.233b36b2','us-south.workspace.bulkjob-wstesttestpart8.e5b68c1e'],
job:'Delete',
refreshToken: 'testString',
};
schematicsService.createWorkspaceDeletionJob(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});

  • createWorkspaceDeletionJobOptions := schematicsService.NewCreateWorkspaceDeletionJobOptions("teststring")
deleteworkspace := []string{"us-south.workspace.bulkjob-wstesttestpart15.b9030d37", "us-south.workspace.bulkjob-wstesttestpart16.3a4a2888"}
createWorkspaceDeletionJobOptions.SetNewWorkspaces(deleteworkspace)
createWorkspaceDeletionJobOptions.SetNewJob("delete")
workspaceBulkDeleteResponse, response, err := schematicsService.CreateWorkspaceDeletionJob(createWorkspaceDeletionJobOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(workspaceBulkDeleteResponse, "", "  ")
fmt.Println(string(b))
fmt.Println(response)

Response
Response Body
WorkspaceBulkDeleteResponse
The response after successfully initiating the bulk job to delete multiple workspaces


Status Code
  • 200
    Successfully initiated the workspace deletion.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 409
    Deletion failed.  The workspace is marked as frozen.  Unfreeze the workspace before you retry the request.
    

  • 429
    Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "job_id": "d16bd5fe2e86886026b8e2ebea3da0e9",
  "job": "delete"
}
Get the workspace deletion job status
Retrieve detailed information for a workspace deletion job status.

   
Authorization


Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see
Schematics service access roles and required permissions.


GET /v1/workspace_jobs/{wj_id}/status
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • wj_id
    Required*
    string
    The workspace job ID.
    

  • curl --location --request GET  https://us-east.schematics.cloud.ibm.com/v1/workspace_jobs/be81cdf8e030ddf07a747c7aa2adcfda/status --header "Content-Type: application/json" --header "Authorization: <access_token> " --header "Cookie: " --data-raw 
  • workspace_job_response = schematics_service.get_workspace_deletion_job_status(
wj_id='<job_id>'
).get_result()
print(json.dumps(workspace_job_response, indent=2))

  • GetWorkspaceDeletionJobStatusOptions getWorkspaceDeletionJobStatusOptions = new GetWorkspaceDeletionJobStatusOptions.Builder()
.wjId("<job_id>")
.build();
Response<WorkspaceJobResponse> response = service.getWorkspaceDeletionJobStatus(getWorkspaceDeletionJobStatusOptions).execute();
WorkspaceJobResponse workspaceJobResponse = response.getResult();
System.out.println(workspaceJobResponse);

  • const params = {
wjId: '<job_id>',
};
schematicsService.getWorkspaceDeletionJobStatus(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});

  • getWorkspaceDeletionJobStatusOptions := schematicsService.NewGetWorkspaceDeletionJobStatusOptions(
"testString",
)
getWorkspaceDeletionJobStatusOptions.SetWjID("<job_id>")
workspaceJobResponse, response, err := schematicsService.GetWorkspaceDeletionJobStatus(getWorkspaceDeletionJobStatusOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(workspaceJobResponse, "", "  ")
fmt.Println(string(b))
fmt.Println(response)

Response
Response Body
WorkspaceJobResponse
The response from the workspace bulk job status.


Status Code
  • 200
    Successfully retrieved details about your workspace deletion job.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 404
    Not found. The specified workspace could not be found. Verify that the workspace ID is correct. To list workspaces in your IBM Cloud account, use the GET /v1/workspaces API.
    

  • 429
    Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "job_status": {
    "last_updated_on": "2021-09-24T05:46:23.266613311Z",
    "success": [
      "us-south.workspace.bulkjob-wstesttestpart1.c67ba74d",
      "us-south.workspace.bulkjob-wstesttestpart2.11bdd6e7"
    ],
    "failed": [
      "us-south.workspace.testWorkspace.a6010c37"
    ]
  }
}
List inventory definitions
Retrieve a list of all Schematics inventories that depends on the API endpoint that you have access. For example, if you use an API endpoint for a geography, such as North America, only inventories that are created in us-south or us-east are retrieved. For more information, about supported API endpoints, see APIendpoints.

 
Authorization


Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see
Schematics service access roles and required permissions.


GET /v2/inventories
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Query Parameters
  • offset
    integer
    The starting position of the item in the list of items. For example, if you have three workspaces in your account, the first workspace is assigned position number 0, the second workspace is assigned position number 1, and so forth. If you have 6 workspaces and you want to list the details for workspaces 2-6, enter 1. To limit the number of workspaces that is returned, use the limit option in addition to the offset option. Negative numbers are not supported and are ignored.
    

    Possible values:  value ≥ 0
  • limit
    integer
    The maximum number of items that you want to list. The number must be a positive integer between 1 and 2000. If no value is provided, 100 is used by default.
    

    Possible values:  1 ≤ value ≤ 2000
    Default: 100
  • sort
    string
    Name of the field to sort-by;  Use the '.' character to delineate sub-resources and sub-fields (eg. owner.last_name). Prepend the field with '+' or '-', indicating 'ascending' or 'descending' (default is ascending)   Ignore unrecognized or unsupported sort field
    

  • profile
    string
    Level of details returned by the get method
    

    Allowable values: [ids,summary]
  • curl --location --request GET https://schematics.cloud.ibm.com/v2/inventories --header "Content-Type: application/json" --header "Authorization: <access_token> " --data-raw "{"name": "dev-inventory538","description": "My dev env inventory","location": "us-east","resource_group": "Default",,"inventories_ini": "[windows] \n 158.177.7.181"}
  • inventory_resource_record_list = schematics_service.list_inventories().get_result()
print(json.dumps(inventory_resource_record_list, indent=2))

  • ListInventoriesOptions listInventoriesOptions = new ListInventoriesOptions.Builder()
.build();
Response<InventoryResourceRecordList> response = service.listInventories(listInventoriesOptions).execute();
InventoryResourceRecordList inventoryResourceRecordList = response.getResult();
System.out.println(inventoryResourceRecordList);

  • schematicsService.listInventories({})
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});

  • listInventoriesOptions := schematicsService.NewListInventoriesOptions()
inventoryResourceRecordList, response, err := schematicsService.ListInventories(listInventoriesOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(inventoryResourceRecordList, "", "  ")
fmt.Println(string(b))
fmt.Println(response)

Response
Response Body
InventoryResourceRecordList
List of Inventory definition records


Status Code
  • 200
    Successful listed all inventory definition resources
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "total_count": 24,
  "limit": 100,
  "offset": 0,
  "inventories": [
    {
      "name": "resourcename",
      "id": ".INVENTORY.resourcename.218b1903",
      "created_at": "2021-03-13T16:34:34.709988453Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "resourcename1",
      "id": ".INVENTORY.resourcename.a5857cd4",
      "created_at": "2021-03-15T10:17:35.244325142Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "abcdinv11",
      "id": "us-south.INVENTORY.abcdinv11.57fe6b53",
      "description": "My description",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-03-26T04:13:55.591652477Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "abcdinv13",
      "id": "us-south.INVENTORY.abcdinv11.72794f6d",
      "description": "My description",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-03-25T11:29:03.692369367Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "2021-03-25T12:25:29.81518941Z",
      "updated_by": "schematics@ibm.com"
    },
    {
      "name": "abcdinv4",
      "id": "us-south.INVENTORY.abcdinv4.d0b2201d",
      "description": "My description",
      "location": "us-south",
      "resource_group": "Default",
      "created_at": "2021-03-25T04:28:08.360433941Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "abcdinv5",
      "id": "us-east.INVENTORY.abcdinv5.ae1247ee",
      "description": "My description",
      "location": "us-south",
      "resource_group": "Default",
      "created_at": "2021-03-25T04:28:31.944210658Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "abcdinv6",
      "id": "us-east.INVENTORY.abcdinv6.b7646b3f",
      "description": "My description",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-03-25T04:30:31.619446477Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "abcdinv7",
      "id": "us-east.INVENTORY.abcdinv7.588385ed",
      "description": "My description",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-03-25T04:30:58.130718895Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "abcdinv8",
      "id": "us-east.INVENTORY.abcdinv8.3608dd80",
      "description": "My description",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-03-25T04:32:25.431638004Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "abcdinv9",
      "id": "us-east.INVENTORY.abcdinv9.54ef1de5",
      "description": "My description",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-03-25T04:33:09.77479562Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "dev-inventory527",
      "id": "us-east.INVENTORY.dev-inventory527.35cefc61",
      "description": "My dev env inventory",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-03-22T09:28:09.172660128Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "dev-inventory5279",
      "id": "us-east.INVENTORY.dev-inventory5279.5024cb04",
      "description": "My dev env inventory",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-03-24T10:06:54.248751996Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "dev-inventory52d7",
      "id": "us-east.INVENTORY.dev-inventory52d7.c401d447",
      "description": "My dev env inventory",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-03-22T09:37:38.070873251Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "dev-inventory52d7p",
      "id": "us-east.INVENTORY.dev-inventory52d7p.972abfb3",
      "description": "My dev env inventory",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-03-22T10:07:47.985128872Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "dev-inventory531",
      "id": "us-east.INVENTORY.dev-inventory531.1f67f6da",
      "description": "My dev env inventory",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-03-25T04:21:09.116751032Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "dev-inventory532",
      "id": "us-east.INVENTORY.dev-inventory532.3625125f",
      "description": "My dev env inventory",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-03-25T04:21:31.918450417Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "dev-inventory538",
      "id": "us-east.INVENTORY.dev-inventory538.1ba768aa",
      "description": "My dev env inventory",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-03-26T07:08:00.264008441Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "dev-inventory5d28d7p",
      "id": "us-east.INVENTORY.dev-inventory5d28d7p.1e90678d",
      "description": "My dev env inventory",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-03-22T11:10:12.608762853Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "dev-inventory5d2d7p",
      "id": "us-east.INVENTORY.dev-inventory5d2d7p.38815610",
      "description": "My dev env inventory",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-03-22T10:15:46.185912518Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "dev-inventory",
      "id": "us-east.INVENTORY.dev-inventory.160c6d33",
      "description": "My dev env inventory",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-03-11T10:49:31.707067866Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "dev-inventory1",
      "id": "us-east.INVENTORY.dev-inventory1.5e8f5354",
      "description": "My dev env inventory",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-03-15T10:56:10.415818711Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "string",
      "id": "us-east.INVENTORY.string.9476a5b3",
      "description": "string",
      "location": "us-east",
      "resource_group": "string",
      "created_at": "2021-03-09T04:07:56.153474027Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "string",
      "id": "us-east.INVENTORY.string.de4b951c",
      "description": "string",
      "location": "us-east",
      "resource_group": "string",
      "created_at": "2021-03-10T17:29:24.274559186Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "string",
      "id": "us-east.INVENTORY.string.f1ef1a24",
      "description": "string",
      "location": "us-east",
      "resource_group": "string",
      "created_at": "2021-03-09T06:19:30.865119938Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "dev-inventoryapidocexample",
      "id": "us-east.INVENTORY.dev-inventoryapidocexample.21788a22",
      "description": "My cloud linux inventory",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-09-29T11:44:58.527220197Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    }
  ]
}
Create an inventory definition
Create an IBM Cloud Schematics inventory as a single IBM Cloud resource where you want to run Ansible playbook by using Schematics actions. For more information, about inventory host groups, refer to creating static and dynamic inventory for Schematics actions.


Note you cannot update the location and region, resource group once an action is created. Also, make sure your IP addresses are in the allowlist.
If your Git repository already contains a host file. Schematics does not overwrite the host file already present in your Git repository.

 
Authorization


Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see
Schematics service access roles and required permissions.


POST /v2/inventories
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Request Body
Required*
InventoryResourceDefinition
Create a Inventory definition resource


  • curl --location --request POST https://schematics.cloud.ibm.com/v2/inventories --header Authorization: <access_token> " --header "Content-Type: application/json" '{"name": "dev-inventoryapidocexample", "description": "My cloud linux inventory","location": "us-east", "resource_group": "Default","inventories_ini": "[windows] \n 158.177.7.181"}'
  • inventory_resource_record = schematics_service.create_inventory(
name= "dev-inventory542",
description= "My dev env inventory",
location= "us-east",
resource_group= "Default",
resource_queries= ["default.RESOURCEQUERY.string.df3d8a47"]
).get_result()
print(json.dumps(inventory_resource_record, indent=2))

  • CreateInventoryOptions createInventoryOptions = new CreateInventoryOptions.Builder()
.name("dev-inventory506")
.description("My dev env inventory")
.location("us-east")
.build();
Response<InventoryResourceRecord> response = service.createInventory(createInventoryOptions).execute();
InventoryResourceRecord inventoryResourceRecord = response.getResult();
System.out.println(inventoryResourceRecord);

  • const params = {
name: "dev-inventory506",
description: "My dev env inventory",
location: "us-east",
resource_group: "Default",
resource_queries: ["default.RESOURCEQUERY.string.df3d8a47"]};
schematicsService.createInventory(params)
.then(res => {console.log(JSON.stringify(res.result, null, 2));})
.catch(err => {
console.warn(err)
});

  • createInventoryOptions := schematicsService.NewCreateInventoryOptions()
createInventoryOptions.SetName("dev-inventory542")
createInventoryOptions.SetDescription("My dev env inventory")
createInventoryOptions.SetLocation("us-east")
inventoryResourceRecord, response, err := schematicsService.CreateInventory(createInventoryOptions)
if err != nil {
panic(err)
}
fmt.Println(response)
b, _ := json.MarshalIndent(inventoryResourceRecord, "", "")
fmt.Println(string(b))

Response
Response Body
InventoryResourceRecord
Complete inventory definition details


Status Code
  • 200
    Successfully created Inventory definition resource
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 409
    The specified resource already exists
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "name": "dev-inventoryapidocexample",
  "id": "us-east.INVENTORY.dev-inventoryapidocexample.21788a22",
  "description": "My cloud linux inventory",
  "location": "us-east",
  "resource_group": "Default",
  "created_at": "2021-09-29T11:44:58.527218494Z",
  "created_by": "schematics@ibm.com",
  "updated_at": "0001-01-01T00:00:00Z",
  "inventories_ini": "[windows] \n158.177.7.181                        "
}
Get an inventory definition
Use this API to retrieve the detailed information for a resource inventory definition used to target an action in your IBM Cloud account. For more information, about inventory get, refer to ibmcloud schematics inventory get.


Note you can fetch only the location and region, resource group from where your inventory is created.

Also, make sure your IP addresses are in the allowlist.

 
Authorization


Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see
Schematics service access roles and required permissions.


GET /v2/inventories/{inventory_id}
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • inventory_id
    Required*
    string
    Resource Inventory Id.  Use GET /v2/inventories API to look up the Resource Inventory definition Ids  in your IBM Cloud account.
    

Query Parameters
  • profile
    string
    Level of details returned by the get method
    

    Allowable values: [summary,detailed,ids]
  • curl --location --request GET https://schematics.cloud.ibm.com/v2/inventories/{inventory_id} —header "Authorization:  <access_token> " —header "Content-Type: application/json "
  • curl --location --request GET curl -X GET \ https://schematics.cloud.ibm.com/v2/inventories/{inventory_id}?profile=detailed —header "Authorization:  <access_token> " —header "Content-Type: application/json "                    
  • inventory_resource_record = schematics_service.get_inventory(
inventory_id='set an inventory ID'
).get_result()
print(json.dumps(inventory_resource_record, indent=2))

  • GetInventoryOptions getInventoryOptions = new GetInventoryOptions.Builder()
.inventoryId("set an inventory Id")
.build();
Response<InventoryResourceRecord> response = service.getInventory(getInventoryOptions).execute();
InventoryResourceRecord inventoryResourceRecord = response.getResult();
System.out.println(inventoryResourceRecord);

  • const params = {inventoryId: 'set an inventory ID',};
schematicsService.getInventory(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});

  • getInventoryOptions := schematicsService.NewGetInventoryOptions(
testString)
getInventoryOptions.SetInventoryID("set an inventory ID")
inventoryResourceRecord, response, err := schematicsService.GetInventory(getInventoryOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(inventoryResourceRecord, "", "  ")
fmt.Println(string(b))
fmt.Println(response)

Response
Response Body
InventoryResourceRecord
Complete inventory definition details


Status Code
  • 200
    Successfully retrieved the resource inventory definition
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 404
    The specified resource was not found
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "name": "dev-inventoryapidocexample",
  "id": "us-east.INVENTORY.dev-inventoryapidocexample.21788a22",
  "description": "My Example cloud linux inventory",
  "location": "us-east",
  "resource_group": "Default",
  "created_at": "2021-09-29T11:44:58.527218494Z",
  "created_by": "schematics@ibm.com",
  "updated_at": "2021-09-29T15:05:19.550795901Z",
  "updated_by": "schematics@ibm.com",
  "inventories_ini": "[windows] \n158.177.7.181                                                "
}
Update an inventory definition
Use this API to update the inventory definition resource used to target an action. For more information, about inventory update, refer to ibmcloud schematics inventory update.


Note you cannot update the location and region, resource group once an action is created.
Also, make sure your IP addresses are in the allowlist.

 
Authorization


Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see
Schematics service access roles and required permissions.


PUT /v2/inventories/{inventory_id}
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • inventory_id
    Required*
    string
    Resource Inventory Id.  Use GET /v2/inventories API to look up the Resource Inventory definition Ids  in your IBM Cloud account.
    

Request Body
Required*
InventoryResourceDefinition
Update the inventory definition resource


  • curl --location --request PUT https://schematics.cloud.ibm.com/v2/inventories/us-east.INVENTORY.dev-inventory538.1ba768aa/ --header "Content-Type: application/json" --header "Authorization: <access_token> " --data-raw "{"name": "MainFrame-dev-inve","description": "My dev env inventory","location": "us-east","resource_group": "Default","inventories_ini": "[windows] \n 158.177.7.181"}
  • inventory_resource_record = schematics_service.replace_inventory(
inventory_id='us-east.INVENTORY.dev-inventory542.475e3f27',
name="dev-inventory542",
description="My dev env inventory text is replaced",
location="us-east",
resource_group= "Default",
resource_queries= ["default.RESOURCEQUERY.string.df3d8a47"]
).get_result()
print(json.dumps(inventory_resource_record, indent=2))

  • ReplaceInventoryOptions replaceInventoryOptions = new ReplaceInventoryOptions.Builder()
.inventoryId("set an inventory Id")
.name("dev-inventory516")
.description("My dev env inventory is Java updated")
.location("us-east")
.build();
Response<InventoryResourceRecord> response = service.replaceInventory(replaceInventoryOptions).execute();
InventoryResourceRecord inventoryResourceRecord = response.getResult();
System.out.println(inventoryResourceRecord);

  • const params = {
inventoryId: 'set an inventory ID',
name:"dev-inventory",
description: "My dev env inventory New Example",
location: "us-east",
resource_group: "Default",
resource_queries: ["default.RESOURCEQUERY.string.df3d8a47"]
};
schematicsService.replaceInventory(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});

  • replaceInventoryOptions := schematicsService.NewReplaceInventoryOptions(
testString)
replaceInventoryOptions.SetInventoryID("set your inventory ID")
replaceInventoryOptions.SetName("dev-inventory548")
replaceInventoryOptions.SetDescription("My dev env inventory is correct")
replaceInventoryOptions.SetLocation("us-east")
inventoryResourceRecord, response, err := schematicsService.ReplaceInventory(replaceInventoryOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(inventoryResourceRecord, "", "  ")
fmt.Println(string(b))
fmt.Println(response)

Response
Response Body
InventoryResourceRecord
Complete inventory definition details


Status Code
  • 200
    Successfully updated the inventory definition resource
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 404
    The specified resource was not found
    

  • 409
    The specified resource is locked, cannot be updated or deleted
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "name": "dev-inventoryapidocexample",
  "id": "us-east.INVENTORY.dev-inventoryapidocexample.21788a22",
  "description": "My Example cloud linux inventory",
  "location": "us-east",
  "resource_group": "Default",
  "created_at": "2021-09-29T11:44:58.527218494Z",
  "created_by": "schematics@ibm.com",
  "updated_at": "2021-09-29T15:05:19.550795901Z",
  "updated_by": "schematics@ibm.com",
  "inventories_ini": "[windows] \n158.177.7.181"
}
Delete an inventory definition
Use this API to delete the resource inventory definition by using the inventory ID that you want to run against. For more information, about inventory delete, refer to ibmcloud schematics inventory delete.


Note you cannot delete the location and region, resource group from where your inventory is created. Also, make sure your IP addresses are in the allowlist.

 
Authorization


Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see
Schematics service access roles and required permissions.


DELETE /v2/inventories/{inventory_id}
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

  • force
    boolean
    Equivalent to -force options in the command line
    

  • propagate
    boolean
    Auto propagate the chaange or deletion to the dependent resources
    

Path Parameters
  • inventory_id
    Required*
    string
    Resource Inventory Id.  Use GET /v2/inventories API to look up the Resource Inventory definition Ids  in your IBM Cloud account.
    

  • curl --location --request DELETE https://schematics.cloud.ibm.com/v2/inventories/us-east.INVENTORY.dev-inventory523.244223cf/  --header "Content-Type: application/json" --header "Authorization: <access_token> " --data-raw "{"name": "dev-inventory538","description": "My dev env inventory","location": "us-east","resource_group": "Default","resource_queries": ["default.RESOURCEQUERY.string.df3d8a47"]}
  • response = schematics_service.delete_inventory(
inventory_id='us-east.INVENTORY.dev-inventory502.e383dcbb'
).get_result()
print(json.dumps(response, indent=2))

  • DeleteInventoryOptions deleteInventoryOptions = new DeleteInventoryOptions.Builder()
.inventoryId("set an inventory Id")
.build();
service.deleteInventory(deleteInventoryOptions).execute();

  • const params = {
inventoryId: 'set an inventory ID',
};
schematicsService.deleteInventory(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});

  • deleteInventoryOptions := schematicsService.NewDeleteInventoryOptions(
testString)
deleteInventoryOptions.SetInventoryID("set inventory Id")
response, err := schematicsService.DeleteInventory(deleteInventoryOptions)
if err != nil {
panic(err)
}
fmt.Println(response)

Response
Status Code
  • 204
    Successfully deleted the resource inventory definition
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 404
    The specified resource was not found
    

  • 409
    Failed to delete the specific resoure.  If the resource is locked, try again after unlocking.
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

No Sample Response
This method does not specify any sample responses.
List resource queries
Retrieve the list of resource query definitions that you have access to.  The list of resource queries that is returned depends on the API  endpoint that you use. For example, if you use an API endpoint for a geography, such as North America, only resource query definitions that are created in us-south or us-east are retrieved. For more information, about supported API endpoints, see API endpoints.


Authorization


Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see
Schematics service access roles and required permissions.


GET /v2/resources_query
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Query Parameters
  • offset
    integer
    The starting position of the item in the list of items. For example, if you have three workspaces in your account, the first workspace is assigned position number 0, the second workspace is assigned position number 1, and so forth. If you have 6 workspaces and you want to list the details for workspaces 2-6, enter 1. To limit the number of workspaces that is returned, use the limit option in addition to the offset option. Negative numbers are not supported and are ignored.
    

    Possible values:  value ≥ 0
  • limit
    integer
    The maximum number of items that you want to list. The number must be a positive integer between 1 and 2000. If no value is provided, 100 is used by default.
    

    Possible values:  1 ≤ value ≤ 2000
    Default: 100
  • sort
    string
    Name of the field to sort-by;  Use the '.' character to delineate sub-resources and sub-fields (eg. owner.last_name). Prepend the field with '+' or '-', indicating 'ascending' or 'descending' (default is ascending)   Ignore unrecognized or unsupported sort field
    

  • profile
    string
    Level of details returned by the get method
    

    Allowable values: [ids,summary]
  • curl --location --request GET https://schematics.cloud.ibm.com/v2/resources_query/ --header "Authorization: <access_token>" --header "Content-Type: application/json" --header "Cookie: " --data-raw "
  • resource_query_record_list = schematics_service.list_resource_query().get_result()
print(json.dumps(resource_query_record_list, indent=2))

  • ListResourceQueryOptions listResourceQueryOptions = new ListResourceQueryOptions.Builder()
.build();
Response<ResourceQueryRecordList> response = service.listResourceQuery(listResourceQueryOptions).execute();
ResourceQueryRecordList resourceQueryRecordList = response.getResult();
System.out.println(resourceQueryRecordList);

  • schematicsService.listResourceQuery({})
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});

  • listResourceQueryOptions := schematicsService.NewListResourceQueryOptions()
resourceQueryRecordList, response, err := schematicsService.ListResourceQuery(listResourceQueryOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(resourceQueryRecordList, "", "  ")
fmt.Println(string(b))
fmt.Println(response)

Response
Response Body
ResourceQueryRecordList
List of Resource query records


Status Code
  • 200
    Successful listed all resource query definitions
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "total_count": 4,
  "limit": 100,
  "offset": 0,
  "ResourceQueries": [
    {
      "id": "default.RESOURCEQUERY.a12344",
      "created_at": "2021-04-09T10:05:33.073223242Z",
      "created_by": "user@in.ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "type": "vsi",
      "name": "demorqcli",
      "id": "default.RESOURCEQUERY.demorqcli.79f53cb8",
      "created_at": "2021-03-31T06:25:27.675614966Z",
      "created_by": "user@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z",
      "queries": [
        {
          "query_type": "workspaces",
          "query_condition": [
            {
              "name": "workspace-id",
              "value": "us-east.workspace.sundeepKfreporttest.22e234125",
              "description": "string"
            },
            {
              "name": "resource-name",
              "value": "tf44234vpc-pubpriv-frontend-vsi",
              "description": "string"
            }
          ]
        }
      ]
    },
    {
      "type": "workspace_resource",
      "name": "hello",
      "id": "default.RESOURCEQUERY.hello.2f12312",
      "created_at": "2021-04-09T10:20:06.572503322Z",
      "created_by": "user@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z",
      "queries": [
        {
          "query_type": "workspaces",
          "query_condition": [
            {
              "name": "workspace-id",
              "value": "us-east.ACTION.kubectlWorkshop.1010101",
              "description": "string"
            },
            {
              "name": "resource-name",
              "value": "123vpc-pubpriv-frontend-vsi",
              "description": "string"
            }
          ]
        }
      ]
    },
    {
      "type": "workspaces",
      "name": "samplequerytest",
      "id": "t12312121vpc-pubpriv-frontend-vsi",
      "created_at": "2021-03-31T06:32:54.065908533Z",
      "created_by": "user@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z"
    }
  ]
}
Create resource query
Use this API to create a resource query definition that will be used to select an IBM Cloud resource or a group of resources as the dynamic inventory for the Schematics Actions.
For more information, about resource query commands, refer to  ibmcloud schematics resource query create.
Note you cannot update the location and region, resource group  once an action is created. Also, make sure your IP addresses are  in the allowlist.
If your Git repository already contains a host file.  Schematics does not overwrite the host file already present in your Git repository.


Authorization


Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see
Schematics service access roles and required permissions.


POST /v2/resources_query
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Request Body
Required*
ResourceQueryDefinition
Create a resource query definition


  • curl --location --request POST https://schematics.cloud.ibm.com/v2/resources_query/ --header "Authorization: <access_token> "  --header "Content-Type: application/json"  --header "Cookie:" --data-raw "{"type": "workspace_resource","name": "hello","queries": [{"query_type": "workspaces","query_condition": [{"name": "workspace-id", "value": "us-east.ACTION.kubectlWorkshop.41901417","description": "string"},{"name": "resource-name","value": "tf00vpc-pubpriv-frontend-vsi","description": "string"}]}]}'
  • resource_query_record = schematics_service.create_resource_query(
type="workspace_resource",
name="hello my world",
queries=[{
query_type:"workspaces",
query_condition: [{
name:"workspace-id",
value:"us-east.ACTION.kubectlWorkshop.41901417",
description:"string"},{
name:"resource-name",
value:"tf00vpc-pubpriv-frontend-vsi",
description:"string"}
]
}
]
).get_result()
print(json.dumps(resource_query_record, indent=2))
  • CreateResourceQueryOptions createResourceQueryOptions = new CreateResourceQueryOptions.Builder()
.type("workspace_resource")
.name("hello my world")
.build();
Response<ResourceQueryRecord> response = service.createResourceQuery(createResourceQueryOptions).execute();
ResourceQueryRecord resourceQueryRecord = response.getResult();
System.out.println(resourceQueryRecord);

  • const params = {
type: "workspace_resource",
name: "hello my world",
queries: [
{
query_type: "workspaces",
query_condition: [
{name: "workspace-id",value: "us-east.ACTION.kubectlWorkshop.41901417",description: "string"},
{name: "resource-name",value: "tf00vpc-pubpriv-frontend-vsi",description: "string"}
]}]};
schematicsService.createResourceQuery(params)
.then(res => {console.log(JSON.stringify(res.result, null, 2));})
.catch(err => {console.warn(err)});

  • createResourceQueryOptions := schematicsService.NewCreateResourceQueryOptions()
createResourceQueryOptions.SetType("workspace_resource")
createResourceQueryOptions.SetName("hello")
resourceQueryRecord, response, err := schematicsService.CreateResourceQuery(createResourceQueryOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(resourceQueryRecord, "", "  ")
fmt.Println(string(b))
fmt.Println(response)

Response
Response Body
ResourceQueryRecord
Describe resource query record


Status Code
  • 200
    Successfully created resource query definition
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 409
    The specified resource already exists
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "type": "workspace_resource",
  "name": "hello",
  "id": "your resource query ID.",
  "created_at": "2021-04-09T10:20:06.572501285Z",
  "created_by": "usera@ibm.com",
  "updated_at": "0001-01-01T00:00:00Z",
  "queries": [
    {
      "query_type": "workspaces",
      "query_condition": [
        {
          "name": "workspace-id",
          "value": "us-east.ACTION.kubectlWorkshop.1010101",
          "description": "string"
        },
        {
          "name": "resource-name",
          "value": "t123vpc-pubpriv-frontend-vsi",
          "description": "string"
        }
      ]
    }
  ]
}
Get resources query
Use this API to retrieve the information resource query by Id.  For more information, about resource query commands, refer to  ibmcloud schematics resource query get.


Authorization


Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see
Schematics service access roles and required permissions.


GET /v2/resources_query/{query_id}
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • query_id
    Required*
    string
    Resource query Id.  Use GET /v2/resource_query API to look up the Resource query definition Ids  in your IBM Cloud account.
    

  • curl --location --request GET https://schematics.cloud.ibm.com/v2/resources_query/default.RESOURCEQUERY.hello.2fdda8ce --header "Authorization: <access_token>"  --header "Content-Type: application/json" --header "Cookie: " --data-raw "
  • GetResourcesQueryOptions getResourcesQueryOptions = new GetResourcesQueryOptions.Builder()
.queryId("set a query Id")
.build();
Response<ResourceQueryRecord> response = service.getResourcesQuery(getResourcesQueryOptions).execute();
ResourceQueryRecord resourceQueryRecord = response.getResult();
System.out.println(resourceQueryRecord);

  • resource_query_record = schematics_service.get_resources_query(
query_id='default.RESOURCEQUERY.hello-my-world.c1789bc1'
).get_result()
print(json.dumps(resource_query_record, indent=2))

  • const params = {
queryId: 'set a resource-query Id',
};
schematicsService.getResourcesQuery(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});

  • getResourcesQueryOptions := schematicsService.NewGetResourcesQueryOptions(
testString)
getResourcesQueryOptions.SetQueryID("set a resource-query Id")
resourceQueryRecord, response, err := schematicsService.GetResourcesQuery(getResourcesQueryOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(resourceQueryRecord, "", "  ")
fmt.Println(string(b))
fmt.Println(response)

Response
Response Body
ResourceQueryRecord
Describe resource query record


Status Code
  • 200
    Successfully fetches a resources query definition.
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 404
    The specified resource was not found
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "type": "workspace_resource",
  "name": "hello",
  "id": "default.RESOURCEQUERY.hello.101010",
  "created_at": "2021-04-09T10:20:06.572503322Z",
  "created_by": "user@ibm.com",
  "updated_at": "0001-01-01T00:00:00Z",
  "queries": [
    {
      "query_type": "workspaces",
      "query_condition": [
        {
          "name": "workspace-id",
          "value": "us-east.ACTION.kubectlWorkshop.101010",
          "description": "string"
        },
        {
          "name": "resource-name",
          "value": "tf1234vpc-pubpriv-frontend-vsi",
          "description": "string"
        }
      ]
    }
  ]
}
Update resources query definition
Use this API to update the resource query definition used to build  the dynamic inventory for the Schematics Action.  For more information, about resource query commands, refer to ibmcloud schematics resource query update.
Note you cannot update the location and region, resource group  once a resource query is created. Also, make sure your IP addresses  are in the allowlist.


Authorization


Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see
Schematics service access roles and required permissions.


PUT /v2/resources_query/{query_id}
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • query_id
    Required*
    string
    Resource query Id.  Use GET /v2/resource_query API to look up the Resource query definition Ids  in your IBM Cloud account.
    

Request Body
Required*
ResourceQueryDefinition
Replace the resources query definition


  • curl --location --request PUT https://schematics.cloud.ibm.comv2/resources_query/default.RESOURCEQUERY.hello.2fdda8ce --header "Authorization:<access_token> " --header "Content-Type: application/json" --header "Cookie: " --data-raw "{ "type": "workspace_resource","name": "hello my world","queries": [{"query_type": "workspaces","query_condition": [{"name": "workspace-id","value": "us-east.ACTION.kubectlWorkshop.41901417","description": "string"},{"name": "resource-name","value": "tf00vpc-pubpriv-frontend-vsi","description": "string"}]}]}
  • resource_query_record = schematics_service.replace_resources_query(
query_id= "set a query Id",
type= "workspace_resource",
name= "hello my world",
queries= [
{
query_type: "workspaces",
query_condition: [
{
name: "workspace-id",
value: "us-east.ACTION.kubectlWorkshop.41901417",
description: "string"
},
{
name: "resource-name",
value: "tf00vpc-pubpriv-frontend-vsi",
description: "string"
}
]}]
).get_result()
print(json.dumps(resource_query_record, indent=2))
]}]}

  • ReplaceResourcesQueryOptions replaceResourcesQueryOptions = new ReplaceResourcesQueryOptions.Builder()
.queryId("set a query Id")
.type("workspace_resource")
.name("hello my world this is resource_query")
.build();
Response<ResourceQueryRecord> response = service.replaceResourcesQuery(replaceResourcesQueryOptions).execute();
ResourceQueryRecord resourceQueryRecord = response.getResult();
System.out.println(resourceQueryRecord);

  • const params = {
queryId: 'set query Id',
type: "workspace_resource",
name: "hello my world updated changes",
};
schematicsService.replaceResourcesQuery(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});

  • replaceResourcesQueryOptions := schematicsService.NewReplaceResourcesQueryOptions(
testString)
replaceResourcesQueryOptions.SetQueryID("default.RESOURCEQUERY.demorqcli.79f53cb8")
replaceResourcesQueryOptions.SetType("workspace_resource")replaceResourcesQueryOptions.SetName("hello my world short description")
resourceQueryRecord, response, err := schematicsService.ReplaceResourcesQuery(replaceResourcesQueryOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(resourceQueryRecord, "", "  ")
fmt.Println(string(b))
fmt.Println(response)

Response
Response Body
ResourceQueryRecord
Describe resource query record


Status Code
  • 200
    Successfully updated the resources query definition
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 409
    The specified resource is locked, cannot be updated or deleted
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "type": "workspace_resource",
  "name": "hello my world",
  "id": "default.RESOURCEQUERY.hello.10101",
  "created_at": "2021-04-09T10:20:06.572501285Z",
  "created_by": "user@ibm.com",
  "updated_at": "2021-04-09T10:34:39.243133239Z",
  "updated_by": "user@ibm.com",
  "queries": [
    {
      "query_type": "workspaces",
      "query_condition": [
        {
          "name": "workspace-id",
          "value": "us-east.ACTION.kubectlWorkshop.12317",
          "description": "string"
        },
        {
          "name": "resource-name",
          "value": "tf12312vpc-pubpriv-frontend-vsi",
          "description": "string"
        }
      ]
    }
  ]
}
Run the resource query
Run the resource query


POST /v2/resources_query/{query_id}
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • query_id
    Required*
    string
    Resource query Id.  Use GET /v2/resource_query API to look up the Resource query definition Ids  in your IBM Cloud account.
    

Response
Response Body
ResourceQueryResponseRecord
Describe resource query


Status Code
  • 200
    Successfully executed resource query
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 409
    The specified resource already exists
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

No Sample Response
This method does not specify any sample responses.
Delete resources query
Use this API to delete the resource query definition by Id.  For more information, about resource query commands, refer to  ibmcloud schematics resource query delete.


Authorization


Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see
Schematics service access roles and required permissions.


DELETE /v2/resources_query/{query_id}
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

  • force
    boolean
    Equivalent to -force options in the command line
    

  • propagate
    boolean
    Auto propagate the chaange or deletion to the dependent resources
    

Path Parameters
  • query_id
    Required*
    string
    Resource query Id.  Use GET /v2/resource_query API to look up the Resource query definition Ids  in your IBM Cloud account.
    

  • curl --location --request DELETE https://schematics.cloud.ibm.com/v2/resources_query/default.RESOURCEQUERY.samplequerytest.699fd513 --header 'Authorization: ' --header "Content-Type: application/json" --header "Cookie: " --data-raw "
  • response = schematics_service.delete_resources_query(
query_id='set query id'
).get_result()
print(json.dumps(response, indent=2))

  • DeleteResourcesQueryOptions deleteResourcesQueryOptions = new DeleteResourcesQueryOptions.Builder()
.queryId("set a query Id")
.build();
service.deleteResourcesQuery(deleteResourcesQueryOptions).execute();

  • const params = {
queryId: 'set query id',
};
schematicsService.deleteResourcesQuery(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});

  • deleteResourcesQueryOptions := schematicsService.NewDeleteResourcesQueryOptions(
testString)
deleteResourcesQueryOptions.SetQueryID("set query id")
response, err := schematicsService.DeleteResourcesQuery(deleteResourcesQueryOptions)
if err != nil {
panic(err)
}
fmt.Println(response)

Response
Status Code
  • 204
    Successfully deletes a resources query definition.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 404
    The specified resource was not found
    

  • 409
    Failed to delete the specific resoure.  If the resource is locked, try again after unlocking.
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

No Sample Response
This method does not specify any sample responses.
Get all registered/unregistered agents in the Account
Get all registered or unregistered agents, in the Account.

   
Authorization
 

Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see Schematics service access
roles and required permissions.


GET /v2/settings/agents
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Query Parameters
  • offset
    integer
    The starting position of the item in the list of items. For example, if you have three workspaces in your account, the first workspace is assigned position number 0, the second workspace is assigned position number 1, and so forth. If you have 6 workspaces and you want to list the details for workspaces 2-6, enter 1. To limit the number of workspaces that is returned, use the limit option in addition to the offset option. Negative numbers are not supported and are ignored.
    

    Possible values:  value ≥ 0
  • limit
    integer
    The maximum number of items that you want to list. The number must be a positive integer between 1 and 2000. If no value is provided, 100 is used by default.
    

    Possible values:  1 ≤ value ≤ 2000
    Default: 100
  • profile
    string
    Level of details returned by the get method
    

    Allowable values: [summary,detailed,ids]
  • filter
    string
    Use new to get all unregistered agents; use saved to get all registered agents.
    

    Allowable values: [all,new,saved]
Response
Response Body
AgentList
The list of agent details.


Status Code
  • 200
    Successfully listed all agent in the account
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "total_count": 2,
  "limit": 100,
  "offset": 0,
  "agents": [
    {
      "name": "smulampaka-agent9",
      "description": "Register agent",
      "resource_group": "Default",
      "tags": [
        "agent"
      ],
      "agent_location": "us-south",
      "location": "eu-de",
      "agent_crn": "crn:v1:staging:public:schematics:eu-de:a/0ddd18d6a00f4e8ea3fb582446c5375c:a39aa93c-4ee1-4219-b4c5-afd75940370a:agent:smulampaka-agent9.deA.01a3",
      "id": "smulampaka-agent9.deA.01a3",
      "registered_at": "2022-07-07T05:32:24.007380557Z",
      "registered_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z",
      "user_state": {
        "state": "enable",
        "set_by": "schematics@ibm.com",
        "set_at": "2022-07-07T05:32:24.007344942Z"
      },
      "connection_state": {
        "state": "Connected",
        "checked_at": "2022-07-07T05:32:24.007386377Z"
      },
      "system_state": {}
    },
    {
      "name": "devagentapi",
      "description": "Register agent description change",
      "resource_group": "Default",
      "tags": [
        "agent"
      ],
      "agent_location": "us-south",
      "location": "eu-de",
      "agent_crn": "crn:v1:staging:public:schematics:eu-de:a/0ddd18d6a00f4e8ea3fb582446c5375c:a39aa93c-4ee1-4219-b4c5-afd75940370a:agent:devagentapi.deA.03a4",
      "id": "devagentapi.deA.03a4",
      "registered_at": "2022-07-07T05:38:06.81474461Z",
      "registered_by": "schematics@ibm.com",
      "updated_at": "2022-07-07T05:38:56.389951235Z",
      "updated_by": "schematics@ibm.com",
      "user_state": {
        "state": "enable",
        "set_by": "schematics@ibm.com",
        "set_at": "2022-07-07T05:38:06.814710293Z"
      },
      "connection_state": {
        "state": "Connected",
        "checked_at": "2022-07-07T05:38:06.814753123Z"
      },
      "system_state": {}
    }
  ]
}
Register the agent with schematics
Register the agent with schematics

   
Authorization
 

Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see Schematics service access
roles and required permissions.


POST /v2/settings/agents
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Request Body
Required*
Agent
Register the agent with schematics.


  • curl --cart --request POST http://schematics.cloud.ibm.com/v2/settings/agents  "Authorization: <access_token>" --header "enable_blueprint: true" "Content-Type: application/json" "Github-token: github_token" -d "{"name": "devagentapi","description": "Register agent","resource_group": "Default", "tags": ["agent"],"location": "eu-de","agent_location": "us-south","profile_id": "smkumar9","user_state": {"state": "enable"}}"
Response
Response Body
Agent
The agent registration details, with user inputs and system generated data.


Status Code
  • 201
    Successfully Registered the agent
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 409
    The specified resource already exists
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "name": "devagentapi",
  "description": "Register agent",
  "resource_group": "5dcf6a39526247fa9cd1ff97a58b7dda",
  "tags": [
    "agent"
  ],
  "agent_location": "us-south",
  "location": "eu-de",
  "profile_id": "smkumar9",
  "agent_crn": "crn:v1:staging:public:schematics:eu-de:a/0ddd18d6a00f4e8ea3fb582446c5375c:a39aa93c-4ee1-4219-b4c5-afd75940370a:agent:devagentapi.deA.03a4",
  "id": "devagentapi.deA.03a4",
  "registered_at": "2022-07-07T05:38:06.814728043Z",
  "registered_by": "schematics@ibm.com",
  "updated_at": "0001-01-01T00:00:00Z",
  "user_state": {
    "state": "enable",
    "set_by": "schematics@ibm.com",
    "set_at": "2022-07-07T05:38:06.814719738Z"
  },
  "connection_state": {
    "state": "Connected",
    "checked_at": "2022-07-07T05:38:06.814736503Z"
  },
  "system_state": {}
}
Get the registered agent details
Reterive list the registered agent details

   
Authorization
 

Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see Schematics service access
roles and required permissions.


GET /v2/settings/agents/{agent_id}
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • agent_id
    Required*
    string
    Agent ID to get the details of agent
    

Query Parameters
  • profile
    string
    Level of details returned by the get method
    

    Allowable values: [summary,detailed,ids]
  • curl --request GET http://schematics.cloud.ibm.com/v2/settings/agents/{agent_id} --header "Authorization: <access_token>" 'X-Feature-Agents: true' "refresh_token: <refresh-token>"
Response
Response Body
Agent
The agent registration details, with user inputs and system generated data.


Status Code
  • 200
    Successfully got the agent details
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 404
    The specified resource was not found
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "name": "agent-beta1-testing",
  "description": "Create Agent",
  "resource_group": "schematics-prod",
  "tags": [
    "env:prod",
    "mytest"
  ],
  "version": "v1.0.0",
  "schematics_location": "us-south",
  "agent_location": "us-south",
  "user_state": {
    "state": "enable",
    "set_by": "schematics@in.ibm.com",
    "set_at": "2023-03-16T06:12:13.684097462Z"
  },
  "agent_crn": "crn:v1:bluemix:public:schematics:us-south:a/<crn>:agent:agent-beta1-testing.soA.748e",
  "created_at": "2023-03-16T06:12:13.684112846Z",
  "creation_by": "schematics@in.ibm.com",
  "updated_at": "0001-01-01T00:00:00Z",
  "system_state": {
    "status_code": "draft"
  },
  "agent_kpi": {
    "availability_indicator": "normal",
    "lifecycle_indicator": "consistent",
    "percent_usage_indicator": "30%"
  }
}
Deregister the agent
Deregistering an agent.

   
Authorization
 

Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see Schematics service access
roles and required permissions.


DELETE /v2/settings/agents/{agent_id}
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • agent_id
    Required*
    string
    Agent ID to get the details of agent
    

  • curl -X DELETE https://schematics.cloud.ibm.com/v2/agents/<agent_id>   -H 'Authorization: Bearer <Auth Key>'   -H 'X-Feature-Agents: true'   -H 'refresh_token: <refresh_token>'
  • DeleteAgentDataOptions deleteAgentDataOptions = new DeleteAgentDataOptions.Builder().xFeatureAgents(true)
.agentId("<agent_id>")
.build();

Response<Void> response = service.deleteAgentData(deleteAgentDataOptions).execute();

Void agentList = response.getResult();
System.out.println(agentList);  

  • response =  schematics_service.delete_agent_data("<agent_id>")agent_list = response.get_result()

print(json.dumps(agent_list, indent=2))                     

  • const params = {xFeatureAgents: true,
agentId: "<agent_id>",
};

schematicsService
.deleteAgentData(params)
.then(response => {
console.log(response.result);
})
.catch(err => {
console.warn(err);
});  

  • result, detailedResponse, err :=  schematicsService.GetAgentData(&schematicsv1.GetAgentDataOptions{XFeatureAgents: core.BoolPtr(true),
AgentID:        core.StringPtr("<agent_id>"),
})
if err != nil {
fmt.Printf("Failed to get the agent data : %v and the response is %s", err, detailedResponse)
}

w, err := json.Marshal(result)
fmt.Print("Agents:", string(w))  

Response
Status Code
  • 204
    Successfully deregistered the agent
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 404
    The specified resource was not found
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

No Sample Response
This method does not specify any sample responses.
Update the agent registration
Update the agent registeration.

   
Authorization
 

Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see Schematics service access
roles and required permissions.


PATCH /v2/settings/agents/{agent_id}
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • agent_id
    Required*
    string
    Agent ID to get the details of agent
    

Request Body
Required*
Agent
Update the agent registration.


  • curl --cart --request PATCH http://schematics.cloud.ibm.com/v2/settings/agents/{agent_id} "Authorization: <access_token>" --header "enable_blueprint: true" "Content-Type: application/json" "Github-token: github_token" -d "{"name": "devagentapi","description": "Register agent description change","resource_group": "Default", "tags": ["agent"],"location": "eu-de","agent_location": "us-south","profile_id": "smkumar9","user_state": {"state": "enable"}}"
Response
Response Body
Agent
The agent registration details, with user inputs and system generated data.


Status Code
  • 201
    Successfully Registered the agent
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 409
    The specified resource already exists
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "name": "devagentapi",
  "description": "Register agent description change",
  "resource_group": "5dcf6a39526247fa9cd1ff97a58b7dda",
  "tags": [
    "agent"
  ],
  "agent_location": "us-south",
  "location": "eu-de",
  "profile_id": "smkumar9",
  "agent_crn": "crn:v1:staging:public:schematics:eu-de:a/0ddd18d6a00f4e8ea3fb582446c5375c:a39aa93c-4ee1-4219-b4c5-afd75940370a:agent:devagentapi.deA.03a4",
  "id": "devagentapi.deA.03a4",
  "registered_at": "2022-07-07T05:38:06.81474461Z",
  "registered_by": "schematics@ibm.com",
  "updated_at": "2022-07-07T05:38:56.389947172Z",
  "updated_by": "schematics@ibm.com",
  "user_state": {
    "state": "enable",
    "set_by": "schematics@ibm.com",
    "set_at": "2022-07-07T05:38:06.814719738Z"
  },
  "connection_state": {
    "state": "Connected",
    "checked_at": "2022-07-07T05:38:06.814753123Z"
  },
  "system_state": {}
}
List agents
Retrieve a list of Schematics agents from your IBM Cloud account that you have access to. The list of agents that is returned depends on the API endpoint that you use. For example, if you use an API endpoint for a geography, such as North America, only agents that are created in us-south or us-east` are returned. For more information about frequently asked questions, see FAQ and Troubleshooting guide.
For more information about supported API endpoints, see API endpoint.

   
Authorization
 

Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see Schematics service access
roles and required permissions.


GET /v2/agents
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Query Parameters
  • offset
    integer
    The starting position of the item in the list of items. For example, if you have three workspaces in your account, the first workspace is assigned position number 0, the second workspace is assigned position number 1, and so forth. If you have 6 workspaces and you want to list the details for workspaces 2-6, enter 1. To limit the number of workspaces that is returned, use the limit option in addition to the offset option. Negative numbers are not supported and are ignored.
    

    Possible values:  value ≥ 0
  • limit
    integer
    The maximum number of items that you want to list. The number must be a positive integer between 1 and 2000. If no value is provided, 100 is used by default.
    

    Possible values:  1 ≤ value ≤ 2000
    Default: 100
  • profile
    string
    Level of details returned by the get method
    

    Allowable values: [summary,detailed,ids]
  • filter
    string
    Use new to get all unregistered agents; use saved to get all registered agents.
    

    Allowable values: [all,new,saved]
  • curl https://schematics.cloud.ibm.com/v2/agents   -H 'Authorization: Bearer <Auth Key>'   -H 'X-Feature-Agents: true'   -H 'refresh_token: <refresh_token>'
  • ListAgentDataOptions listAgentDataOptions = new ListAgentDataOptions.Builder().xFeatureAgents(true)
.build();

Response<AgentDataList> response = service.listAgentData(listAgentDataOptions).execute();

AgentDataList agentList = response.getResult();
System.out.println(agentList);                    

  • response = schematics_service.list_agent_data()
agent_list = response.get_result()

print(json.dumps(agent_list, indent=2))

  • const params = {xFeatureAgents: true,
};
schematicsService
.listAgentData(params)
.then(response => {
console.log(response.result);
})
.catch(err => {
console.warn(err);
});

  • result, detailedResponse, err := 
schematicsService.ListAgentData(&schematicsv1.ListAgentDataOptions
{
XFeatureAgents: core.BoolPtr(true),
})
if err != nil {
fmt.Printf("Failed to list the agent data : %v and the response is %s", err, detailedResponse)
}

w, err := json.Marshal(result)
fmt.Print("Agents:", string(w))

Response
Response Body
AgentDataList
The list of agents.


Status Code
  • 200
    Successfully listed all agents in the account
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "total_count": 2,
  "limit": 100,
  "offset": 0,
  "agents": [
    {
      "name": "smulampaka-agent9",
      "description": "Register agent",
      "resource_group": "Default",
      "tags": [
        "agent"
      ],
      "agent_location": "us-south",
      "location": "eu-de",
      "agent_crn": "crn:v1:staging:public:schematics:eu-de:a/0ddd18d6a00f4e8ea3fb582446c5375c:a39aa93c-4ee1-4219-b4c5-afd75940370a:agent:smulampaka-agent9.deA.01a3",
      "id": "smulampaka-agent9.deA.01a3",
      "registered_at": "2022-07-07T05:32:24.007380557Z",
      "registered_by": "schematics@ibm.com",
      "updated_at": "0001-01-01T00:00:00Z",
      "user_state": {
        "state": "enable",
        "set_by": "schematics@ibm.com",
        "set_at": "2022-07-07T05:32:24.007344942Z"
      },
      "connection_state": {
        "state": "Connected",
        "checked_at": "2022-07-07T05:32:24.007386377Z"
      },
      "system_state": {}
    },
    {
      "name": "devagentapi",
      "description": "Register agent description change",
      "resource_group": "Default",
      "tags": [
        "agent"
      ],
      "agent_location": "us-south",
      "location": "eu-de",
      "agent_crn": "crn:v1:staging:public:schematics:eu-de:a/0ddd18d6a00f4e8ea3fb582446c5375c:a39aa93c-4ee1-4219-b4c5-afd75940370a:agent:devagentapi.deA.03a4",
      "id": "devagentapi.deA.03a4",
      "registered_at": "2022-07-07T05:38:06.81474461Z",
      "registered_by": "schematics@ibm.com",
      "updated_at": "2022-07-07T05:38:56.389951235Z",
      "updated_by": "schematics@ibm.com",
      "user_state": {
        "state": "enable",
        "set_by": "schematics@ibm.com",
        "set_at": "2022-07-07T05:38:06.814710293Z"
      },
      "connection_state": {
        "state": "Connected",
        "checked_at": "2022-07-07T05:38:06.814753123Z"
      },
      "system_state": {}
    }
  ]
}
Create an agent
Subsequently, create an agent definition to manage the agent deployment with the agent configuration that will be used to deploy your agent to its target location.
Getting API endpoint:-


    

  • 

    The Schematics API endpoint that you use to create the agent determines where your Schematics agent run and your data is stored. For more information about supported API endpoints, see API endpoints. * If you use the API endpoint for a geography and not a specific location, such as North America, you can specify the location in your API request body. * If you do not specify the location in the request body, Schematics determines your agent location based on availability. * If you use an API endpoint for a specific location, such as Frankfurt, the location that you enter in your API request body must match your API endpoint. * You also have the option to not specify a location in your API request body if you use a location-specific API endpoint. * Follow the steps to retrieve your IAM access token and authenticate with IBM Cloud Schematics by using the API. * For more information about frequently asked questions, see FAQ and Troubleshooting guide.
    
 
    Authorization
    

    Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see Schematics service access
roles and required permissions.
    

    • 



POST /v2/agents
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Request Body
Required*
AgentData
Create the agent using schematics.


  • curl -X POST https://schematics.cloud.ibm.com/v2/agents \-H 'Authorization: Bearer <Auth Key>' -H 'X-Feature-Agents: true' -H 'refresh_token: <refresh_token> ' -d '{
"name": "AgentName",
"description": "Create Agent",
"resource_group": "Default",
"tags": [
"tag1",
"tag2"
],
"version": "v1.0.0",
"schematics_location": "us-south",
"agent_location": "us-south",
"agent_infrastructure": {
"infra_type": "ibm_kubernetes",
"cluster_id": "cluster_id",
"cluster_resource_group": "Default",
"cos_instance_name": "blueprint_basic",
"cos_bucket_name": "sample_bucket_name",
"cos_bucket_region": "us-east"
},
"agent_inputs": [
{
"name": "ibmcloud_api_key",
"value": "<api_key of the account where cluster and cos are present>",
"metadata": {
"secure": true
}
},
{
"name": "ansible_pull_ibmcloud_api_key",
"value": "jenkins api_key for pulling agents images",
"metadata": {
"secure": true
}
},
{   
"name": "devops_api_key",
"value": "api_key where you want to create agent and run fvts",
"metadata": {
"secure": true
}
}
],
"user_state": {
"state": "enable"
}
}'

  • AgentInfrastructure agentInfrastructureModel = new AgentInfrastructure.Builder().infraType("ibm_kubernetes")
.clusterId("testString")
.clusterResourceGroup("testString")
.cosInstanceName("testString")
.cosBucketName("testString")
.cosBucketRegion("testString")
.build();


AgentMetadataInfo agentMetadataInfoModel = new AgentMetadataInfo.Builder()
.name("purpose")
.value(java.util.Arrays.asList("git", "terraform", "ansible"))
.build();


VariableMetadata variableMetadataModel = new VariableMetadata.Builder()
.type("boolean")
.aliases(java.util.Arrays.asList("testString"))
.description("testString")
.cloudDataType("testString")
.defaultValue("testString")
.linkStatus("normal")
.secure(true)
.immutable(true)
.hidden(true)
.required(true)
.options(java.util.Arrays.asList("testString"))
.minValue(Long.valueOf("26"))
.maxValue(Long.valueOf("26"))
.minLength(Long.valueOf("26"))
.maxLength(Long.valueOf("26"))
.matches("testString")
.position(Long.valueOf("26"))
.groupBy("testString")
.source("testString")
.build();


VariableData variableDataModel = new VariableData.Builder()
.name("testString")
.value("testString")
.useDefault(true)
.metadata(variableMetadataModel)
.build();


AgentUserState agentUserStateModel = new AgentUserState.Builder()
.state("enable")
.build();


AgentKPIData agentKpiDataModel = new AgentKPIData.Builder()
.availabilityIndicator("available")
.lifecycleIndicator("consistent")
.percentUsageIndicator("testString")
.applicationIndicators(java.util.Arrays.asList("testString"))
.infraIndicators(java.util.Arrays.asList("testString"))
.build();


CreateAgentDataOptions createAgentDataOptionsModel = new CreateAgentDataOptions.Builder()
.xFeatureAgents(true)
.name("AgentFromJavaSDK")
.resourceGroup("Default")
.version("v1.0.0")
.schematicsLocation("us-south")
.agentLocation("us-south")
.agentInfrastructure(agentInfrastructureModel)
.description("Create Agent")
.tags(java.util.Arrays.asList("testString"))
.agentMetadata(java.util.Arrays.asList(agentMetadataInfoModel))
.agentInputs(java.util.Arrays.asList(variableDataModel))
.userState(agentUserStateModel)
.agentKpi(agentKpiDataModel)
.build();

Response<AgentData> response = service.createAgentData(createAgentDataOptionsModel).execute();

AgentData agentCreate = response.getResult();
System.out.println(agentCreate);                   

  • agent_infrastructure_model = {'infra_type': 'ibm_kubernetes',
'cluster_id': 'blrpsgow026e2vt98t0g',
'cluster_resource_group': 'Default',
'cos_instance_name': 'agent-dev-cos',
'cos_bucket_name': 'agent-dev-cos-bucket',
'cos_bucket_region': 'us-south',
}

agent_metadata_info_model = {
'name': 'purpose',
'value': ['git'],
}

variable_metadata_model = {
'type': 'boolean',
'aliases': ['testString'],
'description': 'testString',
'cloud_data_type': 'testString',
'default_value': 'testString',
'link_status': 'normal',
'secure': True,
'immutable': True,
'hidden': True,
'required': True,
'options': ['testString'],
'min_value': 38,
'max_value': 38,
'min_length': 38,
'max_length': 38,
'matches': 'testString',
'position': 38,
'group_by': 'testString',
'source': 'testString',
}

variable_data_model = {
'name': 'ibmcloud_api_key',
'value': 'Uqd6nEZEkLRp2VP30H2o-b5b6qcdevpY3w9_g3hs31L5',
'use_default': True,
'metadata': variable_metadata_model,
}

agent_user_state_model = {
'state': 'enable',
}

agent_kpi_data_model = {
'availability_indicator': 'available',
'lifecycle_indicator': 'consistent',
'percent_usage_indicator': 'testString',
'application_indicators': ['testString'],
'infra_indicators': ['testString'],
}

response = schematics_service.create_agent_data(
name='MyDevAgent',
resource_group='Default',
version='v1.0.0',
schematics_location='us-south',
agent_location='us-south',
agent_infrastructure=agent_infrastructure_model,
description='Create Agent',
tags=['env:test','mytest'],
agent_metadata=[agent_metadata_info_model],
agent_inputs=[variable_data_model],
user_state=agent_user_state_model,
agent_kpi=agent_kpi_data_model,
)

agent_data = response.get_result()
print(json.dumps(agent_data, indent=2))

  • const agentInfrastructureModel = {
infra_type: 'ibm_kubernetes',
cluster_id: 'testString',
cluster_resource_group: 'testString',
cos_instance_name: 'testString',
cos_bucket_name: 'testString',
cos_bucket_region: 'testString',
};

const agentMetadataInfoModel = {
name: 'purpose',
value: ['git', 'terraform', 'ansible'],
};

const variableMetadataModel = {
type: 'boolean',
aliases: ['testString'],
description: 'testString',
cloud_data_type: 'testString',
default_value: 'testString',
link_status: 'normal',
secure: true,
immutable: true,
hidden: true,
required: true,
options: ['testString'],
min_value: 38,
max_value: 38,
min_length: 38,
max_length: 38,
matches: 'testString',
position: 38,
group_by: 'testString',
source: 'testString',
};

const variableDataModel = {
name: 'testString',
value: 'testString',
use_default: true,
metadata: variableMetadataModel,
};

const agentUserStateModel = {
state: 'enable',
};

const agentKpiDataModel = {
availability_indicator: 'available',
lifecycle_indicator: 'consistent',
percent_usage_indicator: 'testString',
application_indicators: ['testString'],
infra_indicators: ['testString'],
};

const params = {
name: 'AgentFromNode',
resourceGroup: 'Default',
version: 'v1.0.0',
schematicsLocation: 'us-south',
agentLocation: 'us-south',
agentInfrastructure: agentInfrastructureModel,
description: 'Create Agent',
tags: ['testString'],
agentMetadata: [agentMetadataInfoModel],
agentInputs: [variableDataModel],
userState: agentUserStateModel,
agentKpi: agentKpiDataModel,
xFeatureAgents: true,
};

schematicsService
.createAgentData(params)
.then(response => {
console.log(response.result);
})
.catch(err => {
console.warn(err);
});

  • agentInfrastructureModel := new(schematicsv1.AgentInfrastructure) agentInfrastructureModel.InfraType = core.StringPtr("ibm_kubernetes")
agentInfrastructureModel.ClusterID = core.StringPtr("testString")
agentInfrastructureModel.ClusterResourceGroup = core.StringPtr("testString")
agentInfrastructureModel.CosInstanceName = core.StringPtr("testString")
agentInfrastructureModel.CosBucketName = core.StringPtr("testString")
agentInfrastructureModel.CosBucketRegion = core.StringPtr("testString")

agentMetadataInfoModel := new(schematicsv1.AgentMetadataInfo)
agentMetadataInfoModel.Name = core.StringPtr("purpose")
agentMetadataInfoModel.Value = []string{"git", "terraform", "ansible"}

variableMetadataModel := new(schematicsv1.VariableMetadata)
variableMetadataModel.Type = core.StringPtr("boolean")
variableMetadataModel.Aliases = []string{"testString"}
variableMetadataModel.Description = core.StringPtr("testString")
variableMetadataModel.CloudDataType = core.StringPtr("testString")
variableMetadataModel.DefaultValue = core.StringPtr("testString")
variableMetadataModel.LinkStatus = core.StringPtr("normal")
variableMetadataModel.Secure = core.BoolPtr(true)
variableMetadataModel.Immutable = core.BoolPtr(true)
variableMetadataModel.Hidden = core.BoolPtr(true)
variableMetadataModel.Required = core.BoolPtr(true)
variableMetadataModel.Options = []string{"testString"}
variableMetadataModel.MinValue = core.Int64Ptr(int64(38))
variableMetadataModel.MaxValue = core.Int64Ptr(int64(38))
variableMetadataModel.MinLength = core.Int64Ptr(int64(38))
variableMetadataModel.MaxLength = core.Int64Ptr(int64(38))
variableMetadataModel.Matches = core.StringPtr("testString")
variableMetadataModel.Position = core.Int64Ptr(int64(38))
variableMetadataModel.GroupBy = core.StringPtr("testString")
variableMetadataModel.Source = core.StringPtr("testString")

variableDataModel := new(schematicsv1.VariableData)
variableDataModel.Name = core.StringPtr("testString")
variableDataModel.Value = core.StringPtr("testString")
variableDataModel.UseDefault = core.BoolPtr(true)
variableDataModel.Metadata = variableMetadataModel

agentUserStateModel := new(schematicsv1.AgentUserState)
agentUserStateModel.State = core.StringPtr("enable")

agentKpiDataModel := new(schematicsv1.AgentKPIData)
agentKpiDataModel.AvailabilityIndicator = core.StringPtr("available")
agentKpiDataModel.LifecycleIndicator = core.StringPtr("consistent")
agentKpiDataModel.PercentUsageIndicator = core.StringPtr("testString")
agentKpiDataModel.ApplicationIndicators = []interface{}{"testString"}
agentKpiDataModel.InfraIndicators = []interface{}{"testString"}

result, detailedResponse, err := schematicsService.CreateAgentData(&schematicsv1.CreateAgentDataOptions{
XFeatureAgents:      core.BoolPtr(true),
Name:                core.StringPtr("MyDevAgentNithin"),
ResourceGroup:       core.StringPtr("Default"),
Version:             core.StringPtr("v1.0.0"),
SchematicsLocation:  core.StringPtr("us-south"),
AgentLocation:       core.StringPtr("us-south"),
AgentInfrastructure: agentInfrastructureModel,
Description:         core.StringPtr("Create Agent"),
Tags:                []string{"testString"},
AgentMetadata:       []schematicsv1.AgentMetadataInfo{*agentMetadataInfoModel},
AgentInputs:         []schematicsv1.VariableData{*variableDataModel},
UserState:           agentUserStateModel,
AgentKpi:            agentKpiDataModel,
})
if err != nil {
fmt.Printf("Failed to create the agent : %v and the response is %s", err, detailedResponse)
}

w, err := json.Marshal(result)
fmt.Print("Agents:", string(w)))

Response
Response Body
AgentData
The agent details, with user inputs and system generated data.


Status Code
  • 201
    Successfully created the agent
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 409
    The specified resource already exists
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "name": "agent-beta1-testing",
  "description": "Create Agent",
  "resource_group": "ba8818923fe846e6a8fb5c6d72075768",
  "tags": [
    "env:prod",
    "mytest"
  ],
  "version": "v1.0.0",
  "schematics_location": "us-south",
  "agent_location": "us-south",
  "user_state": {
    "state": "enable",
    "set_by": "test@in.ibm.com",
    "set_at": "2023-03-16T06:12:13.684097462Z"
  },
  "agent_crn": "crn:v1:bluemix:public:schematics:us-south:a/<crn_value>:agent:agent-beta1-testing.soA.748e",
  "id": "agent-beta1-testing.soA.748e",
  "created_at": "2023-03-16T06:12:13.684112846Z",
  "creation_by": "test@in.ibm.com",
  "updated_at": "0001-01-01T00:00:00Z",
  "system_state": {
    "status_code": "draft"
  }
}
Get agent details
Retrieve a detailed configuration of an agent with a specific agent ID. The agent that is returned depends on the API endpoint that you use. For example, if you use an API endpoint for a geography, such as North America, only agents that are created in us-south or us-east` are returned. For more information about frequently asked questions, see FAQ and Troubleshooting guide.
For more information about supported API endpoints, see API endpoint.

   
Authorization
 

Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see Schematics service access
roles and required permissions.


GET /v2/agents/{agent_id}
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • agent_id
    Required*
    string
    Agent ID to get the details of agent
    

Query Parameters
  • profile
    string
    Level of details returned by the get method
    

    Allowable values: [summary,detailed,ids]
  • curl https://schematics.cloud.ibm.com/v2/agents/<agent_id>   -H 'Authorization: Bearer <ApiKey>'   -H 'X-Feature-Agents: true'   -H 'refresh_token: <refresh token>'
  • GetAgentDataOptions getAgentDataOptions = new GetAgentDataOptions.Builder().xFeatureAgents(true)
.agentId("<agent_id>")
.build();

Response<AgentData> response = service.getAgentData(getAgentDataOptions).execute();

AgentData agentList = response.getResult();
System.out.println(agentList);                   

  • response =  schematics_service.get_agent_data("<agent_id>")agent_list = response.get_result()

print(json.dumps(agent_list, indent=2)) 

  • const params = {xFeatureAgents: true,
agentId: "MyDevAgentNithinNew.soA.f2ed",
};

schematicsService
.getAgentData(params)
.then(response => {
console.log(response.result);
})
.catch(err => {
console.warn(err);
});

  • result, detailedResponse, err :=  schematicsService.GetAgentData(&schematicsv1.GetAgentDataOptions{XFeatureAgents: core.BoolPtr(true),
AgentID:        core.StringPtr("<agent_id>"),
})
if err != nil {
fmt.Printf("Failed to get the agent data : %v and the response is %s", err, detailedResponse)
}

w, err := json.Marshal(result)
fmt.Print("Agents:", string(w))
 

Response
Response Body
AgentData
The agent details, with user inputs and system generated data.


Status Code
  • 200
    Successfully got the agent details
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 404
    The specified resource was not found
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "name": "agent-beta1-testing",
  "description": "Create Agent",
  "resource_group": "schematics-prod",
  "tags": [
    "env:prod",
    "mytest"
  ],
  "version": "v1.0.0",
  "schematics_location": "us-south",
  "agent_location": "us-south",
  "user_state": {
    "state": "enable",
    "set_by": "schematics@in.ibm.com",
    "set_at": "2023-03-16T06:12:13.684097462Z"
  },
  "agent_crn": "crn:v1:bluemix:public:schematics:us-south:a/<crn>:agent:agent-beta1-testing.soA.748e",
  "created_at": "2023-03-16T06:12:13.684112846Z",
  "creation_by": "schematics@in.ibm.com",
  "updated_at": "0001-01-01T00:00:00Z",
  "system_state": {
    "status_code": "draft"
  },
  "agent_kpi": {
    "availability_indicator": "normal",
    "lifecycle_indicator": "consistent",
    "percent_usage_indicator": "30%"
  }
}
Update agent
Use update agent API to update or replace the entire agent. For more information about steps to apply UPDATE and PUT command, see Deploying agent.
For more information about supported API endpoints, see API endpoint.

   
Authorization
 

Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see Schematics service access
roles and required permissions.


PUT /v2/agents/{agent_id}
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

  • refresh_token
    string
    This IAM token is required only when trying to update an agent from one version to other.
    

    Retrieving refresh token:
    

      

    • Use export IBMCLOUD_API_KEY=<ibmcloud_api_key>, and execute curl -X POST "https://iam.cloud.ibm.com/identity/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$IBMCLOUD_API_KEY" -u bx:bx.
      • 

    • For more information, about creating IAM access token and API Docs, refer, IAM access token and Create API key.
      • 

    

    Limitation:
    

      

    • If the token is expired, you can use refresh token to get a new IAM access token.
      • 

    • The refresh_token parameter cannot be used to retrieve a new IAM access token.
      • 

    • When the IAM access token is about to expire, use the API key to create a new access token.
      • 

    

Path Parameters
  • agent_id
    Required*
    string
    Agent ID to get the details of agent
    

Request Body
Required*
AgentData
Update the agent registration.


  • curl -X PUT https://schematics.cloud.ibm.com/v2/agents/{agent_id} \-H 'Authorization: Bearer <Auth Key>' -H 'X-Feature-Agents: true' -H 'refresh_token: <refresh_token> ' -d '{
"name": "AgentName",
"description": "New Description",
"resource_group": "Default",
"tags": [
"tag1",
"tag2"
],
"version": "v1.0.0",
"schematics_location": "us-south",
"agent_location": "us-south",
"agent_infrastructure": {
"infra_type": "ibm_kubernetes",
"cluster_id": "cluster_id",
"cluster_resource_group": "Default",
"cos_instance_name": "blueprint_basic",
"cos_bucket_name": "sample_bucket_name",
"cos_bucket_region": "us-east"
},
"agent_inputs": [
{
"name": "ibmcloud_api_key",
"value": "<api_key of the account where cluster and cos are present>",
"metadata": {
"secure": true
}
},
{
"name": "ansible_pull_ibmcloud_api_key",
"value": "jenkins api_key for pulling agents images",
"metadata": {
"secure": true
}
},
{   
"name": "devops_api_key",
"value": "api_key where you want to create agent and run fvts",
"metadata": {
"secure": true
}
}
],
"user_state": {
"state": "enable"
}
}'

  • AgentInfrastructure agentInfrastructureModel = new AgentInfrastructure.Builder().infraType("ibm_kubernetes")
.clusterId("testString")
.clusterResourceGroup("testString")
.cosInstanceName("testString")
.cosBucketName("testString")
.cosBucketRegion("testString")
.build();


AgentMetadataInfo agentMetadataInfoModel = new AgentMetadataInfo.Builder()
.name("purpose")
.value(java.util.Arrays.asList("git", "terraform", "ansible"))
.build();


VariableMetadata variableMetadataModel = new VariableMetadata.Builder()
.type("boolean")
.aliases(java.util.Arrays.asList("testString"))
.description("testString")
.cloudDataType("testString")
.defaultValue("testString")
.linkStatus("normal")
.secure(true)
.immutable(true)
.hidden(true)
.required(true)
.options(java.util.Arrays.asList("testString"))
.minValue(Long.valueOf("26"))
.maxValue(Long.valueOf("26"))
.minLength(Long.valueOf("26"))
.maxLength(Long.valueOf("26"))
.matches("testString")
.position(Long.valueOf("26"))
.groupBy("testString")
.source("testString")
.build();


VariableData variableDataModel = new VariableData.Builder()
.name("testString")
.value("testString")
.useDefault(true)
.metadata(variableMetadataModel)
.build();


AgentUserState agentUserStateModel = new AgentUserState.Builder()
.state("enable")
.build();


AgentKPIData agentKpiDataModel = new AgentKPIData.Builder()
.availabilityIndicator("available")
.lifecycleIndicator("consistent")
.percentUsageIndicator("testString")
.applicationIndicators(java.util.Arrays.asList("testString"))
.infraIndicators(java.util.Arrays.asList("testString"))
.build();


CreateAgentDataOptions createAgentDataOptionsModel = new CreateAgentDataOptions.Builder()
.xFeatureAgents(true)
.agentId("<agent_id>")  
.name("AgentFromJavaSDK")
.resourceGroup("Default")
.version("v1.0.0")
.schematicsLocation("us-south")
.agentLocation("us-south")
.agentInfrastructure(agentInfrastructureModel)
.description("New Description")
.tags(java.util.Arrays.asList("testString"))
.agentMetadata(java.util.Arrays.asList(agentMetadataInfoModel))
.agentInputs(java.util.Arrays.asList(variableDataModel))
.userState(agentUserStateModel)
.agentKpi(agentKpiDataModel)
.build();

Response<AgentData> response = service.updateAgentData(updateAgentDataOptionsModel).execute();

AgentData agentUpdate = response.getResult();
System.out.println(agentUpdate);                     

  • agent_infrastructure_model = {'infra_type': 'ibm_kubernetes',
'cluster_id': 'blrpsgow026e2vt98t0g',
'cluster_resource_group': 'Default',
'cos_instance_name': 'agent-dev-cos',
'cos_bucket_name': 'agent-dev-cos-bucket',
'cos_bucket_region': 'us-south',
}

agent_metadata_info_model = {
'name': 'purpose',
'value': ['git'],
}

variable_metadata_model = {
'type': 'boolean',
'aliases': ['testString'],
'description': 'testString',
'cloud_data_type': 'testString',
'default_value': 'testString',
'link_status': 'normal',
'secure': True,
'immutable': True,
'hidden': True,
'required': True,
'options': ['testString'],
'min_value': 38,
'max_value': 38,
'min_length': 38,
'max_length': 38,
'matches': 'testString',
'position': 38,
'group_by': 'testString',
'source': 'testString',
}

variable_data_model = {
'name': 'ibmcloud_api_key',
'value': 'Uqd6nEZEkLRp2VP30H2o-b5b6qcdevpY3w9_g3hs31L5',
'use_default': True,
'metadata': variable_metadata_model,
}

agent_user_state_model = {
'state': 'enable',
}

agent_kpi_data_model = {
'availability_indicator': 'available',
'lifecycle_indicator': 'consistent',
'percent_usage_indicator': 'testString',
'application_indicators': ['testString'],
'infra_indicators': ['testString'],
}

response = schematics_service.update_agent_data(
agent_id='<agent_id>', 
name='MyDevAgent',
resource_group='Default',
version='v1.0.0',
schematics_location='us-south',
agent_location='us-south',
agent_infrastructure=agent_infrastructure_model,
description='Create Agent',
tags=['env:test','mytest'],
agent_metadata=[agent_metadata_info_model],
agent_inputs=[variable_data_model],
user_state=agent_user_state_model,
agent_kpi=agent_kpi_data_model,
)

agent_data = response.get_result()
print(json.dumps(agent_data, indent=2))

  • const agentInfrastructureModel = {infra_type: 'ibm_kubernetes',
cluster_id: 'testString',
cluster_resource_group: 'testString',
cos_instance_name: 'testString',
cos_bucket_name: 'testString',
cos_bucket_region: 'testString',
};

const agentMetadataInfoModel = {
name: 'purpose',
value: ['git', 'terraform', 'ansible'],
};

const variableMetadataModel = {
type: 'boolean',
aliases: ['testString'],
description: 'testString',
cloud_data_type: 'testString',
default_value: 'testString',
link_status: 'normal',
secure: true,
immutable: true,
hidden: true,
required: true,
options: ['testString'],
min_value: 38,
max_value: 38,
min_length: 38,
max_length: 38,
matches: 'testString',
position: 38,
group_by: 'testString',
source: 'testString',
};

const variableDataModel = {
name: 'testString',
value: 'testString',
use_default: true,
metadata: variableMetadataModel,
};

const agentUserStateModel = {
state: 'enable',
};

const agentKpiDataModel = {
availability_indicator: 'available',
lifecycle_indicator: 'consistent',
percent_usage_indicator: 'testString',
application_indicators: ['testString'],
infra_indicators: ['testString'],
};

const params = {
agentId: 'AgentFromNode.soA.3c2f',
name: 'AgentFromNode',
resourceGroup: 'Default',
version: 'v1.0.0',
schematicsLocation: 'us-south',
agentLocation: 'us-south',
agentInfrastructure: agentInfrastructureModel,
description: 'New Description',
tags: ['testString'],
agentMetadata: [agentMetadataInfoModel],
agentInputs: [variableDataModel],
userState: agentUserStateModel,
agentKpi: agentKpiDataModel,
xFeatureAgents: true,
};

schematicsService
.updateAgentData(params)
.then(response => {
console.log(response.result);
})
.catch(err => {
console.warn(err);
});

  • agentInfrastructureModel := new(schematicsv1.AgentInfrastructure) agentInfrastructureModel.InfraType = core.StringPtr("ibm_kubernetes")
agentInfrastructureModel.ClusterID = core.StringPtr("testString")
agentInfrastructureModel.ClusterResourceGroup = core.StringPtr("testString")
agentInfrastructureModel.CosInstanceName = core.StringPtr("testString")
agentInfrastructureModel.CosBucketName = core.StringPtr("testString")
agentInfrastructureModel.CosBucketRegion = core.StringPtr("testString")

agentMetadataInfoModel := new(schematicsv1.AgentMetadataInfo)
agentMetadataInfoModel.Name = core.StringPtr("purpose")
agentMetadataInfoModel.Value = []string{"git", "terraform", "ansible"}

variableMetadataModel := new(schematicsv1.VariableMetadata)
variableMetadataModel.Type = core.StringPtr("boolean")
variableMetadataModel.Aliases = []string{"testString"}
variableMetadataModel.Description = core.StringPtr("testString")
variableMetadataModel.CloudDataType = core.StringPtr("testString")
variableMetadataModel.DefaultValue = core.StringPtr("testString")
variableMetadataModel.LinkStatus = core.StringPtr("normal")
variableMetadataModel.Secure = core.BoolPtr(true)
variableMetadataModel.Immutable = core.BoolPtr(true)
variableMetadataModel.Hidden = core.BoolPtr(true)
variableMetadataModel.Required = core.BoolPtr(true)
variableMetadataModel.Options = []string{"testString"}
variableMetadataModel.MinValue = core.Int64Ptr(int64(38))
variableMetadataModel.MaxValue = core.Int64Ptr(int64(38))
variableMetadataModel.MinLength = core.Int64Ptr(int64(38))
variableMetadataModel.MaxLength = core.Int64Ptr(int64(38))
variableMetadataModel.Matches = core.StringPtr("testString")
variableMetadataModel.Position = core.Int64Ptr(int64(38))
variableMetadataModel.GroupBy = core.StringPtr("testString")
variableMetadataModel.Source = core.StringPtr("testString")

variableDataModel := new(schematicsv1.VariableData)
variableDataModel.Name = core.StringPtr("testString")
variableDataModel.Value = core.StringPtr("testString")
variableDataModel.UseDefault = core.BoolPtr(true)
variableDataModel.Metadata = variableMetadataModel

agentUserStateModel := new(schematicsv1.AgentUserState)
agentUserStateModel.State = core.StringPtr("enable")

agentKpiDataModel := new(schematicsv1.AgentKPIData)
agentKpiDataModel.AvailabilityIndicator = core.StringPtr("available")
agentKpiDataModel.LifecycleIndicator = core.StringPtr("consistent")
agentKpiDataModel.PercentUsageIndicator = core.StringPtr("testString")
agentKpiDataModel.ApplicationIndicators = []interface{}{"testString"}
agentKpiDataModel.InfraIndicators = []interface{}{"testString"}

result, detailedResponse, err := schematicsService.UpdateAgentData(&schematicsv1.UpdateAgentDataOptions{
AgentID:             core.StringPtr("<agent_id>"),
XFeatureAgents:      core.BoolPtr(true),
Name:                core.StringPtr("MyDevAgentNithin"),
ResourceGroup:       core.StringPtr("Default"),
Version:             core.StringPtr("v1.0.0"),
SchematicsLocation:  core.StringPtr("us-south"),
AgentLocation:       core.StringPtr("us-south"),
AgentInfrastructure: agentInfrastructureModel,
Description:         core.StringPtr("Create Agent"),
Tags:                []string{"testString"},
AgentMetadata:       []schematicsv1.AgentMetadataInfo{*agentMetadataInfoModel},
AgentInputs:         []schematicsv1.VariableData{*variableDataModel},
UserState:           agentUserStateModel,
AgentKpi:            agentKpiDataModel,
})
if err != nil {
fmt.Printf("Failed to create the agent : %v and the response is %s", err, detailedResponse)
}

w, err := json.Marshal(result)
fmt.Print("Agents:", string(w)))

Response
Response Body
AgentData
The agent details, with user inputs and system generated data.


Status Code
  • 201
    Successfully Updated the agent
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 409
    The specified resource already exists
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "name": "agent-beta1-testing",
  "description": "New Description",
  "resource_group": "ba8818923fe846e6a8fb5c6d72075768",
  "tags": [
    "env:prod",
    "mytest"
  ],
  "version": "v1.0.0",
  "schematics_location": "us-south",
  "agent_location": "us-south",
  "user_state": {
    "state": "enable",
    "set_by": "test@in.ibm.com",
    "set_at": "2023-03-16T06:12:13.684097462Z"
  },
  "agent_crn": "crn:v1:bluemix:public:schematics:us-south:a/<crn_value>:agent:agent-beta1-testing.soA.748e",
  "id": "agent-beta1-testing.soA.748e",
  "created_at": "2023-03-16T06:12:13.684112846Z",
  "creation_by": "test@in.ibm.com",
  "updated_at": "0001-01-01T00:00:00Z",
  "system_state": {
    "status_code": "draft"
  }
}
Delete agent
Use this API to disable and delete the agent. Follow the steps to retrieve your IAM access token and authenticate with IBM Cloud Schematics by using the API.
For more information about frequently asked questions, see FAQ and Troubleshooting guide.

   
Authorization
 

Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see Schematics service access
roles and required permissions.


DELETE /v2/agents/{agent_id}
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • agent_id
    Required*
    string
    Agent ID to get the details of agent
    

Query Parameters
  • force
    boolean
    Equivalent to -force options in the command line, default is false
    

  • curl -X DELETE https://schematics.cloud.ibm.com/v2/agents/<agent_id>   -H 'Authorization: Bearer <Auth Key>'   -H 'X-Feature-Agents: true'   -H 'refresh_token: <refresh_token>'
  • DeleteAgentDataOptions deleteAgentDataOptions = new DeleteAgentDataOptions.Builder().xFeatureAgents(true)
.agentId("<agent_id>")
.build();

Response<Void> response = service.deleteAgentData(deleteAgentDataOptions).execute();

Void agentList = response.getResult();
System.out.println(agentList);  

  • response =  schematics_service.delete_agent_data("<agent_id>")agent_list = response.get_result()

print(json.dumps(agent_list, indent=2))                     

  • const params = {xFeatureAgents: true,
agentId: "<agent_id>",
};

schematicsService
.deleteAgentData(params)
.then(response => {
console.log(response.result);
})
.catch(err => {
console.warn(err);
});  

  • result, detailedResponse, err :=  schematicsService.GetAgentData(&schematicsv1.GetAgentDataOptions{XFeatureAgents: core.BoolPtr(true),
AgentID:        core.StringPtr("<agent_id>"),
})
if err != nil {
fmt.Printf("Failed to get the agent data : %v and the response is %s", err, detailedResponse)
}

w, err := json.Marshal(result)
fmt.Print("Agents:", string(w))  

Response
Status Code
  • 204
    Successfully deleted the agent
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 404
    The specified resource was not found
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

No Sample Response
This method does not specify any sample responses.
Get agent versions
Retrieve the list of agent version's available to be deployed.
For more information about supported API endpoints, see API endpoint.

   
Authorization
 

Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see Schematics service access
roles and required permissions.


GET /v2/agents/versions
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

  • curl --request GET \ --url https://schematics.cloud.ibm.com/v2/agents/versions \ --header 'authorization: Bearer <access_key>' \ --header 'refresh_token: <refresh_token>' \ --header 'x-feature-agents: true'
Response
Response Body
AgentVersions
Agent versions available to be deployed


Status Code
  • 200
    Successfully got the agent versions.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 404
    The specified resource was not found
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "supported_agent_versions": [
    {
      "display_name": "v1.0.0",
      "agent_version": "1.0.0"
    },
    {
      "display_name": "v1.0.0-beta2",
      "agent_version": "1.0.0-beta2"
    }
  ]
}
Get pre-requisite scanner job status
Use get pre-requisite scanner job status API for deploying an agent by using the agent_id, job_id. The API results the status as pending, in-progress, success, or failed in a string format. For more information about supported API endpoints, see API endpoint.


Authorization


Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access
roles and required permissions.


GET /v2/agents/{agent_id}/prs
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • agent_id
    Required*
    string
    Agent ID to get the details of agent
    

  • curl --request GET \ --url https://schematics.cloud.ibm.com/v2/agents/<agent_id>/prs \ --header 'authorization: Bearer <access_key>' \ --header 'refresh_token: <refresh_token>' \ --header 'x-feature-agents: true'
Response
Response Body
AgentPRSJob
Run a pre-requisite scanner for deploying agent.


Status Code
  • 202
    Successfully retrieved pre-requisite scanner job status.
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 409
    The specified resource already exists
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

No Sample Response
This method does not specify any sample responses.
Run pre-requisite scanner job
Use run pre-requisite scanner job API before deploying an agent. The API results the agent prs job updation time with the E-mail address and the status in a string format. For more information about supported API endpoints, see API endpoint.


Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see [Schematics service access 
   roles and required permissions](https://cloud.ibm.com/docs/schematics?topic=schematics-access#access-roles).
PUT /v2/agents/{agent_id}/prs
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • agent_id
    Required*
    string
    Agent ID to get the details of agent
    

Query Parameters
  • force
    boolean
    Equivalent to -force options in the command line, default is false
    

  • curl --request PUT \ --url https://schematics.cloud.ibm.com/v2/agents/<agent_id>/prs \ --header 'authorization: Bearer <access_key>' \ --header 'refresh_token: <refresh_token>' \ --header 'x-feature-agents: true'
Response
Response Body
AgentPRSJob
Run a pre-requisite scanner for deploying agent.


Status Code
  • 202
    Successfully started pre-requisite scanner job.
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 409
    The specified resource already exists
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

No Sample Response
This method does not specify any sample responses.
Get agent health check job
Use get agent health check job API to retrieve the agent health check job status based on the agent ID. For more information about supported API endpoints, see API endpoint.


Authorization


Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access
roles and required permissions.


GET /v2/agents/{agent_id}/health
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • agent_id
    Required*
    string
    Agent ID to get the details of agent
    

  • curl --request GET \ --url https://schematics.cloud.ibm.com/v2/agents/<agent_id>/health \ --header 'authorization: Bearer <access_key>' \ --header 'refresh_token: <refresh_token>' \ --header 'x-feature-agents: true'
Response
Response Body
AgentHealthJob
Agent health check


Status Code
  • 202
    Successfully retrieved agent health check job status
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 409
    The specified resource already exists
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

No Sample Response
This method does not specify any sample responses.
Run agent health check
Use run agent health check job API to execute an agent health check job based on the agent ID. For more information about supported API endpoints, see API endpoint.


Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see [Schematics service access 
   roles and required permissions](https://cloud.ibm.com/docs/schematics?topic=schematics-access#access-roles).
PUT /v2/agents/{agent_id}/health
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • agent_id
    Required*
    string
    Agent ID to get the details of agent
    

Query Parameters
  • force
    boolean
    Equivalent to -force options in the command line, default is false
    

  • curl --request PUT \ --url https://schematics.cloud.ibm.com/v2/agents/<agent_id>/health \ --header 'authorization: Bearer <access_key>' \ --header 'refresh_token: <refresh_token>' \ --header 'x-feature-agents: true'
Response
Response Body
AgentHealthJob
Agent health check


Status Code
  • 202
    Successfully started running the agent health check job
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 409
    The specified resource already exists
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

No Sample Response
This method does not specify any sample responses.
Get agent deployment job
Use get agent deployment job API to retrieve the agent deployment job status based on the agent ID. For more information about supported API endpoints, see API endpoint.


Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see [Schematics service access 
   roles and required permissions](https://cloud.ibm.com/docs/schematics?topic=schematics-access#access-roles).
GET /v2/agents/{agent_id}/deploy
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • agent_id
    Required*
    string
    Agent ID to get the details of agent
    

  • curl --request GET \ --url https://schematics.cloud.ibm.com/v2/agents/<agent_id>/deploy \ --header 'authorization: Bearer <access_key>' \ --header 'refresh_token: <refresh_token>' \ --header 'x-feature-agents: true'
Response
Response Body
AgentDeployJob
Post-installations checks for Agent health.


Status Code
  • 202
    Successfully retrieved agent deployment job details
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 409
    The specified resource already exists
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

No Sample Response
This method does not specify any sample responses.
Run the agent deployment job
Use run agent deployment job API to execute the agent deployment job based on the agent ID. For more information about supported API endpoints, see API endpoint.


Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see [Schematics service access 
   roles and required permissions](https://cloud.ibm.com/docs/schematics?topic=schematics-access#access-roles).
PUT /v2/agents/{agent_id}/deploy
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • agent_id
    Required*
    string
    Agent ID to get the details of agent
    

Query Parameters
  • force
    boolean
    Equivalent to -force options in the command line, default is false
    

  • curl --request PUT \ --url https://schematics.cloud.ibm.com/v2/agents/<agent_id>/deploy \ --header 'authorization: Bearer <access_key>' \ --header 'refresh_token: <refresh_token>' \ --header 'x-feature-agents: true'
Response
Response Body
AgentDeployJob
Post-installations checks for Agent health.


Status Code
  • 202
    Successfully ran agent deployment job
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 409
    The specified resource already exists
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

No Sample Response
This method does not specify any sample responses.
Delete resources provisioned by agent
Use this API to destroy the resources provisioned for running an agent.


DELETE /v2/agents/{agent_id}/resources
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

  • refresh_token
    Required*
    string
    The IAM refresh token for the user or service identity.
    

    Retrieving refresh token:
    

      

    • Use export IBMCLOUD_API_KEY=<ibmcloud_api_key>, and execute curl -X POST "https://iam.cloud.ibm.com/identity/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$IBMCLOUD_API_KEY" -u bx:bx.
      • 

    • For more information, about creating IAM access token and API Docs, refer, IAM access token and Create API key.
      • 

    

    Limitation:
    

      

    • If the token is expired, you can use refresh token to get a new IAM access token.
      • 

    • The refresh_token parameter cannot be used to retrieve a new IAM access token.
      • 

    • When the IAM access token is about to expire, use the API key to create a new access token.
      • 

    

Path Parameters
  • agent_id
    Required*
    string
    Agent ID to get the details of agent
    

Response
Status Code
  • 202
    Successfully accepted the request to delete the resources
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 404
    The specified resource was not found
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

No Sample Response
This method does not specify any sample responses.
Get a KMS settings
Retrieve the kms instance that is integrated with Schematics for the byok and kyok. For each geographic location supported in Schematics we can have different kms settings. For example US and EU will have different kms settings.


Authorization


Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see
Schematics service access roles and required permissions.


GET /v2/settings/kms
Auditing
Calling this method generates the following auditing event.
  • schematics.kms_settings.read
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Query Parameters
  • location
    Required*
    string
    The location of the Resource
    

  • curl --location --request GET  http://us-south.schematics.cloud.ibm.com/v2/settings/kms?location=US --header "Authorization: <access_token> "—header “Content-Type: application/json "
  • GetKmsSettingsOptions getKmsSettingsOptions = new  GetKmsSettingsOptions.Builder()
.location("US")
.build();
Response<KMSSettings> response =  service.getKmsSettings(getKmsSettingsOptions).execute();
KMSSettings kmsSettings =  response.getResult();

System.out.println(kmsSettings);
  • kms_settings = schematics_service.get_kms_settings(
  location='US'
  ).get_result()
print(json.dumps(kms_settings, indent=2))
  • const params = {
  location: 'US',
};

schematicsService.getKmsSettings(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});

  • getKmsSettingsOptions := schematicsService.NewGetKmsSettingsOptions(
"testString",
)
getKmsSettingsOptions.SetLocation("US")
kmsSettings, response, err := schematicsService.GetKmsSettings(getKmsSettingsOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(kmsSettings, "", "  ")
fmt.Println(string(b))
fmt.Println(response)
Response
Response Body
KMSSettings
User defined kms settings information.


Status Code
  • 200
    Successfully retrieved the kms settings.
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 404
    The kms settings not found.
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "location": "US",
  "encryption_scheme": "byok",
  "resource_group": "Default",
  "primary_crk": {
    "kms_name": "Key Protect-xxx",
    "key_crn": "crn:v1:public:kms:us-south:a/010101010:key:3a14ceaf-c679-455d-10101010",
    "kms_private_endpoint": "your private end point",
    "key_name": "rootk123"
  },
  "secondary_crk": null
}
Update a KMS settings
Replace or Update kms settings for a given location can be updated.
Note you can update the kms settings only once. For example, if you use an API endpoint for a geography, such as North America, only kms settings for that region can be retrieved.


Authorization


Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see
Schematics service access roles and required permissions.


PUT /v2/settings/kms
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Request Body
Required*
KMSSettings
Options to be provided with updating kms settings.


  • curl --location --request PUT https://schematics.cloud.ibm.com/v2/settings/kms?location=US --header "Authorization: <access_token> "—header “Content-Type: application/json "  --data-raw "{"location": "your-location", "encryption_scheme": "byok or kyok", "resource_group": "Default", "primary_crk": {"kms_name": "Key Protect-xxx","key_crn": "crn:v1:public:kms:us-south:a/010101010:key:3a14ceaf-c679-455d-10101010,","kms_private_endpoint": "<your_private_endpoint_url>"}}"
  • KMSSettingsPrimaryCrk setting = new KMSSettingsPrimaryCrk.Builder()
.kmsName("Key Protect-2h")
.keyCrn("crn:v1:bluemix:public:kms:us-south:a/6dd8772094b442c98deb5fe293e8f6cf:295f5cb7-07a1-4a21-b458-16a5554ab523:key:4795a33b-5923-421c-a6ea-fc884d5faf5a")
.kmsPrivateEndpoint("https://private.us-south.kms.cloud.ibm.com")
.build();
UpdateKmsSettingsOptions updateKmsSettingsOptions = new UpdateKmsSettingsOptions.Builder()
.location("US")
.encryptionScheme("byok")
.resourceGroup("Default")
.primaryCrk(setting)
.build();
Response<KMSSettings> response1 = service.updateKmsSettings(updateKmsSettingsOptions).execute();
KMSSettings kmsSettings1 = response1.getResult();
System.out.println(kmsSettings1);

  • kms_settings = schematics_service.update_kms_settings(
location='US',
encryption_scheme= "byok",
resource_group= "Default",
primary_crk= {
'kms_name': "Key Protect-2h",
'key_crn': "crn:v1:bluemix:public:kms:us-south:a/6dd8772094b442c98deb5fe293e8f6cf:295f5cb7-07a1-4a21-b458-16a5554ab523:key:4795a33b-5923-421c-a6ea-fc884d5faf5a",
'kms_private_endpoint': "https://private.us-south.kms.cloud.ibm.com",
}
).get_result()
print(json.dumps(kms_settings, indent=2))

  • const params = {
encryptionScheme:'byok',
location:'US',
resourceGroup:'Default',
primaryCrk:{
kms_name:"Key Protect-2h",
key_crn:"crn:v1:bluemix:public:kms:us-south:a/6dd8772094b442c98deb5fe293e8f6cf:295f5cb7-07a1-4a21-b458-16a5554ab523:key:4795a33b-5923-421c-a6ea-fc884d5faf5a",
kms_private_endpoint:"https://private.us-south.kms.cloud.ibm.com"
}
};
schematicsService.updateKmsSettings(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});

  • updateKmsSettingsOptions := schematicsService.NewUpdateKmsSettingsOptions()
updateKmsSettingsOptions.SetLocation("US")
updateKmsSettingsOptions.SetEncryptionScheme("byok")
updateKmsSettingsOptions.SetResourceGroup("Default")
primaryCrk := &schematicsv1.KMSSettingsPrimaryCrk{
KmsName:            core.StringPtr("Key Protect-w2"),
KeyCrn:             core.StringPtr("<crn:v1:staging"),
KmsPrivateEndpoint: core.StringPtr("https://qa.private.us-south.kms.cloud.ibm.com"),
}
updateKmsSettingsOptions.SetPrimaryCrk(primaryCrk)
kmsSettings, response, err := schematicsService.UpdateKmsSettings(updateKmsSettingsOptions)
if err != nil {
fmt.Println(err)
}
b, _ := json.MarshalIndent(kmsSettings, "", "  ")
fmt.Println(string(b))
fmt.Println(response) 

Response
Response Body
KMSSettings
User defined kms settings information.


Status Code
  • 200
    Successfully retrieved the kms settings.
    

  • 400
    Bad request - Verify the location, payload, or query parameters in the request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "location": "US",
  "encryption_scheme": "byok",
  "resource_group": "Default",
  "primary_crk": {
    "kms_name": "Key Protect-xxx",
    "key_crn": "crn:v1:public:kms:us-south:a/010101010:key:3a14ceaf-c679-455d-10101010",
    "kms_private_endpoint": "your private end point URL",
    "key_name": "rootk1"
  },
  "secondary_crk": null
}
List KMS instances
Lists the kms instances of your IBM Cloud account to find your Key Protect or Hyper Protect Crypto Services by using the location and encrypted scheme.

 
Authorization


Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see
Schematics service access roles and required permissions.


GET /v2/settings/kms_instances
Auditing
Calling this method generates the following auditing event.
  • schematics.kms_instances.read
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Query Parameters
  • encryption_scheme
    Required*
    string
    The encryption scheme to be used
    

  • location
    Required*
    string
    The location of the Resource
    

  • resource_group
    string
    The resource group (by default, fetch from all resource groups) name or ID
    

  • limit
    integer
    The maximum number of items that you want to list. The number must be a positive integer between 1 and 2000. If no value is provided, 100 is used by default.
    

    Possible values:  1 ≤ value ≤ 2000
    Default: 100
  • sort
    string
    Name of the field to sort-by;  Use the '.' character to delineate sub-resources and sub-fields (eg. owner.last_name). Prepend the field with '+' or '-', indicating 'ascending' or 'descending' (default is ascending)   Ignore unrecognized or unsupported sort field
    

  • curl --location --request GET  http://schematics.cloud.ibm.com/v2/settings/kms_instances/?location=US&encryption_scheme=byok --header "Authorization: <access_token> "—header "Content-Type: <content-type> "
  • ListKmsOptions listKmsOptions = new ListKmsOptions.Builder()
.encryptionScheme(“byok”)
.location("US")
.build();
Response<KMSDiscovery> response = service.listKms(listKmsOptions).execute();
KMSDiscovery kmsDiscovery = response.getResult();
System.out.println(kmsDiscovery);

  • kms_discovery = schematics_service.list_kms(
encryption_scheme='byok',
location='US'
).get_result()
print(json.dumps(kms_discovery, indent=2))

  • const params = {
encryptionScheme: 'byok',
location: 'US',
};
schematicsService.listKms(params)
.then(res => {
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});

  • listKmsOptions := schematicsService.NewListKmsOptions(
"testString",
"testString",
)
listKmsOptions.SetLocation("US")
listKmsOptions.SetEncryptionScheme("byok")
kmsDiscovery, response, err := schematicsService.ListKms(listKmsOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(kmsDiscovery, "", "  ")
fmt.Println(string(b))
fmt.Println(response)

Response
Response Body
KMSDiscovery
Discover kms instances in the account based on location.


Status Code
  • 200
    Successfully discovered the KMS instance from the customer account.
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 404
    kms instance not found in the account.
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "location": "US",
  "limit": "10",
  "encryption_scheme": "byok",
  "resource_group": "Default",
  "kms_instances": [
    {
      "kms_crn": "crn:v1:public:kms:us-south:a/010101010:key:3a14ceaf-c679-455d-10101010",
      "kms_name": "Key Protect-xxx",
      "keys": [
        {
          "name": "rootk123",
          "crn": "crn:v1::public:kms:us-south:alalalallala1231231la"
        }
      ],
      "public_endpoint": "https://kms.cloud.ibm.com",
      "private_endpoint": "https://kms.cloud.ibm.com"
    }
  ]
}
List policies
Retrieve a list of all policies from the account that you have access. the list of policies that is returned depends on the API endpoint that you use. For example, if you use an API endpoint for a geography, such as North America, only policies that are created in us-south or us-east are returned.
For more information about supported API endpoints, see API endpoint.

   
Authorization
 

Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see Schematics service access
roles and required permissions.


GET /v2/settings/policies
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Query Parameters
  • offset
    integer
    The starting position of the item in the list of items. For example, if you have three workspaces in your account, the first workspace is assigned position number 0, the second workspace is assigned position number 1, and so forth. If you have 6 workspaces and you want to list the details for workspaces 2-6, enter 1. To limit the number of workspaces that is returned, use the limit option in addition to the offset option. Negative numbers are not supported and are ignored.
    

    Possible values:  value ≥ 0
  • limit
    integer
    The maximum number of items that you want to list. The number must be a positive integer between 1 and 2000. If no value is provided, 100 is used by default.
    

    Possible values:  1 ≤ value ≤ 2000
    Default: 100
  • profile
    string
    Level of details returned by the get method
    

    Allowable values: [summary,detailed,ids]
  • curl -X --request GET http://schematics.cloud.ibm.com/v2/settings/policies \  --header "Authorization: <access_token> " --header -H "Content-Type: application/json" "Cookie: " 
Response
Response Body
PolicyList
The list of Schematics customization policies.


Status Code
  • 200
    Successfully listed all policies in the account
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "total_count": 2,
  "limit": 100,
  "offset": 0,
  "agents": [
    {
      "name": "policy-7004bc1a-d5bf-4908-a34a-46dfd6977722",
      "id": "policy-7004bc1a-d5bf-4908-a34a-46dfd6977722.eaP.ff3c",
      "account": "1f7277194bb748cdb1d35fd8fb85a7cb",
      "description": "Created agent-assignment-policy for the workspace: us-east.workspace.Final_test_ws-3.721df95e, agent: Agent-CLI-Final-Testing.eaA.6416",
      "resource_group": "15a5b53ee3ec4657a311fd8c0392f875",
      "location": "us-east",
      "state": {
        "state": "draft",
        "set_by": "schematics@ibm.com",
        "set_at": "2022-07-11T10:22:53.566430493Z"
      },
      "policy_kind": "agent_assignment_policy",
      "created_at": "2022-07-11T10:22:53.566430493Z",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "name": "policy-906e2aca-dc99-4e2b-8329-83d951849769",
      "id": "policy-906e2aca-dc99-4e2b-8329-83d951849769.eaP.d44b",
      "account": "1f7277194bb748cdb1d35fd8fb85a7cb",
      "description": "Created agent-assignment-policy for the workspace: us-east.workspace.agent-binded-cli-final.843f38e0, agent: cli-agent.eaA.8a61",
      "resource_group": "15a5b53ee3ec4657a311fd8c0392f875",
      "location": "us-east",
      "state": {
        "state": "draft",
        "set_by": "schematics@ibm.com",
        "set_at": "2022-07-12T09:03:07.04045137Z"
      },
      "policy_kind": "agent_assignment_policy",
      "created_at": "2022-07-12T09:03:07.04045137Z",
      "updated_at": "0001-01-01T00:00:00Z"
    }
  ]
}
Create a policy account
Use this API to create a policy using Schematics to select one or more Schematics objects (such as, Workspaces, Action) to deliver targeted Schematics feature. For more information about frequently asked questions, see FAQ and Troubleshooting guide.

   
Authorization
 

Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see Schematics service access
roles and required permissions.


POST /v2/settings/policies
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Request Body
Required*
Policy
Create a new policy in account


  • curl -X --request POST http://schematics.cloud.ibm.com/v2/settings/agents  "Authorization: <access_token>" --header "enable_blueprint: true" "Content-Type: application/json" -d "{	"name": "new-policy-dev", "description": "Policy for job execution of secured workspaces on agent1", "resource_group": "Default",	"tags": [	"policy:secured-job"], "location": "us-south",	"policy_kind": "agent_assignment_policy", "policy_target": {	"selector_kind": "ids",	"selector_ids": [	"latest-agent.soA.c4a0"	]	}, "policy_parameter": {		"agent_assignment_policy_parameter": {"selector_kind": "ids","selector_ids": ["us-south.workspace.gb.s91762c7"]}}}""
Response
Response Body
Policy
Detailed information about the Schematics customization policy.  This policy can be used to customize the behaviour or the core Schematics service.


Status Code
  • 201
    Successfully created the policy
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 409
    The specified resource already exists
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "name": "new-policy-dev",
  "description": "Policy for job execution of secured workspaces on agent1",
  "resource_group": "Default",
  "tags": [
    "policy:secured-job"
  ],
  "location": "us-south",
  "state": {
    "state": "draft",
    "set_by": "schematics@ibm.com",
    "set_at": "2022-07-12T10:54:16.270132296Z"
  },
  "policy_kind": "agent_assignment_policy",
  "policy_target": {
    "selector_kind": "ids",
    "selector_ids": [
      "latest-agent.soA.c4a0"
    ]
  },
  "policy_parameter": {
    "agent_assignment_policy_parameter": {
      "selector_kind": "ids",
      "selector_ids": [
        "us-south.workspace.gb.s91762c7"
      ]
    }
  },
  "id": "new-policy-dev.soP.b2de",
  "crn": "crn:v1:bluemix:public:schematics:us-south:a/2g7200134cc638bgh1d35fd8fb85a7cb:8ae4cd72-0k99-416c-b6ce-0b662l520a4p:policy:new-policy-dev.soP.b2de",
  "account": "1f7277194bb748cdb1d35fd8fb85a7cb",
  "created_at": "2022-07-12T10:54:16.270132296Z",
  "updated_at": "0001-01-01T00:00:00Z"
}
Get policy
Retrieve the detailed information of a policy details identified by policy_id. For more information about frequently asked questions, see FAQ and Troubleshooting guide.
For more information about supported API endpoints, see API endpoint.

   
Authorization
 

Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see Schematics service access
roles and required permissions.


GET /v2/settings/policies/{policy_id}
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • policy_id
    Required*
    string
    ID to get the details of policy
    

Query Parameters
  • profile
    string
    Level of details returned by the get method
    

    Allowable values: [summary,detailed,ids]
  • curl -X --request GET http://schematics.cloud.ibm.com/v2/settings/policies/{policy_id}  --header "Authorization: <access_token> " --header -H "Content-Type: application/json" "Cookie: " 
Response
Response Body
Policy
Detailed information about the Schematics customization policy.  This policy can be used to customize the behaviour or the core Schematics service.


Status Code
  • 200
    Successfully got the policy details
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 404
    The specified resource was not found
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "name": "new-policy-dev",
  "description": "Policy for job execution of secured workspaces on agent1",
  "resource_group": "Default",
  "tags": [
    "policy:secured-job"
  ],
  "location": "us-south",
  "state": {
    "state": "draft",
    "set_by": "schematics@ibm.com",
    "set_at": "2022-07-12T10:54:16.270132296Z"
  },
  "policy_kind": "agent_assignment_policy",
  "policy_target": {
    "selector_kind": "ids",
    "selector_ids": [
      "latest-agent.soA.c4a0"
    ]
  },
  "policy_parameter": {
    "agent_assignment_policy_parameter": {
      "selector_kind": "ids",
      "selector_ids": [
        "us-south.workspace.gb.s91762c7"
      ]
    }
  },
  "id": "new-policy-dev.soP.b2de",
  "crn": "crn:v1:bluemix:public:schematics:us-south:a/2g7200134cc638bgh1d35fd8fb85a7cb:8ae4cd72-0k99-416c-b6ce-0b662l520a4p:policy:new-policy-dev.soP.b2de",
  "account": "1f7277194bb748cdb1d35fd8fb85a7cb",
  "created_at": "2022-07-12T10:54:16.270132296Z",
  "updated_at": "0001-01-01T00:00:00Z"
}
Delete policy
Use this API to delete the policy. Follow the steps to retrieve your IAM access token and authenticate with IBM Cloud Schematics by using the API. For more information about frequently asked questions, see FAQ and Troubleshooting guide.

   
Authorization
 

Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see Schematics service access
roles and required permissions.


DELETE /v2/settings/policies/{policy_id}
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • policy_id
    Required*
    string
    ID to get the details of policy
    

  • curl -X --request DELETE https://schematics.cloud.ibm.com/v2/settings/policies/{policy_id} --header "Authorization: <access_token> "
Response
Status Code
  • 204
    Successfully deleted the policy
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 404
    The specified resource was not found
    

  • 409
    The specified resource is locked, cannot be updated or deleted
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

No Sample Response
This method does not specify any sample responses.
Update policy
Use update policy API to update or replace the policy details by using policy ID. For more information about supported API endpoints, see API endpoint. Follow the steps to retrieve your IAM access token and authenticate with IBM Cloud Schematics by using the API.
For more information about frequently asked questions, see FAQ and Troubleshooting guide.

   
Authorization
 

Schematics support generic authorization for its resources.
For more information, about Schematics access and permissions, see Schematics service access
roles and required permissions.


PATCH /v2/settings/policies/{policy_id}
Request
Custom Headers
  • Authorization
    Required*
    string
    The IAM access token for your IBM Cloud account.  You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'.  To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.
    

Path Parameters
  • policy_id
    Required*
    string
    ID to get the details of policy
    

Request Body
Required*
Policy
Update the policy details


  • curl -X --request PATCH http://schematics.cloud.ibm.com/v2/settings/policies/{policy_id} "Authorization: <access_token>" --header "enable_blueprint: true" "Content-Type: application/json" -d "{	"name": "new-policy-dev", "description": "Policy for job execution of secured workspaces on agent1 updated", "resource_group": "Default",	"tags": [	"policy:secured-job"], "location": "us-south",	"policy_kind": "agent_assignment_policy", "policy_target": {	"selector_kind": "ids",	"selector_ids": [	"latest-agent.soA.c4a0"	]	}, "policy_parameter": {		"agent_assignment_policy_parameter": {"selector_kind": "ids","selector_ids": ["us-south.workspace.gb.s91762c7"]}}}""
Response
Response Body
Policy
Detailed information about the Schematics customization policy.  This policy can be used to customize the behaviour or the core Schematics service.


Status Code
  • 200
    Successfully updated the policy details
    

  • 400
    Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.
    

  • 401
    The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.
    

  • 403
    Unauthorized access.  Check that you have the correct access credentials and permissions.
    

  • 404
    The specified resource was not found
    

  • 409
    The specified resource is locked, cannot be updated or deleted
    

  • 500
    Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.
    

Example responses
  • {
  "name": "new-policy-dev",
  "description": "Policy for job execution of secured workspaces on agent1 updated",
  "resource_group": "Default",
  "tags": [
    "policy:secured-job"
  ],
  "location": "us-south",
  "state": {
    "state": "draft",
    "set_by": "schematics@ibm.com",
    "set_at": "2022-07-12T10:54:16.270132296Z"
  },
  "policy_kind": "agent_assignment_policy",
  "policy_target": {
    "selector_kind": "ids",
    "selector_ids": [
      "latest-agent.soA.c4a0"
    ]
  },
  "policy_parameter": {
    "agent_assignment_policy_parameter": {
      "selector_kind": "ids",
      "selector_ids": [
        "us-south.workspace.gb.s91762c7"
      ]
    }
  },
  "id": "new-policy-dev.soP.b2de",
  "crn": "crn:v1:bluemix:public:schematics:us-south:a/2g7200134cc638bgh1d35fd8fb85a7cb:8ae4cd72-0k99-416c-b6ce-0b662l520a4p:policy:new-policy-dev.soP.b2de",
  "account": "1f7277194bb748cdb1d35fd8fb85a7cb",
  "created_at": "2022-07-12T10:54:16.270132296Z",
  "updated_at": "2022-07-12T11:32:47.012053722Z"
}
id=curlclassName=tab-item-selected