iModelHub is the control center for iModels. It is responsible for coordinating concurrent access to iModels as well as changes made to them in a form of [Changesets](https://www.itwinjs.org/learning/glossary/#changeset).

Overview of [iModelHub](https://www.itwinjs.org/learning/imodelhub/) and [iModels](https://www.itwinjs.org/learning/imodels/).

These APIs lets you retrieve metadata about the iModels pushed to iModelHub. To view, create or update your iModels use [iTwin.js](https://www.itwinjs.org/) client libraries.


imodels-v2

Added technology preview operation `Fork iModel`.

Added `forkedFrom` property to `Get Create iModel Operation Details` operation response.

Added support for ordering collection by `createdDateTime` property in `Get iModel Named Versions` operation.

Added optional `$search` query parameter to `Get iModel Named Versions` operation.

Added ordering by `createdDateTime` for `Get iTwin iModels` operation.

Added technology preview operation `Get iModel Role Permissions`.

Added technology preview operation `Update iModel Role Permissions`.

Added technology preview operation `Create Changeset Extended Data`.

Added technology preview operation `Get Changeset Extended Data`.

Added technology preview operation `Get Changesets Extended Data`.

Added technology preview operation `Create iModel Changeset Group`.

Added technology preview operation `Get iModel Changeset Group`.

Added technology preview operation `Get iModel Changeset Groups`.

Added technology preview operation `Update iModel Changeset Group`.

Added `groupId` property to `Create iModel Changeset` operation request body.

Added `groupId` property to `Create iModel Changeset`, `Update iModel Changeset`, `Get iModel Changeset` and `Get iModel Changesets` operation responses.

Added optional `$search` query parameter to `Get iTwin iModels` operation.

Added `dataCenterLocation` property to `Get iTwin iModels`, `Get iModel`, `Update-iModel` and `Create-iModel` operation responses.

Added `isSecured` property to `Get iTwin iModels`, `Get iModel`, `Update-iModel` and `Create-iModel` operation responses.

iModels API version 2 is generally available

`Create  iModel` operation now accepts `iTwinId` property and no longer accepts `projectId` property.
iModels operations responses now contain `iTwinId` property and no longer contain `projectId` property.

This information is included in every event the webhook will receive.

base-event

content

object

eventType

string

enqueuedDateTime

iTwinId

messageId

webhookId

Base Event

Event that gets triggered when the iModel is deleted.

iModels.iModelDeleted.v1-event

Globally Unique Identifier of the iModel.

imodelId

Globally Unique Identifier of the user that deleted the iModel.

userId

iModels.iModelDeleted.v1

Event that gets triggered when the iModel is created.

iModels.iModelCreated.v1-event

Globally Unique Identifier of the user that created the iModel.

iModels.iModelCreated.v1

Event that gets triggered when new Named Version is created for the iModel.

iModels.namedVersionCreated.v1-event

Changeset id is a 40 characters SHA1 hash that is used to validate Changeset. The id of Changeset is generated from the id of its parent as well as its contents.

changesetId

Index of the Changeset (increasing, but not necessarily sequential).

changesetIndex

Globally Unique Identifier of the user that created iModel named version.

Globally Unique Identifier of the Named Version.

versionId

iModels.namedVersionCreated.v1

Event that gets triggered when there are new changes to the iModel which are ready to be processed.

iModels.changesReady.v1-event

Globally Unique Identifier of the user that iModel changeset belongs to.

iModels.changesReady.v1

imodels

---

Complete [iModel](https://www.itwinjs.org/learning/glossary/#imodel) creation from Baseline File by confirming that file was uploaded to file storage.

 Baseline File is the base iModel file that does not have any changesets applied. For creating an iModel from a custom Baseline File see [Create iModel using a Baseline File](https://developer.bentley.com/apis/imodels/operations/create-imodel/#createanimodelusingabaselinefile).

### 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](https://developer.bentley.com/apis/overview/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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


complete-imodel-baseline-file-upload

OAuth access token with `itwin-platform` scope

Authorization

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

Accept

default

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.

HeaderNotFound

InvalidAuthorizationScheme

InvalidHeaderValue

RequiredScopeMissing

Unauthorized

InvalidApplicationTier

User is not authorized to complete Baseline File upload.

Specified iModel was not found, it does not have an associated Baseline File entity or the file was not uploaded to the storage.

iModelNotFound

BaselineFileNotFound

FileNotFound

File size specified during iModel creation does not match the actual file size of the uploaded file.

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)

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

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

retry-after

---

Retrieves the metadata of a Baseline File. Baseline File is the base iModel file that does not have any changesets applied.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_webview` permission assigned at the iModel level and at least `imodels_webview` permission assigned at the iTwin level. If permissions at the iModel level are not configured, then user must have `imodels_webview` permission assigned at the iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin the iModel belongs to.

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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

**Note:** `download` property requires user to have at least `imodels_read` permission. If user has only `imodels_webview` permission `download` will always be null.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-imodel-baseline-file-details

Specified iModel was not found or it does not have an associated Baseline File entity.

---

Acquires a new [Briefcase](https://www.itwinjs.org/learning/glossary/#briefcase).

Briefcases are the local copies of iModel that users can acquire to work with the iModel. Users can make changes to their copy of iModel and then push them as a single Changeset file into iModelHub. For more information on Briefcases see [working with Briefcases](https://www.itwinjs.org/learning/imodelhub/briefcases/).

**Note:** The total number of Briefcases a single user can acquire is limited. The error code `ResourceQuotaExceeded` is returned when you exceed the limit. The current limit is 100 total briefcases.

The number of Briefcases a single user can acquire per minute is also limited. The error code `RateLimitExceeded` is returned when you exceed the limit. The current limit per minute is 100.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_read` permission assigned at the iModel level and at least `imodels_webview` permission assigned at the iTwin level. If permissions at the iModel level are not configured, then user must have `imodels_read` permission assigned at the iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin the iModel belongs to.

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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


acquire-imodel-briefcase

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

Content-Type

User is not authorized to acquire a Briefcase.

iModel is not initialized and modify operations are not allowed.

Indicates how long the user agent should wait before making a follow-up request.

TooManyRequests

RateLimitExceeded

---

Retrieves the details of a [Briefcase](https://www.itwinjs.org/learning/glossary/#briefcase).

Briefcases are the local copies of iModel that users can acquire to work with the iModel. Users can make changes to their copy of iModel and then push them as a single Changeset file into iModelHub. For more information on Briefcases see [working with Briefcases](https://www.itwinjs.org/learning/imodelhub/briefcases/).

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_webview` permission assigned at the iModel level and at least `imodels_webview` permission assigned at the iTwin level. If permissions at the iModel level are not configured, then user must have `imodels_webview` permission assigned at the iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin the iModel belongs to.

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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-imodel-briefcase-details

briefcaseId

Specified iModel or Briefcase was not found.

BriefcaseNotFound

---

Retrieves a list of [Briefcases](https://www.itwinjs.org/learning/glossary/#briefcase) for the iModel specified by the iModel id.

Briefcases are the local copies of iModel that users can acquire to work with the iModel. Users can make changes to their copy of iModel and then push them as a single Changeset file into iModelHub. For more information on Briefcases see [working with Briefcases](https://www.itwinjs.org/learning/imodelhub/briefcases/).

### Notes

The `Prefer` header can be used to specify how much result metadata is desired by the client. The `Prefer` request header field is used to indicate that particular server behaviors are preferred by the client but are not required for successful completion of the request.

This operation supports `"return=representation"` and `"return=minimal"` preferences.

The `"return=representation"` preference indicates that the client prefers that the server include an entity representing the current state of the resource in the response to a successful request.
The `"return=minimal"` preference indicates that the client wishes the server to return only a minimal response to a successful request. This is the default preference if `Prefer` header is not specified.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_webview` permission assigned at the iModel level and at least `imodels_webview` permission assigned at the iTwin level. If permissions at the iModel level are not configured, then user must have `imodels_webview` permission assigned at the iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin the iModel belongs to.

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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-imodel-briefcases

The $top query option requests the number of items in the queried collection to be included in the result. E.g. to return only first collection item provide the following query: $top=1. When $top parameter is not provided default is set to 100. $top value cannot exceed 1000.

$top

The $skip query option requests the number of items in the queried collection that are to be skipped and not included in the result. E.g. to return items from the collection starting at the third place provide the following query: $skip=2.

$skip

The ownerId query option allows users to filter Briefcases by their ownerId property. Valid values for this parameter are strings. Strings should be not empty, consist not only of whitespace and not exceed 255 characters. The 'me' keyword can be used to reference the current user. Current user is a user that the access token used for request belongs to. E.g. to return Briefcases owned by the current user provide the following query: ownerId=me.

ownerId

Indicates a level of details in the response. This operation supports 'return=representation' and 'return=minimal' preferences.

Prefer

minimal

representation

---

Deletes the specified [Briefcase](https://www.itwinjs.org/learning/glossary/#briefcase).

Briefcases are the local copies of iModel that users can acquire to work with the iModel. Users can make changes to their copy of iModel and then push them as a single Changeset file into iModelHub. For more information on Briefcases see [working with Briefcases](https://www.itwinjs.org/learning/imodelhub/briefcases/).

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

To release any Briefcase user must have `imodels_manage` permission assigned at the iModel level. If permissions at the iModel level are not configured, then user must have `imodels_manage` permission assigned at the iTwin level. To release a Briefcase that the user owns `imodels_webview` permission is enough.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin the iModel belongs to.

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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---

release-imodel-briefcase

User is not authorized to release a Briefcase.

---

Creates a new Changeset Group.

Changeset Groups are a way to logically group [Changesets](https://www.itwinjs.org/learning/glossary/#changeset). Changesets that belong to the same Changeset Group may be interpreted as one logical change to the iModel, for example, iModel synchronization process may create multiple Changesets but they all represent one synchronization run.

The intended workflow is as follows:

1. Application creates a Changeset Group.

2. Application pushes one or more Changesets to that Changeset Group by setting `groupId` property on the Changeset entity.

3. [Application updates Changeset Group](https://developer.bentley.com/apis/imodels-v2/operations/update-imodel-changeset-group/) and sets its `state` value to `completed`.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission assigned at the iModel level and at least `imodels_webview` permission assigned at the iTwin level. If permissions at the iModel level are not configured, then user must have `imodels_write` permission assigned at the iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin the iModel belongs to.

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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


create-imodel-changeset-group

User is not authorized to create a Changeset Group.

---

Retrieves the details of a Changeset Group.

Changeset Groups are a way to logically group [Changesets](https://www.itwinjs.org/learning/glossary/#changeset). Changesets that belong to the same Changeset Group may be interpreted as one logical change to the iModel, for example, iModel synchronization process may create multiple Changesets but they all represent one synchronization run.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_webview` permission assigned at the iModel level and at least `imodels_webview` permission assigned at the iTwin level. If permissions at the iModel level are not configured, then user must have `imodels_webview` permission assigned at the iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin the iModel belongs to.

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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-imodel-changeset-group-details

changesetGroupId

Specified iModel or Changeset Group was not found.

ChangesetGroupNotFound

---

Retrieves a list of Changeset Groups for the iModel specified by the iModel id.

Changeset Groups are a way to logically group [Changesets](https://www.itwinjs.org/learning/glossary/#changeset). Changesets that belong to the same Changeset Group may be interpreted as one logical change to the iModel, for example, iModel synchronization process may create multiple Changesets but they all represent one synchronization run.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_webview` permission assigned at the iModel level and at least `imodels_webview` permission assigned at the iTwin level. If permissions at the iModel level are not configured, then user must have `imodels_webview` permission assigned at the iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin the iModel belongs to.

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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-imodel-changeset-groups

---

Closes an existing Changeset Group.

Please refer to [Create iModel Changeset Group](https://developer.bentley.com/apis/imodels-v2/operations/create-imodel-changeset-group/) operation documentation for information about the purpose of Changeset Groups.

Closing a Changeset Group means that there will be no more [Changesets](https://www.itwinjs.org/learning/glossary/#changeset) in the logical group, for example, synchronization process has processed all iModel changes and will not push any more Changesets. If a Changeset Group is closed, meaning its `state` property value is `completed`, `timedOut` or `forciblyClosed`, no more Changesets referencing that particular Group will be accepted. Users can only close the Changeset Group by setting `completed` state value as other values are set by iModels API.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission assigned at the iModel level and at least `imodels_webview` permission assigned at the iTwin level. If permissions at the iModel level are not configured, then user must have `imodels_write` permission assigned at the iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin the iModel belongs to.

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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


update-imodel-changeset-group

User is not authorized to update a Changeset Group.

Changeset Group is already closed or the iModel is not initialized.

ChangesetGroupIsClosed

iModelNotInitialized

InvalidiModelsRequest

MissingRequestBody

---

Adds application specific data to the specified [Changeset](https://www.itwinjs.org/learning/glossary/#changeset).

Extended data is an application specific data associated to the Changeset. This data is not interpreted by the service. Extended data must be a valid json object encoded as base64 string.

Extended data can only be set once by the principal who created the Changeset. Maximum supported data field size is 204800 bytes (200 KiB).

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission assigned at the iModel level and at least `imodels_webview` permission assigned at the iTwin level. If permissions at the iModel level are not configured, then user must have `imodels_write` permission assigned at the iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin the iModel belongs to.

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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---

create-imodel-changeset-extended-data

changeset

User is not authorized to create a Changeset Extended Data.

Specified iModel or Changeset was not found.

ChangesetNotFound

iModel is not initialized, a Changeset Extended Data already exists.

application/json;ChangesetExtendedDataExists

ChangesetExtendedDataExists

---

Creates the metadata of a [Changeset](https://www.itwinjs.org/learning/glossary/#changeset).

For more information on creating and retrieving Changesets using iTwin.js see [working with Changesets](https://www.itwinjs.org/learning/imodelhub/briefcases/).

 **Important: This operation should only be used by iTwin.js. For creating and uploading a valid Changeset please use iTwin.js libraries.**

Pushing a Changeset consists of three steps:

1. Create Changeset metadata.
2. Upload Changeset file to blob storage using `upload` property link from the response of Changeset metadata creation.
```
Request syntax:
    PUT upload HTTP/1.1
Request headers:
    x-ms-blob-type: BlockBlob
```

3. Complete the Changeset push by confirming that Changeset file was uploaded successfully. See [Update iModel Changeset](https://developer.bentley.com/apis/imodels/operations/update-imodel-changeset/) operation for the documentation.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission assigned at the iModel level and at least `imodels_webview` permission assigned at the iTwin level. If permissions at the iModel level are not configured, then user must have `imodels_write` permission assigned at the iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin the iModel belongs to.

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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---

create-imodel-changeset

User is not authorized to create a Changeset.

iModel is not initialzied, a Changeset with the same id already exists, 'parentId' property value does not point to the latest changes or another user is currently in a process of pushing a changeset.

NewerChangesExist

ChangesetExists

ConflictWithAnotherUser

ChangesetGroupClosed

---

Checkpoint is a pre-processed iModel baseline file that has changes up to a certain Changeset already applied and is stored on the server. This can be used to reduce number of Changesets needed to apply to get to a certain version of the iModel.

A Checkpoint is generated when a Named Version is created for that changeset.

Checkpoint can be stored in two different ways:

1. `download` property will have a Azure Blob storage link to a full `.bim` file that has changes applied up to the Changeset specified by `changesetIndex` and `changesetId` properties.
2. `containerAccessInfo` will have an access key to Azure Blob container that stores the Checkpoint in 4 MB blocks. **Important: This property should only be used by iTwin.js libraries.**

A successfully generated Checkpoint will have one or both of these properties.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_read` permission assigned at the iModel level and at least `imodels_webview` permission assigned at the iTwin level. If permissions at the iModel level are not configured, then user must have `imodels_read` permission assigned at the iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin the iModel belongs to.

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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-changeset-checkpoint

Specified iModel, Changeset or Checkpoint was not found.

CheckpointNotFound

---

Retrieves the details of a Changesets Extended Data.

Extended data is an application specific data associated to the [Changeset](https://www.itwinjs.org/learning/glossary/#changeset). This data is not interpreted by the service. Extended data must be a valid json object encoded as base64 string.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_webview` permission assigned at the iModel level and at least `imodels_webview` permission assigned at the iTwin level. If permissions at the iModel level are not configured, then user must have `imodels_webview` permission assigned at the iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin the iModel belongs to.

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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---

get-imodel-changeset-extended-data-details

Specified iModel, Changeset or Changeset Extended Data was not found.

application/json;ChangesetExtendedDataNotFound

ChangesetExtendedDataNotFound

---

Retrieves a list of extended Changeset data entries for the iModel specified by the iModel id.

Extended data is an application specific data associated to the [Changeset](https://www.itwinjs.org/learning/glossary/#changeset). This data is not interpreted by the service. Extended data must be a valid json object encoded as base64 string.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_webview` permission assigned at the iModel level and at least `imodels_webview` permission assigned at the iTwin level. If permissions at the iModel level are not configured, then user must have `imodels_webview` permission assigned at the iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin the iModel belongs to.

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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-imodel-changesets-extended-data

---

Retrieves the metadata of a [Changeset](https://www.itwinjs.org/learning/glossary/#changeset).

For more information on creating and retrieving Changesets using iTwin.js see [working with Changesets](https://www.itwinjs.org/learning/imodelhub/briefcases/).

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_webview` permission assigned at the iModel level and at least `imodels_webview` permission assigned at the iTwin level. If permissions at the iModel level are not configured, then user must have `imodels_webview` permission assigned at the iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin the iModel belongs to.

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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

**Note:** `download` property requires user to have at least `imodels_read` permission. If user has only `imodels_webview` permission `download` will always be null.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-imodel-changeset-details

---

Retrieves a list of [Changesets](https://www.itwinjs.org/learning/glossary/#changeset) for the iModel specified by the iModel id.

[Changesets](https://www.itwinjs.org/learning/glossary/#changeset) form a linear timeline of the iModel changes. 
For more information on creating and retrieving Changesets using iTwin.js see [working with Changesets](https://www.itwinjs.org/learning/imodelhub/briefcases/).

### Notes

The `Prefer` header can be used to specify how much result metadata is desired by the client. The `Prefer` request header field is used to indicate that particular server behaviors are preferred by the client but are not required for successful completion of the request.

This operation supports `"return=representation"` and `"return=minimal"` preferences.

The `"return=representation"` preference indicates that the client prefers that the server include an entity representing the current state of the resource in the response to a successful request.
The `"return=minimal"` preference indicates that the client wishes the server to return only a minimal response to a successful request. This is the default preference if `Prefer` header is not specified.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_webview` permission assigned at the iModel level and at least `imodels_webview` permission assigned at the iTwin level. If permissions at the iModel level are not configured, then user must have `imodels_webview` permission assigned at the iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin the iModel belongs to.

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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

**Note:** `download` property requires user to have at least `imodels_read` permission. If user has only `imodels_webview` permission `download` will always be null.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-imodel-changesets

The $orderBy query option allows clients to request ascending using 'asc' or descending using 'desc' order of the returned collection by one of the item properties. Currently the only supported property for Changesets is 'index'. When neither 'asc' or 'desc' keyword is specified the collection is sorted in ascending order. To sort the collection in descending order provide 'desc' keyword e.g.: $orderBy=index desc

$orderBy

The afterIndex query option allows clients to query Changesets which have an index that is greater than the one specified in the query. E.g. to return Changesets that have an index greater than or equal to 2 provide the following query: afterIndex=1. This query option is useful when user wants to query the most recent Changesets starting from the one that is already present in the local copy of the iModel. This can be used together with lastIndex option to specify Changeset index range, afterIndex denotes an exclusive start of the range.

afterIndex

The lastIndex query option allows clients to query Changesets which have an index that is less than or equal to the one specified in the query. E.g. to return Changesets that have an index less than or equal to 10 provide the following query: lastIndex=10. This can be used together with afterIndex option to specify Changeset index range, lastIndex denotes an inclusive end of the range.

lastIndex

---

Confirm that [Changeset](https://www.itwinjs.org/learning/glossary/#changeset) file has been uploaded to file storage and finalize Changeset push.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission assigned at the iModel level and at least `imodels_webview` permission assigned at the iTwin level. If permissions at the iModel level are not configured, then user must have `imodels_write` permission assigned at the iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin the iModel belongs to.

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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


update-imodel-changeset

User is not authorized to update a Changeset.

Specified iModel, Changeset, Briefcase or file was not found. FileNotFound will be returned if the server cannot find the uploaded Changeset file.

Changeset already exists, another user is currently pushing a Changeset or the iModel is not initialized.

---

Clones the specified iModel. 

Cloning an iModel means that a new iModel is created by importing data from the source iModel. That new iModel is considered to be an iModel clone. Id of the source iModel is specified in the request url while the id of the target iTwin which will contain the new iModel is specified in the request body.

### Relationship between the source iModel and the iModel clone

iModel clone is a valid standalone iModel. After the iModel cloning process is completed, no new changes are synchronized to the iModel clone from the source iModel. iModel clone is not deleted if the source iModel is deleted.

### iModel clone content and metadata

The target iModel name and description can be specified when cloning an iModel, by default name and description are taken from the source iModel. iModel extent is always taken from the source iModel.

[iModel Baseline](https://developer.bentley.com/apis/imodels-v2/operations/get-imodel-baseline-file-details/) is always copied from the source iModel to the target iModel. User can specify until which point [Changesets](https://developer.bentley.com/apis/imodels-v2/operations/get-imodel-changesets/) should be copied to the target iModel, by default all source iModel Changesets are copied. The rest of source iModel entities are not copied.

### Operation state

Clone iModel is an asynchronous operation. To check the status of the operation please follow the link present in `Create-iModel-Operation` response header. The link points to [Get Create iModel Operation details](https://developer.bentley.com/apis/imodels-v2/operations/get-create-imodel-operation-details/) endpoint of the target iModel. When the target iModel's Create Operation `state` property is set to `successful` it means the cloning process is complete and iModel is ready to be used.

`Location` header value is a link to [Get iModel details](https://developer.bentley.com/apis/imodels-v2/operations/get-imodel-details/) endpoint of the target iModel which provides metadata about the the target iModel as well as when it is ready to be used. When target iModel's `state` property is set to `initialized` the iModel is ready to be used.

Please note that iModel may be marked as `initialized` before the iModel Create Operation is marked as `successful`. Such behavior allows target iModel to be utilized faster. The cloning background process first of all copies the critical iModel data and marks the iModel as `initialized`, and then copies additional data used to improve performance for iModel viewing and authoring workflows.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have the following permissions:
- `imodels_manage` permission at the source iModel iTwin level. 
- `imodels_manage` permission at the target iTwin level. 

If source iModel has iModel level permissions configured, then user must have at least `imodels_webview` permission assigned at iModel level.

Alternatively the user should be an Organization Administrator both for the Organization that owns source iModel iTwin and the Organization that owns target 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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) 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 | 20 calls per minute |
<br/>
---


clone-imodel

iTwinIdOnly

ChangesetIndex

Target iModel name

ChangesetId

The resource location which is a URL to the new iModel.

Location

A URL which points to [Get Create iModel Operation details](https://developer.bentley.com/apis/imodels-v2/operations/get-create-imodel-operation-details/) endpoint for the new iModel.

Create-iModel-Operation

Specified source iTwin, iModel or Changeset were not found.

iTwinNotFound

iModel with the same name already exists in the iTwin or the source iModel is not initialized.

iModelExists

---

Creates an [iModel](https://www.itwinjs.org/learning/glossary/#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
```

3. Complete the iModel creation by confirming that Baseline File was uploaded successfully. See [Complete iModel Baseline Upload](https://developer.bentley.com/apis/imodels/operations/complete-imodel-baseline-file-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](https://developer.bentley.com/apis/imodels/operations/get-imodel-baseline-file-details/) operation.

### 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](https://developer.bentley.com/apis/overview/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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) 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 |
<br/>
---

create-imodel

Overall model of wind and solar farms in Sun City

Sun City Renewable-energy Plant

EmptyiModel

FromTemplate

FromBaselineFile

Empty iModel

iModel from Template

application/json;iModel from Baseline File

iModel from Baseline File

User is not authorized to create an iModel.

iModel with the same name already exists within the iTwin.

---

Deletes [iModel](https://www.itwinjs.org/learning/glossary/#imodel).

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have the `imodels_delete` 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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


delete-imodel

User is not authorized to delete an iModel.

---

Creates an iModel Fork. An iModel Fork is a new iModel which is a full or partial clone of the source iModel, but the difference between an iModel Fork and an iModel clone is that Fork iModels can be edited and then merged back to the source iModel.

### Relationship between source and Fork iModels

An iModel Fork is a valid standalone iModel. An iModel Fork is not deleted if the source iModel is deleted.

When the iModel forking process is completed, no new changes are synchronized to the iModel Fork from the source iModel.

[iModel Create Operation Details](https://dev-developer.bentley.com/apis/imodels-v2/operations/get-create-imodel-operation-details/) operation can be used to determine if the current iModel is a Fork.

### iModel Fork content and metadata

The iModel Fork name and description can be specified when forking an iModel, by default name and description are taken from the source iModel. iModel extent is always taken from the source iModel.

[iModel Baseline](https://developer.bentley.com/apis/imodels-v2/operations/get-imodel-baseline-file-details/) is always copied from the source iModel to the iModel Fork. User can specify until which point [Changesets](https://developer.bentley.com/apis/imodels-v2/operations/get-imodel-changesets/) should be copied to the iModel Fork, by default all source iModel Changesets are copied. The rest of source iModel entities are not copied.

### Operation state

Forking an iModel is an asynchronous operation. To check the status of the operation please follow the link present in `Create-iModel-Operation` response header. The link points to [Get Create iModel Operation details](https://developer.bentley.com/apis/imodels-v2/operations/get-create-imodel-operation-details/) endpoint of the iModel Fork. When the iModel Fork's Create Operation `state` property is set to `successful` it means the forking process is complete and iModel is ready to be used.

#### `sourceIsMissingFederationGuids` state

If `state` returned by [Get Create iModel Operation details](https://developer.bentley.com/apis/imodels-v2/operations/get-create-imodel-operation-details/) is equal to `sourceIsMissingFederationGuids`, it means that iModel Fork creation failed because some elements in the source iModel do not have [FederationGuid](https://www.itwinjs.org/bis/guide/fundamentals/federationguids/) property set. In order to proceed users must populate missing FederationGuid values and retry the iModel Fork creation request.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have the following permissions:
- `imodels_manage` permission at the source iModel iTwin level.
- `imodels_manage` permission at the iTwin, in which the iModel Fork will be created, level.

If source iModel has iModel level permissions configured, then user must have at least `imodels_webview` permission assigned.

Alternatively the user should be an Organization Administrator both for the Organization that owns source iModel iTwin and the Organization that owns the Fork iModel 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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

**Important**: Fork iModel operation is in closed preview mode currently and only selected applications can utilize it.

### 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 | 20 calls per minute |
<br/>
---


Changelog

Apr 4, 2024

Mar 29, 2024

Feb 20, 2024

Jan 23, 2024

Jun 20, 2023

Nov 7, 2022

Aug 18, 2022