Introduction

IBM Cloud Schematics delivers Terraform-as-a-Service 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, multi-tier cloud environments.

Before you begin

Charges

IBM Cloud Schematics workspaces are provided to you at no cost. However, when you decide to apply your Terraform template in IBM Cloud by using the /v1/workspaces/{id}/apply API, you are charged for the IBM Cloud resources that are described in your Terraform template. Make sure to review available service plans and pricing information for each resource that you are about to create. Some services come with a limit per IBM Cloud account. If you are about to reach the service limit for your account, the resource is not provisioned until you increase the service quota, or remove existing services first.

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. Learn more about IAM.

Authorization

To use the IBM Cloud Schematics API, you must be authorized to work 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 required 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 required 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, al 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 geography. Make sure that your data can be stored in these regions before you start using Schematics.

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

https://schematics.cloud.ibm.com

Private: https://private-us.schematics.cloud.ibm.com
IBM Cloud Schematics actions 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 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 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

Private: https://private-eu.schematics.cloud.ibm.com
IBM Cloud Schematics actions 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 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 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.

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 required 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 could 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 have been made within a time window. Wait before calling the API again.
500 Internal Server Error IBM Cloud Schematics is currently unavailable. Your request could not be processed. Please wait a 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 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.

Methods

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

Response

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

Status Code

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

List supported Schematics locations

Retrieve a list of IBM Cloud locations where you can create Schematics workspaces.

GET /v1/locations

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

  • curl -X GET https://schematics.cloud.ibm.com/v1/locations -H "Authorization: <iam_token>"

Response

A list of IBM Cloud locations where you can create Schematics workspaces.

Status Code

  • Successfully returned location information.

  • 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 resource groups

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

GET /v1/resource_groups

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

  • curl -X GET https://schematics.cloud.ibm.com/v1/resource_groups -H "Authorization: <iam_token>"

Response

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

Status Code

  • Successfully returned resource group information.

  • 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
  • {
      "resource_group_id": "469557713b904c6485d59fe833cf0a68",
      "crn": "crn:v1:bluemix:public:resource-controller::a/6ef045fd2b43266cfe8e6388dd2ec098::resource-group:469557713b904c6485d59fe833cf0a68",
      "name": "rg2",
      "state": "ACTIVE",
      "default": false,
      "account_id": "6ef045fd2b43266cfe8e6388dd2ec098"
    }

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.

GET /v1/workspaces

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Query Parameters

  • The position of the workspace in the list of workspaces, from which you want to start listing your workspaces. 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.

  • The maximum number of workspaces 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.

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

Response

Response parameters when listing workspaces from your IBM Cloud account.

Status Code

  • Successfully listed the workspaces that you have access to.

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

  • Unauthorized access. Verify that you are assigned the Viewer, Writer, or Manager service access role in IAM for IBM Cloud Schematics.

  • 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": "myworkspace-123456",
          "name": "myworkspace",
          "type": [
            "terraform_v0.12"
          ],
          "description": "",
          "tags": [],
          "created_at": "2019-08-21T14:07:21.400337433Z",
          "created_by": "user@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": "f4b7ad74-a24c-4a",
              "folder": ".",
              "type": "terraform_v0.12",
              "values_url": "<values_url>",
              "values": "",
              "values_metadata": [
                {
                  "name": "variable",
                  "type": "string"
                }
              ],
              "variablestore": [
                {
                  "name": "variable",
                  "secure": false,
                  "value": "value",
                  "type": "",
                  "description": ""
                }
              ]
            }
          ],
          "runtime_data": [
            {
              "id": "f4b7ad74-a24c-4a",
              "engine_name": "terraform",
              "engine_version": "terraformv0.12.24",
              "state_store_url": "<state_store_url>",
              "log_store_url": "<log_store_url>"
            }
          ],
          "shared_data": {
            "resource_group_id": ""
          },
          "updated_at": "0001-01-01T00:00:00Z",
          "last_health_check_at": "0001-01-01T00:00:00Z"
        }
      ]
    }

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.

Note: 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.
  • Before you create Schematics workspace, you need to create the IAM access token for your IBM Cloud Account. For more information, about creating IAM access token, refer, Get token password.

Note: You can set the environment values export ACCESS_TOKEN=<access_token> and export REFRESH_TOKEN=<refresh_token> obtained by the IAM access token in create workspace curl command.

