openapi: 3.1.0
info:
title: iTwin iModels API
description: >-
Create, clone, fork, and manage iModels — Bentley's specialized information containers
for the lifecycle of infrastructure assets. Operations cover iModel CRUD, changesets, named
versions, briefcases, locks, users, baselines, and thumbnails.
version: '2.0'
contact:
name: Bentley Developer Relations
url: https://developer.bentley.com/apis/imodels-v2/
license:
name: Bentley Developer Portal Terms
url: https://developer.bentley.com/legal/
servers:
- url: https://api.bentley.com/imodels
description: iTwin Platform Production
externalDocs:
description: iTwin iModels API Documentation
url: https://developer.bentley.com/apis/imodels-v2/
tags:
- name: iModels
description: Create, query, clone, fork, and delete iModels.
- name: Changesets
description: Manage changesets that record modifications to an iModel.
- name: Named Versions
description: Create and query named versions that pin a point in an iModel's history.
- name: Briefcases
description: Acquire and release briefcases for iModel authoring sessions.
- name: Locks
description: Acquire and release element-level locks during authoring.
- name: Users
description: Manage user access and statistics for iModels.
- name: Baselines
description: Manage iModel baseline files.
- name: Thumbnails
description: Retrieve iModel preview thumbnails.
security:
- OAuth2: []
paths:
/:
get:
tags: [iModels]
summary: Get iModels
operationId: GetIModels
parameters:
- name: iTwinId
in: query
required: true
schema: { type: string, format: uuid }
- name: $top
in: query
schema: { type: integer }
- name: $skip
in: query
schema: { type: integer }
responses:
'200':
description: List of iModels
content:
application/json:
schema:
$ref: '#/components/schemas/IModelList'
post:
tags: [iModels]
summary: Create iModel
operationId: CreateIModel
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateIModel'
responses:
'201':
description: iModel created
content:
application/json:
schema:
$ref: '#/components/schemas/IModel'
/{iModelId}:
parameters:
- name: iModelId
in: path
required: true
schema: { type: string, format: uuid }
get:
tags: [iModels]
summary: Get iModel
operationId: GetIModel
responses:
'200':
description: iModel details
content:
application/json:
schema:
$ref: '#/components/schemas/IModel'
patch:
tags: [iModels]
summary: Update iModel
operationId: UpdateIModel
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateIModel'
responses:
'200':
description: iModel updated
delete:
tags: [iModels]
summary: Delete iModel
operationId: DeleteIModel
responses:
'204':
description: iModel deleted
/{iModelId}/clone:
parameters:
- name: iModelId
in: path
required: true
schema: { type: string, format: uuid }
post:
tags: [iModels]
summary: Clone iModel
operationId: CloneIModel
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CloneIModel'
responses:
'202':
description: Clone job accepted
/{iModelId}/fork:
parameters:
- name: iModelId
in: path
required: true
schema: { type: string, format: uuid }
post:
tags: [iModels]
summary: Fork iModel
operationId: ForkIModel
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ForkIModel'
responses:
'202':
description: Fork job accepted
/{iModelId}/changesets:
parameters:
- name: iModelId
in: path
required: true
schema: { type: string, format: uuid }
get:
tags: [Changesets]
summary: Get Changesets
operationId: GetChangesets
responses:
'200':
description: List of changesets
content:
application/json:
schema:
$ref: '#/components/schemas/ChangesetList'
post:
tags: [Changesets]
summary: Create Changeset
operationId: CreateChangeset
responses:
'201':
description: Changeset created
/{iModelId}/changesets/{changesetId}:
parameters:
- name: iModelId
in: path
required: true
schema: { type: string, format: uuid }
- name: changesetId
in: path
required: true
schema: { type: string }
get:
tags: [Changesets]
summary: Get Changeset
operationId: GetChangeset
responses:
'200':
description: Changeset details
content:
application/json:
schema:
$ref: '#/components/schemas/Changeset'
/{iModelId}/namedversions:
parameters:
- name: iModelId
in: path
required: true
schema: { type: string, format: uuid }
get:
tags: [Named Versions]
summary: Get Named Versions
operationId: GetNamedVersions
responses:
'200':
description: List of named versions
content:
application/json:
schema:
$ref: '#/components/schemas/NamedVersionList'
post:
tags: [Named Versions]
summary: Create Named Version
operationId: CreateNamedVersion
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateNamedVersion'
responses:
'201':
description: Named version created
/{iModelId}/namedversions/{namedVersionId}:
parameters:
- name: iModelId
in: path
required: true
schema: { type: string, format: uuid }
- name: namedVersionId
in: path
required: true
schema: { type: string, format: uuid }
get:
tags: [Named Versions]
summary: Get Named Version
operationId: GetNamedVersion
responses:
'200':
description: Named version details
content:
application/json:
schema:
$ref: '#/components/schemas/NamedVersion'
/{iModelId}/briefcases:
parameters:
- name: iModelId
in: path
required: true
schema: { type: string, format: uuid }
get:
tags: [Briefcases]
summary: Get Briefcases
operationId: GetBriefcases
responses:
'200':
description: List of briefcases
post:
tags: [Briefcases]
summary: Acquire Briefcase
operationId: AcquireBriefcase
responses:
'201':
description: Briefcase acquired
/{iModelId}/locks:
parameters:
- name: iModelId
in: path
required: true
schema: { type: string, format: uuid }
get:
tags: [Locks]
summary: Get Locks
operationId: GetLocks
responses:
'200':
description: List of locks
patch:
tags: [Locks]
summary: Update Locks
operationId: UpdateLocks
responses:
'200':
description: Locks updated
/{iModelId}/users:
parameters:
- name: iModelId
in: path
required: true
schema: { type: string, format: uuid }
get:
tags: [Users]
summary: Get IModel Users
operationId: GetIModelUsers
responses:
'200':
description: List of users
/{iModelId}/users/{userId}:
parameters:
- name: iModelId
in: path
required: true
schema: { type: string, format: uuid }
- name: userId
in: path
required: true
schema: { type: string, format: uuid }
get:
tags: [Users]
summary: Get IModel User
operationId: GetIModelUser
responses:
'200':
description: User details
/{iModelId}/thumbnail:
parameters:
- name: iModelId
in: path
required: true
schema: { type: string, format: uuid }
get:
tags: [Thumbnails]
summary: Get Thumbnail
operationId: GetThumbnail
responses:
'200':
description: Thumbnail image
content:
image/png:
schema:
type: string
format: binary
/{iModelId}/baselinefile:
parameters:
- name: iModelId
in: path
required: true
schema: { type: string, format: uuid }
get:
tags: [Baselines]
summary: Get Baseline File
operationId: GetBaselineFile
responses:
'200':
description: Baseline file metadata and download URL
components:
securitySchemes:
OAuth2:
type: oauth2
description: iTwin Platform OAuth2 — Bentley IMS
flows:
authorizationCode:
authorizationUrl: https://ims.bentley.com/connect/authorize
tokenUrl: https://ims.bentley.com/connect/token
scopes:
itwin-platform: Full access to iTwin Platform APIs
schemas:
IModel:
type: object
properties:
id: { type: string, format: uuid }
displayName: { type: string }
name: { type: string }
description: { type: string }
state: { type: string, enum: [initialized, notInitialized] }
iTwinId: { type: string, format: uuid }
createdDateTime: { type: string, format: date-time }
creatorId: { type: string, format: uuid }
dataCenterLocation: { type: string }
IModelList:
type: object
properties:
iModels:
type: array
items: { $ref: '#/components/schemas/IModel' }
CreateIModel:
type: object
required: [iTwinId, name]
properties:
iTwinId: { type: string, format: uuid }
name: { type: string }
description: { type: string }
extent:
type: object
properties:
southWest:
type: object
properties:
latitude: { type: number }
longitude: { type: number }
northEast:
type: object
properties:
latitude: { type: number }
longitude: { type: number }
UpdateIModel:
type: object
properties:
name: { type: string }
description: { type: string }
CloneIModel:
type: object
required: [iTwinId, name]
properties:
iTwinId: { type: string, format: uuid }
name: { type: string }
changesetId: { type: string }
ForkIModel:
type: object
required: [iTwinId, name]
properties:
iTwinId: { type: string, format: uuid }
name: { type: string }
changesetId: { type: string }
Changeset:
type: object
properties:
id: { type: string }
displayName: { type: string }
description: { type: string }
index: { type: integer }
parentId: { type: string }
creatorId: { type: string, format: uuid }
pushDateTime: { type: string, format: date-time }
state: { type: string }
containingChanges: { type: integer }
fileSize: { type: integer, format: int64 }
briefcaseId: { type: integer }
ChangesetList:
type: object
properties:
changesets:
type: array
items: { $ref: '#/components/schemas/Changeset' }
NamedVersion:
type: object
properties:
id: { type: string, format: uuid }
displayName: { type: string }
name: { type: string }
description: { type: string }
changesetId: { type: string }
changesetIndex: { type: integer }
createdDateTime: { type: string, format: date-time }
state: { type: string, enum: [visible, hidden] }
NamedVersionList:
type: object
properties:
namedVersions:
type: array
items: { $ref: '#/components/schemas/NamedVersion' }
CreateNamedVersion:
type: object
required: [name, changesetId]
properties:
name: { type: string }
description: { type: string }
changesetId: { type: string }
Error:
type: object
properties:
error:
type: object
properties:
code: { type: string }
message: { type: string }
details:
type: array
items:
type: object
properties:
code: { type: string }
message: { type: string }
target: { type: string }