List supported locations

GET /v2/locations

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

&lt;h3&gt;Authorization&lt;/h3&gt; 

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&#x3D;schematics-access#access-roles).

Request

Response

200 - Successfully listed all the locations.

locations

array

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

List resource groups

GET /v1/resource_groups

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

&lt;h3&gt;Authorization&lt;/h3&gt; 

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&#x3D;schematics-access#access-roles).

Request

Response

200 - Successfully returned resource groups information.

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

Request

Response

The Terraform version that is used when you apply Terraform templates with Schematics.

API endpoints.

&lt;h3&gt;Authorization&lt;/h3&gt; 

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&#x3D;schematics-access#access-roles).">

List workspaces

GET /v1/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.

&lt;h3&gt;Authorization&lt;/h3&gt; 

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&#x3D;schematics-access#access-roles).

Auditing

Calling this method generates the following auditing event.

schematics.workspace.list

Request

Path Parameters

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.

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.

profile

string

Level of details returned by the get method

resource_group

string

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

Response

200 - Successfully listed the workspaces that you have access to.

count

integer

The number of workspaces in the IBM Cloud account that you have access to and that matched your search criteria.

limit

integer

The `limit` value that you set in your API request and that represents the maximum number of workspaces that you wanted to list.

offset

integer

The `offset` value that you set in your API request. The offset value represents the position number of the workspace from which you wanted to start listing your workspaces.

workspaces

array

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

<h3>Authorization</h3>

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

Create a workspace

POST /v1/workspaces

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.

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.workspace.create

agent id which is binded to with the workspace.

settings

array

Input settings to be applied to the workspace, for example, `job_timeout_override`

Path Parameters

Query Parameters

Response

Information about the Target used by the templates originating from IBM Cloud catalog offerings. This information is not relevant when you create a workspace from your own Terraform template.

status

string

The status of the workspace.

**Active**: After you successfully ran your infrastructure code by applying your Terraform execution plan, the state of your workspace changes to &#x60;Active&#x60;. 

**Connecting**: Schematics tries to connect to the template in your source repo. If successfully connected, the template is downloaded and metadata, such as input parameters, is extracted. After the template is downloaded, the state of the workspace changes to &#x60;Scanning&#x60;. 

**Draft**: The workspace is created without a reference to a GitHub or GitLab repository. 

**Failed**: If errors occur during the execution of your infrastructure code in IBM Cloud Schematics, your workspace status is set to &#x60;Failed&#x60;. 

**Inactive**: The Terraform template was scanned successfully and the workspace creation is complete. You can now start running Schematics plan and apply jobs to provision the IBM Cloud resources that you specified in your template. If you have an &#x60;Active&#x60; workspace and decide to remove all your resources, your workspace is set to &#x60;Inactive&#x60; after all your resources are removed. 

**In progress**: When you instruct IBM Cloud Schematics to run your infrastructure code by applying your Terraform execution plan, the status of our workspace changes to &#x60;In progress&#x60;. 

**Scanning**: The download of the Terraform template is complete and vulnerability scanning started. If the scan is successful, the workspace state changes to &#x60;Inactive&#x60;. If errors in your template are found, the state changes to &#x60;Template Error&#x60;. 

**Stopped**: The Schematics plan, apply, or destroy job was cancelled manually. 

**Template Error**: The Schematics template contains errors and cannot be processed.

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

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Delete a workspace

DELETE /v1/workspaces/{w_id}

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.

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.workspace.delete

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Get workspace details

GET /v1/workspaces/{w_id}

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

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.workspace.read

Request

Path Parameters

w_id

Required *

string

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

Query Parameters

Response

Information about the Target used by the templates originating from IBM Cloud catalog offerings. This information is not relevant when you create a workspace from your own Terraform template.

status

string

The status of the workspace.

**Active**: After you successfully ran your infrastructure code by applying your Terraform execution plan, the state of your workspace changes to &#x60;Active&#x60;. 

