
The Saved Views API provides a central place to store view information so it can be retrieved or shared across applications.


savedviews

# Saved Views API

This API provides functionality to store, share, organize, and retrieve saved views.

## Saved Views

Saved views enable applications to maintain display information on how to visualize an iTwin. The information stored in a saved view depends on its type. A saved view relates to an iTwin.js view definition, which comes in three different flavors:

- **3D View**: these views include camera position, camera angle, camera extents, viewed categories and viewed models.
- **Drawing Views**: these views include the origin of the view, angles, the model being viewed and the viewed categories.
- **Sheet Views**: these views include all the information from drawing views, and includes optional width, height, scale and sheet related properties, like sheet attachments.

Saved views can be shared, have thumbnails, be organized into groups, and have a list of user-defined tags.

Saved views are always related to a specific iTwin or a specific Project.

## Thumbnails

The API has operations to upload and get images related to a specific saved view. These images are typically used as thumbnails to show how the saved view looks when visualizing it. You can request the images in two sizes: `full` and `thumbnail`.

## Groups

The API allows for the creation of Groups that can be used to organize collections of saved views. Groups can be shared if desired. The user can then query saved views that are associated with a specific group by using its id.

## Tags

The API allows for marking saved views with user-created tags. Tags are simple strings that users can use for organization purposes.

## Permissions

Users have access to Saved Views as long as they have access to the iModel or iTwin they are querying.

Shared Views can be read by all users that have access to the iModel or iTwin. A view is considered shared, if the `shared` field in its data is `true`. A user cannot edit or delete another user's shared saved view.

