Link Search Menu Expand Document Documentation Menu
Documentation

Workspace APIs

Introduced 2.18

Use the Workspace APIs to manage workspaces in OpenSearch Dashboards.

These endpoints are served by OpenSearch Dashboards, so send requests to the OpenSearch Dashboards host and port (5601 by default). Requests that use POST, PUT, or DELETE require the osd-xsrf: true header. Scripts written for Kibana OSS send the kbn-xsrf: true header instead, and OpenSearch Dashboards rejects these requests with the error Request must contain a osd-xsrf header. To fix this error, replace kbn-xsrf with osd-xsrf in your scripts.

List workspaces

You can use the following endpoint to retrieve a list of workspaces:

POST {osd_host}:{port}/api/workspaces/_list

The following table lists the available path parameters.

Parameter Data type Required Description
search String Optional A query string used to filter workspaces with simple query syntax, for example, simple_query_string.
searchFields Array Optional Specifies which fields to perform the search query against.
sortField String Optional The field name to use for sorting results.
sortOrder String Optional Specifies ascending or descending sort order.
perPage Number Optional The number of workspace results per page.
page Number Optional The number of pages of results to retrieve.
permissionModes Array Optional A list of permissions to filter by.

Example request

curl -k -u admin:admin \
  -H 'osd-xsrf: true' \
  -H 'Content-Type: application/json' \
  -X POST 'https://localhost:5601/api/workspaces/_list' \
  -d '{}'

The following example response shows a successful API call:

{
  "success": true,
  "result": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "workspaces": [
      {
        "name": "test4",
        "description": "test4",
        "features": [
          "use-case-all"
        ],
        "lastUpdatedTime": "2025-09-10T14:47:04.741Z",
        "id": "B9Le1w",
        "permissionMode": "read"
      }
    ]
  }
}

Get a workspace

You can use the following endpoint to retrieve a single workspace:

GET {osd_host}:{port}/api/workspaces/{id}

The following table lists the available path parameters. All path parameters are required.

Parameter Data type Required Description
<id> String Required Identifies the unique workspace to be retrieved.

Example request

curl -k -u admin:admin -X GET 'https://localhost:5601/api/workspaces/B9Le1w'

The following example response shows a successful API call:

{
  "success": true,
  "result": {
    "name": "test4",
    "description": "test4",
    "features": [
      "use-case-all"
    ],
    "lastUpdatedTime": "2025-09-10T14:47:04.741Z",
    "id": "B9Le1w"
  }
}

Create a workspace

You can use the following endpoint to create a workspace:

POST {osd_host}:{port}/api/workspaces

The following table lists the available path parameters.

Parameter Data type Required Description
attributes Object Required Defines the workspace attributes.
attributes.id String Optional The ID of the workspace.
permissions Object Optional Specifies the permissions for the workspace.
settings Object Optional Specifies the settings for the workspace.

Example request

curl -k -XPOST "https://localhost:5601/api/workspaces" \
  -H "Content-Type: application/json" \
  -H "osd-xsrf: true" \
  -d '{
    "attributes": {
      "id": "my_workspace",
      "name": "test4",
      "description": "test4",
      "features": ["use-case-all"]
    }
  }' -u admin:admin

The following example response shows a successful API call:

{
    "success": true,
    "result": {
        "id": "B9Le1w"
    }
}

Update a workspace

You can use the following endpoint to update the attributes and permissions for a workspace:

PUT {osd_host}:{port}/api/workspaces/{id}

The following table lists the available path parameters.

Parameter Data type Required Description
<id> String Required Identifies the unique workspace to be retrieved.
attributes Object Required Defines the workspace attributes.
permissions Object Optional Specifies the permissions for the workspace.

Example request without permissions object

curl -k -XPUT "https://localhost:5601/api/workspaces/B9Le1w" \
  -H "Content-Type: application/json" \
  -H "osd-xsrf: true" \
  -d '{
    "attributes": {
      "name": "test5",
      "description": "Updated description"
    }
  }' -u admin:admin

The following example response shows a successful API call:

{
    "success": true,
    "result": true
}

Example request with permissions object

When a request includes a permissions object, each user or group must be assigned the set of permission modes required for the desired access level. For example, read-only access requires both the library_read and read permission modes:

curl -k -u admin:admin \
  -H 'osd-xsrf: true' \
  -H 'Content-Type: application/json' \
  -X PUT 'https://localhost:5601/api/workspaces/B9Le1w' \
  -d '{
    "attributes": {},
    "settings": {
      "permissions": {
        "library_write": { "users": ["obs-admin-user"] },
        "write": { "users": ["obs-admin-user"] },
        "library_read": { "groups": ["obs-read-users"] },
        "read": { "groups": ["obs-read-users"] }
      }
    }
  }'