POST /v1/workspaces

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, you need to create the IAM access token for your IBM Cloud Account. For more information, about creating IAM access token, refer, Get token password.

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

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_v0.12"],"location": "<location>","description": "<workspace_description>","resource_group": "<resource_group_ID>","tags": [],"template_repo": {"url": "<source_repo_url>"},"template_data": [{"folder": ".","type": "terraform_v0.12","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_v0.12"],"location": "<location>","description": "<workspace_description>","resource_group": "<resource_group_ID>","tags": [],"template_repo": {"url": ""},"template_data": [{"folder": ".","type": "terraform_v0.12","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_v0.12"],"description": "<workspace_description>","tags": [],"template_repo": {"url": "<source_repo_url>"},"template_data": [{"folder": ".","type": "terraform_v0.12","env_values":[{"GIT_PASSWORD":"<yourtoken>"},{"GIT_ASKPASS":"<your_script_to_execute>"}]}]}'

Response

Overview of workspace details

Status Code

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

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

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

  • Unauthorized access. Verify that you are assigned the Writer or Manager service access role in IAM for IBM Cloud Schematics.

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

  • Too many requests have been made within a time window. Wait before calling the API again.

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

  • 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_v0.12"
      ],
      "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_v0.12",
          "values_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/template_data/a123456b/values",
          "values": "",
          "values_metadata": [
            {
              "name": "variable1",
              "type": "value1"
            },
            {
              "name": "variable2",
              "type": "value2"
            }
          ],
          "variablestore": [
            {
              "name": "variable1",
              "secure": false,
              "value": "value1",
              "type": "",
              "description": ""
            },
            {
              "name": "variable2",
              "secure": false,
              "value": "value2",
              "type": "",
              "description": ""
            }
          ]
        }
      ],
      "runtime_data": [
        {
          "id": "a123456b",
          "engine_name": "terraform",
          "engine_version": "v0.12.24",
          "state_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a123456b/state_store",
          "log_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a123456b/log_store"
        }
      ],
      "shared_data": {
        "resource_group_id": ""
      },
      "updated_at": "0001-01-01T00:00:00Z",
      "last_health_check_at": "0001-01-01T00:00:00Z"
    }

Get workspace details

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

GET /v1/workspaces/{id}

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

  • The ID of the workspace for which you want to retrieve detailed information. 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>"

Response

Overview of workspace details

Status Code

  • Successfully retrieved details about your workspace.

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

  • Unauthorized access. Verify that you are assigned the Viewer, Writer, or Manager service access role in IAM for IBM Cloud Schematics.

  • 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/workspace API.

  • 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": "myworkspace-123456",
      "name": "myworkspace",
      "type": [
        "terraform_v0.12"
      ],
      "description": "This is a workspace created with the API",
      "resource_group": "aa11bb22aa11bb22",
      "location": "eu-de",
      "tags": [],
      "created_at": "2019-11-06T16:19:32.352418401Z",
      "created_by": "user@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": "a123456",
          "folder": ".",
          "type": "terraform_v0.12",
          "values_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/template_data/a123456/values",
          "values": "",
          "values_metadata": [
            {
              "name": "variable1",
              "type": "string"
            },
            {
              "name": "variable2",
              "type": "string"
            }
          ],
          "variablestore": [
            {
              "name": "variable1",
              "secure": false,
              "value": "value1",
              "type": "",
              "description": ""
            },
            {
              "name": "variable2",
              "secure": false,
              "value": "value2",
              "type": "",
              "description": ""
            }
          ]
        }
      ],
      "runtime_data": [
        {
          "id": "a123456",
          "engine_name": "terraform",
          "engine_version": "v0.12.24",
          "state_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a123456/state_store",
          "log_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a123456/log_store"
        }
      ],
      "shared_data": {
        "resource_group_id": ""
      },
      "updated_at": "0001-01-01T00:00:00Z",
      "last_health_check_at": "0001-01-01T00:00:00Z"
    }

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.

PATCH /v1/workspaces/{id}

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

  • The ID of the workspace that you want to update. To find the ID, use the GET /v1/workspaces API.

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

Response

Overview of workspace details

