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
The iTwin Id
The class that you wish to query on. If not specified then all repostiories are returned.
The subClass that you wish to query on. If specified, class is also required.
Request headers
OAuth access token with itwin-platform
scope
Setting to application/vnd.bentley.itwin-platform.v1+json
is recommended.
Response 200 OK
OK
{ "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.
{ "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.
{ "error": { "code": "iTwinNotFound", "message": "Requested iTwin is not available." } }
Response 422 Unprocessable Entity
Invalid request to get Repositories
{ "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.
{ "error": { "code": "RateLimitExceeded", "message": "The client sent more requests than allowed by this API for the current tier of the client." } }
Response headers
Number of seconds to wait until client is allowed to make more requests.
iTwin-repositories-response
{ "type": "object", "properties": { "repositories": { "type": "array", "items": { "$ref": "#/components/schemas/iTwin-repository" } } }, "required": [ "repositories" ], "additionalProperties": false }
iTwin Repository Class
The class of your iTwin repository.
{ "type": "string", "title": "iTwin Repository Class", "description": "The class of your iTwin repository.", "enum": [ "RealityData", "iModels", "Storage", "Forms", "Construction", "GeographicInformationSystem", "CesiumCuratedContent", "SensorData", "Subsurface", "GeospatialFeatures", "PdfPlansets" ] }
iTwin Repository SubClass
The subclass of your iTwin repository.
{ "type": "string", "title": "iTwin Repository SubClass", "description": "The subclass of your iTwin repository.", "enum": [ "WebMapService", "WebMapTileService", "ArcGIS", "UrlTemplate", "Performance", "EvoWorkspace" ] }
iTwin-repository
The iTwin repository id.
The repository name that can be displayed to the user.
The uri for the repository.
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).
Additional options that are needed when requesting data from the repository.
{ "type": "object", "properties": { "id": { "type": "string", "description": "The iTwin repository id." }, "class": { "$ref": "#/components/schemas/iTwinRepositoryClass", "description": "The repository class." }, "subClass": { "$ref": "#/components/schemas/iTwinRepositorySubClass", "description": "The repository subclass." }, "displayName": { "type": "string", "description": "The repository name that can be displayed to the user." }, "uri": { "type": "string", "description": "The uri for the repository." }, "capabilities": { "type": "object", "required": [ "resources" ], "properties": { "resources": { "$ref": "#/components/schemas/ResourcesCapability" } }, "description": "Links to additional capabiblies provided by the repository. Currently, only the [resources](https://developer.bentley.com/apis/itwins/operations/get-repository-resources/) capability is suported. It is a read only value returned for certain classes.", "additionalProperties": false }, "authentication": { "$ref": "#/components/schemas/AuthenticationInfo", "description": "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": { "oneOf": [ { "$ref": "#/components/schemas/GIS-General-Options" }, { "$ref": "#/components/schemas/GIS-UrlTemplate-Options" } ], "description": "Additional options that are needed when requesting data from the repository." } }, "additionalProperties": false }
GIS-General-Options
Options that may be needed to query or display data from the repository.
Query parameters that should be added to the uri when making a request.
{ "type": "object", "properties": { "queryParameters": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Query parameters that should be added to the uri when making a request." } }, "required": [ "queryParameters" ], "description": "Options that may be needed to query or display data from the repository.", "additionalProperties": false }
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.
Query parameters that should be added to the uri when making a request.
Minimum level-of-detail that can be requested.
Maximum level-of-detail that can be requested.
{ "type": "object", "properties": { "queryParameters": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Query parameters that should be added to the uri when making a request." }, "minimumLevel": { "type": "integer", "description": "Minimum level-of-detail that can be requested." }, "maximumLevel": { "type": "integer", "description": "Maximum level-of-detail that can be requested." } }, "required": [ "minimumLevel", "maximumLevel" ], "description": "Options that can be used in the construtor of the [UrlTemplateImageryProvider](https://cesium.com/learn/cesiumjs/ref-doc/UrlTemplateImageryProvider.html). Also includes the general options that allow you to specify query parameters if needed.", "additionalProperties": false }
ResourcesCapability
A uri containing the endpoint that will return the list of resources in the repository.
{ "type": "object", "properties": { "uri": { "type": "string", "description": "A uri containing the endpoint that will return the list of resources in the repository." } }, "additionalProperties": false }
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.
One of a server-defined set of error codes.
The key to use for Header or QueryParameter auth types.
The value to use for Header or QueryParameter auth types.
The value to use for Basic auth type.
The value to use for Basic auth type.
{ "type": "object", "description": "Contains all of the information needed to authenticate to the specified API. For example, if type=Header then add a header using key=value.", "properties": { "type": { "type": "string", "description": "One of a server-defined set of error codes." }, "key": { "type": "string", "description": "The key to use for Header or QueryParameter auth types." }, "value": { "type": "string", "description": "The value to use for Header or QueryParameter auth types." }, "username": { "type": "string", "description": "The value to use for Basic auth type." }, "password": { "type": "string", "description": "The value to use for Basic auth type." } }, "required": [ "type" ], "additionalProperties": false }
Error
Contains error information.
One of a server-defined set of error codes.
A human-readable representation of the error.
The target of the error.
{ "type": "object", "description": "Contains error information.", "properties": { "code": { "type": "string", "description": "One of a server-defined set of error codes." }, "message": { "type": "string", "description": "A human-readable representation of the error." }, "target": { "type": "string", "description": "The target of the error.", "nullable": true } }, "required": [ "code", "message" ], "additionalProperties": true }
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.
{ "type": "object", "title": "Error Response", "description": "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.", "properties": { "error": { "description": "Error information.", "$ref": "#/components/schemas/Error" } }, "required": [ "error" ], "additionalProperties": false }
Was this page helpful?