Table of contents
iTwins
Download API definition:
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}/resources/{resourceId}/graphics

Returns a Uri and additional options needed for accessing the graphics content for the specified resource.

Examples

The simplest example is for the iModels repository. The graphics element for a given resource (in this case an iModel) will contain only a link to the 3D tiles that were generated for the iModel.

{
    "graphics": [
        {
            "type": "3DTILES",
            "uri": "https://d1sv4h3mfcamq8.cloudfront.net/a7a1eeb7-53a8-438e-995b-9c9263435cd2/tileset.json?sv=2024-05-04&spr=https&se=2025-06-28T23%3A59%3A59Z&sr=c&sp=rl&sig=jQZAWMZMR8ODPd4QaHhvQcUsQdEDzzotapW2eZ%2FScXY%3D&Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly9kMXN2NGdC9hN2Ex6MTc1MTE1NTE5OX19fV19&Key-Pair-Id=KLCW9M7K500GR&Signature=pZJ8qOmKPNQXrzoOWrZ3UeNqk7MJnNBRrBalXUkLyPs5-cy2LGZWDeKHkCjRgRaP-pYq1J1m1n4bvmjb~8LAFeuJd3JDDC53g48b1lvCivp8MyvQAzzVG-2hZyl9eWQVDSxzwDNyl9Pi~oPD0iqMwav7ku-QejHMJi~v499~IEu-ma7vHkGJRoVpQTccacLBoi1kJFWCMP8kVwi7bfU4SbDZYZU~mmA__"
        }
    ]
}

Cesium requires a Bearer token to access the graphics content that is different than the one used to call the iTwin Repositories API. This token is returned in the response so that the client can add the correct Authorization header when making requests to the specified uri.

{
   "graphics": [
      {
         "type": "IMAGERY",
         "uri": "https://assets.ion.cesium.com/us-east-1/asset_depot/3954/Sentinel-2/2021/",
         "authentication": {
             "type": "Header",
             "key": "Authorization",
             "value": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJjYTI4MWMzYy0yMzQyLTQyNWMtOGJjMC0xzIiwiaWF0IjoxNzUwNDU1MjQ2LCJleHAiOjE3NTA0NTg4NDZ9.sG9TnnwExucPrOhNXN1tswqNMK27IdAoiYI2cZuqazE"
         }
      }
   ]
}             

Some graphics may return additional information that can be used to populate one of the Cesium imagery providers. In that case, a provider element will be returned with the name of the provider to use and options to pass to the provider constructor. The example below shows additional options provided by the PdfPlansets repository that can be used along with the url to create a UrlTemplateImageryProvider. The bounds are required to create the Rectangle that is passed to the provider. Currently, only the PdfPlansets repository will return additional provider information and only the UrlTemplateImageryProvider is supported. More will be supported in the future as needed.

{
   "graphics": [
      {
         "type": "IMAGERY",
         "uri": "https://connect-pdfgeoindexingservice-eus.bentley.com/api/contexts/0a80582e-5a4a-4fd6-8266-bea00985e6da/map/plansets/b8c32c1e-a9d4-45f9-9ca1-3aaec7d2a5b1/tiles/{x}/{y}/{z}?discipline=E",
         "authentication": {
             "type": "Header",
             "key": "Authorization",
             "value": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJjYTI4MWQyLTQyNWMtOGIiwiaWF0IjoxNzUwNDU1MjQ2LCJleHAiOjE3NTA0NTg4NDZ9.sG9TnnwExucPrOhNXN1tswqNMK27IdAoiYI2cZuqazE"
         }
         "provider": {
             "name": "UrlTemplateImageryProvider",
             "options": {                 
                 "bounds": [
                     -92.34891237980125,
                     41.94798557014749,
                     -91.88709739940597,
                     41.97902703642597
                 ],
                 "tilingScheme": "WebMercatorTilingScheme",
                 "credit": "© Bentley Systems"
             }
         }
      }
   ]
}

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

The calling user must be a member of the specified iTwin and have access to the resource.

Request parameters

Name
Required?
Description
iTwinId
Yes

The iTwin Id

repositoryId
Yes

The repository Id

resourceId
Yes

The resourceId

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
{
    "graphics": [{
        "type": "IMAGERY",
        "uri": "https://assets.ion.cesium.com/us-east-1/asset_depot/3954/Sentinel-2/2021/",
        "authentication": {
            "type": "Header",
            "key": "Authorization",
            "value": "Bearer eyGhbGI6IkpXVCJ9.eyJqdGkiOiI4MDFiMjU5NC0xMDVjLTRmMzMtYWU5OS01ZGY1NTUzYWIwOGYiLCJpZCI6MjUzMzcyLCJhc3NldElkIjozOTU0LCJhc3NldHMiOnsiMzk1NCI6eyJ0eXBlIjoiSU1BR0VSWSIsInByZWZpeCI6IlNlbnRpbmVsLTIvMjAyMSJ9fSwic3JjIjoiZTM2ODExN2QtNDAwZC00NjJhLWI3ZjItNDFmNjI1OTFiNmQzIiiaWF0IjoxNzQwMTY5NTY0CJleHAiOjE3NDAxNzMxNjR9.AGS9D1dx8e6HoqUIYFZnc9K7v0gMOoTMcOflh4Nk4"
        }
    }]
}

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

Graphics

Name
Type
Description
uri
String

A uri containing the location of the graphics content. This value can be cached but be aware that it might change over time. Some might contain a SAS key that expires after some time.

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).

provider

Some repositories may provide additional information that can be used by a CesiumJS provider. The name and options will be provided here.

GraphicsProvider

Name
Type
Description
name
String

The name of the provider. Currently only UrlTemplateImageryProvider is supported. More will be added as needed.

options

Additional options for the provider. The properties contained in options will depend on the provider name. If the provider name is UrlTemplateImageryProvider then options will contain properties that can be used in the constructor for that provider.

UrlTemplateImageryProviderOptions

Name
Type
Description
bounds
Number[]

Bounding box as [west, south, east, north] in degrees. Use to create the Rectangle needed in the UrlTemplateImageryProvider constructor.

tilingScheme
String

The tiling scheme used (e.g., 'WebMercatorTilingScheme').

credit
String

Attribution or credit for the imagery provider.

ContentType

The type of graphics content.

Name
Type
Description
3DTILES
String
GLTF
String
IMAGERY
String
TERRAIN
String
KML
String
CZML
String
GEOJSON
String

GraphicsArrayResponse

Name
Type
Description
graphics

List of graphics items for the resource.

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?