spaces

Use this resource to retrieve a list of spaces that meet specified criteria, or to create a new space.

Method summary

HTTP Method	Path	Description
GET	/bwl/spaces	Returns a list of spaces that meet specified criteria. The criteria are expressed using zero or more filter parameters (`archived-state`, `parent-space-id`, `parent-space-name`, `top-space-only`) and exactly one search parameter (`name` or `tag`). Only spaces that you have access to will be returned.
POST	/bwl/spaces	Creates a space.

GET /spaces

Description: Use this method to return a list of spaces that meet specified criteria.

Resource information

Requirements	Description
Response format	JSON
Requires authentication	Yes
Supports OAuth 2 client credentials	Yes using a User Service ID containing Artifact Reporting Category

Parameters

Name	Location	Description	Required	Type
X-IBM-API-Version	Header	The version of this API. If you are programming against the API, you MUST include the version. If omitted, the latest version of the API is used, which might be incompatible with prior versions. The current value is `1.0.0`.	No	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
archived-state	Query	Filters the results based on the archived state of the space. If not specified, `active` is assumed. The only allowed values are `active` and `archived`.	No	String
name	Query	If specified, only spaces with this exact name are returned. Either a name or a tag must be specified, but not both.	No	String
parent-space-id	Query	The identifier of the space to search within. If not specified, the search is account wide. If this space contains child spaces, the child spaces will also be searched. If both a parent-space-id and parent-space-name are specified, the parent-space-id takes precedence.	No	String
parent-space-name	Query	The name of the space to search within. If not specified, the search is account wide. If both a parent-space-id and parent-space-name are specified, the parent-space-id takes precedence.	No	String
tag	Query	If specified, only spaces with this exact tag are returned. Either a name or a tag must be specified, but not both.	No	String
top-space-only	Query	If true, only top-level spaces are returned. Child spaces are not included.	No	Boolean

Response

Example 1 input - Create a new space

Create a space with the name "New Space."

Using User Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"  
   -H "Content-Type:application/json" -X POST --data "{\"name\":\"New Space\"}" 
   "https://your_server_url/bwl/spaces"

Using Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"  
   -H "Content-Type:application/json" -X POST --data "{\"name\":\"New Space\"}" "https://your_server_url/bwl/spaces"

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 "{\"name\":\"New Space\"}" "https://your_server_url/bwl/spaces"

Example 1 output - Create a new space

The new space is created and assigned an ID.

{
"name": "New Space", "id" : "20012a"
}

Example 2 input - Create a new space as a child of another space

Using User Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"  
   -H "Content-Type:application/json" -X POST --data "{\"name\":\"New Space\"}" 
   "https://your_server_url/bwl/spaces"

Using Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"  
   -H "Content-Type:application/json" -X POST --data "{\"name\":\"New Space\"}" "https://your_server_url/bwl/spaces"

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 "{\"name\":\"New Space\"}" "https://your_server_url/bwl/spaces"

Example 2 output - Create a new space as a child of another space

The new child space is created and assigned an ID.

{
"name": "New Child Space", "id" : "20012b"
}

Response properties

id: The ID of the new space.
name: The name of the new space.

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: The specified credentials are invalid. This user isn't an editor for this process. 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.

POST /spaces

Description: Use this method to create a space.

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 500 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`.	Yes	String
X-On-Behalf-Of	Header	The user context. The value must be a username in the account. The user must have permission to create an artifact in the account and the specified parent space, if any.	Required if Service ID OAuth credentials are used. Not required when using User Service ID OAuth credential.	String

Request JSON body

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

Name	Location	Description	Required	Type
name	JSON body	The name of the new space.	Yes	String
parent-space-id	JSON body	The ID of the parent space for the new space.	No	String

Response

Example 1 input - Create a new space

Create a space with the name "New Space."

Using User Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"  
   -H "Content-Type:application/json" -X POST --data "{\"name\":\"New Space\"}" 
   "https://your_server_url/bwl/spaces"

Using Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"  
   -H "Content-Type:application/json" -X POST --data "{\"name\":\"New Space\"}" "https://your_server_url/bwl/spaces"

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 "{\"name\":\"New Space\"}" "https://your_server_url/bwl/spaces"

Example 1 output - Create a new space

The new space is created and assigned an ID.

{
"name": "New Space", "id" : "20012a"
}

Example 2 input - Create a new space as a child of another space

Using User Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"  
   -H "Content-Type:application/json" -X POST --data "{\"name\":\"New Space\"}" 
   "https://your_server_url/bwl/spaces"

Using Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"  
   -H "Content-Type:application/json" -X POST --data "{\"name\":\"New Space\"}" "https://your_server_url/bwl/spaces"

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 "{\"name\":\"New Space\"}" "https://your_server_url/bwl/spaces"

Example 2 output - Create a new space as a child of another space

The new child space is created and assigned an ID.

{
"name": "New Child Space", "id" : "20012b"
}

Response properties

id: The ID of the new space.
name: The name of the new space.

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. This response could appear for the following reasons: The JSON body is missing from the request. The parent-space-id provided does not exist in this account. The `name` property is missing from the JSON request body.
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	This user does not have permission to create a space in 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.