Creates an iModel fork. An iModel fork is a new iModel which is a full or partial clone of the main (source) iModel, but the difference between an iModel fork and an iModel clone is that forks can be edited and then merged back to the main iModel using Merge iModel transformation.
Relationship between main and fork iModels
An iModel fork is a valid standalone iModel. An iModel fork is not deleted if the main iModel is deleted.
When the iModel forking process is completed, no new changes are synchronized to the iModel fork from the main iModel.
iModel Create 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 main iModel. iModel extent is always taken from the main iModel.
iModel Baseline is always copied from the main iModel to the iModel fork. User can specify until which point Changesets should be copied to the iModel fork, by default all main iModel Changesets are copied. The rest of main 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 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.
mainIModelIsMissingFederationGuids state
If state returned by Get Create iModel Operation details is equal to mainIModelIsMissingFederationGuids, it means that iModel fork creation failed because some elements in the main iModel do not have FederationGuid property set. In order to proceed users must populate missing FederationGuid values in main iModel using Populate Federation Guids transformation 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 page.
Authorization
User must have the following permissions:
imodels_managepermission at the main iModel iTwin level.imodels_managepermission at the iTwin, in which the iModel fork will be created, level.
If main 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 main iModel iTwin and the Organization that owns the iModel fork iTwin.
For more information please refer to Account Administrator documentation section on Access Control API documentation 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.
---
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
ForkiModel (ChangesetId)
Id of the iTwin in which the new iModel will be created.
Id of the latest main iModel Changeset that should be copied to the iModel fork. Changeset can also be specified using an index, see changesetIndex property. If neither changesetId nor changesetIndex are provided, all existing main iModel Changesets are copied to the iModel fork. If "changesetId": "" is specified, no Changesets are copied to the iModel fork, only main iModel Baseline is copied.
Index of the latest main iModel Changeset that should be copied to the iModel fork. Changeset can also be specified using an id, see changesetId property. If neither changesetId nor changesetIndex are provided, all existing main iModel Changesets are copied to the iModel fork. If "changesetIndex": 0 is specified, no Changesets are copied to the iModel fork, only main iModel Baseline is copied. Valid changesetIndex values are non-negative integers.
Name of the iModel that will be created. If name is not provided, main 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 iModel that will be created. If description is not provided, main iModel description will be used. Valid description values are non-empty strings that are not longer than 255 characters.
Option to control how Changesets are copied from the main iModel to the iModel fork. If set to true, Changesets will be copied individually and the history will be preserved. If set to false, Changesets will be squashed and applied to the Baseline resulting in an iModel fork without Changeset history. The default value is false.
Example
{ "iTwinId": "98418aa0-9059-458b-b9e4-245cf6131a55", "changesetId": "1f2e04b666edce395e37a795e2231e995cbf8349", "name": "Target iModel name", "description": "Target iModel description", "preserveHistory": true }
ForkiModel (ChangesetIndex)
Id of the iTwin in which the new iModel will be created.
Id of the latest main iModel Changeset that should be copied to the iModel fork. Changeset can also be specified using an index, see changesetIndex property. If neither changesetId nor changesetIndex are provided, all existing main iModel Changesets are copied to the iModel fork. If "changesetId": "" is specified, no Changesets are copied to the iModel fork, only main iModel Baseline is copied.
Index of the latest main iModel Changeset that should be copied to the iModel fork. Changeset can also be specified using an id, see changesetId property. If neither changesetId nor changesetIndex are provided, all existing main iModel Changesets are copied to the iModel fork. If "changesetIndex": 0 is specified, no Changesets are copied to the iModel fork, only main iModel Baseline is copied. Valid changesetIndex values are non-negative integers.
Name of the iModel that will be created. If name is not provided, main 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 iModel that will be created. If description is not provided, main iModel description will be used. Valid description values are non-empty strings that are not longer than 255 characters.
Option to control how Changesets are copied from the main iModel to the iModel fork. If set to true, Changesets will be copied individually and the history will be preserved. If set to false, Changesets will be squashed and applied to the Baseline resulting in an iModel fork without Changeset history. The default value is false.
Example
{ "iTwinId": "98418aa0-9059-458b-b9e4-245cf6131a55", "changesetIndex": 5 }
ForkiModel (ITwinIdOnly)
Id of the iTwin in which the new iModel will be created.
Id of the latest main iModel Changeset that should be copied to the iModel fork. Changeset can also be specified using an index, see changesetIndex property. If neither changesetId nor changesetIndex are provided, all existing main iModel Changesets are copied to the iModel fork. If "changesetId": "" is specified, no Changesets are copied to the iModel fork, only main iModel Baseline is copied.
Index of the latest main iModel Changeset that should be copied to the iModel fork. Changeset can also be specified using an id, see changesetId property. If neither changesetId nor changesetIndex are provided, all existing main iModel Changesets are copied to the iModel fork. If "changesetIndex": 0 is specified, no Changesets are copied to the iModel fork, only main iModel Baseline is copied. Valid changesetIndex values are non-negative integers.
Name of the iModel that will be created. If name is not provided, main 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 iModel that will be created. If description is not provided, main iModel description will be used. Valid description values are non-empty strings that are not longer than 255 characters.
Option to control how Changesets are copied from the main iModel to the iModel fork. If set to true, Changesets will be copied individually and the history will be preserved. If set to false, Changesets will be squashed and applied to the Baseline resulting in an iModel fork without Changeset history. The default value is false.
Example
{ "iTwinId": "98418aa0-9059-458b-b9e4-245cf6131a55" }
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 fork iModel.
{ "error": { "code": "InsufficientPermissions", "message": "The user has insufficient permissions for the requested operation." } }
Response 404 Not Found
Specified target iTwin, main iModel or main iModel 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 main 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 fork 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.
Fork iModel Request
Information that should be provided to start iModel fork creation.
Id of the iTwin in which the new iModel will be created.
Id of the latest main iModel Changeset that should be copied to the iModel fork. Changeset can also be specified using an index, see changesetIndex property. If neither changesetId nor changesetIndex are provided, all existing main iModel Changesets are copied to the iModel fork. If "changesetId": "" is specified, no Changesets are copied to the iModel fork, only main iModel Baseline is copied.
Index of the latest main iModel Changeset that should be copied to the iModel fork. Changeset can also be specified using an id, see changesetId property. If neither changesetId nor changesetIndex are provided, all existing main iModel Changesets are copied to the iModel fork. If "changesetIndex": 0 is specified, no Changesets are copied to the iModel fork, only main iModel Baseline is copied. Valid changesetIndex values are non-negative integers.
Name of the iModel that will be created. If name is not provided, main 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 iModel that will be created. If description is not provided, main iModel description will be used. Valid description values are non-empty strings that are not longer than 255 characters.
Option to control how Changesets are copied from the main iModel to the iModel fork. If set to true, Changesets will be copied individually and the history will be preserved. If set to false, Changesets will be squashed and applied to the Baseline resulting in an iModel fork without Changeset history. The default value is false.
{ "type": "object", "title": "Fork iModel Request", "description": "Information that should be provided to start iModel fork creation.", "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 main iModel Changeset that should be copied to the iModel fork. Changeset can also be specified using an index, see `changesetIndex` property. If neither `changesetId` nor `changesetIndex` are provided, all existing main iModel Changesets are copied to the iModel fork. If `\"changesetId\": \"\"` is specified, no Changesets are copied to the iModel fork, only main [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 main iModel Changeset that should be copied to the iModel fork. Changeset can also be specified using an id, see `changesetId` property. If neither `changesetId` nor `changesetIndex` are provided, all existing main iModel Changesets are copied to the iModel fork. If `\"changesetIndex\": 0` is specified, no Changesets are copied to the iModel fork, only main [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 iModel that will be created. If `name` is not provided, main 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 iModel that will be created. If `description` is not provided, main iModel description will be used. Valid `description` values are non-empty strings that are not longer than 255 characters.", "nullable": true }, "preserveHistory": { "type": "boolean", "description": "Option to control how Changesets are copied from the main iModel to the iModel fork. If set to `true`, Changesets will be copied individually and the history will be preserved. If set to `false`, Changesets will be squashed and applied to the Baseline resulting in an iModel fork without Changeset history. The default value is `false`.", "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?