Status Code

  • Successfully updated the workspace metadata.

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

  • Unauthorized access. Verify that you are assigned the Writer or Manager service access role in IAM for IBM Cloud Schematics.

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

  • Could not update the workspace metadata. The workspace is frozen and disabled for updates. Unfreeze the workspace first, before you try again.

  • Too many requests have been made within a time window. Wait before calling the API again.

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

  • 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_v0.12"
      ],
      "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_v0.12",
          "values_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/template_data/a123456b/values",
          "values": "",
          "values_metadata": [
            {
              "name": "variable1",
              "type": "value1"
            },
            {
              "name": "variable2",
              "type": "value2"
            }
          ],
          "variablestore": [
            {
              "name": "variable1",
              "secure": false,
              "value": "value1",
              "type": "",
              "description": ""
            },
            {
              "name": "variable2",
              "secure": false,
              "value": "value2",
              "type": "",
              "description": ""
            }
          ]
        }
      ],
      "runtime_data": [
        {
          "id": "a123456b",
          "engine_name": "terraform",
          "engine_version": "v0.12.24",
          "state_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a123456b/state_store",
          "log_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a123456b/log_store"
        }
      ],
      "shared_data": {
        "resource_group_id": ""
      },
      "updated_at": "0001-01-01T00:00:00Z",
      "last_health_check_at": "0001-01-01T00:00:00Z"
    }

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.

PUT /v1/workspaces/{id}

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

  • The ID of the workspace that you want to update. To find the ID, use the GET /v1/workspaces API.

Workspace

  • curl --request PUT --url https://schematics.cloud.ibm.com/v1/workspaces/{id} -H "Authorization: <iam_token>" -d '{"template_repo": { "url": "<source_repo_url>", "repo_url": "<catalog_repo_url>"}, "catalog_ref": {"item_id": "<item_ID>", "item_name": "<item_name>", "item_url": "<item_url>", "item_readme_url": "<item_readme_url>", "item_icon_url": "<item_icon_url>", "offering_version": "<offering_version>", "launch_url": "<launch_url>"}}'

Response

Overview of workspace details

Status Code

  • Successfully updated the workspace metadata.

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

  • Unauthorized access. Verify that you are assigned the Writer or Manager service access role in IAM for IBM Cloud Schematics.

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

  • Could not update the workspace template information. The workspace is frozen and disabled for updates. Unfreeze the workspace first, before you try again.

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

  • 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_v0.12"
      ],
      "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_v0.12",
          "values_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/template_data/a123456b/values",
          "values": "",
          "values_metadata": [
            {
              "name": "variable1",
              "type": "value1"
            },
            {
              "name": "variable2",
              "type": "value2"
            }
          ],
          "variablestore": [
            {
              "name": "variable1",
              "secure": false,
              "value": "value1",
              "type": "",
              "description": ""
            },
            {
              "name": "variable2",
              "secure": false,
              "value": "value2",
              "type": "",
              "description": ""
            }
          ]
        }
      ],
      "runtime_data": [
        {
          "id": "a123456b",
          "engine_name": "terraform",
          "engine_version": "v0.12.24",
          "state_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a123456b/state_store",
          "log_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a123456b/log_store"
        }
      ],
      "shared_data": {
        "resource_group_id": ""
      },
      "updated_at": "0001-01-01T00:00:00Z",
      "last_health_check_at": "0001-01-01T00:00:00Z"
    }

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}?destroyResources=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.

DELETE /v1/workspaces/{id}

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

  • The IAM refresh token for your IBM Cloud account. The refresh token is required only if you want to delete all IBM Cloud resources that the workspaces manages along with deleting the workspace. If you want to delete the workspace only and keep all your IBM Cloud resources, no refresh token is required. To retrieve the refresh token, use the IAM POST /identity/token API. For more information, see the API docs.

Path Parameters

  • The ID of the workspace that you want to delete. To find the workspace ID, use the GET /v1/workspaces API.

Query Parameters

  • If set to true, all IBM Cloud resources that the workspace manages are also deleted. If set to false, you remove the workspace only. Your IBM Cloud resources are still available and must be managed with the resource dashboard or CLI afterwards.

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

Response

Status Code

  • Successfully deleted the workspace.

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

  • Unauthorized access. Verify that you are assigned the Manager service access role in IAM for IBM Cloud Schematics.

  • Deletion failed. The workspace is frozen and disabled for updates. Unfreeze the workspace first before you try to delete the workspace.

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

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

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.

