Table of contents
iTwins
Download API definition:
GET https://dev-api.bentley.com/itwins/{iTwinId}/repositories[?class][&subClass]

Gets the details of all respositories that contain data for the iTwin.

Every repository has a class, displayName and uri. There are also be optional properties such as authentication, options and capabilities that are specific to the repository class.

If no Class is specified then all repositories containing data for the iTwin will be returned.

For the following classes, the repository information is automatically generated and returned only if the repository contains data for the iTwin.

  • iModels
  • RealityData
  • Storage
  • Forms
  • GeospatialFeatures
  • CesiumCuratedContent
  • PdfPlansets

Repositories for the following Classes/SubClasses can be registered manually using the POST endpoint.

  • GeographicInformationSystem
    • WebMapService
    • WebMapTileService
    • ArcGIS
    • UrlTemplate
  • Construction
    • Performance
  • Subsurface
    • EvoWorkspace

Examples

If an iTwin has Forms data then you can get the uri to access that data by using this api and specifying iTwinId = 547d397a-9921-4e4f-a7a2-c47fc19219b0 and Class = Forms. It will return a single repository.

{
   "repositories": [
   {
      "id": "forms", (The id for auto generated repositories is the same as the class name)
      "class": "Forms",        
      "uri": "https://api.bentley.com/forms?projectId=547d397a-9921-4e4f-a7a2-c47fc19219b0"
   }]

If you do not specify a class then all repositories that have data for the iTwin will be returned. If an iTwin has reality data and iModels then the following repositories will be returned. These repositories also have a resources endpoint that can be used to get the resources in the repository. Calling the resources endpoint for iModels will return the id and name of all iModels in the iTwin. The resources endpoint is not available for all repositories.

{
   "repositories": [
      {
         "id": "imodels",
         "class": "iModels",
         "displayName": "iModels",
         "uri": "https://api.bentley.com/imodels?iTwinId=9c276ef4-22e6-4c7f-b385-cb40ba3163be",
         "capabilities": {
            "resources": {
               "uri": "https://api.bentley.com/iTwins/9c276ef4-22e6-4c7f-b385-cb40ba3163be/repositories/imodels/resources"
         }
      },
      {
         "id": "realitydata", 
         "class": "RealityData",  
         "displayName": "Reality Data",
         "uri": "https://api.bentley.com/reality-management/reality-data?iTwinId=9c276ef4-22e6-4c7f-b385-cb40ba3163be",
         "capabilities": {
            "resources": {
               "uri": "https://api.bentley.com/iTwins/9c276ef4-22e6-4c7f-b385-cb40ba3163be/repositories/realitydata/resources"
         }
      }
   ]
}        

Note: The resources API is only available for Tech Preview and could change. Currently, only these repositories will return the resources uri.

  • iModels
  • RealityData
  • GeospatialFeatures
  • CesiumCuratedContent
  • PdfPlansets

If a repository is registered manually then it will also be returned in the list of repositories. The information is not auto generated. It will return whatever the user specified when it was registerd. For example, if you register a UrlTemplate repository, it will be returned in the list of repositories for the iTwin. It will likely contain the optional authentication and options properties since these are usually needed for GeographicInformationSystem repositories.

{
   "repositories": [
      {
        "id": "a7a1c020-6c53-4f7f-a9ad-618b811cfeb4"
        "class": "GeographicInformationSystem",
        "subClass": "UrlTemplate",
        "displayName": "My xyz template server",
        "uri": "http://basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png",
        "authentication": {
           "type": "Header",
           "key": "X-Api-Key",
           "value": "mySecretApiKey"
        },
        "options": {
        "queryParameters": {
              "apiVersion": "1.5.1"
           },
        "minimumLevel": 10,
        "maximumLevel": 20
        }
      }
   ]
}  

Note: The resources API is only available for Tech Preview and could change or be removed in the future.

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.

Authorization

User must be an Organization Administrator for the Organization that owns the specified iTwin Repository or be an iTwin team member.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities Licensing, Cloud, and Web Services wiki page.

Request parameters

Name
Required?
Description
iTwinId
Yes

The iTwin Id

class
No

The class that you wish to query on. If not specified then all repostiories are returned.

subClass
No

The subClass that you wish to query on. If specified, class is also required.

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.

Response 200 OK

OK

json
{
    "repositories": [{
            "id": "cesiumcuratedcontent",
            "class": "CesiumCuratedContent",
            "displayName": "Cesium Curated Content",
            "uri": "https://api.bentley.com/curated-content/cesium",
            "capabilities": {
                "resources": {
                    "uri": "https://api.bentley.com/iTwins/599fbb1e-0907-49ee-aa3e-da2504e899db/repositories/cesiumcuratedcontent/resources"
                }
            }
        },
        {
            "id": "realitydata",
            "class": "RealityData",
            "displayName": "Reality Data",
            "uri": "https://api.bentley.com/reality-management/reality-data?iTwinId=9c276ef4-22e6-4c7f-b385-cb40ba3163be",
            "capabilities": {
                "resources": {
                    "uri": "https://api.bentley.com/iTwins/9c276ef4-22e6-4c7f-b385-cb40ba3163be/repositories/realitydata/resources"
                }
            }
        },
        {
            "id": "e2ecdff7-2802-48bf-9bfa-d418c740c8cd",
            "class": "GeographicInformationSystem",
            "subClass": "UrlTemplate",
            "displayName": "My xyz template server",
            "uri": "http://basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png",
            "authentication": {
                "type": "Header",
                "key": "X-Api-Key",
                "value": "mySecretApiKey"
            },
            "options": {
                "queryParameters": {
                    "apiVersion": "1.5.1"
                },
                "minimumLevel": 10,
                "maximumLevel": 20
            }
        }
    ]
}

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 404 Not Found

This response indicates that the specified repository was not found.

json
{
    "error": {
        "code": "iTwinNotFound",
        "message": "Requested iTwin is not available."
    }
}

Response 422 Unprocessable Entity

Invalid request to get Repositories

json
{
    "error": {
        "code": "InvalidiTwinsRequest",
        "message": "Cannot query iTwin Repositories.",
        "details": [{
                "code": "InvalidValue",
                "message": "A valid iTwin Repository Class was not specified in the query.",
                "target": "class"
            },
            {
                "code": "InvalidValue",
                "message": "A valid iTwin Repository SubClass was not specified in the query.",
                "target": "subClass"
            },
            {
                "code": "InvalidValue",
                "message": "iTwinId contains an invalid value.",
                "target": "iTwinId"
            }
        ]
    }
}

Response 429 Too many requests

This response indicates that the client sent more requests than allowed by this API for the current tier of the client.

json
{
    "error": {
        "code": "RateLimitExceeded",
        "message": "The client sent more requests than allowed by this API for the current tier of the client."
    }
}

Response headers

Name
Description
retry-after

Number of seconds to wait until client is allowed to make more requests.

iTwin-repositories-response

Name
Type
Description
repositories

iTwin Repository Class

The class of your iTwin repository.

Name
Type
Description
RealityData
String
iModels
String
Storage
String
Forms
String
Construction
String
GeographicInformationSystem
String
CesiumCuratedContent
String
SensorData
String
Subsurface
String
GeospatialFeatures
String
PdfPlansets
String

iTwin Repository SubClass

The subclass of your iTwin repository.

Name
Type
Description
WebMapService
String
WebMapTileService
String
ArcGIS
String
UrlTemplate
String
Performance
String
EvoWorkspace
String

iTwin-repository

Name
Type
Description
id
String

The iTwin repository id.

class

The repository class.

subClass

The repository subclass.

displayName
String

The repository name that can be displayed to the user.

uri
String

The uri for the repository.

capabilities.resources
authentication

Some repositories require additional authorization information. If there is authentication information, then inspect the authentication.type property to determine how to handle it. You will need to add a header, query parameter or use basic auth. In some cases, the authentication info will expire (usually after 1 hour).

options

Additional options that are needed when requesting data from the repository.

GIS-General-Options

Options that may be needed to query or display data from the repository.

Name
Type
Description
queryParameters
Object

Query parameters that should be added to the uri when making a request.

GIS-UrlTemplate-Options

Options that can be used in the construtor of the UrlTemplateImageryProvider. Also includes the general options that allow you to specify query parameters if needed.

Name
Type
Description
queryParameters
Object

Query parameters that should be added to the uri when making a request.

minimumLevel
Integer

Minimum level-of-detail that can be requested.

maximumLevel
Integer

Maximum level-of-detail that can be requested.

ResourcesCapability

Name
Type
Description
uri
String

A uri containing the endpoint that will return the list of resources in the repository.

AuthenticationInfo

Contains all of the information needed to authenticate to the specified API. For example, if type=Header then add a header using key=value.

Name
Type
Description
type
String

One of a server-defined set of error codes.

key
String

The key to use for Header or QueryParameter auth types.

value
String

The value to use for Header or QueryParameter auth types.

username
String

The value to use for Basic auth type.

password
String

The value to use for Basic auth type.

Error

Contains error information.

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, null

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.

Name
Type
Description
error

Error information.

Was this page helpful?