iModels

iModels

Download API definition:

POST https://sampleHostName/imodels/

Creates an iModel. There are three different ways to create an iModel.

Create an empty iModel

To create an empty iModel do not provide template and baselineFile properties.

Create an iModel from an existing iModel

To create an iModel from another iModel provide template property. The server will apply changesets up to the one specified by changesetId property to the source iModel file and use it as a Baseline File for the newly created iModel. User must have imodels_read permissions to the source iModel. Source and target iTwins must be in the same data center.

Create an iModel using a Baseline File.

Creating an iModel using a Baseline File allows to upload a custom iModel file that will become the base file of the created iModel. There are three steps in creating an iModel from a Baseline File:

  1. Create a new iModel and provide baselineFile property. It is important to provide correct file size or the iModel creation will fail in the later steps.

  2. Upload Baseline File to blob storage using upload property link from the response of iModel creation.

Request syntax:
    PUT upload HTTP/1.1
Request headers:
    x-ms-blob-type: BlockBlob
  1. Complete the iModel creation by confirming that Baseline File was uploaded successfully. See Complete iModel Baseline Upload operation for the documentation.

iModel initialization

When creating an empty iModel it will be initialized immediately. When creating an iModel using template or baselineFile properties initialization will be scheduled and it's state is reflected in the state property. For a more detailed information about initialization state see Get iModel Baseline File operation.

Authentication

Requires Authorization header with valid Bearer token for scope imodels:modify.

For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.

Authorization

User must have the imodels_manage permission assigned at the iTwin level or be an Organization Administrator for the Organization that owns a given 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.

Rate limits

This operation has a lower rate limit than the rest of iModels API operations. If an application exceeds the rate limit it will receive an HTTP error code 429 "Too Many Requests". The error response includes a Retry-After header that indicates how long clients should wait before retrying.

Tier
Rate limit
Trial
5 calls per minute
Basic, Premium, Enterprise
50 calls per minute


Request headers

Name
Required?
Description
Authorization
Yes

OAuth access token with scope imodels:modify

Accept
No

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

Content-Type
No

Indicates request body content type. Supported media type is application/json.

Request body

iModelCreate

Name
Type
Required?
Description
No data.

iModelCreate

Name
Type
Required?
Description
No data.

iModelCreate

Name
Type
Required?
Description
No data.

Response 201 Created

OK

json

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

Response 403 Forbidden

User is not authorized to create an iModel.

json

Response 404 Not Found

Specified iTwin was not found.

json

Response 409 Conflict

iModel with the same name already exists within the iTwin.

json

Response 422 Unprocessable Entity

The 422 (Unprocessable Entity) status code indicates that the request cannot be processed by the server due to a client error (e.g. malformed request syntax)

json

Response 429 Too many requests

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

json

Response headers

Name
Description
retry-after

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