openapi: 3.1.0
info:
  title: Siemens MindSphere Asset Management Aspect Types Timeseries 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: Timeseries
  description: Time-series data read and write operations
paths:
  /timeseries:
    put:
      operationId: putMultipleTimeseries
      summary: Ingest time-series data for multiple assets/aspects
      description: Creates or updates time-series data for multiple asset-aspect combinations in a single request. Each entry specifies an assetId, aspectName, and array of timestamped data points.
      tags:
      - Timeseries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/TimeseriesInput'
      responses:
        '204':
          description: Data ingested successfully (no content)
        '400':
          description: Validation error in request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — insufficient scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /timeseries/{assetId}/{aspectName}:
    put:
      operationId: putTimeseries
      summary: Ingest time-series data for a single asset aspect
      description: Creates or updates time-series data for a specific asset and aspect. Each data point must include a _time field (ISO 8601 UTC) and values for aspect variables.
      tags:
      - Timeseries
      parameters:
      - $ref: '#/components/parameters/AssetId'
      - $ref: '#/components/parameters/AspectName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/TimeseriesDataPoint'
      responses:
        '204':
          description: Data ingested successfully
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Asset or aspect not found
    get:
      operationId: getTimeseries
      summary: Query time-series data for an asset aspect
      description: Retrieves time-series data for a specific asset and aspect within a time range. Supports time range queries, field selection, and result limiting. Data is returned ordered by timestamp ascending.
      tags:
      - Timeseries
      parameters:
      - $ref: '#/components/parameters/AssetId'
      - $ref: '#/components/parameters/AspectName'
      - name: from
        in: query
        required: true
        description: Start of time range (ISO 8601 UTC)
        schema:
          type: string
          format: date-time
        example: '2026-01-01T00:00:00Z'
      - name: to
        in: query
        required: true
        description: End of time range (ISO 8601 UTC)
        schema:
          type: string
          format: date-time
        example: '2026-01-01T01:00:00Z'
      - name: limit
        in: query
        required: false
        description: Maximum number of data points to return (max 2000)
        schema:
          type: integer
          default: 2000
          maximum: 2000
      - name: select
        in: query
        required: false
        description: Comma-separated list of variable names to include
        schema:
          type: string
        example: temperature,pressure
      - name: sort
        in: query
        required: false
        description: Sort order by _time
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      - name: latestValue
        in: query
        required: false
        description: Return only the most recent data point
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Time-series data points
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TimeseriesDataPoint'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '404':
          description: Asset or aspect not found
    delete:
      operationId: deleteTimeseries
      summary: Delete time-series data for an asset aspect
      description: Deletes all time-series data within an hourly-aligned time range for a specific asset and aspect. The time range must align to UTC hour boundaries.
      tags:
      - Timeseries
      parameters:
      - $ref: '#/components/parameters/AssetId'
      - $ref: '#/components/parameters/AspectName'
      - name: from
        in: query
        required: true
        description: Start of hourly-aligned range (ISO 8601 UTC)
        schema:
          type: string
          format: date-time
        example: '2026-01-01T00:00:00Z'
      - name: to
        in: query
        required: true
        description: End of hourly-aligned range (ISO 8601 UTC)
        schema:
          type: string
          format: date-time
        example: '2026-01-01T01:00:00Z'
      responses:
        '204':
          description: Data deleted successfully
        '400':
          description: Invalid time range (not hour-aligned or invalid format)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
components:
  schemas:
    TimeseriesDataPoint:
      type: object
      required:
      - _time
      properties:
        _time:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp for the data point
          example: '2026-01-01T00:00:00.000Z'
      additionalProperties:
        description: Variable values keyed by variable name. Variable types are defined in the aspect configuration (DOUBLE, LONG, BOOLEAN, STRING, BIG_STRING, INT, TIMESTAMP).
        oneOf:
        - type: number
        - type: boolean
        - type: string
        - type: 'null'
    TimeseriesInput:
      type: object
      required:
      - assetId
      - aspectName
      - data
      properties:
        assetId:
          type: string
          format: uuid
        aspectName:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/TimeseriesDataPoint'
    ErrorResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique error identifier
        message:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              message:
                type: string
  parameters:
    AssetId:
      name: assetId
      in: path
      required: true
      description: Unique MindSphere asset identifier (UUID)
      schema:
        type: string
        format: uuid
      example: 5d7e59d0-8c94-4bce-8a0c-3a7fcc9a1234
    AspectName:
      name: aspectName
      in: path
      required: true
      description: Aspect name (must match asset type aspect configuration)
      schema:
        type: string
      example: EnvironmentData
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT