artifacts/{artifact_id}

Use this resource to copy, move, rename, archive, or delete an artifact, such as a space, process, decision, policy, or process app, or to publish or unpublish a process or decision.

Method summary

HTTP Method	Path	Description
PUT	/bwl/artifacts/{artifact_id}	Moves, renames, or archives a space, process, decision, policy, or process app, or publishes or unpublishes a process or decision.
POST	/bwl/artifacts/{artifact_id}	Copies a space, process, decision, policy, or process app.
DELETE	/bwl/artifacts/{artifact_id}	Deletes a space, process, decision, policy, or process app.

PUT /artifacts/{artifact_id}

Description: Use this method to move an artifact to another space, rename an artifact, archive an artifact, or publish or unpublish a process or decision.

Resource information

Requirements	Description
Response format	JSON
Requires authentication	Yes
Supports OAuth 2 client credentials	Yes using a User Service ID containing Artifact Authoring Category
Rate limited	IBM Blueworks Live applies a rate limit that determines how often this API can be called within a specific period. The allowed rate is 200 requests per hour. The rate limit is applied to the whole account. Even if different authentication methods are used, the single account-wide rate is applied across all users. Once the rate limit for the API is exceeded for the account, the next request is rejected with status code 429 and response header `Retry-After`, which indicates the number of seconds when the next request can be made.

Parameters

Name	Location	Description	Required	Type
Content-Type	Header	The value must be `application/json`.	Required when there is content in the request body	String
X-On-Behalf-Of	Header	The user context. The value must be a username in the account. The user must have permission to perform the action in the account and in the specified parent space, if any.	Required if Service ID OAuth credentials are used. Not required when using User Service ID OAuth credential.	String
artifact_id	Path	The ID of the artifact to move, rename, or archive.	Yes	String
action	Query	The action to perform on the artifact. The actions are: move rename archive publish unpublish	Yes	String
revision-id	Query	The ID of the revision of the process or decision to publish. This parameter works only with the `publish` action. To get revision values, call the revision API with the artifact ID. If no revision is passed in, the most recent version is published.	No	String

Request JSON body

The request body is a JSON object containing the following properties:

Name	Location	Description	Required	Type
parent-space-id	JSON body	The ID of the parent space to move the artifact into.	Required for a process, decision, policy, or process app. For a space, if this parameter is not provided, the space is moved to the top of the library.	String
name	JSON body	The new name to give the artifact.	Required for the rename action	String

Response

Example 1 input - Move an artifact from one space to another

Move an artifact with the ID caa123456789 from one space to another space. The second space has the ID dff123456789. Both spaces must be in the same account.

Using User Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"   
  -H "Content-Type:application/json"
  -X PUT --data "{\"parent-space-id\":\"dff123456789\"}"
  "https://your_server_url/bwl/artifacts/caa123456789?action=move"

Using Service ID OAuth 2 client credentials with user context:

curl -i -H "Authorization: Bearer access_token"   
  -H "Content-Type:application/json" -H "X-On-Behalf-Of:user_name@domain.com" 
  -X PUT --data "{\"parent-space-id\":\"dff123456789\"}"
  "https://your_server_url/bwl/artifacts/caa123456789?action=move"

Example 2 input - Move a space to the top of the library

Move a space without specifying a parent space.

Using OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token" 
  -H "Content-Type:application/json" -X PUT "https://your_server_url/bwl/artifacts/caa123456789?action=move"

Example 3 input - Rename an artifact

Rename an artifact from its previous name to "new_name."

Using User Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"   
  -H "Content-Type:application/json" 
  -X PUT --data "{\"name\":\"new_name\"}"
  "https://your_server_url/bwl/artifacts/caa123456789?action=rename"

Using Service ID OAuth 2 client credentials with user context:

curl -i -H "Authorization: Bearer access_token"   
  -H "Content-Type:application/json" -H "X-On-Behalf-Of:user_name@domain.com" 
  -X PUT --data "{\"name\":\"new_name\"}"
  "https://your_server_url/bwl/artifacts/caa123456789?action=rename"

Example 4 input - Archive an artifact

Archive an artifact.

Using User Service ID OAuth 2 client credentials with user context:

curl -i -H "Authorization: Bearer access_token"  
  -H "Content-Type:application/json" 
  -X PUT "https://your_server_url/bwl/artifacts/caa123456789?action=archive"

Using Service ID OAuth 2 client credentials with user context:

curl -i -H "Authorization: Bearer access_token"  
  -H "Content-Type:application/json" -H "X-On-Behalf-Of:user_name@domain.com" 
  -X PUT "https://your_server_url/bwl/artifacts/caa123456789?action=archive"

Example 5 input - Publish a process or decision

Publish a specific revision of a process or decision.

Using Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"  
  -H "Content-Type:application/json" 
  -X PUT "https://your_server_url/bwl/artifacts/2e0008?action=publish&revision-id=2e0073"

Using Service ID OAuth 2 client credentials with user context:

curl -i -H "Authorization: Bearer access_token"  
  -H "Content-Type:application/json" -H "X-On-Behalf-Of:user_name@domain.com" 
  -X PUT "https://your_server_url/bwl/artifacts/2e0008?action=publish&revision-id=2e0073"

Example 6 input - Unpublish a process or decision

Unpublish a process or decision.

Using User Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"  
  -H "Content-Type:application/json" 
  -X PUT "https://your_server_url/bwl/artifacts/2e0008?action=unpublish"

Using Service ID OAuth 2 client credentials with user context:

curl -i -H "Authorization: Bearer access_token"  
  -H "Content-Type:application/json" -H "X-On-Behalf-Of:user_name@domain.com" 
  -X PUT "https://your_server_url/bwl/artifacts/2e0008?action=unpublish"

Example output: If the request is successful, a 200 OK message is returned.

Response headers

Header name	Description
Retry-After	When the next request can be made, in number of seconds.

Response messages

HTTP code	Reason
200	The request was completed successfully.
400	There was an error processing the request. A policy ID doesn't exist in the account, the JSON body is missing from the request, or a required parameter is missing.
401	This user didn't pass authentication. This response could appear for the following reasons: An invalid username or password was provided. This user belongs to multiple accounts and an account wasn't specified in the request.
403	Access is forbidden. This message might appear for one of the following reasons: This user doesn't have permission to move, rename, archive, publish, or unpublish this artifact. This user doesn't have permission to copy an artifact to this parent space. APIs aren't enabled by the administrator. APIs must be enabled on the Account Information tab. The administrator didn't accept the Terms and Conditions of service.
404	The artifact or revision ID does not exist in the account.
429	The request exceeded the rate limit of the API for this account.

POST/artifacts/{artifact_id}

Description: Use this method to copy an artifact, such as a space, process, decision, policy, or process app.

Resource information

Requirements	Description
Response format	JSON
Requires authentication	Yes
Supports OAuth 2 client credentials	Yes using a User Service ID containing Artifact Authoring Category
Rate limited	IBM Blueworks Live applies a rate limit that determines how often this API can be called within a specific period. The allowed rate for copying spaces is 10 requests per hour. The allowed rate for copying other artifacts is 100 requests per hour. The rate limit is applied to the whole account. Even if different authentication methods are used, the single account-wide rate is applied across all users. Once the rate limit for the API is exceeded for the account, the next request is rejected with status code 429 and response header `Retry-After`, which indicates the number of seconds when the next request can be made.

Parameters

Name	Location	Description	Required	Type
Content-Type	Header	The value must be `application/json`.	Required when there is content in the request body	String
X-On-Behalf-Of	Header	The user context. The value must be a username in the account. The user must have permission to copy an artifact in the account and to the specified parent space, if any.	Required if Service ID OAuth credentials are used. Not required when using User Service ID OAuth credential.	String
artifact_id	Path	The ID of the artifact to copy.	Yes	String

Request JSON body

The request body is a JSON object containing the following properties:

Name	Location	Description	Required	Type
parent-space-id	JSON body	The ID of the parent space to copy the artifact into.	No. For a process, decision, policy, or process app, if this parameter is not provided, the artifact is copied in the current space. For a space, if this parameter is not provided, the space is copied to the top of the library.	String
name	JSON body	The new name to give the artifact.	No. If this parameter is not provided and the artifact is copied in the current space, the new artifact is named Copy of `artifact`.	String

Response

Example 1 input - Copy an artifact from one space to another

Copy a process with process ID c00f9543, name My new process, and target space ID d00a8894 from one space to another space. Both spaces must be in the same account.

Using User Service ID OAuth 2 client credentials with user context:

curl -i -H "Authorization: Bearer access_token"   
  -H "Content-Type:application/json" 
  -X POST --data "{\"parent-space-id\":\"d00a8894\", \"name\":\"My new process\"}"
  "https://your_server_url/bwl/artifacts/c00f9543"

Using Service ID OAuth 2 client credentials with user context:

