Get repository - iTwins | iTwin Platform

iTwins

Download API definition:

Get repository

This operation is a Technical Preview and is available for testing purposes only. Do not use in production.

GET https://dev-api.bentley.com/itwins/{iTwinId}/repositories/{repositoryId}

Gets the details of the specified repository.

The repository will only be returned if it contains at least one resource. Otherwise, it will return 404 (NotFound).

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

Request parameters

iTwinId

Yes

The iTwin Id

repositoryId

Yes

The repository Id

Request headers

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

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

Response

Response 200 OK

json

{
    "repository": {
        "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": "iTwinRepositoryNotFound",
        "message": "Requested iTwin Repository is not available."
    }
}

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

retry-after

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

Definitions

iTwin-repository-response

repository

iTwin-repository

json

{
    "type": "object",
    "properties": {
        "repository": {
            "$ref": "#/components/schemas/iTwin-repository"
        }
    },
    "required": [
        "repository"
    ],
    "additionalProperties": false
}

iTwin Repository Class

The class of the iTwin repository.

RealityData

String

iModels

String

Storage

String

Forms

String

Construction

String

GeographicInformationSystem

String

CesiumCuratedContent

String

SensorData

String

Subsurface

String

GeospatialFeatures

String

PdfPlansets

String

IndexedMedia

String

json

{
    "type": "string",
    "title": "iTwin Repository Class",
    "description": "The class of the iTwin repository.",
    "enum": [
        "RealityData",
        "iModels",
        "Storage",
        "Forms",
        "Construction",
        "GeographicInformationSystem",
        "CesiumCuratedContent",
        "SensorData",
        "Subsurface",
        "GeospatialFeatures",
        "PdfPlansets",
        "IndexedMedia"
    ]
}

iTwin Repository SubClass

The subclass of the iTwin repository.

WebMapService

String

WebMapTileService

String

ArcGIS

String

UrlTemplate

String

OgcApiFeatures

String

Performance

String

EvoWorkspace

String

json

{
    "type": "string",
    "title": "iTwin Repository SubClass",
    "description": "The subclass of the iTwin repository.",
    "enum": [
        "WebMapService",
        "WebMapTileService",
        "ArcGIS",
        "UrlTemplate",
        "OgcApiFeatures",
        "Performance",
        "EvoWorkspace"
    ]
}

iTwin Repository Authentication Type

This value determines how to process the authentication information returned from the API.

Header

String

QueryParameter

String

Basic

String

OAuth2AuthorizationCodePKCE

String

json

{
    "type": "string",
    "title": "iTwin Repository Authentication Type",
    "description": "This value determines how to process the authentication information returned from the API.",
    "enum": [
        "Header",
        "QueryParameter",
        "Basic",
        "OAuth2AuthorizationCodePKCE"
    ]
}

iTwin-repository

String

The iTwin repository id.

class

iTwinRepositoryClass

The repository class.

subClass

iTwinRepositorySubClass

The repository subclass.

displayName

String

The repository name that can be displayed to the user.

uri

String

The uri for the repository.

capabilities.resources

ResourcesCapability

authentication

One of: ApiKey-Authentication Basic-Authentication OAuth2AuthCodePKCE-Authentication

Some repositories require authentication. If authentication details are provided, inspect the authentication.type property to determine the required method. You may need to add an Api Key (header or query parameter), use basic authentication, or implement OAuth2 authorization code flow.

options

One of: GIS-General-Options GIS-UrlTemplate-Options

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

json

{
    "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": {
            "oneOf": [
                {
                    "$ref": "#/components/schemas/ApiKey-Authentication"
                },
                {
                    "$ref": "#/components/schemas/Basic-Authentication"
                },
                {
                    "$ref": "#/components/schemas/OAuth2AuthCodePKCE-Authentication"
                }
            ],
            "description": "Some repositories require authentication. If authentication details are provided, inspect the `authentication.type` property to determine the required method. You may need to add an Api Key (header or query parameter), use basic authentication, or implement OAuth2 authorization code flow."
        },
        "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.

queryParameters

Object

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

json

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

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.

json

{
    "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

uri

String

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

json

{
    "type": "object",
    "properties": {
        "uri": {
            "type": "string",
            "description": "A uri containing the endpoint that will return the list of resources in the repository."
        }
    },
    "additionalProperties": false
}

ApiKey-Authentication

Contains the information needed to authenticate to the specified API using an api key.

type

iTwinRepositoryAuthType

key

String

The key to use for Header or QueryParameter auth types.

value

String

The value to use for Header or QueryParameter auth types.

json

{
    "type": "object",
    "description": "Contains the information needed to authenticate to the specified API using an api key. ",
    "properties": {
        "type": {
            "$ref": "#/components/schemas/iTwinRepositoryAuthType"
        },
        "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."
        }
    },
    "required": [
        "type",
        "key",
        "value"
    ],
    "additionalProperties": false
}

Basic-Authentication

Contains the information needed to authenticate to the specified API using Basic authentication.

type

iTwinRepositoryAuthType

username

String

The username to use for Basic auth type.

password

String

The password to use for Basic auth type.

json

{
    "type": "object",
    "description": "Contains the information needed to authenticate to the specified API using Basic authentication.",
    "properties": {
        "type": {
            "$ref": "#/components/schemas/iTwinRepositoryAuthType"
        },
        "username": {
            "type": "string",
            "description": "The username to use for Basic auth type."
        },
        "password": {
            "type": "string",
            "description": "The password to use for Basic auth type."
        }
    },
    "required": [
        "type",
        "username",
        "password"
    ],
    "additionalProperties": false
}

OAuth2AuthCodePKCE-Authentication

Contains the information needed to authenticate to the specified API using OAuth2 authentication.

type

iTwinRepositoryAuthType

clientId

String

The OAuth2 client identifier registered with the authorization server.

scopes

String

A space-separated list of permissions (scopes) your app is requesting.

authorizationEndpoint

String

The URL where the user is redirected to start the OAuth2 authorization process.

tokenEndpoint

String

The URL used to exchange the authorization code for access and refresh tokens.

redirectUri

String

The URI where the authorization server will redirect the user after authorization is complete.

json

{
    "type": "object",
    "description": "Contains the information needed to authenticate to the specified API using OAuth2 authentication.",
    "properties": {
        "type": {
            "$ref": "#/components/schemas/iTwinRepositoryAuthType"
        },
        "clientId": {
            "type": "string",
            "description": "The OAuth2 client identifier registered with the authorization server."
        },
        "scopes": {
            "type": "string",
            "description": "A space-separated list of permissions (scopes) your app is requesting."
        },
        "authorizationEndpoint": {
            "type": "string",
            "description": "The URL where the user is redirected to start the OAuth2 authorization process."
        },
        "tokenEndpoint": {
            "type": "string",
            "description": "The URL used to exchange the authorization code for access and refresh tokens."
        },
        "redirectUri": {
            "type": "string",
            "description": "The URI where the authorization server will redirect the user after authorization is complete."
        }
    },
    "required": [
        "type",
        "clientId",
        "scopes",
        "authorizationEndpoint",
        "tokenEndpoint",
        "redirectUri"
    ],
    "additionalProperties": false
}

Error

Contains error information.

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.

json

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

error

Error

Error information.

json

{
    "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?