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
The iTwin Id
The repository Id
The resourceId
Request headers
OAuth access token with itwin-platform
scope
Setting to application/vnd.bentley.itwin-platform.v1+json
is recommended.
Response 200 OK
OK
{ "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.
{ "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": "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.
Graphics
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.
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).
Some repositories may provide additional information that can be used by a CesiumJS provider. The name and options will be provided here.
{ "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ContentType" }, "uri": { "type": "string", "description": "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": { "$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)." }, "provider": { "$ref": "#/components/schemas/GraphicsProvider", "description": "Some repositories may provide additional information that can be used by a CesiumJS provider. The name and options will be provided here." } }, "required": [ "type", "uri" ], "additionalProperties": false }
GraphicsProvider
The name of the provider. Currently only UrlTemplateImageryProvider is supported. More will be added as needed.
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.
{ "type": "object", "properties": { "name": { "type": "string", "description": "The name of the provider. Currently only [UrlTemplateImageryProvider](https://cesium.com/learn/cesiumjs/ref-doc/UrlTemplateImageryProvider.html) is supported. More will be added as needed." }, "options": { "oneOf": [ { "$ref": "#/components/schemas/UrlTemplateImageryProviderOptions" } ], "description": "Additional options for the provider. The properties contained in options will depend on the provider name. If the provider name is [UrlTemplateImageryProvider](https://cesium.com/learn/cesiumjs/ref-doc/UrlTemplateImageryProvider.html) then options will contain properties that can be used in the [constructor](https://cesium.com/learn/cesiumjs/ref-doc/UrlTemplateImageryProvider.html#.ConstructorOptions) for that provider." } }, "additionalProperties": false }
UrlTemplateImageryProviderOptions
Bounding box as [west, south, east, north] in degrees. Use to create the Rectangle needed in the UrlTemplateImageryProvider constructor.
The tiling scheme used (e.g., 'WebMercatorTilingScheme').
Attribution or credit for the imagery provider.
{ "type": "object", "properties": { "bounds": { "type": "array", "description": "Bounding box as [west, south, east, north] in degrees. Use to create the [Rectangle](https://cesium.com/learn/cesiumjs/ref-doc/Rectangle.html) needed in the UrlTemplateImageryProvider constructor.", "items": { "type": "number", "format": "double" }, "minItems": 4, "maxItems": 4 }, "tilingScheme": { "type": "string", "description": "The tiling scheme used (e.g., 'WebMercatorTilingScheme')." }, "credit": { "type": "string", "description": "Attribution or credit for the imagery provider." } }, "additionalProperties": false }
ContentType
The type of graphics content.
{ "type": "string", "enum": [ "3DTILES", "GLTF", "IMAGERY", "TERRAIN", "KML", "CZML", "GEOJSON" ], "description": "The type of graphics content." }
GraphicsArrayResponse
{ "type": "object", "properties": { "graphics": { "type": "array", "description": "List of graphics items for the resource.", "items": { "$ref": "#/components/schemas/Graphics" } } }, "required": [ "graphics" ], "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?