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


savedviews

Added technology preview operation 'Create Extension'.

Added technology preview operation 'Delete extension'.

Added technology preview operation 'Get all extensions'.

Added technology preview operation 'Get extension'.

Removed 'category' from operation 'Create savedview', 'Update savedview', 'Get all savedviews', 'Get saved view'.

---

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.

---


Changelog

Nov 22, 2022

Apr 11, 2022