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 is always copied from the source iModel to the target iModel. User can specify until which point 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 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 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 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.
For more information please refer to Account Administrator documentation section on Access Control API documentation 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.
---
Request parameters
iModel id
Request headers
OAuth access token with itwin-platform
scope
Setting to application/vnd.bentley.itwin-platform.v2+json
is recommended.
Request body
CloneiModel (ITwinIdOnly)
Id of the iTwin in which the new iModel will be created.
Id of the latest source iModel Changeset that should be copied to the target iModel. Changeset can also be specified using an index, see changesetIndex
property. If neither changesetId
nor changesetIndex
are provided, all existing source iModel Changesets are copied to the target iModel. If "changesetId": ""
is specified, no Changesets are copied to the target iModel, only original iModel Baseline is copied.
Index of the latest source iModel Changeset that should be copied to the target iModel. Changeset can also be specified using an id, see changesetId
property. If neither changesetId
nor changesetIndex
are provided, all existing source iModel Changesets are copied to the target iModel. If "changesetIndex": 0
is specified, no Changesets are copied to the target iModel, only original iModel Baseline is copied. Valid changesetIndex
values are non-negative integers.
Name of the new iModel that will be created. If name
is not provided, original iModel name will be used. iModel name must be unique within the iTwin. Valid name
values are non-empty strings that are not longer than 255 characters.
Description of the new iModel that will be created. If description
is not provided, original iModel description will be used. Valid description
values are non-empty strings that are not longer than 255 characters.
Example
{ "iTwinId": "98418aa0-9059-458b-b9e4-245cf6131a55" }
CloneiModel (ChangesetIndex)
Id of the iTwin in which the new iModel will be created.
Id of the latest source iModel Changeset that should be copied to the target iModel. Changeset can also be specified using an index, see changesetIndex
property. If neither changesetId
nor changesetIndex
are provided, all existing source iModel Changesets are copied to the target iModel. If "changesetId": ""
is specified, no Changesets are copied to the target iModel, only original iModel Baseline is copied.
Index of the latest source iModel Changeset that should be copied to the target iModel. Changeset can also be specified using an id, see changesetId
property. If neither changesetId
nor changesetIndex
are provided, all existing source iModel Changesets are copied to the target iModel. If "changesetIndex": 0
is specified, no Changesets are copied to the target iModel, only original iModel Baseline is copied. Valid changesetIndex
values are non-negative integers.
Name of the new iModel that will be created. If name
is not provided, original iModel name will be used. iModel name must be unique within the iTwin. Valid name
values are non-empty strings that are not longer than 255 characters.
Description of the new iModel that will be created. If description
is not provided, original iModel description will be used. Valid description
values are non-empty strings that are not longer than 255 characters.
Example
{ "iTwinId": "98418aa0-9059-458b-b9e4-245cf6131a55", "changesetIndex": 5 }
CloneiModel (ChangesetId)
Id of the iTwin in which the new iModel will be created.
Id of the latest source iModel Changeset that should be copied to the target iModel. Changeset can also be specified using an index, see changesetIndex
property. If neither changesetId
nor changesetIndex
are provided, all existing source iModel Changesets are copied to the target iModel. If "changesetId": ""
is specified, no Changesets are copied to the target iModel, only original iModel Baseline is copied.
Index of the latest source iModel Changeset that should be copied to the target iModel. Changeset can also be specified using an id, see changesetId
property. If neither changesetId
nor changesetIndex
are provided, all existing source iModel Changesets are copied to the target iModel. If "changesetIndex": 0
is specified, no Changesets are copied to the target iModel, only original iModel Baseline is copied. Valid changesetIndex
values are non-negative integers.
Name of the new iModel that will be created. If name
is not provided, original iModel name will be used. iModel name must be unique within the iTwin. Valid name
values are non-empty strings that are not longer than 255 characters.
Description of the new iModel that will be created. If description
is not provided, original iModel description will be used. Valid description
values are non-empty strings that are not longer than 255 characters.
Example
{ "iTwinId": "98418aa0-9059-458b-b9e4-245cf6131a55", "changesetId": "1f2e04b666edce395e37a795e2231e995cbf8349", "name": "Target iModel name", "description": "Target iModel description" }
Response 202 Accepted
Accepted
Response headers
The resource location which is a URL to the new iModel.
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 403 Forbidden
User is not authorized to clone iModel.
{ "error": { "code": "InsufficientPermissions", "message": "The user has insufficient permissions for the requested operation." } }
Response 404 Not Found
Specified source iTwin, iModel or Changeset were not found.
{ "error": { "code": "iTwinNotFound", "message": "Requested iTwin is not available." } }
Response 409 Conflict
iModel with the same name already exists in the iTwin or the source iModel is not initialized.
{ "error": { "code": "iModelExists", "message": "iModel with the same name already exists within the iTwin." } }
Response 415 Unsupported Media Type
This response indicates that the user has specified not supported media type in the request.
{ "error": { "code": "UnsupportedMediaType", "message": "Media Type is not supported." } }
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)
{ "error": { "code": "InvalidiModelsRequest", "message": "Cannot clone iModel.", "details": [{ "code": "InvalidRequestBody", "message": "Failed to parse request body. Make sure it is a valid JSON." }, { "code": "MissingRequiredProperty", "message": "Required property is missing.", "target": "iTwinId" }, { "code": "InvalidValue", "message": "'' is not a valid 'name' value. The value cannot be empty or consist only of whitespace characters.", "target": "name" } ] } }
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.
Clone iModel Request
Information that should be provided to start iModel cloning.
Id of the iTwin in which the new iModel will be created.
Id of the latest source iModel Changeset that should be copied to the target iModel. Changeset can also be specified using an index, see changesetIndex
property. If neither changesetId
nor changesetIndex
are provided, all existing source iModel Changesets are copied to the target iModel. If "changesetId": ""
is specified, no Changesets are copied to the target iModel, only original iModel Baseline is copied.
Index of the latest source iModel Changeset that should be copied to the target iModel. Changeset can also be specified using an id, see changesetId
property. If neither changesetId
nor changesetIndex
are provided, all existing source iModel Changesets are copied to the target iModel. If "changesetIndex": 0
is specified, no Changesets are copied to the target iModel, only original iModel Baseline is copied. Valid changesetIndex
values are non-negative integers.
Name of the new iModel that will be created. If name
is not provided, original iModel name will be used. iModel name must be unique within the iTwin. Valid name
values are non-empty strings that are not longer than 255 characters.
Description of the new iModel that will be created. If description
is not provided, original iModel description will be used. Valid description
values are non-empty strings that are not longer than 255 characters.
{ "type": "object", "title": "Clone iModel Request", "description": "Information that should be provided to start iModel cloning.", "properties": { "iTwinId": { "type": "string", "description": "Id of the iTwin in which the new iModel will be created." }, "changesetId": { "type": "string", "description": "Id of the latest source iModel Changeset that should be copied to the target iModel. Changeset can also be specified using an index, see `changesetIndex` property. If neither `changesetId` nor `changesetIndex` are provided, all existing source iModel Changesets are copied to the target iModel. If `\"changesetId\": \"\"` is specified, no Changesets are copied to the target iModel, only original [iModel Baseline](https://developer.bentley.com/apis/imodels-v2/operations/get-imodel-baseline-file-details/) is copied.", "nullable": true }, "changesetIndex": { "type": "integer", "format": "int64", "description": "Index of the latest source iModel Changeset that should be copied to the target iModel. Changeset can also be specified using an id, see `changesetId` property. If neither `changesetId` nor `changesetIndex` are provided, all existing source iModel Changesets are copied to the target iModel. If `\"changesetIndex\": 0` is specified, no Changesets are copied to the target iModel, only original [iModel Baseline](https://developer.bentley.com/apis/imodels-v2/operations/get-imodel-baseline-file-details/) is copied. Valid `changesetIndex` values are non-negative integers.", "nullable": true }, "name": { "type": "string", "description": "Name of the new iModel that will be created. If `name` is not provided, original iModel name will be used. iModel name must be unique within the iTwin. Valid `name` values are non-empty strings that are not longer than 255 characters.", "nullable": true }, "description": { "type": "string", "description": "Description of the new iModel that will be created. If `description` is not provided, original iModel description will be used. Valid `description` values are non-empty strings that are not longer than 255 characters.", "nullable": true } }, "required": [ "iTwinId" ], "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?