PUT /v1/workspaces/{id}/templates/{template_id}/template_repo_upload

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

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

  • 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

  • The TAR file that holds your Terraform template.

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

Response

The response body when uploading a TAR file.

Status Code

  • Successfully uploaded the TAR file to your workspace.

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

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

  • Unauthorized access. Verify that you are assigned the Writer, or Manager service access role in IAM for IBM Cloud Schematics.

  • The workspace ID could not be found. Retrieve the workspace ID by using the GET /v1/workspaces API and try again.

  • 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": "da53f57b-f7de-49",
      "file_value": "mytarfile.tar",
      "has_received_file": true
    }

Perform a Schematics plan action

Run a Schematics plan action against your workspace. The plan action 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 action.

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

POST /v1/workspaces/{id}/plan

Request

Custom Headers

  • The IAM refresh token for your IBM Cloud account. To retrieve the refresh token, use the IAM POST /identity/token API. For more information, see the API docs.

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

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

Path Parameters

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

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

Response

Response parameter when you create a Terraform execution plan.

Status Code

  • Successfully performed a Schematics plan action.

  • Bad request. Verify that you provided all input parameters, such as the IAM refresh token. To create a refresh token, use the IAM POST /identity/token API.

  • The IAM authorization or refresh token 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.

  • Unauthorized access. Verify that you are assigned the Writer or Manager service access role in IAM for IBM Cloud Schematics. In addition, make sure that you have the required permissions to work with the resources that are described in your templates.

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

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

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

  • 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 apply action

Run a Schematics apply action against your workspace. An apply action 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 your IBM Cloud resources is stored in a Terraform state file that IBM Cloud Schematics uses 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 action.

Note: This API returns an activity 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 actions that Schematics is about to perform, create a Terraform execution plan with the POST /v1/workspaces/{id}/plan API.

PUT /v1/workspaces/{id}/apply

Request

Custom Headers

  • The IAM refresh token for your IBM Cloud account. To retrieve the refresh token, use the IAM POST /identity/token API. For more information, see the IAM API documentation.

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

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

Path Parameters

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

A list of resources that you want to target for creation or update. Resources must be targeted by using the resource address, such as ibm_is_instance.vm. If the targeted resource specifies the count attribute and no index is specified in the resource address, such as ibm_is_instance.vm1[1], all instances that share the same resource name are targeted for creation or update. For more information about the Terraform target feature, see Resource targeting{: external}.

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

Response

Response parameter for successfully initiating a request to apply a Terraform template in IBM Cloud.

Status Code

  • Successfully ran a Schematics apply action against your workspace.

  • The IAM refresh token for your IBM Cloud account. To retrieve the refresh token, use the IAM POST /identity/token API. For more information, see the IAM API documentation.

  • Unauthorized access. Verify that you are assigned the Writer or Manager service access role in IAM for IBM Cloud Schematics. In addition, make sure that you have the required permissions to work with the IBM Cloud resource that you configured in your Terraform template.

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

  • Apply failed. The workspace is frozen and disabled for updates. Unfreeze the workspace first before you try to run a Schematics apply action in IBM Cloud.

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

  • 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 destroy action

Run a Schematics destroy action against your workspace. A destroy action 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 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 action.

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

PUT /v1/workspaces/{id}/destroy

Request

Custom Headers

  • The IAM refresh token for your IBM Cloud account. To retrieve the refresh token, use the IAM POST /identity/token API. For more information, see the IAM API documentation.

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

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

Path Parameters

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

A list of resources that you want to target for deletion. Resources must be targeted by using the resource address, such as ibm_is_instance.vm. If the targeted resource specifies the count attribute and no index is specified in the resource address, such as ibm_is_instance.vm[1], all instances that share the same resource name are targeted for deletion. Also, if the targeted resource can only be deleted if dependent resources are deleted, such as a VPC can only be deleted if the attached subnet is deleted, then all dependent resources are targeted for deletion as well. For more information about the Terraform target feature, see Resource targeting{: external}.

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

Response

Response parameters for successfully initiating a request to remove IBM Cloud resources.