**Connecting**: Schematics tries to connect to the template in your source repo. If successfully connected, the template is downloaded and metadata, such as input parameters, is extracted. After the template is downloaded, the state of the workspace changes to &#x60;Scanning&#x60;. 

**Draft**: The workspace is created without a reference to a GitHub or GitLab repository. 

**Failed**: If errors occur during the execution of your infrastructure code in IBM Cloud Schematics, your workspace status is set to &#x60;Failed&#x60;. 

**Inactive**: The Terraform template was scanned successfully and the workspace creation is complete. You can now start running Schematics plan and apply jobs to provision the IBM Cloud resources that you specified in your template. If you have an &#x60;Active&#x60; workspace and decide to remove all your resources, your workspace is set to &#x60;Inactive&#x60; after all your resources are removed. 

**In progress**: When you instruct IBM Cloud Schematics to run your infrastructure code by applying your Terraform execution plan, the status of our workspace changes to &#x60;In progress&#x60;. 

**Scanning**: The download of the Terraform template is complete and vulnerability scanning started. If the scan is successful, the workspace state changes to &#x60;Inactive&#x60;. If errors in your template are found, the state changes to &#x60;Template Error&#x60;. 

**Stopped**: The Schematics plan, apply, or destroy job was cancelled manually. 

**Template Error**: The Schematics template contains errors and cannot be processed.

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.

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Update workspace metadata

PATCH /v1/workspaces/{w_id}

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.

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.workspace.update

Input settings to be applied to the workspace, for example, `job_timeout_override`

Path Parameters

w_id

Required *

string

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

Query Parameters

Response

Information about the Target used by the templates originating from IBM Cloud catalog offerings. This information is not relevant when you create a workspace from your own Terraform template.

status

string

The status of the workspace.

**Active**: After you successfully ran your infrastructure code by applying your Terraform execution plan, the state of your workspace changes to &#x60;Active&#x60;. 

**Connecting**: Schematics tries to connect to the template in your source repo. If successfully connected, the template is downloaded and metadata, such as input parameters, is extracted. After the template is downloaded, the state of the workspace changes to &#x60;Scanning&#x60;. 

**Draft**: The workspace is created without a reference to a GitHub or GitLab repository. 

**Failed**: If errors occur during the execution of your infrastructure code in IBM Cloud Schematics, your workspace status is set to &#x60;Failed&#x60;. 

**Inactive**: The Terraform template was scanned successfully and the workspace creation is complete. You can now start running Schematics plan and apply jobs to provision the IBM Cloud resources that you specified in your template. If you have an &#x60;Active&#x60; workspace and decide to remove all your resources, your workspace is set to &#x60;Inactive&#x60; after all your resources are removed. 

**In progress**: When you instruct IBM Cloud Schematics to run your infrastructure code by applying your Terraform execution plan, the status of our workspace changes to &#x60;In progress&#x60;. 

**Scanning**: The download of the Terraform template is complete and vulnerability scanning started. If the scan is successful, the workspace state changes to &#x60;Inactive&#x60;. If errors in your template are found, the state changes to &#x60;Template Error&#x60;. 

**Stopped**: The Schematics plan, apply, or destroy job was cancelled manually. 

**Template Error**: The Schematics template contains errors and cannot be processed.

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.

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions. ">

Update workspace

PUT /v1/workspaces/{w_id}

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.

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.workspace.update

Input settings to be applied to the workspace, for example, `job_timeout_override`

Path Parameters

w_id

Required *

string

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

Query Parameters

Response

Information about the Target used by the templates originating from IBM Cloud catalog offerings. This information is not relevant when you create a workspace from your own Terraform template.

status

string

The status of the workspace.

**Active**: After you successfully ran your infrastructure code by applying your Terraform execution plan, the state of your workspace changes to &#x60;Active&#x60;. 

**Connecting**: Schematics tries to connect to the template in your source repo. If successfully connected, the template is downloaded and metadata, such as input parameters, is extracted. After the template is downloaded, the state of the workspace changes to &#x60;Scanning&#x60;. 