For more control, you can use the [Access Control API](https://developer.bentley.com/apis/access-control/). In the `Saved Views` category in permissions, assign the `Manage` permission. This permission allows the user to:
1. Delete and update shared saved views
2. Delete and update shared groups
3. Delete and update shared saved views' extensions
4. Update shared saved views' thumbnails

---

Creates an extension that contains custom data in a saved view.

Extensions allow a saved view to be enhanced with custom data. The extensions have to be defined in a proprietary .JSON schema file. For now, only three extensions are available:
## Extension Schemas
The following extensions are available and are shown below in the details sections.
The details sections contain the schema followed by an example of that schema.
### Per Model Category Visibility - Schema
<details>
    <summary>Per Model Category Visibility Details</summary>
```
[
   {
   "type": "array",
   "name": "perModelCategoryVisibilityProps",
   "required": true,
      "items": {
         "type": "object",
         "required": true,
         "properties": [
            {
               "name": "modelId",
               "type": "Id64String",
               "required": true
            },
            {
               "name": "categoryId",
               "type": "Id64String",
               "required": true
            },
            {
               "name": "visible",
               "type": "boolean",
               "required": true
            }            
         ]
      }
   }
]
```
Per Model Category Visibility - Example
```
{
  "perModelCategoryVisibilityProps": [
    {
      "modelId": "0x20000000079",
      "categoryId": "0x2000000003e",
      "visible": true
    },
    {
      "modelId": "0x20000000079",
      "categoryId": "0x2000000004e",
      "visible": false
    }
  ]
}
```
</details>
### Emphasize Elements - Schema
<details>
    <summary>Emphasize Elements Details</summary>
```
[
   {
   "type": "object",
   "name": "emphasizeElementsProps",
   "required": true,
      "properties": [
         {
            "name": "neverDrawn",
            "type": "array",
            "required": false,
            "items": {
               "type": "Id64String"
            }         
         },
         {
            "name": "alwaysDrawn",
            "type": "array",
            "required": false,
            "items": {
               "type": "Id64String"
            }         
         },
         {
            "name": "isAlwaysDrawnExclusive",
            "type": "boolean",
            "required": false
         },
         {
            "name": "alwaysDrawnExclusiveEmphasized",
            "type": "array",
            "required": false,
            "items": {
               "type": "Id64String"
            }         
         },
         {
            "name": "defaultAppearance",
            "type": "object",
            "required": false,
            "properties": [
               {
                  "name": "rgb",
                  "type": "object",
                  "properties": [
                     {
                        "name": "r",
                        "type": "number",
                        "required": true
                     },
                     {
                        "name": "g",
                        "type": "number",
                        "required": true
                     },
                     {
                        "name": "b",
                        "type": "number",
                        "required": true
                     }
                  ]
               },
               {
                  "name": "weight",
                  "type": "number"
               },
               {
                  "name": "transparency",
                  "type": "number"
               },
               {
                  "name": "viewDependentTransparency",
                  "type": "boolean"
               },
               {
                  "name": "linePixels",
                  "type": "integer"
               },
               {
                  "name": "ignoresMaterial",
                  "type": "boolean"
               },
               {
                  "name": "nonLocatable",
                  "type": "boolean"
               },
               {
                  "name": "emphasized",
                  "type": "boolean"
               }
            ]
         },
         {
            "name": "appearanceOverride",
            "type": "array",
            "items": {
               "type": "object",
               "properties": [
                  {
                     "name": "overrideType",
                     "type": "integer"
                  },
                  {
                     "name": "color",
                     "type": "number"
                  },
                  {
                     "name": "ids",
                     "type": "array",
                     "items": {
                        "type": "Id64String"
                     }
                  }
               ]
            }
         },
         {
            "name": "wantEmphasis",
            "type": "boolean"
         },
         {
            "name": "unanimatedAppearance",
            "type": "object",
            "required": false,
            "properties": [
               {
                  "name": "rgb",
                  "type": "object",
                  "properties": [
                     {
                        "name": "r",
                        "type": "number",
                        "required": true
                     },
                     {
                        "name": "g",
                        "type": "number",
                        "required": true
                     },
                     {
                        "name": "b",
                        "type": "number",
                        "required": true
                     }
                  ]
               },
               {
                  "name": "weight",
                  "type": "number"
               },
               {
                  "name": "transparency",
                  "type": "number"
               },
               {
                  "name": "viewDependentTransparency",
                  "type": "boolean"
               },
               {
                  "name": "linePixels",
                  "type": "integer"
               },
               {
                  "name": "ignoresMaterial",
                  "type": "boolean"
               },
               {
                  "name": "nonLocatable",
                  "type": "boolean"
               },
               {
                  "name": "emphasized",
                  "type": "boolean"
               }
            ]
         }
      ]
   }
]
```
Emphasize Elements - Example
```
{
  "emphasizeElementsProps": {
    "neverDrawn": [
      "0x20000003865",
      "0x20000003864",
      "0x200000055e4",
      "0x200000055e3",
      "0x200000039af",
      "0x200000039ae"
    ]
  }
}
```
</details>
### Visibility Override - Schema
<details>
    <summary>Visibility Override Details</summary>
```
[
   {
      "name": "visibilityOverrideProps",
      "type": "object",
      "required": true,
      "properties": [
        {
          "name": "subCategoryOverrides",
          "type": "array",
          "items": {
            "type": "object",
            "properties": [
              {
                "name": "ids",
                "type": "array",
                "required": true,
                "items": {
                  "type": "Id64String"
                }
              },
              {
                "name": "app",
                "type": "object",
                "required": true,
                "properties": [
                  {
                    "name": "rgb",
                    "type": "object",
                    "properties": [
                      {
                        "name": "r",
                        "type": "number",
                        "required": true
                      },
                      {
                        "name": "g",
                        "type": "number",
                        "required": true
                      },
                      {
                        "name": "b",
                        "type": "number",
                        "required": true
                      }
                    ]
                  },
                  {
                    "name": "weight",
                    "type": "number"
                  },
                  {
                    "name": "transparency",
                    "type": "number"
                  },
                  {
                    "name": "viewDependentTransparency",
                    "type": "boolean"
                  },
                  {
                    "name": "linePixels",
                    "type": "integer"
                  },
                  {
                    "name": "ignoresMaterial",
                    "type": "boolean"
                  },
                  {
                    "name": "nonLocatable",
                    "type": "boolean"
                  },
                  {
                    "name": "emphasized",
                    "type": "boolean"
                  }
                ]
              }
            ]
          }
        },
        {
          "name": "modelOverrides",
          "type": "array",
          "items": {
            "type": "object",
            "properties": [
              {
                "name": "ids",
                "type": "array",
                "required": true,
                "items": {
                  "type": "Id64String"
                }
              },
              {
                "name": "app",
                "type": "object",
                "required": true,
                "properties": [
                  {
                    "name": "rgb",
                    "type": "object",
                    "properties": [
                      {
                        "name": "r",
                        "type": "number",
                        "required": true
                      },
                      {
                        "name": "g",
                        "type": "number",
                        "required": true
                      },
                      {
                        "name": "b",
                        "type": "number",
                        "required": true
                      }
                    ]
                  },
                  {
                    "name": "weight",
                    "type": "number"
                  },
                  {
                    "name": "transparency",
                    "type": "number"
                  },
                  {
                    "name": "viewDependentTransparency",
                    "type": "boolean"
                  },
                  {
                    "name": "linePixels",
                    "type": "integer"
                  },
                  {
                    "name": "ignoresMaterial",
                    "type": "boolean"
                  },
                  {
                    "name": "nonLocatable",
                    "type": "boolean"
                  },
                  {
                    "name": "emphasized",
                    "type": "boolean"
                  }
                ]
              }
            ]
          }
        },
        {
          "name": "catEmphasizeOverride",
          "type": "object",
          "properties": [
            {
              "name": "ids",
              "type": "array",
              "required": true,
              "items": {
                "type": "Id64String"
              }
            },
            {
              "name": "app",
              "type": "object",
              "required": true,
              "properties": [
                {
                  "name": "rgb",
                  "type": "object",
                  "properties": [
                    {
                      "name": "r",
                      "type": "number",
                      "required": true
                    },
                    {
                      "name": "g",
                      "type": "number",
                      "required": true
                    },
                    {
                      "name": "b",
                      "type": "number",
                      "required": true
                    }
                  ]
                },
                {
                  "name": "weight",
                  "type": "number"
                },
                {
                  "name": "transparency",
                  "type": "number"
                },
                {
                  "name": "viewDependentTransparency",
                  "type": "boolean"
                },
                {
                  "name": "linePixels",
                  "type": "integer"
                },
                {
                  "name": "ignoresMaterial",
                  "type": "boolean"
                },
                {
                  "name": "nonLocatable",
                  "type": "boolean"
                },
                {
                  "name": "emphasized",
                  "type": "boolean"
                }
              ]
            }
          ]
        },
        {
          "name": "modelEmphasizeOverride",
          "type": "object",
          "properties": [
            {
              "name": "ids",
              "type": "array",
              "required": true,
              "items": {
                "type": "Id64String"
              }
            },
            {
              "name": "app",
              "type": "object",
              "required": true,
              "properties": [
                {
                  "name": "rgb",
                  "type": "object",
                  "properties": [
                    {
                      "name": "r",
                      "type": "number",
                      "required": true
                    },
                    {
                      "name": "g",
                      "type": "number",
                      "required": true
                    },
                    {
                      "name": "b",
                      "type": "number",
                      "required": true
                    }
                  ]
                },
                {
                  "name": "weight",
                  "type": "number"
                },
                {
                  "name": "transparency",
                  "type": "number"
                },
                {
                  "name": "viewDependentTransparency",
                  "type": "boolean"
                },
                {
                  "name": "linePixels",
                  "type": "integer"
                },
                {
                  "name": "ignoresMaterial",
                  "type": "boolean"
                },
                {
                  "name": "nonLocatable",
                  "type": "boolean"
                },
                {
                  "name": "emphasized",
                  "type": "boolean"
                }
              ]
            }
          ]
        }
      ]
   }
]
```
Visibility Override - Example
```
{
  "visibilityOverrideProps": {
    "subCategoryOverrides": [
      {
        "ids": [
          "0x200000009e5",
          "0x20000000a45"
        ],
        "app": {
          "rgb": {
            "r": 12,
            "g": 12,
            "b": 107
          },
          "transparency": 0.46
        }
      },
      {
        "ids": [
          "0x20000007771",
          "0x20000007810"
        ],
        "app": {
          "rgb": {
            "r": 12,
            "g": 12,
            "b": 107
          },
          "transparency": 0.46
        }
      }
    ]
  }
}
```
</details>

Later on, consumers of the API will be allowed to define their own extensions.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:modify` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


create-extension

Id of the saved view to create an extension for.

savedViewId

Payload of the extension that includes the extension name and the data.

OAuth access token with `savedviews:modify` or `itwin-platform` scope

Authorization

Setting to `application/vnd.bentley.itwin-platform.v1+json` is recommended.

Accept

default

This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.

HeaderNotFound

application/json;InvalidAuthorizationScheme

InvalidAuthorizationScheme

InvalidHeaderValue

RequiredScopeMissing

Unauthorized

The user has insufficient permissions for the requested operation.

This response indicates that the user has sent too many requests in a given amount of time.

The number of requests exceeds the rate-limit for the client subscription.

retry-after

---

Deletes an extension in a saved view.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:modify` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


delete-extension

extensionName

---

Get a list of extensions that exist in a saved view.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:read` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


get-all-extensions

OAuth access token with `savedviews:read` or `itwin-platform` scope

---

Get an extension from a saved view.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:read` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


get-extension

---

Creates a group to organize saved views.

Note: any string parameter being passed in the payload will be rejected if it contains any of the following characters: `<, >, &, ", ', .`

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:modify` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


create-group

---

Deletes a group, saved views assigned to that group will not be deleted.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:modify` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


delete-group

groupId

---

Retrieves all groups associated to a iTwin or iTwin/iModel combination.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:read` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


get-all-groups

iTwinId

iModelId

List of all available groups for the iTwin and iModel.

---

Retrieves information for a single group.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:read` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


get-group

---

Updates a group.

Note: any string parameter being passed in the payload will be rejected if it contains any of the following characters: `<, >, &, ", ', .`

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:modify` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


update-group

---

Generates or retrieves an Url for the image or thumbnail associated to a saved view.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:read` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


get-image

size

---

Allow uploading an image representing the saved view. Image will be available at full size and as a thumbnail size.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:modify` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


add-image

---

Creates a saved view. The saved view must include one an only view: 3D, Sheet or Drawing. 

Note: any string parameter being passed in the payload will be rejected if it contains any of the following characters: `<, >, &, ", ', .`

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:modify` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


create-savedview

Please use https://www.itwinjs.org/reference/imodeljs-common/views/viewstateprops/ for reference

---

Deletes a saved view, images assigned to that saved view will be deleted as well.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:modify` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


delete-savedview

---

Retrieves all saved view associated to a iTwin, iTwin/iModel combination or group, at least one parameter must be provided.

This operation supports pagination and will sort saved views by displayName.

As the view data can be quite large, this collection call will not contain the view data themselves. To retrieve the data, make a call to [Get saved view](../get-savedview)

Extension data is returned as a list of links to query further. If you want to obtain the full saved view data, including extension data, use the `Prefer` header with `return=representation`.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:read` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


get-all-savedviews

$top

$skip

Controls the returned data. Setting to `return=representation` will return the saved views with all the extension data in a single payload. Setting to `return=minimal` will return the saved views with the list of extensions that exist and links to query those separately.

Prefer

List of all saved views associated to the query.

Minimal

Representation

---

Retrieves a saved view. Extension data is returned as a list of links to query further. If you want to obtain the full saved view data, including extension data, use the `Prefer` header with `return=representation`.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:read` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


get-savedview

Controls the returned data. Setting to `return=representation` will return the saved view with all the extension data in a single payload. Setting to `return=minimal` will return the saved view with the list of extensions that exist and links to query those separately.

---

Updates a saved view.

Note: any string parameter being passed in the payload will be rejected if it contains any of the following characters: `<, >, &, ", ', .`

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:modify` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


update-savedview

---

Creates a tag to organize saved views.

Note: any string parameter being passed in the payload will be rejected if it contains any of the following characters: `<, >, &, ", ', .`

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:modify` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


create-tag

---

Deletes a tag, tags must be unassigned from every saved view before they can be deleted.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:modify` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


delete-tag

tagId

---

Retrieves all tags associated to a iTwin or iTwin/iModel combination.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:read` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


get-all-tags

List of all available tags for the iTwin and iModel.

---

Retrieves information for a single tag.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:read` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


get-tag

---

Renames a tag.

Note: any string parameter being passed in the payload will be rejected if it contains any of the following characters: `<, >, &, ", ', .`

### Authentication

Requires `Authorization` header with valid Bearer token for scope `savedviews:modify` or `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---
