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 }