openapi: 3.1.0
info:
  title: AspenTech Inmation Web API
  description: >-
    The AspenTech Inmation Web API provides HTTP and WebSocket interfaces for external
    applications to interact with the AspenTech Inmation industrial IoT and time-series
    data platform. RPC-based REST APIs enable access to process data, system services,
    and automation functions for manufacturing and energy operations.
  version: 1.108.0
  contact:
    name: AspenTech Support
    url: https://atdocs.inmation.com/api/1.108/webapi/index.html

servers:
  - url: http://{hostname}:8002
    description: Inmation Web API server
    variables:
      hostname:
        default: localhost
        description: Inmation server hostname or IP address

security:
  - basicAuth: []
  - bearerToken: []

tags:
  - name: Data
    description: Read and write process data points
  - name: Historical
    description: Historical time-series data access

  - name: Items
    description: Configuration item management
  - name: System
    description: System information and health
paths:
  /api:
    post:
      operationId: executeRpcCall
      summary: Execute RPC call
      description: >-
        Execute an Inmation RPC (Remote Procedure Call) operation. The Inmation Web API
        uses a unified POST endpoint with JSON-RPC-style requests to perform data reads,
        writes, and system operations.
      tags: [Data]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RpcRequest'
            examples:
              readData:
                summary: Read current value of a data item
                value:
                  jsonrpc: "2.0"
                  method: "data.read"
                  params:
                    paths:
                      - "/System/Core/Tag1"
                  id: 1
              writeData:
                summary: Write value to a data item
                value:
                  jsonrpc: "2.0"
                  method: "data.write"
                  params:
                    items:
                      - path: "/System/Core/Tag1"
                        value: 42.5
                  id: 2
      responses:
        '200':
          description: RPC response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RpcResponse'
        '400':
          description: Invalid RPC request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RpcErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/data/read:
    post:
      operationId: readDataItems
      summary: Read current process data values
      description: Read the current value of one or more process data items (tags) by path.
      tags: [Data]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [paths]
              properties:
                paths:
                  type: array
                  description: List of item paths to read
                  items:
                    type: string
                  example: ["/System/Core/Temperature", "/System/Core/Pressure"]
      responses:
        '200':
          description: Data values for requested items
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/DataItem'

  /api/data/write:
    post:
      operationId: writeDataItems
      summary: Write process data values
      description: Write values to one or more process data items (tags) by path.
      tags: [Data]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [items]
              properties:
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/DataWriteRequest'
      responses:
        '200':
          description: Write result
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/WriteResult'

  /api/data/readhistory:
    post:
      operationId: readHistoricalData
      summary: Read historical time-series data
      description: >-
        Retrieve historical time-series data for one or more process items within
        a specified time range. Supports raw, interpolated, and aggregated retrieval modes.
      tags: [Historical]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [paths, startTime, endTime]
              properties:
                paths:
                  type: array
                  items:
                    type: string
                startTime:
                  type: string
                  format: date-time
                  description: Start of historical range (ISO 8601)
                endTime:
                  type: string
                  format: date-time
                  description: End of historical range (ISO 8601)
                retrievalMode:
                  type: string
                  enum: [Raw, Interpolated, Average, Minimum, Maximum, Count]
                  default: Raw
                numberOfIntervals:
                  type: integer
                  description: Number of intervals for aggregated retrieval
      responses:
        '200':
          description: Historical data values
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/HistoricalDataResult'

  /api/sys/info:
    get:
      operationId: getSystemInfo
      summary: Get system information
      description: Retrieve Inmation system information including version, license, and server status.
      tags: [System]
      responses:
        '200':
          description: System information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemInfo'

  /api/item/get:
    post:
      operationId: getConfigurationItem
      summary: Get configuration item
      description: Retrieve configuration and properties for an Inmation system item by path.
      tags: [Items]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [path]
              properties:
                path:
                  type: string
                  description: Full path to the item (e.g., /System/Core/MyFolder/MyItem)
      responses:
        '200':
          description: Item configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigurationItem'

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    bearerToken:
      type: http
      scheme: bearer

  responses:
    Unauthorized:
      description: Unauthorized - invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    RpcRequest:
      type: object
      required: [jsonrpc, method, id]
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
        method:
          type: string
          description: RPC method name (e.g., data.read, data.write, sys.info)
        params:
          type: object
          additionalProperties: true
        id:
          oneOf:
            - type: integer
            - type: string

    RpcResponse:
      type: object
      properties:
        jsonrpc:
          type: string
        result:
          description: Response result (type varies by method)
        id:
          oneOf:
            - type: integer
            - type: string

    RpcErrorResponse:
      type: object
      properties:
        jsonrpc:
          type: string
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
            data:
              type: object
        id:
          oneOf:
            - type: integer
            - type: string

    DataItem:
      type: object
      description: Current value of a process data item
      properties:
        path:
          type: string
          description: Full item path
        value:
          description: Current process value (numeric, string, or boolean)
        quality:
          type: integer
          description: OPC quality code (192 = Good, 0 = Bad)
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the current value
        error:
          type: string
          description: Error message if item could not be read

    DataWriteRequest:
      type: object
      required: [path, value]
      properties:
        path:
          type: string
        value:
          description: Value to write (numeric, string, or boolean)
        timestamp:
          type: string
          format: date-time

    WriteResult:
      type: object
      properties:
        path:
          type: string
        success:
          type: boolean
        error:
          type: string

    HistoricalDataResult:
      type: object
      properties:
        path:
          type: string
        values:
          type: array
          items:
            type: object
            properties:
              value:
                description: Historical value
              quality:
                type: integer
              timestamp:
                type: string
                format: date-time

    SystemInfo:
      type: object
      properties:
        version:
          type: string
        serverName:
          type: string
        serverTime:
          type: string
          format: date-time
        licenseStatus:
          type: string
          enum: [Valid, Expired, Trial]
        uptime:
          type: integer
          description: Server uptime in seconds

    ConfigurationItem:
      type: object
      properties:
        path:
          type: string
        itemType:
          type: string
        name:
          type: string
        description:
          type: string
        properties:
          type: object
          additionalProperties: true

    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string