Status Code

  • Successfully initiated a Schematics destroy action against your workspace.

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

  • Unauthorized access. Verify that you are assigned the Writer or Manager service access role in IAM for IBM Cloud Schematics. In addition, verify that you have the required resource permissions to remove the resource from IBM Cloud.

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

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

  • 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 refresh action

Run a Schematics refresh action against your workspace. A refresh action 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 ID that you use to retrieve the URL to the log file with the GET /v1/workspaces/{id}/actions/{action_id}/logs API.

PUT /v1/workspaces/{id}/refresh

Request

Custom Headers

  • The IAM refresh token for your IBM Cloud account. To retrieve the refresh token, use the IAM POST /identity/token API. For more information, see the IAM API documentation.

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

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

Path Parameters

  • The ID of the workspace for which you want to perform a Schematics refresh action. To find the workspace ID, use the GET /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>"

Response

Response parameters for successfully initiating a request to refresh the Terraform statefile of a workspace.

Status Code

  • Successfully initiated a Schematics refresh action against your workspace.

  • One or more input parameters could not be found or are provided in the wrong format.

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

  • Unauthorized access. Verify that you are assigned the Writer or Manager service access role in IAM for IBM Cloud Schematics.

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

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

  • 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 all workspace actions

Retrieve a list of all actions that ran against a workspace. Actions are generated when you use the PUT /v1/workspaces/{id}/apply, POST /v1/workspaces/{id}/plan, or DELETE /v1/workspaces/{id}/destroy API.

GET /v1/workspaces/{id}/actions

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

  • The ID of the workspace for which you want to list actions. To find the workspace ID, use the GET /workspaces API.

Query Parameters

  • The maximum number of actions that you want to include in your response. The number that you enter must be between 1 and 200. If no number is provided, 100 is used by default.

  • The position of the action in the list of actions, from which you want to start listing your actions. For example, if you have three actions, the first action is assigned position number 0, the second action is assigned position number 1, and so forth. If you have 6 actions and you want to list the details for actions 2-6, enter 1. To limit the number of actions that is returned, use the limit option in addition to the offset option. Negative numbers are not supported and are ignored.

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

Response

Response parameter for listing actions for a workspace.

Status Code

  • Successfully retrieved activities for the workspace.

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

  • Unauthorized access. Verify that you are assigned the Reader, Writer, or Manager service access role in IAM for IBM Cloud Schematics.

  • 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 action details

Get the details for a workspace action that ran against the workspace. This API returns 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/{id}/actions/{action_id}

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

  • The ID of the workspace for which you want to retrieve action details. To find the workspace ID, use the GET /workspaces API.

  • The ID of the action for which you want to retrieve details. To find the action 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>"

Response

Information about the actions of a workspace.

Status Code

  • Successfully retrieved details about the action.

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

  • Unauthorized access. Verify that you are assigned the Reader, Writer, or Manager service access role in IAM for IBM Cloud Schematics.

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

  • 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 a Schematics apply action

Stop a Schematics apply action that currently runs against your workspace. Only Schematics apply actions can be stopped with this API.

Note: If you remove the Schematics apply action 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 action to be completed first. Then, any other resource creations, updates, or deletions that are included in your Terraform template file are ignored.

DELETE /v1/workspaces/{id}/actions/{action_id}

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

  • The ID of the workspace where you want to stop the Schematics apply action. To find the workspace ID, use the GET /workspaces API.

  • The ID of the Schematics apply action that you want to stop. To find the action ID, use the GET /v1/workspaces/{id}/actions API. Note that the action name must be apply.

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

Response

Status Code

  • Successfully stopped your Schematics apply action.

  • The specified action cannot be stopped because the action 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 action.

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

  • Unauthorized access. Verify that you are assigned the Manager service access role in IAM for IBM Cloud Schematics.

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

  • The specified action is not a Schematics apply action. Verify that you entered the correct action ID. To find the ID of the action, use the GET /v1/workspaces/{id}/actions API.

  • 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 action log URL

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

GET /v1/workspaces/{id}/actions/{action_id}/logs

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

  • The ID of the workspace for which you want to retrieve action logs. To find the workspace ID, use the GET /workspaces API.

  • The ID of the action for which you want to retrieve the log file URL. To find the action 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: <iam_token>"

Response

Information about the workspace action logs.