**Draft**: The workspace is created without a reference to a GitHub or GitLab repository. 

**Failed**: If errors occur during the execution of your infrastructure code in IBM Cloud Schematics, your workspace status is set to &#x60;Failed&#x60;. 

**Inactive**: The Terraform template was scanned successfully and the workspace creation is complete. You can now start running Schematics plan and apply jobs to provision the IBM Cloud resources that you specified in your template. If you have an &#x60;Active&#x60; workspace and decide to remove all your resources, your workspace is set to &#x60;Inactive&#x60; after all your resources are removed. 

**In progress**: When you instruct IBM Cloud Schematics to run your infrastructure code by applying your Terraform execution plan, the status of our workspace changes to &#x60;In progress&#x60;. 

**Scanning**: The download of the Terraform template is complete and vulnerability scanning started. If the scan is successful, the workspace state changes to &#x60;Inactive&#x60;. If errors in your template are found, the state changes to &#x60;Template Error&#x60;. 

**Stopped**: The Schematics plan, apply, or destroy job was cancelled manually. 

**Template Error**: The Schematics template contains errors and cannot be processed.

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.

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Request

Path Parameters

w_id

Required *

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Upload a TAR file to your workspace

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

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.

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.workspace.update

Request

Request Body

Upload template tar file

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.

Query Parameters

Response

200 - Successfully uploaded the TAR file to your workspace.

file_value

string

Tar file value.

has_received_file

boolean

Has received tar file?

id

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

w_id

Required *

string

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

Query Parameters

offset

integer

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.

Response

200 - Successfully retrieved list of workspace jobs.

actions

array

List of workspace jobs

workspace_id

string

The ID of the workspace.

workspace_name

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Stop the workspace job

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

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. <h3>Authorization</h3>

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

Request

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.

Query Parameters

Response

202 - Successfully initiated the stopping of workspace job.

activityid

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

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.

Query Parameters

Response

200 - Successfully retrieved the workspace jobs details.

action_id

string

The ID of the activity or job. You can use the ID to retrieve the logs for that job by using the `GET /v1/workspaces/{id}/actions/{action_id}/logs` API.

message

array

Information about the success or failure of your job, including a success or error code and the timestamp when the job succeeded or failed.

name

string

The type of actovoty or job that ran against your workspace.

APPLY: The apply job was created when you used the `PUT /v1/workspaces/{id}/apply` API to apply a Terraform template in IBM Cloud.
DESTROY: The destroy job was created when you used the `DELETE /v1/workspaces/{id}/destroy` API to remove all resources that are associated with your workspace.
PLAN: The plan job was created when you used the `POST /v1/workspaces/{id}/plan` API to create a Terraform execution plan.

performed_at

string

The timestamp when the job was initiated.

performed_by

string

The user ID who initiated the job.

status

string

The status of your activity or job. To retrieve the URL to your job logs, use the GET /v1/workspaces/{id}/actions/{action_id}/logs API.

COMPLETED: The job completed successfully.
CREATED: The job was created, but the provisioning, modification, or removal of IBM Cloud resources has not started yet.
FAILED: An error occurred during the plan, apply, or destroy job. Use the job ID to retrieve the URL to the log files for your job.
IN PROGRESS: The job is in progress. You can use the log_url to access the logs.

templates

array

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Run Terraform Commands

PUT /v1/workspaces/{w_id}/commands

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

<h3>Authorization</h3>

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

Request

Request Body

TerraformCommands

command value

commands

array

List of commands. You can execute single set of commands or multiple commands. For more information, about the payload of the multiple commands, refer to Commands.

operation_name

string

Command name

description

string

Command description

Path Parameters

w_id

Required *

string

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

Query Parameters

Response

200 - Successfully updated the workspace metadata.

activityid

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

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.

<h3>Authorization</h3>

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

Perform a Schematics `apply` job

