• Get Started
  • Documentation
  • Samples
  • Blog
  • Pricing
    • Table of contents
    Overview
    Samples
    Changelog
    Saved Views
    Download API definition:
    Create Extension
    PUT https://api.bentley.com/savedviews/{savedViewId}/extensions

    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

    Per Model Category Visibility Details

    [
   {
   "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
    }
  ]
}

    Emphasize Elements - Schema

    Emphasize Elements Details

    [
   {
   "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"
    ]
  }
}

    Visibility Override - Schema

    Visibility Override Details

    [
   {
      "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
        }
      }
    ]
  }
}

    Later on, consumers of the API will be allowed to define their own extensions.

    Authentication

    Requires Authorization header with valid Bearer token for scope itwin-platform.

    For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.

    Request

    Request parameters

    Name
    In
    Required?
    Description
    savedViewId
    template
    Yes

    Id of the saved view to create an extension for.

    Request headers

    Name
    Required?
    Description
    Authorization
    Yes

    OAuth access token with itwin-platform scope

    Accept
    Yes

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

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

    Request body

    CreateExtension

    Name
    Type
    Required?
    Description
    extensionName
    String
    No

    Name of the extension.

    data
    String
    No

    Payload of extension.

    Example

    json
    {
    "extensionName": "MyExtensionName",
    "data": "{\"myExtensionData\": 123}"
}

    Response

    Response 201 Created

    Created extension.

    json
    {
    "extension": {
        "extensionName": "My Extension",
        "markdownUrl": "https://github.com/iTwin/saved-views-extensions/my-extension/my-extension.md",
        "schemaUrl": "https://github.com/iTwin/saved-views-extensions/my-extension/my-extension-schema.json",
        "data": "{ \"myExtensionData\": 123 }",
        "_links": {
            "iTwin": {
                "href": "https://api.bentley.com/iTwins/c6b0bf8d-033d-4291-9931-9b20f2135111"
            },
            "project": {
                "href": "https://api.bentley.com/projects/c6b0bf8d-033d-4291-9931-9b20f2135111"
            },
            "imodel": {
                "href": "https://api.bentley.com/imodels/b2db2e65-24a5-4958-abf5-91a60b94e8a5"
            },
            "savedView": {
                "href": "https://api.bentley.com/savedviews/AB2ckLPpC-REkuTK99srqHONv7DGPQORQpkxmyDyE1ERZS7bsqUkWEmr9ZGmC5TopQ"
            },
            "self": {
                "href": "https://api.bentley.com/savedviews/AB2ckLPpC-REkuTK99srqHONv7DGPQORQpkxmyDyE1ERZS7bsqUkWEmr9ZGmC5TopQ/extensions/Extension_Name"
            }
        }
    }
}

    Response 401 Unauthorized

    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.

    json
    {
    "error": {
        "code": "HeaderNotFound",
        "message": "Header Authorization was not found in the request. Access denied."
    }
}

    Response 403 Forbidden

    The user has insufficient permissions for the requested operation.

    json
    {
    "error": {
        "code": "InsufficientPermissions",
        "message": "The user has insufficient permissions for the requested operation."
    }
}

    Response 404 Not Found

    Requested savedview is not available.

    json
    {
    "error": {
        "code": "SavedViewNotFound",
        "message": "Requested savedview is not available."
    }
}

    Response 422 Unprocessable Entity

    Cannot create group.

    json
    {
    "error": {
        "code": "InvalidSavedviewsRequest",
        "message": "Cannot update extension.",
        "details": [{
            "code": "InvalidRequestBody",
            "message": "extensionName must be a string.",
            "target": "extensionName"
        }]
    }
}

    Response 429 Too many requests

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

    json
    {
    "error": {
        "code": "TooManyRequests",
        "message": "More requests were received than the subscription rate-limit allows."
    }
}

    Response headers

    Name
    Description
    retry-after

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

    Definitions

    CreateExtension

    TableSchema
    Name
    Type
    Description
    extensionName
    String

    Name of the extension.

    data
    String

    Payload of extension.

    CreateExtensionResponse

    TableSchema
    Name
    Type
    Description
    extension.extensionName
    String
    extension.markdownUrl
    String
    extension.schemaUrl
    String
    extension.data
    String
    extension._links.iTwin.href
    String
    extension._links.project.href
    String
    extension._links.imodel.href
    String
    extension._links.savedView.href
    String
    extension._links.self.href
    String

    Error

    Contains error information.

    TableSchema
    Name
    Type
    Description
    code
    String

    One of a server-defined set of error codes.

    message
    String

    A human-readable representation of the error.

    target
    String

    The target of the error.

    Error Response

    Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.

    TableSchema
    Name
    Type
    Description
    error
    Error

    Error information.