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://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 your iTwin repository.

RealityData

String

iModels

String

Storage

String

Forms

String

Construction

String

GeographicInformationSystem

String

CesiumCuratedContent

String

SensorData

String

Subsurface

String

GeospatialFeatures

String

PdfPlansets

String

json

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

WebMapService

String

WebMapTileService

String

ArcGIS

String

UrlTemplate

String

Performance

String

EvoWorkspace

String

json

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

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

AuthenticationInfo

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

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

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
}

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.

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.

json

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

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?