Status Code

  • Successfully retrieved the log file URL for your action.

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

  • Unauthorized access. Verify that you have the Reader, Writer, or Manager service access role in IAM for IBM Cloud Schematics.

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

  • 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 action log URL for all workspace templates

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

GET /v1/workspaces/{id}/log_stores

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

  • The ID of the workspace for which you want to retrieve log store URLs. To find the workspace ID, use the GET /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>"

Response

Information about the log file URL for the most recent action that ran against your workspace.

Status Code

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

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

  • Unauthorized access. Verify that you are assigned the Reader, Writer, or Manager service access role in IAM for IBM Cloud Schematics.

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

  • 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 logs for a workspace action

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

GET /v1/workspaces/{id}/runtime_data/{template_id}/log_store/actions/{action_id}

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

  • The ID of the workspace for which you want to retrieve action logs. To find the workspace ID, use the GET /workspaces API.

  • The ID of the action (activity) that ran against your workspace ID. To find the action ID, use the GET /v1/workspaces/{id}/actions API.

  • The ID that was assigned to your Terraform template or IBM Cloud catalog software template. To find the ID, use the GET /v1/workspaces API.

Query Parameters

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

  • Enter false to remove all Terraform command prefixes from each Terraform command section of your log output.

  • Enter false to remove any null_resource log lines from your log output. This option can be used only if you defined a null_resource in your Terraform configuration file.

  • Enter true to show a new line instead of \n for multi-line Ansible logs. This option is available only if you run Ansible code that creates Ansible log output.

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

Response

The Terraform log information for a workspace action.

Status Code

  • Successfully retrieved the Terraform logs for a workspace action.

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

  • Unauthorized access. Verify that you assigned the Reader, Writer, or Manager service access role in IAM for IBM Cloud Schematics.

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

  • 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 the latest action for a workspace template

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

GET /v1/workspaces/{id}/runtime_data/{template_id}/log_store

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

  • The ID of the workspace for which you want to retrieve action logs. To find the workspace ID, use the GET /workspaces API.

  • The ID that was assigned to your Terraform template or IBM Cloud catalog software template. To find the ID, use the GET /v1/workspaces API.

Query Parameters

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

  • Enter false to remove all Terraform command prefixes from each Terraform command section of your log output.

  • Enter false to remove any null_resource log lines from your log output. This option can be used only if you defined a null_resource in your Terraform configuration file.

  • Enter true to show a new line instead of for multi-line Ansible logs. This option is available only if you run Ansible code that creates Ansible log output.

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

Response

The Terraform logs for the most recent workspace action.

Status Code

  • Successfully retrieved the Terraform logs for the most recent workspace action.

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

  • Unauthorized access. Verify that you are assigned the Reader, Writer, or Manager service access role in IAM for IBM Cloud Schematics.

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

  • 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 Terraform statefile URL

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.

GET /v1/workspaces/{id}/state_stores

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

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

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

Response

Information about the Terraform statefile URL.

Status Code

  • Successfully retrieved the URL to the Terraform statefile.

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

  • Unauthorized access. Verify that you are assigned the Reader, Writer or Manager service access role in IAM for IBM Cloud Schematics.

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

  • 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": "a111111b11-1aa1-1a",
          "engine_name": "terraform",
          "engine_version": "terraformv0.12.24",
          "state_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a111111b11-1aa1-1a/state_store"
        }
      ]
    }

Show Terraform statefile content

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/{id}/runtime_data/{template_id}/state_store

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

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

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

Response

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

Status Code

  • Successfully retrieved the information from the Terraform statefile.

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

  • Unauthorized access. Verify that you are assigned the Writer service access role in IAM for IBM Cloud Schematics.

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

  • 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": []
        }
      ]
    }

List workspace resources

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

GET /v1/workspaces/{id}/resources

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

  • The ID of the workspace for which you want to retrieve the associated IBM Cloud resources. To find the workspace ID, use the GET /workspaces API.

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

Response

Information about the IBM Cloud resources that are associated with your workspace.

