Table of contents
iTwins
Download API definition:
PUT https://dev-api.bentley.com/itwins/{iTwinId}/image

Uploads an image for the specified iTwin. Maximum supported size is 5 megabytes.

A small, thumbnail image will be automatically generated based on the uploaded image. For convenience, the link to this thumbnail is also returned in the 'image' property on the iTwin.

Upload the image by adding a binary stream to the request body. You must specify the Content-Type header as either image/png or image/jpeg.

C# Example:

 var stream = File.OpenRead("c:/test.jpg");
 var streamContent = new StreamContent(stream);
 streamContent.Headers.ContentType = new MediaTypeHeaderValue ("image/jpeg");
 var response = await httpClient.PutAsync($"{iTwinId}/image", streamContent);

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 user must have the itwins_modify permission on the iTwin in order to add an image to the iTwin.

An Organization Administrator can modify any iTwins owned by their Organization. This allows Organization Administrators to upload an iTwin image.

Organization Administrators are power users for all iTwins owned by their organization. They will be able to create, modify or delete any iTwin. Example: john.doe@example.com is an Organization Administrator that works for Example Industries. John will be able to create iTwins and those iTwins will belong to Example Industries. John and any other Organization Administrator for Example Industries will be able to update or delete the iTwin. Any user (an employee of Example Industries, or an external participant) can be invited to collaborate on the iTwin.

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

Name
Required?
Description
iTwinId
Yes

iTwin ID associated with Image.

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.

Content-Type
Yes

Indicates request body content type. Must be image/png or image/jpeg.

Binary Image

Response 201 Created

iTwin Image uploaded successfully.

json
{
    "image": {
        "id": "b3bd3a79-c5b4-41f5-ba5f-6d8c338d788a",
        "smallImageName": "small_b3bd3a79-c5b4-41f5-ba5f-6d8c338d788a.jpeg",
        "smallImageUrl": "https://crdeveussa01.blob.core.windows.net/context-thumbnails/small_b3bd3a79-c5b4-41f5-ba5f-6d8c338d788a.jpeg?sv=2018-03-28&sr=b&sig=cuvNWKQE7hCsc4R12LPRSi%2BVOw0EhlB3pHxnrwHK4G8%3D&se=2023-06-28T00%3A00%3A00Z&sp=r",
        "largeImageName": "large_b3bd3a79-c5b4-41f5-ba5f-6d8c338d788a.jpeg",
        "largeImageUrl": "https://crdeveussa01.blob.core.windows.net/context-images/large_b3bd3a79-c5b4-41f5-ba5f-6d8c338d788a.jpeg?sv=2018-03-28&sr=b&sig=n%2BP%2BdGc1Uum4WHEm8Ji9ipZm6tM9d1r8b2iQS%2FjuOEM%3D&se=2023-06-28T00%3A00%3A00Z&sp=r"
    }
}

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 one of the associated entities could not be found.

json
{
    "error": {
        "code": "iTwinNotFound",
        "message": "Requested iTwin is not available."
    }
}

Response 413 Request Entity Too Large

Indicates that the file the user attempted to upload is above the maximum size.

json
{
    "error": {
        "code": "RequestTooLarge",
        "message": "Provided file is greater than the maximum allowed file size of 5MB."
    }
}

Response 422 Unprocessable Entity

Invalid request to add iTwin image. Review the 'Field Values' section near the top of this page.

json
{
    "error": {
        "code": "InvalidiTwinsRequest",
        "message": "Cannot create iTwin Image.",
        "details": [{
                "code": "ReadOnlyProperty",
                "message": "Id is read only and cannot be modified.",
                "target": "id"
            },
            {
                "code": "InvalidRequestBody",
                "message": "The iTwin Image is too big.  It cannot be greater than 5 MB.",
                "target": "image"
            },
            {
                "code": "InvalidValue",
                "message": "The width or height dimensions of the image cannot be greater than 5 times the size of each other.",
                "target": "image"
            }
        ]
    }
}

Response 429 Too many requests

This response indicates that the user has sent too many requests in a given amount of time.

json
{
    "error": {
        "code": "TooManyRequests",
        "message": "More requests were received than the subscription rate-limit allows."
    }
}

Response headers

Name
Description
retry-after

The number of requests exceeds the rate-limit for the client subscription.

image-response

Name
Type
Description
image

image

Name
Type
Description
id
String

The unique id of the image.

smallImageName
String

The generated name of the small image. It is unique and will only change if the image changes. The small image is an automatically generated thumbnail of the uploaded image.

smallImageUrl
String

The URL of the small image. This URL is also returned as a property on each iTwin. This makes it easy to use as a thumbnail.

largeImageName
String

The generated name of the uploaded image. It is unique and will only change if the image changes.

largeImageUrl
String

The URL of the large image. Usually, only the small image is used but this URL will provide the orginal large image if needed.

image-binary

The binary image file

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.