PUT /v1/workspaces/{w_id}/apply

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.

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.workspace-resources.create

Request

Request Body

WorkspaceActivityOptions

Workspace 'apply' job options

action_options

WorkspaceActivityOptionsTemplate

Workspace job options template

target

array

A list of Terraform resources to target.

tf_vars

array

Terraform variables for the workspace job options.

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.

Query Parameters

Response

202 - Successfully ran a Schematics `apply` job against your workspace.

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

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Perform a Schematics `destroy` job

PUT /v1/workspaces/{w_id}/destroy

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.

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.workspace-resources.delete

Request

Request Body

WorkspaceActivityOptions

Workspace destroy command options

action_options

WorkspaceActivityOptionsTemplate

Workspace job options template

target

array

A list of Terraform resources to target.

tf_vars

array

Terraform variables for the workspace job options.

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.

Query Parameters

Response

202 - Successfully initiated a Schematics `destroy` job against your workspace.

activityid

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Perform a Schematics `plan` job

POST /v1/workspaces/{w_id}/plan

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.

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.workspace-resources.plan

Request

Request Body

WorkspaceActivityOptions

Workspace 'plan' job options

action_options

WorkspaceActivityOptionsTemplate

Workspace job options template

target

array

A list of Terraform resources to target.

tf_vars

array

Terraform variables for the workspace job options.

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.

Query Parameters

Response

202 - Successfully performed a Schematics `plan` job.

activityid

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Perform a Schematics `refresh` job

PUT /v1/workspaces/{w_id}/refresh

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.

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.workspace.refresh

Request

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.

Query Parameters

Response

202 - Successfully initiated a Schematics `refresh` job against your workspace.

activityid

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

List workspace input variables

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

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

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.workspace.template_values

Request

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.

Query Parameters

Response

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

values_metadata

array

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

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

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

Auditing

Calling this method generates the following auditing event.

schematics.workspace.template_values

Request

Request Body

UserValuesRequest

Replace a Workspace input values

env_values

array

A list of environment variables that you want to apply during the execution of a bash script or Terraform job. This field must be provided as a list of key-value pairs, for example, TF_LOG=debug. Each entry will be a map with one entry where `key is the environment variable name and value is value`. You can define environment variables for IBM Cloud catalog offerings that are provisioned by using a bash script. See example to use special environment variable that are supported by Schematics.

values

string

User values

variablestore

array

VariablesRequest -

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

Query Parameters

Response

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

env_values

array

env_values_map

array

values

string

User values

variablestore

array

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Get workspace template details

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

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

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.workspace.template_metadata_values

Request

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.

Query Parameters

Response

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

runtime_data

array

Information about the provisioning engine, state file, and runtime logs.

shared_data

SharedTargetData

Information about the Target used by the templates originating from the IBM Cloud catalog offerings. This information is not relevant for workspace created using your own Terraform template.

template_data

array

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

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

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

Request

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.

Query Parameters

Response

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

values_metadata

array

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

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

Deprecated: This v1 API will be decommissioned within 12 months. Please migrate to the v2 API: `GET /v2/workspaces/{w_id}/template_data/{t_id}/values_metadata`. Retrieve the metadata for all the workspace input variables that are declared in the template that your workspace points to.

Request

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

Query Parameters

Response

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.

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Request

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.

Query Parameters

Response

200 - Successfully retrieved the output values in JSON format.

id

string

The ID that was assigned to your Terraform template or IBM Cloud catalog software template

folder

string

The subfolder in the GitHub or GitLab repository where your Terraform template is stored. If the template is stored in the root directory, `.` is returned.

type

string

The Terraform version that was used to apply your template

values

array

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

GET /v1/workspaces/{w_id}/output_values