For a complete list of permission modes and the access levels they provide, see Defining workspace collaborators.

Delete a workspace

You can use the following endpoint to delete a workspace:

DELETE {osd_host}:{port}/api/workspaces/{id}

The following table lists the available path parameters. All path parameters are required.

Parameter Data type Required Description
<id> String Required Identifies the unique workspace to be retrieved.

Example request

curl -k -u admin:admin \
  -H 'osd-xsrf: true' \
  -X DELETE 'https://localhost:5601/api/workspaces/B9Le1w'

The following example response shows a successful API call:

{
    "success": true,
    "result": true
}

Duplicate saved objects

You can use the following endpoint to copy saved objects between workspaces:

POST {osd_host}:{port}/api/workspaces/_duplicate_saved_objects

The following table lists the available path parameters.

Parameter Data type Required Description
objects Array Required Specifies the saved objects to be duplicated.
targetWorkspace String Required Identifies the destination workspace for copying.
includeReferencesDeep Boolean Optional Determines whether to copy all referenced objects to the target workspace. Default is true.

The following table lists the attributes of the object in the objects parameter.

Parameter Data type Required Description
type String Required Defines the saved object classification, such as index-pattern, config, or dashboard.
id String Required The ID of the saved object.

Example request

curl -k -u admin:admin \
  -H 'osd-xsrf: true' \
  -H 'Content-Type: application/json' \
  -X POST 'https://localhost:5601/api/workspaces/_duplicate_saved_objects' \
  -d '{
    "objects": [
      { "type": "index-pattern", "id": "619cc200-ecd0-11ee-95b1-e7363f9e289d" }
    ],
    "targetWorkspace": "9gt4lB"
  }'

The following example response shows a successful API call:

{
    "successCount": 1,
    "success": true,
    "successResults": [
        {
            "type": "index-pattern",
            "id": "619cc200-ecd0-11ee-95b1-e7363f9e289d",
            "meta": {
                "title": "test*",
                "icon": "indexPatternApp"
            },
            "destinationId": "f4b724fd-9647-4bbf-bf59-610b43a62c75"
        }
    ]
}

Associate saved objects

You can use the following endpoint to associate saved objects with a workspace:

POST {osd_host}:{port}/api/workspaces/_associate

The following table lists the available path parameters.

Parameter Data type Required Description
workspaceId String Required Identifies the target workspace for object association.
savedObjects Array Required Specifies the list of saved objects to be copied.

The following table lists the attributes of the object in the savedObjects parameter.

Parameter Data type Required Description
type String Required Defines the saved object classification, such as index-pattern, config, or dashboard.
id String Required The ID of the saved object.

Example request

curl -k -u admin:admin \
  -H 'osd-xsrf: true' \
  -H 'Content-Type: application/json' \
  -X POST 'https://localhost:5601/api/workspaces/_associate' \
  -d '{
    "savedObjects": [
      { "type": "index-pattern", "id": "619cc200-ecd0-11ee-95b1-e7363f9e289d" }
    ],
    "workspaceId": "9gt4lB"
  }'

The following example response shows a successful API call:

{
    "success": true,
    "result": [
        {
            "id": "619cc200-ecd0-11ee-95b1-e7363f9e289d",
        }
    ]
}

Dissociate saved objects

You can use the following endpoint to dissociate saved objects from a workspace:

POST {osd_host}:{port}/api/workspaces/_dissociate

The following table lists the available path parameters.

Parameter Data type Required Description
workspaceId String Required The target workspace with which to associate the objects.
savedObjects Array Required A list of saved objects to copy.

The following table lists the attributes of the savedObjects parameter.

Parameter Data type Required Description
type String Required The type of the saved object, such as index-pattern, config, or dashboard.
id String Required The ID of the saved object.

Example request

curl -k -u admin:admin \
  -H 'osd-xsrf: true' \
  -H 'Content-Type: application/json' \
  -X POST 'https://localhost:5601/api/workspaces/_dissociate' \
  -d '{
    "savedObjects": [
      { "type": "index-pattern", "id": "619cc200-ecd0-11ee-95b1-e7363f9e289d" }
    ],
    "workspaceId": "9gt4lB"
  }'

The following example response shows a successful API call:

{
    "success": true,
    "result": [
        {
            "id": "619cc200-ecd0-11ee-95b1-e7363f9e289d",
        }
    ]
}
350 characters left

Have a question? .

Want to contribute? or .