spaces/{space-id}

Use this resource to retrieve information about a specific space.

Method summary

HTTP Method	Path	Description
GET	/bwl/spaces/{space-id}	Retrieves information about a specific space. You must have access to this space.

GET /spaces/{space-id}

Description: Use this method to return the details of a specific space.

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
space-id	Path	The identifier of the space to retrieve.	Yes	String
archived-state	Query	Filters the returned child artifacts based on the archived state of the artifact. If not specified, `active` is assumed. The permitted values are `all`, `active`, and `archived`.	No	String
include-subspaces	Query	Whether to include details of the subspaces in the response.	No	Boolean
published-state	Query	Filters the returned child artifacts based on the published state of the artifact. Child policies and child spaces are unaffected by this filter. If not specified, `all` is assumed. The permitted values are `all`, `published`, and `unpublished`.	No	String

Response

Example input

GET the details of a specific space:

Using OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"  
    "https://your_server_url/bwl/spaces/1310cb?include-subspaces=true"

Example output

GET the details of a specific space:

{
  "name": "My Space",
  "id": "1310cb",
  "tags": [
    "demo",
    "space-details-api"
  ],
  "description": "Space Details API Example Output",
  "goals": [
    {
      "description": "Goal 1",
      "weight": "high"
    },
    {
      "description": "Goal 2",
      "weight": "medium"
    },
    {
      "description": "Goal 3",
      "weight": "low"
    }
  ],
  "users": [
    {
      "participant": {
        "name": "Edith Editor",
        "id": "50023",
        "type": "user"
      },
      "permissions": {
        "blueprint-processes": true,
        "automate-processes": true,
        "compose-decisions": true,
        "author-policies": true,
        "manage-and-edit": true
      }
    },
    {
      "participant": {
        "type": "all-editors"
      },
      "permissions": {
        "blueprint-processes": true,
        "automate-processes": true,
        "compose-decisions": true,
        "author-policies": true,
        "manage-and-edit": false
      }
    },
    {
      "participant": {
        "type": "all-contributors"
      },
      "permissions": {
        "blueprint-processes": false,
        "automate-processes": true,
        "compose-decisions": false,
        "author-policies": false,
        "manage-and-edit": false
      }
    },
    {
      "participant": {
        "type": "all-community"
      },
      "permissions": {
        "blueprint-processes": false,
        "automate-processes": false,
        "compose-decisions": false,
        "author-policies": false,
        "manage-and-edit": false
      }
    },
    {
      "participant": {
        "name": "My Custom Group",
        "id": "1310d7",
        "type": "user-group"
      },
      "permissions": {
        "blueprint-processes": true,
        "automate-processes": true,
        "compose-decisions": false,
        "author-policies": true,
        "manage-and-edit": false
      }
    }
  ],
  "subspaces": [
    {
      "name": "My Subspace",
      "id": "131934",
      "tags": [
        "child-of-root-space",
        "subspace"
      ],
      "goals": [
        {
          "description": "Subspace goal 1",
          "weight": "low"
        },
        {
          "description": "Subspace goal 2",
          "weight": "medium"
        },
        {
          "description": "Subspace goal 3",
          "weight": "high"
        }
      ],
      "users": [
        {
          "participant": {
            "name": "Edith Editor",
            "id": "50023",
            "type": "user"
          },
          "permissions": {
            "blueprint-processes": true,
            "automate-processes": true,
            "compose-decisions": true,
            "author-policies": true,
            "manage-and-edit": true
          }
        },
        {
          "participant": {
            "type": "all-editors"
          },
          "permissions": {
            "blueprint-processes": true,
            "automate-processes": true,
            "compose-decisions": true,
            "author-policies": true,
            "manage-and-edit": false
          }
        },
        {
          "participant": {
            "type": "all-contributors"
          },
          "permissions": {
            "blueprint-processes": false,
            "automate-processes": true,
            "compose-decisions": false,
            "author-policies": false,
            "manage-and-edit": false
          }
        },
        {
          "participant": {
            "type": "all-community"
          },
          "permissions": {
            "blueprint-processes": false,
            "automate-processes": false,
            "compose-decisions": false,
            "author-policies": false,
            "manage-and-edit": false
          }
        }
      ],
      "space-ids": [
        "1310cb"
      ],
      "space-names": [
        "My Space"
      ],
      "archived-state": "active",
      "last-modified-date": "2017-01-13T04:34:47.073+0000",
      "last-modified-by-user": {
        "id": "50029",
        "full-name": "Edith Editor",
        "email-address": "edith"
      },
      "created-date": "2017-01-12T22:29:51.106+0000",
      "created-by-user": {
        "id": "50029",
        "full-name": "Edith Editor",
        "email-address": "edith"
      }
    }
  ],
  "blueprints": [
    {
      "id": "1310dc",
      "name": "My Blueprint",
      "type": "blueprint",
      "tags": [
        "lambda"
      ],
      "space-ids": [
        "1310cb"
      ],
      "space-names": [
        "My Space"
      ],
      "archived-state": "active",
      "published-state": "unpublished",
      "last-modified-date": "2017-01-12T22:32:57.146+0000",
      "last-modified-by-user": {
        "id": "50029",
        "full-name": "Edith Editor",
        "email-address": "edith"
      },
      "created-date": "2017-01-12T22:29:51.106+0000",
      "created-by-user": {
        "id": "50029",
        "full-name": "Edith Editor",
        "email-address": "edith"
      }
    }
  ],
  "decisions": [
    {
      "id": "1c002a",
      "name": "My Published Decision",
      "type": "decision",
      "current-name": "My Published Decision",
      "space-ids": [
        "1310cb"
      ],
      "space-names": [
        "My Space"
      ],
      "archived-state": "active",
      "published-state": "published",
      "last-modified-date": "2017-01-13T20:34:15.237+0000",
      "last-modified-by-user": {
        "id": "50029",
        "full-name": "Edith Editor",
        "email-address": "edith"
      },
      "created-date": "2017-01-12T22:29:51.106+0000",
      "created-by-user": {
        "id": "50029",
        "full-name": "Edith Editor",
        "email-address": "edith"
      },
      "published-date": "2017-01-13T20:34:15.237+0000",
      "published-snapshot-name": "v1",
      "published-snapshot-date": "2017-01-13T20:34:11.362+0000"
    }
  ],
  "policies": [
    {
      "id": "1a001d",
      "name": "My Archived Policy",
      "type": "policy",
      "tags": [
        "archived"
      ],
      "space-ids": [
        "1310cb"
      ],
      "space-names": [
        "My Space"
      ],
      "archived-state": "archived",
      "last-modified-date": "2017-01-13T15:10:55.676+0000",
      "last-modified-by-user": {
        "id": "50029",
        "full-name": "Edith Editor",
        "email-address": "edith"
      },
      "created-date": "2017-01-12T22:29:51.106+0000",
      "created-by-user": {
        "id": "50029",
        "full-name": "Edith Editor",
        "email-address": "edith"
      }
    }
  ],
  "archived-state": "active",
  "last-modified-date": "2017-01-15T00:21:55.841+0000",
  "process-apps": [
    {
      "id": "131902",
      "name": "My Process App",
      "type": "process-app",
      "space-ids": [
        "1310cb"
      ],
      "space-names": [
        "My Space"
      ],
      "archived-state": "active",
      "published-state": "unpublished",
      "last-modified-date": "2017-01-12T22:34:02.175+0000",
      "last-modified-by-user": {
        "id": "50029",
        "full-name": "Edith Editor",
        "email-address": "edith"
      },
      "created-date": "2017-01-12T22:29:51.106+0000",
      "created-by-user": {
        "id": "50029",
        "full-name": "Edith Editor",
        "email-address": "edith"
      }
    }
  ]
}

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 because you have insufficient permissions for the specified space.
404	The space-id parameter identifies a space that does not exist 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.