curl -i -H "Authorization: Bearer access_token"   
  -H "Content-Type:application/json" -H "X-On-Behalf-Of:user_name@domain.com" 
  -X POST --data "{\"parent-space-id\":\"d00a8894\", \"name\":\"My new process\"}"
  "https://your_server_url/bwl/artifacts/c00f9543"

Example 1 output - Copy an artifact from one space to another

The new process is copied and assigned an ID.

{
  "new-artifact-id" : "130d43"
}

Example 2 input - Copy a space to the top of the library

Copy a space with ID c00f9543 and new name My new space without specifying a parent space.

Using OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"   
  -H "Content-Type:application/json" -X POST --data "{\"name\":\"My new space\"}" 
  "https://your_server_url/bwl/artifacts/c00f9543"

Example 2 output - Copy a space to the top of the library

The new space is copied to the top of the library and assigned an ID.

{
  "new-artifact-id" : "270b41"
}

Example 3 input - Copy an artifact that contains some artifacts that can't be copied

Copy a space that contains some artifacts that can't be copied.

curl -i -H "Authorization: Bearer access_token"  
   -H "Content-Type:application/json" -X POST --data "{\"parent-space-id\":\"d00a8894\", \"name\":\"My new space\"}"
   "https://your_server_url/bwl/artifacts/c00f9543"

Example 3 output - Copy an artifact that contains some artifacts that can't be copied

The output is a list of the artifacts that were copied and warning messages for the artifacts that were not copied.

{
   "new-artifact-id": "560001",
   "new-artifact-name": "My new space",
   "copied-artifacts": [
      "124a71",
      "124a26"
   ],
   "not-copied": [
      {
         "code": "BWLCS01",
         "message": "These artifacts are archived and cannot be copied.",
         "items": [
            "122a35",
            "124a43"
         ]
      },
      {
         "code": "BWLCS03",
         "message": "These file attachments are missing and cannot be copied.",
         "items": [
            "d22e5",
            "d24a43"
         ]
      }
   ]
}
}

Validation messages

Error code	Error message
BWLCS01	These artifacts are archived and cannot be copied.
BWLCS02	This user does not have permission to copy these artifacts.
BWLCS03	These file attachments are missing and cannot be copied.

Response headers

Header name	Description
Retry-After	When the next request can be made, in number of seconds.

Response messages

HTTP code	Reason
200	The request was completed successfully.
400	There was an error processing the request. A policy ID doesn't exist in the account, the JSON body is missing from the request, or a required parameter is missing.
401	This user didn't pass authentication. This response could appear for the following reasons: An invalid username or password was provided. This user belongs to multiple accounts and an account wasn't specified in the request.
403	Access is forbidden. This message might appear for one of the following reasons: This user doesn't have permission to copy this process. This user doesn't have permission to copy an artifact to this parent space. APIs aren't enabled by the administrator. APIs must be enabled on the Account Information tab. The administrator didn't accept the Terms and Conditions of service.
429	The request exceeded the rate limit of the API for this account.

DELETE /bwl/artifacts/{artifact_id}

Description: Use this method to delete a space, process, decision, policy, or process app. The artifact must be archived to be deleted. If the artifact has running instances or running governance workflows, or if deleting the artifact results in broken links, the deletion fails unless you add the force parameter.

Resource information

Requirements	Description
Response format	JSON
Requires authentication	Yes. The user must be an account administrator.
Supports OAuth 2 client credentials	Yes using a User Service ID containing Artifact Authoring Category
Rate limited	IBM Blueworks Live applies a rate limit that determines how often this API can be called within a specific period. The allowed rate is 200 requests per hour. The rate limit is applied to the whole account. Even if different authentication methods are used, the single account-wide rate is applied across all users. Once the rate limit for the API is exceeded for the account, the next request is rejected with status code 429 and response header `Retry-After`, which indicates the number of seconds when the next request can be made.

Parameters

Name	Location	Description	Required	Type
X-On-Behalf-Of	Header	The user context. The value must be a username in the account. The user must have permission to delete artifacts in the account.	Required if Service ID OAuth credentials are used. Not required when using User Service ID OAuth credential.	String
id	Path	The ID of the artifact to delete.	Yes	String
force	Query	Force the deletion. If you set this parameter to true, the artifact is deleted even if it has running instances or running governance workflows, and even if deleting it results in broken links. Warnings and linkage errors are summarized in the response.	No	Boolean

Response

Example 1 input - Delete an artifact

Delete an artifact.

Using User Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"   
  -H "Content-Type:application/json" 
  -X DELETE "https://your_server_url/bwl/artifacts/c00f9543"

Using Service ID OAuth 2 client credentials with user context:

curl -i -H "Authorization: Bearer access_token"   
  -H "Content-Type:application/json" -H "X-On-Behalf-Of:user_name@domain.com" 
  -X DELETE "https://your_server_url/bwl/artifacts/c00f9543"

Example 1 output - Delete an artifact

In this example, the artifact is not deleted.

HTTP/1.1 409 Conflict
{
    "developer-message": "This artifact was not deleted because there are active artifacts that contain links to it or incomplete work items based on it",
    "user-message": "This artifact was not deleted because there are active artifacts that contain links to it or incomplete work items based on it.",
    "using-artifacts": [
        {
            "id": "6000be",
            "name": "LinkedToA",
            "type": "blueprint",
            "space-ids": [
                "6000b5"
            ],
            "space-names": [
                "XSpace"
            ],
            "archived-state": "active",
            "published-state": "unpublished",
            "last-modified-date": "2020-09-02T19:13:19.041+0000"
        },
        {
            "id": "601d45",
            "name": "LinkedToB",
            "type": "blueprint",
            "space-ids": [
                "601d3c"
            ],
            "space-names": [
                "YSpace"
            ],
            "archived-state": "active",
            "published-state": "unpublished",
            "last-modified-date": "2020-09-02T19:14:57.266+0000"
        }
    ],
    "active-workitems": [
        {
            "id": "86005a",
            "name": "App1 - Launch me",
            "app-id": "86002b",
            "space-ids": [
                "770002",
                "840006"
            ],
            "space-names": [
                "ASpace",
                "BSpace"
            ]
        }
    ]
}

Example 2 input - Force deletion of an artifact

Force deletion of an artifact.

Using User service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"   
  -H "Content-Type:application/json" 
  -X DELETE "https://your_server_url/bwl/artifacts/c00f9543?force=true"

Using Service ID OAuth 2 client credentials with user context:

curl -i -H "Authorization: Bearer access_token"   
  -H "Content-Type:application/json" -H "X-On-Behalf-Of:user_name@domain.com" 
  -X DELETE "https://your_server_url/bwl/artifacts/c00f9543?force=true"

Example 2 output - Force deletion of an artifact

The artifact is deleted with warnings.

HTTP/1.1 200 OK
{ 
  "developer-message": "Artifact deleted with warnings. There are active artifacts that contained links to it or incomplete work items based on it",
    "user-message": "Artifact deleted with warnings. There are active artifacts that contained links to it or incomplete work items based on it.",
    "using-artifacts": [
        {
            "id": "6000be",
            "name": "LinkedToA",
            "type": "blueprint",
            "space-ids": [
                "6000b5"
            ],
            "space-names": [
                "XSpace"
            ],
            "archived-state": "active",
            "published-state": "unpublished",
            "last-modified-date": "2020-09-02T19:13:19.041+0000"
        },
        {
            "id": "601d45",
            "name": "LinkedToB",
            "type": "blueprint",
            "space-ids": [
                "601d3c"
            ],
            "space-names": [
                "YSpace"
            ],
            "archived-state": "active",
            "published-state": "unpublished",
            "last-modified-date": "2020-09-02T19:14:57.266+0000"
        }
    ],
    "active-workitems": [
        {
            "id": "86005a",
            "name": "App1 - Launch me",
            "app-id": "86002b",
            "space-ids": [
                "770002",
                "840006"
            ],
            "space-names": [
                "ASpace",
                "BSpace"
            ]
        }
    ]
}

Response headers

Header name	Description
Retry-After	When the next request can be made, in number of seconds.

Response messages

HTTP code	Reason
200	The request was completed successfully.
400	There was an error processing the request. Required parameters were missing or contained invalid values.
401	This user didn't pass authentication. This response could appear for the following reasons: An invalid username or password was provided. This user belongs to multiple accounts and an account wasn't specified in the request.
403	Access is forbidden. This message might appear for one of the following reasons: This user doesn't have permission to delete this artifact. This user doesn't have permission to delete all the child spaces. The artifact is a training space or contains a training space. APIs aren't enabled by the administrator. APIs must be enabled on the Account Information tab. The administrator didn't accept the Terms and Conditions of service.
409	The command failed because the artifact has active links to it or work items based on it.
429	The request exceeded the rate limit of the API for this account.

More details

To get more details about the operations and response values, use a Swagger Editor to view the APIs:

Download the rest-apis.zip file.
Extract the openapi.yaml file.
Open a web browser, and navigate to https://editor-next.swagger.io/.
Import openapi.yaml using the File > Import File option.