Status Code

  • Successfully retrieved the resources in JSON format.

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

  • Unauthorized access. Verify that you have the Reader, Writer or Manager service access role in IAM for IBM Cloud Schematics.

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

  • 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": "a12v3411-11a11",
      "folder": ".",
      "type": "terraform_v0.12",
      "resources": [
        {
          "resource_id": "1234a678-1234-54a1-9223-1a111b2222",
          "resource_name": "ibm_is_subnet.subnet1",
          "resource_type": "ibm_is_subnet",
          "resource_crn": "",
          "resource_icon_url": "",
          "resource_controller_url": "",
          "resource_group_name": "",
          "resource_status": ""
        },
        {
          "resource_id": "1234a678-1234-54a1-9223-1a111b2223",
          "resource_name": "ibm_is_vpc.vpc",
          "resource_type": "ibm_is_vpc",
          "resource_crn": "",
          "resource_icon_url": "",
          "resource_controller_url": "",
          "resource_group_name": "",
          "resource_status": ""
        }
      ],
      "related_resources": [
        {
          "resource_id": "data.ibm_is_image.ubuntu",
          "resource_name": "",
          "resource_type": "ibm_is_image",
          "resource_crn": "",
          "resource_icon_url": "",
          "resource_controller_url": "",
          "resource_group_name": "",
          "resource_status": ""
        },
        {
          "resource_id": "data.ibm_resource_group.group",
          "resource_name": "",
          "resource_type": "ibm_resource_group",
          "resource_crn": "",
          "resource_icon_url": "",
          "resource_controller_url": "",
          "resource_group_name": "",
          "resource_status": ""
        },
        {
          "resource_id": "data.ibm_is_ssh_key.ssh_key_id",
          "resource_name": "",
          "resource_type": "ibm_is_ssh_key",
          "resource_crn": "",
          "resource_icon_url": "",
          "resource_controller_url": "",
          "resource_group_name": "",
          "resource_status": ""
        }
      ]
    }

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/{id}/output_values

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

  • The ID of the workspace for which you want to retrieve output 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

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

Status Code

  • Successfully retrieved the output values in JSON format.

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

  • Unauthorized access. Verify that you are assigned the Reader, Writer, or Manager service access role in IAM for IBM Cloud Schematics.

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

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

Get workspace template details

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

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

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

  • The ID of the workspace for which you want to retrieve information about the associated Terraform template. To find the workspace ID, use the GET /v1/workspaces API.

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

Response

Information about the template that your workspace points to.

Status Code

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

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

  • Unauthorized access. Verify that you are assigned the Reader, Writer or Manager service access role in IAM for IBM Cloud Schematics.

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

  • 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": ""
      }
    }

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/{id}/templates/readme

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

  • The ID of the workspace for which you want to retrieve the README.md file that is stored in the GitHub or GitLab repository that your workspace points to. To find the workspace ID, use the GET /v1/workspaces API.

Query Parameters

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

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

Response

The README.md file for the template that your workspace points to.

Status Code

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

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

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

  • Unauthorized access. Verify that you are assigned the Reader, Writer, or Manager service access role in IAM for IBM Cloud Schematics.

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

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

List workspace input variables

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

GET /v1/workspaces/{id}/template_data/{template_id}/values

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

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

  • The ID of the Terraform template for which you want to retrieve all 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 -H "Authorization: <iam_token>"

Response

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

Status Code

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

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

  • Unauthorized access. Verify that you are assigned the Reader, Writer or Manager service access role in IAM for IBM Cloud Schematics.

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

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

Update workspace input variables

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

PUT /v1/workspaces/{id}/template_data/{template_id}/values

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

  • The ID of the workspace for which you want to update input variables. To find the ID, use the GET /v1/workspaces API.

  • The ID of the Terraform template for which you want to update 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.

Input parameter to update workspace input variables.

  • curl --request PUT --url https://schematics.cloud.ibm.com/v1/workspaces/{id}/template_data/{template_id}/values -H "Authorization: <iam_token>" -d '{"env_values": [{"env_key":"env_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

Information about workspace input variables.

Status Code

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

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

  • Unauthorized access. Verify that you are assigned the Writer or Manager service access role in IAM for IBM Cloud Schematics.

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

  • 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 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/{id}/template_data/{template_id}/values_metadata

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. To retrieve the token, run ibmcloud iam oauth-tokens in the IBM Cloud CLI.

Path Parameters

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

  • 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

Information about workspace variable metadata.

Status Code

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

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

  • Unauthorized access. Verify that you are assigned the Reader, Writer or Manager service access role in IAM for IBM Cloud Schematics.

  • The specified workspace or template ID 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.

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