Deprecated: This v1 API will be decommissioned within 12 months. Please migrate to the v2 API: `GET /v2/workspaces/{w_id}/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.

Request

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.

Query Parameters

Response

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.

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Request

Path Parameters

w_id

Required *

string

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

Query Parameters

Response

List of null resources

resources_count

integer

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

GET /v1/workspaces/{w_id}/resources

Deprecated: This v1 API will be decommissioned within 12 months. Please migrate to the v2 API: `GET /v2/workspaces/{w_id}/resources`. Retrieve a list of IBM Cloud resources that you created with your workspace.

Request

Path Parameters

w_id

Required *

string

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

Query Parameters

Response

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.

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Get Terraform statefile URL

GET /v1/workspaces/{w_id}/state_stores

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.

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.workspace.template_state_stores

Request

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.

Query Parameters

Response

200 - Successfully retrieved the URL to the Terraform statefile.

runtime_data

array

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

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

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.

Request

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.

Query Parameters

Response

200 - Successfully retrieved the information from the Terraform statefile.

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Get workspace job log URL

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

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.

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.workspace.log_stores

Request

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.

Query Parameters

Response

200 - Successfully retrieved the log file URL for your job.

action_id

string

The ID of the activity or job that ran against your workspace.

name

string

The type of actovoty or job that ran against your workspace.

APPLY: The apply job was created when you used the `PUT /v1/workspaces/{id}/apply` API to apply a Terraform template in IBM Cloud.
DESTROY: The destroy job was created when you used the `DELETE /v1/workspaces/{id}/destroy` API to remove all resources that are associated with your workspace.
PLAN: The plan job was created when you used the `POST /v1/workspaces/{id}/plan` API to create a Terraform execution plan.

templates

array

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

GET /v1/workspaces/{w_id}/log_stores

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.

Request

Path Parameters

w_id

Required *

string

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

Query Parameters

Response

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

runtime_data

array

Runtime data

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Show latest logs for a workspace template

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

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

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.workspace.state_stores

Request

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

Response

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Request

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

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

Response

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Delete one or more workspace

POST /v1/workspace_jobs

Delete one or multiple Schematics workspace. Deleting a workspace does not destroy the resources from the Schematics workspace.

<h3>Authorization</h3>

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

Request

Request Body

WorkspaceBulkDeleteRequest

Create a workspace deletion job

job

string

Job type such as delete of a batch operation.

version

string

A version of the terraform template.

workspaces

array

The List of workspaces to be deleted.

Path Parameters

Query Parameters

Response

200 - Successfully initiated the workspace deletion.

job

string

The workspace deletion job name.

job_id

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions. ">

Get the workspace deletion job status

GET /v1/workspace_jobs/{wj_id}/status

Retrieve detailed information for a workspace deletion job status.

<h3>Authorization</h3>

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

Request

Path Parameters

wj_id

Required *

string

The workspace job ID.

Query Parameters

Response

200 - Successfully retrieved details about your workspace deletion job.

job_status

WorkspaceJobStatusType

Status of the workspace bulk 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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

Auditing

Calling this method generates the following auditing event.

schematics.action.list

Request

Path Parameters

Query Parameters

offset

integer

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.

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

Response

200 - Successfully retrieved all actions.

total_count

integer

Total number of records

limit

integer

Number of records returned

offset

integer

Skipped number of records

actions

array

Message text

message_id

POST /v2/actions

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.

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.action.create

Source of templates, playbooks, or controls

source_type

Required *

Query Parameters

Response

201 - Successfully created a new Action definition

name

string

The unique name of your action. The name can be up to 128 characters long and can include alphanumeric characters, spaces, dashes, and underscores. Example you can use the name to stop action.

description

string

Action description

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Delete an action

DELETE /v2/actions/{action_id}

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.

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.action.delete

Request

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

Response

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.

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions. ">

Get action details

GET /v2/actions/{action_id}

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.

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.action.read

Request

Path Parameters

action_id

Required *

string

Action description

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

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

Update an action

PATCH /v2/actions/{action_id}

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.

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.action.update

Request

Request Body

Action

Action

name

string

The unique name of your action. The name can be up to 128 characters long and can include alphanumeric characters, spaces, dashes, and underscores. Example you can use the name to stop action.

description

string

Action description

string

set_by

string

Name of the User who set the state of the Object

set_at

string

When the User who set the state of the Object

source_readme_url

string

URL of the `README` file, for the source URL.

source

ExternalSource

Source of templates, playbooks, or controls

source_type

Required *

string

redacted

string

This is used to check if the credentials are masked or not

use_default

boolean

True, will ignore the data in the value attribute, instead the data in metadata.default_value will be used

metadata

object

An user editable metadata for the credential variables.

link

string

The reference link to the variable value By default the expression points to `$self.value`.

string

Encryption scheme

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

Response

200 - Successfully updated an action.

name

string

The unique name of your action. The name can be up to 128 characters long and can include alphanumeric characters, spaces, dashes, and underscores. Example you can use the name to stop action.

description

string

Action description

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions. ">

Upload a TAR file to an action

PUT /v2/actions/{action_id}/template_repo_upload

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.

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.action.update

Request

Request Body

Upload template tar file

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

Response

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

file_value

string

Tar file value.

has_received_file

boolean

Has received tar file?

id

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

List jobs

GET /v2/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}`.

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.job.list

