openapi: 3.1.0
info:
  title: Siemens MindSphere Asset Management API
  description: >-
    The MindSphere Asset Management API enables creating and managing assets,
    defining aspect types and asset types, configuring data models, and handling
    connectivity for IoT devices. Supports hierarchical asset structures for
    digital twin modeling of industrial equipment.
  version: "3.0"
  contact:
    name: Siemens MindSphere Developer Support
    url: https://documentation.mindsphere.io/MindSphere/apis/advanced-assetmanagement/api-assetmanagement-overview.html
servers:
  - url: https://gateway.eu1.mindsphere.io/api/assetmanagement/v3
    description: MindSphere Asset Management EU1

security:
  - BearerAuth: []

tags:
  - name: Aspect Types
    description: Aspect type (data model template) management
  - name: Asset Types
    description: Asset type definition management
  - name: Assets
    description: Asset instance management
paths:
  /assets:
    get:
      operationId: listAssets
      summary: List all assets
      description: >-
        Returns a paginated list of assets visible to the tenant. Supports filtering
        by asset type, parent asset, and name.
      tags:
        - Assets
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 0
        - name: size
          in: query
          schema:
            type: integer
            default: 10
            maximum: 100
        - name: sort
          in: query
          schema:
            type: string
            example: "name,asc"
        - name: filter
          in: query
          description: JSON filter expression
          schema:
            type: string
      responses:
        '200':
          description: Paginated list of assets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetListResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden

    post:
      operationId: createAsset
      summary: Create a new asset
      description: Creates a new asset of a specified asset type.
      tags:
        - Assets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetCreate'
      responses:
        '201':
          description: Asset created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Asset with this name already exists under the parent

  /assets/{assetId}:
    get:
      operationId: getAsset
      summary: Retrieve an asset
      description: Returns detailed information for a specific asset.
      tags:
        - Assets
      parameters:
        - $ref: '#/components/parameters/AssetId'
      responses:
        '200':
          description: Asset details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '404':
          description: Asset not found

    patch:
      operationId: updateAsset
      summary: Update an asset
      description: Updates mutable properties of an asset such as name, description, and variables.
      tags:
        - Assets
      parameters:
        - $ref: '#/components/parameters/AssetId'
        - name: If-Match
          in: header
          required: true
          schema:
            type: string
          description: ETag for optimistic concurrency control
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetUpdate'
      responses:
        '200':
          description: Asset updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '409':
          description: Conflict — ETag mismatch

    delete:
      operationId: deleteAsset
      summary: Delete an asset
      description: Deletes an asset and all its child assets and associated time-series data.
      tags:
        - Assets
      parameters:
        - $ref: '#/components/parameters/AssetId'
        - name: If-Match
          in: header
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Asset deleted
        '404':
          description: Not found
        '409':
          description: Conflict

  /assettypes:
    get:
      operationId: listAssetTypes
      summary: List asset types
      description: Returns available asset type definitions.
      tags:
        - Asset Types
      parameters:
        - name: page
          in: query
          schema:
            type: integer
        - name: size
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: List of asset types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetTypeListResponse'

    post:
      operationId: createAssetType
      summary: Create an asset type
      description: Creates a new asset type with aspect associations and variable definitions.
      tags:
        - Asset Types
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetTypeCreate'
      responses:
        '201':
          description: Asset type created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetType'

  /assettypes/{id}:
    get:
      operationId: getAssetType
      summary: Retrieve an asset type
      description: Returns details for a specific asset type.
      tags:
        - Asset Types
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Asset type ID (tenant.name)
      responses:
        '200':
          description: Asset type details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetType'
        '404':
          description: Not found

  /aspecttypes:
    get:
      operationId: listAspectTypes
      summary: List aspect types
      description: Returns all aspect type definitions (data model templates).
      tags:
        - Aspect Types
      parameters:
        - name: page
          in: query
          schema:
            type: integer
        - name: size
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: List of aspect types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AspectTypeListResponse'

    post:
      operationId: createAspectType
      summary: Create an aspect type
      description: >-
        Creates a new aspect type defining a group of related variables for
        telemetry data. Variables are typed (DOUBLE, LONG, BOOLEAN, STRING, etc.)
        with optional units and default values.
      tags:
        - Aspect Types
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AspectTypeCreate'
      responses:
        '201':
          description: Aspect type created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AspectType'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  parameters:
    AssetId:
      name: assetId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Asset UUID

  schemas:
    Asset:
      type: object
      properties:
        assetId:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        typeId:
          type: string
          description: Asset type ID reference
        parentId:
          type: string
          format: uuid
          nullable: true
          description: Parent asset UUID (null for root)
        timezone:
          type: string
          description: IANA timezone identifier
          example: "Europe/Berlin"
        twinType:
          type: string
          enum: [performance, simulation, shop_floor]
        location:
          $ref: '#/components/schemas/Location'
        variables:
          type: array
          items:
            $ref: '#/components/schemas/VariableValue'
        aspects:
          type: array
          items:
            $ref: '#/components/schemas/AspectRef'
        etag:
          type: integer
          description: Optimistic locking version
        tenantId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    AssetCreate:
      type: object
      required:
        - name
        - typeId
      properties:
        name:
          type: string
          maxLength: 128
        externalId:
          type: string
          description: External identifier for the asset
        description:
          type: string
          maxLength: 2048
        typeId:
          type: string
        parentId:
          type: string
          format: uuid
        timezone:
          type: string
          default: "Europe/Berlin"
        twinType:
          type: string
          enum: [performance, simulation, shop_floor]
        location:
          $ref: '#/components/schemas/Location'
        variables:
          type: array
          items:
            $ref: '#/components/schemas/VariableValue'

    AssetUpdate:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        timezone:
          type: string
        location:
          $ref: '#/components/schemas/Location'
        variables:
          type: array
          items:
            $ref: '#/components/schemas/VariableValue'

    AssetListResponse:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            assets:
              type: array
              items:
                $ref: '#/components/schemas/Asset'
        page:
          $ref: '#/components/schemas/PageMetadata'
        _links:
          $ref: '#/components/schemas/HALLinks'

    AssetType:
      type: object
      properties:
        id:
          type: string
          description: Asset type identifier (tenant.name)
        name:
          type: string
        description:
          type: string
        parentTypeId:
          type: string
          description: Parent asset type for inheritance
        instantiable:
          type: boolean
          description: Whether assets can be directly instantiated from this type
        scope:
          type: string
          enum: [private, public]
        aspects:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              aspectTypeId:
                type: string
        variables:
          type: array
          items:
            $ref: '#/components/schemas/VariableDefinition'

    AssetTypeCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string
        parentTypeId:
          type: string
        instantiable:
          type: boolean
          default: true
        scope:
          type: string
          enum: [private, public]
        aspects:
          type: array
          items:
            type: object
            required:
              - name
              - aspectTypeId
            properties:
              name:
                type: string
              aspectTypeId:
                type: string
        variables:
          type: array
          items:
            $ref: '#/components/schemas/VariableDefinition'

    AssetTypeListResponse:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            assetTypes:
              type: array
              items:
                $ref: '#/components/schemas/AssetType'
        page:
          $ref: '#/components/schemas/PageMetadata'

    AspectType:
      type: object
      properties:
        id:
          type: string
          description: Aspect type identifier (tenant.name)
        name:
          type: string
        description:
          type: string
        category:
          type: string
          enum: [static, dynamic]
          description: static=configuration data, dynamic=time-series telemetry
        scope:
          type: string
          enum: [private, public]
        variables:
          type: array
          items:
            $ref: '#/components/schemas/VariableDefinition'

    AspectTypeCreate:
      type: object
      required:
        - name
        - category
        - variables
      properties:
        name:
          type: string
        description:
          type: string
        category:
          type: string
          enum: [static, dynamic]
        scope:
          type: string
          enum: [private, public]
          default: private
        variables:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/VariableDefinition'

    AspectTypeListResponse:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            aspectTypes:
              type: array
              items:
                $ref: '#/components/schemas/AspectType'
        page:
          $ref: '#/components/schemas/PageMetadata'

    VariableDefinition:
      type: object
      required:
        - name
        - dataType
      properties:
        name:
          type: string
        dataType:
          type: string
          enum: [BOOLEAN, INT, LONG, DOUBLE, STRING, BIG_STRING, TIMESTAMP]
        unit:
          type: string
          description: Unit of measurement (e.g., "°C", "bar", "rpm")
        searchable:
          type: boolean
          default: false
        length:
          type: integer
          description: Max length for STRING type
        defaultValue:
          description: Default value for the variable
          oneOf:
            - type: number
            - type: string
            - type: boolean
            - type: "null"
        qualityCode:
          type: boolean
          description: Whether OPC-UA quality codes are supported

    VariableValue:
      type: object
      required:
        - name
        - value
      properties:
        name:
          type: string
        value:
          oneOf:
            - type: number
            - type: string
            - type: boolean
            - type: "null"

    AspectRef:
      type: object
      properties:
        name:
          type: string
        aspectTypeId:
          type: string

    Location:
      type: object
      properties:
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code
        region:
          type: string
        locality:
          type: string
        streetAddress:
          type: string
        postalCode:
          type: string
        longitude:
          type: number
          minimum: -180
          maximum: 180
        latitude:
          type: number
          minimum: -90
          maximum: 90
        altitude:
          type: number
          description: Altitude in meters

    PageMetadata:
      type: object
      properties:
        size:
          type: integer
        totalElements:
          type: integer
        totalPages:
          type: integer
        number:
          type: integer

    HALLinks:
      type: object
      additionalProperties:
        type: object
        properties:
          href:
            type: string
            format: uri

    ErrorResponse:
      type: object
      properties:
        id:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              message:
                type: string