Request

Path Parameters

Query Parameters

offset

integer

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.

string

list jobs

Response

200 - Successfully listed the jobs that you have access to.

total_count

integer

Total number of records

limit

integer

Number of records returned

offset

integer

Skipped number of records

jobs

array

schematics.job.create

The description of your job is derived from the related action or workspace. The description can be up to 2048 characters long in size.

JobData

Job data

job_type

assignment_policy_id

string

ID of the agent assignment policy, that is used to bind the Agent to schematics object

Path Parameters

Query Parameters

Response

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Stop the running Job, and delete the Job

DELETE /v2/jobs/{job_id}

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.

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.job.delete

Request

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

Response

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.

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Get a job

GET /v2/jobs/{job_id}

Retrieve the detailed information of Job

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.job.read

Request

Path Parameters

job_id

Required *

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Update a job

PUT /v2/jobs/{job_id}

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

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.job.update

The description of your job is derived from the related action or workspace. The description can be up to 2048 characters long in size.

JobData

Job data

job_type

assignment_policy_id

string

ID of the agent assignment policy, that is used to bind the Agent to schematics object

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

Response

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

GET /v2/jobs/{job_id}/logs

Retrieve the job logs <h3>Authorization</h3> Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

Auditing

Calling this method generates the following auditing event.

schematics.job.read

Request

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

Response

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

GET /v2/jobs/{job_id}/files

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.

Auditing

Calling this method generates the following auditing event.

schematics.job.read

Request

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.

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Get a KMS settings

GET /v2/settings/kms

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. <h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.kms_settings.read

Request

Path Parameters

Query Parameters

location

Required *

string

The location of the Resource

Response

200 - Successfully retrieved the kms settings.

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Update a KMS settings

PUT /v2/settings/kms

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. <h3>Authorization</h3>

string

The CRN of the secondary key.

Response

200 - Successfully retrieved the kms settings.

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

List KMS instances

GET /v2/settings/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.

<h3>Authorization</h3>

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

Auditing

Calling this method generates the following auditing event.

schematics.kms_instances.read

Request

Path Parameters

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.

sort

string

Response

200 - Successfully discovered the KMS instance from the customer account.

total_count

integer

The total number of records.

limit

integer

The number of records returned.

offset

integer

The skipped number of records.

kms_instances

array

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

List inventory definitions

GET /v2/inventories

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.

<h3>Authorization</h3>

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

Request

Path Parameters

Query Parameters

limit

integer

Number of records returned

offset

integer

Skipped number of records

inventories

array

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

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

Create an inventory definition

POST /v2/inventories

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.

<h3>Authorization</h3>

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

Request

Request Body

InventoryResourceDefinition

Create a Inventory definition resource

name

string

The unique name of your Inventory definition. The name can be up to 128 characters long and can include alphanumeric characters, spaces, dashes, and underscores.

description

string

The description of your Inventory definition. The description can be up to 2048 characters long in size.

redacted

string

This is used to check if the credentials are masked or not

use_default

boolean

True, will ignore the data in the value attribute, instead the data in metadata.default_value will be used

metadata

object

An user editable metadata for the credential variables.

link

string

The reference link to the variable value By default the expression points to `$self.value`.

inventory_view

InventoryView

Inventories' structured view for the provided inventory

groups

array

List of inventory groups

Response

201 - Successfully created Inventory definition resource

name

string

The unique name of your Inventory. The name can be up to 128 characters long and can include alphanumeric characters, spaces, dashes, and underscores.

id

string

Inventory id

description

string

The description of your Inventory. The description can be up to 2048 characters long in size.

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

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.

<h3>Authorization</h3>

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

Request

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

Response

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.

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

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.

<h3>Authorization</h3>

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

Request

Path Parameters

inventory_id

Required *

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

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.

<h3>Authorization</h3>

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

Request

Request Body

InventoryUpdateResourceDefinition

Update the inventory definition resource

name

string

The unique name of your Inventory definition. The name can be up to 128 characters long and can include alphanumeric characters, spaces, dashes, and underscores.

description

string

The description of your Inventory definition. The description can be up to 2048 characters long in size.

redacted

string

This is used to check if the credentials are masked or not

use_default

boolean

True, will ignore the data in the value attribute, instead the data in metadata.default_value will be used

metadata

object

An user editable metadata for the credential variables.

link

string

The reference link to the variable value By default the expression points to `$self.value`.

inventory_view

InventoryView

Inventories' structured view for the provided inventory

groups

array

List of inventory groups

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

Response

201 - Successfully updated the inventory definition resource

name

string

The unique name of your Inventory. The name can be up to 128 characters long and can include alphanumeric characters, spaces, dashes, and underscores.

id

string

Inventory id

description

string

The description of your Inventory. The description can be up to 2048 characters long in size.

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

List resource queries

GET /v2/resources_query

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. <h3>Authorization</h3>

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

Request

Path Parameters

Query Parameters

limit

integer

Number of records returned

offset

integer

Skipped number of records

resource_queries

array

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

Request

Request Body

ResourceQueryDefinition

Create a resource query definition

type

string

Resource type (cluster, vsi, icd, vpc)

name

string

Resource query name

queries

array

List of resource queries

Response

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Delete resources query

DELETE /v2/resources_query/{query_id}

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.

<h3>Authorization</h3>

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

Request

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.

Query Parameters

Response

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.

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Get resources query

GET /v2/resources_query/{query_id}

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.

<h3>Authorization</h3>

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

Request

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.

Query Parameters

Response

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Request

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.

Query Parameters

Response

200 - Successfully executed resource query

response

array

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Request

Request Body

ResourceQueryDefinition

Replace the resources query definition

type

string

Resource type (cluster, vsi, icd, vpc)

name

string

Resource query name

queries

array

List of resource queries

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.

Query Parameters

Response

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Get variable metadata by parsing the template

POST /v2/template_metadata_processor

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

<h3>Authorization</h3>

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

Request

Request Body

TemplateMetaDataRequest

Create template metadata request.

region

string

Region on which request should process. Applicable only on global endpoint.

template_type

Required *

string

Template type such as terraform, ansible, helm, cloudpak, or bash script.

source

Required *

ExternalSource

Source of templates, playbooks, or controls

source_type

Required *

string

Type of source for the Template

git

object

The connection details to the Git source repository.

catalog

object

The connection details to the IBM Cloud Catalog source.

source_type

string

Type of source for the Template

Path Parameters

Query Parameters

Response

200 - Successfully processed the template.

type

string

The template type such as terraform, ansible, helm, cloudpak, or bash script.

variables

array

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions. ">

List agents

GET /v2/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.

<h3>Authorization</h3>

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

Request

Path Parameters

Query Parameters

offset

integer

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.

profile

string

Level of details returned by the get method

filter

string

Use `new` to get all unregistered agents; use `saved` to get all registered agents.

Response

200 - Successfully listed all agents in the account

total_count

integer

The total number of records.

limit

integer

The number of records returned.

offset

integer

The skipped number of records.

agents

array

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions. ">

Create an agent

POST /v2/agents

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.

<h3>Authorization</h3>

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

Request

Request Body

AgentData

Create the agent using schematics.

name

string

Encryption scheme

Response

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

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions. ">

Delete agent

DELETE /v2/agents/{agent_id}

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.

<h3>Authorization</h3>

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

Request

Path Parameters

agent_id

Required *

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions. ">

Get agent details

GET /v2/agents/{agent_id}

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.

<h3>Authorization</h3>

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

Request

Path Parameters

agent_id

Required *

string

tags

array

Tags for the agent.

version

string

Agent version

EncryptionInfo

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions. ">

Update agent

PUT /v2/agents/{agent_id}

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.

<h3>Authorization</h3>

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

Request

Request Body

AgentData

Update the agent registration.

name

string

Encryption scheme

Path Parameters

agent_id

Required *

string

Agent ID to get the details of agent

Query Parameters

Response

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

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions.">

Get agent versions

GET /v2/agents/versions

Retrieve the list of agent version's available to be deployed. For more information about supported API endpoints, see API endpoint.

<h3>Authorization</h3>

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

Request

Response

200 - Successfully got the agent versions.

supported_agent_versions

array

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

PUT /v2/agents/{agent_id}/prs

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. <h3>Authorization</h3> Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

Request

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

Response

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Request

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

Response

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Request

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

Response

The outcome of the agent deployment job, in a formatted log string.

log_url

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Request

Path Parameters

agent_id

Required *

string

Agent ID to get the details of agent

Query Parameters

Response

202 - Successfully accepted the request to delete the resources

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

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions. ">

List policies

GET /v2/settings/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.

<h3>Authorization</h3>

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

Request

Path Parameters

Query Parameters

offset

integer

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.

profile

string

Level of details returned by the get method

Response

200 - Successfully listed all policies in the account

total_count

integer

The total number of policy records.

limit

integer

The number of policy records returned.

offset

integer

The skipped number of policy records.

policies

array

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions. ">

Create a policy account

POST /v2/settings/policies

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.

<h3>Authorization</h3>

string

When the User who set the state of the Object

kind

Required *

201 - Successfully created the policy

name

string

Name of Schematics customization policy

description

string

The description of Schematics customization policy.

resource_group

string

The resource group name for the policy. By default, Policy will be created in `default` Resource Group

tags

array

Tags for the Schematics customization policy

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions. ">

Delete policy

DELETE /v2/settings/policies/{policy_id}

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.

<h3>Authorization</h3>

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

Request

Path Parameters

policy_id

Required *

string

ID to get the details of policy

Query Parameters

Response

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.

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions. ">

Get policy

GET /v2/settings/policies/{policy_id}

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.

<h3>Authorization</h3>

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

Request

Path Parameters

policy_id

Required *

string

tags

array

Tags for the Schematics customization policy

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

Schematics service access roles and required permissions. ">

Update policy

PATCH /v2/settings/policies/{policy_id}

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.

<h3>Authorization</h3>

string

When the User who set the state of the Object

kind

Required *

policy_id

Required *

string

ID to get the details of policy

Query Parameters

Response

200 - Successfully updated the policy details

name

string

Name of Schematics customization policy

description

string

The description of Schematics customization policy.

resource_group

string

The resource group name for the policy. By default, Policy will be created in `default` Resource Group

tags

array

Tags for the Schematics customization policy

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.

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.

message

string

Message text

message_id

string

The message ID for translation.

request_id

string

The request ID for request tracking.

status_code

integer

The API response code.

timestamp

string

The API response timestamp.