openapi: 3.0.3

info:
  title: AI Asset Manager API
  version: v3
  license: {name: Copyright 2025 Siemens AG. All Rights Reserved. Confidential.}

servers:
- url: /api/v3
- url: /mlmanager/api/v3
- url: /assetmanager/api/v3

security:
- AccessToken: []

components:

  securitySchemes:
    AccessToken: {type: apiKey, in: cookie, name: authToken}

  responses:
    BadRequest:
      description: Required parameters missing or invalid request body.
      content:
        application/json: {schema: {$ref: "#/components/schemas/Error"}}
    Unauthorized:
      description: Access token is missing or invalid.
      content:
        application/json: {schema: {$ref: "#/components/schemas/Error"}}
    Forbidden:
      description: Access to the requested resource is forbidden.
      content:
        application/json: {schema: {$ref: "#/components/schemas/Error"}}
    InternalServerError:
      description: Unexpected error. Please retry later.
      content:
        application/json: {schema: {$ref: "#/components/schemas/Error"}}

  schemas:

    AppInfo:
      type: object
      properties:
        appVersion: {type: string, description: Application version}

    UserInfo:
      type: object
      properties:
        mail: {type: string, description: E-mail}
        role: {type: string, description: Role}
        capabilities: {type: array, items: {type: string}}

    DeviceInfo:
      type: object
      properties:
       id:         {type: string,  description: Device ID}
       name:       {type: string,  description: Device Name}
       status:     {type: string,  description: Status}
       lastOnline: {type: integer, description: Timestamp when the device was last seen online}

    DeviceDetails:
      type: object
      properties:
        id:     {type: string, description: Device ID}
        stats:  {type: object, description: Device Statistics}
        apps:   {type: array, items: {type: object}, description: Installed applications}
        errors: {type: array, items: {type: string}, description: List of errors encountered while collecting information}

    Deployment:
      type: object
      properties:
        pkgId:     {type: string, description: Package ID}
        devId:     {type: string, description: Device ID}
        appId:     {type: string, description: Application ID}
        status:    {type: string, description: Deployment status}
        message:   {type: string, description: Deployment message}
        createdAt: {type: string, description: Creation timestamp}
        updatedAt: {type: string, description: Update timestamp}
        createdBy: {type: string, description: User who created the deployment}
        updatedBy: {type: string, description: User who updated the deployment}

    AIISDetails:
      type: object
      properties:
        status:    {type: string                                                    , description: Status    }
        info:      {$ref: "#/components/schemas/AIISBuildInfo"                      , description: Info      }
        pipelines: {type: array, items: {$ref: "#/components/schemas/AIISPipeline"} , description: Pipelines }
        errors:    {type: array, items: {type: string}                              , description: Errors    }

    AIISBuildInfo:
      type: object
      properties:
        production:                   {type: string                      , description: Production     }
        version:                      {type: string                      , description: Version        }
        apiVersion:                   {type: string                      , description: ApiVersion     }
        isGPUEnabledApp:              {type: boolean                     , description: GPUEnabled     }
        maxNumberOfDeployedPipelines: {type: integer                     , description: MaxPipelines   }
        pythonVersions:               {type: array, items: {type: string}, description: PythonVersions }

    AIISPipeline:
      type: object
      properties:
        id:          {type: string , description:  ID       }
        name:        {type: string , description:  Name     }
        description: {type: string , description:  Desc     }
        packageId:   {type: string , description:  PackageID}
        version:     {type: string , description:  Version  }
        status:      {type: string , description:  Status   }
        isActive:    {type: boolean, description:  IsActive }

    CmdCreateDeployment:
      type: object
      required: [pkgId, devId, appId]
      properties:
        pkgId: {type: string, description: Package ID}
        devId: {type: string, description: Device ID}
        appId: {type: string, description: Application ID}
        variables:
          type: array
          items: {$ref: "#/components/schemas/PatchVariable"}
          description: Variables to be patched

    CmdPkgVariables:
      type: object
      properties:
        variables:
          type: array
          items: {$ref: "#/components/schemas/PackageVariable"}
          description: List of package variables to be mapped

    CmdMapVariables:
      type: object
      properties:
        variables:
          type: array
          items: {$ref: "#/components/schemas/MappableVariable"}
          description: List of mappable variables to be patched

    PackageVariable:
      type: object
      properties:
        name:     {type: string, description: Name}
        type:     {type: string, description: Type}
        isInput:  {type: boolean, description: Whether variable is input}
        isMetric: {type: boolean, description: Whether variable is metric}

    MappableVariable:
      type: object
      properties:
        name:           {type: string, description: Name}
        type:           {type: string, description: Type}
        topic:          {type: string, description: Topic}
        topicName:      {type: string, description: Topic Name}
        componentName:  {type: string, description: Component Name}
        connector:
          type: object
          properties:
            name:     {type: string, description: Connector name}
            type:     {type: string, description: Connector type}
            dataType: {type: string, description: Connector data type}

    PatchVariable:
      type: object
      properties:
        id:           {type: string, description: ID}
        topicName:    {type: string, description: Topic name}
        topic:        {type: string, description: Topic}
        connectorId:  {type: string, description: Connector ID}

    Error:
      type: object
      properties:
        error: {type: string, description: Error message}

tags:
- {name: Info, description: User and app information}
- {name: Devices, description: Device management}
- {name: Packages, description: Package management}
- {name: Edge Apps, description: Edge App management}

paths:

  /app-info:

    get:
      tags: [Info]
      summary: Get app information.
      operationId: AppInfo
      description: |
        **Authorized roles:** `Admin`, `AppAdmin`, `Operator`, `Viewer`

        Returns information about the application.
      responses:
        "200":
          description: Application info
          content:
            application/json: {schema: {$ref: "#/components/schemas/AppInfo"}}
        "400": {$ref: "#/components/responses/BadRequest"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "403": {$ref: "#/components/responses/Forbidden"}
        "500": {$ref: "#/components/responses/InternalServerError"}

  /user-info:

    get:
      tags: [Info]
      summary: Get user information.
      operationId: UserInfo
      description: |
        **Authorized roles:** `Admin`, `AppAdmin`, `Operator`, `Viewer`

        Returns information about the requesting user.
      responses:
        "200":
          description: User info
          content:
            application/json: {schema: {$ref: "#/components/schemas/UserInfo"}}
        "400": {$ref: "#/components/responses/BadRequest"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "403": {$ref: "#/components/responses/Forbidden"}
        "500": {$ref: "#/components/responses/InternalServerError"}

  /devices:

    get:
      tags: [Devices]
      summary: Get the list of Devices
      operationId: ListDevices
      description: |
        **Authorized roles:** `Admin`, `AppAdmin`, `Operator`, `Viewer`

        Returns the list of devices
      responses:
        "200":
          description: List of devices
          content:
            application/json: {schema: {type: array, items: {$ref: "#/components/schemas/DeviceInfo"}}}
        "400": {$ref: "#/components/responses/BadRequest"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "403": {$ref: "#/components/responses/Forbidden"}
        "500": {$ref: "#/components/responses/InternalServerError"}

  /deployments:

    get:
      tags: [Packages]
      summary: Get the list of Deployments
      operationId: ListDeployments
      description: |
        **Authorized roles:** `Admin`, `AppAdmin`, `Operator`, `Viewer`

        Returns the list of deployments with optional filtering
      parameters:
      - {in: query, schema: {type: string}, name: devId, description: Filter by device ID}
      - {in: query, schema: {type: string}, name: appId, description: Filter by application ID}
      - {in: query, schema: {type: string}, name: pkgId, description: Filter by package ID}
      responses:
        "200":
          description: List of deployments
          content:
            application/json: {schema: {type: array, items: {$ref: "#/components/schemas/Deployment" }}}
        "400": {$ref: "#/components/responses/BadRequest"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "403": {$ref: "#/components/responses/Forbidden"}
        "500": {$ref: "#/components/responses/InternalServerError"}

    post:
      tags: [Packages]
      summary: () Create a new deployment
      operationId: CreateDeployment
      description: |
        **Authorized roles:** `Admin`, `AppAdmin`, `Operator`

        Create a new deployment
      requestBody:
        required: true
        description: Specifies what package to deploy to which target.
        content:
          applicaiton/json: {schema: {$ref: "#/components/schemas/CmdCreateDeployment"}}
      responses:
        "201":
          description: Deployment created successfully
          content:
            application/json: {schema: {$ref: "#/components/schemas/Deployment"}}
        "400": {$ref: "#/components/responses/BadRequest"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "403": {$ref: "#/components/responses/Forbidden"}
        "500": {$ref: "#/components/responses/InternalServerError"}

  /packages/{id}/variables:

    get:
      summary: Get package variables
      operationId: GetPackageVariables
      description: |
        **Authorized roles:** `Admin`, `AppAdmin`, `Operator`, `Viewer`

        Return the lists of variables for the specified package
      tags: [Packages]
      parameters:
      - {in: path, required: true, name: id, description: Package ID, schema: {type: string}}
      responses:
        "200":
          description: Package variables
          content:
            application/json: {schema: {type: array, items: {$ref: "#/components/schemas/PackageVariable"}}}
        "400": {$ref: "#/components/responses/BadRequest"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "403": {$ref: "#/components/responses/Forbidden"}
        "500": {$ref: "#/components/responses/InternalServerError"}

  /agents/pkg-variables:

    post:
      tags: [Packages]
      summary: Get agent package variables
      operationId: PostAgentPkgVariables
      description: |
        **Authorized roles:** `Admin`, `AppAdmin`, `Operator`, `Viewer`

        Obtains the mappable variables for a list of package variables
      parameters:
      - {in: query, required: true, name: devId,      description: Device ID,      schema: {type: string}}
      - {in: query, required: true, name: appId,      description: Application ID, schema: {type: string}}
      - {in: query, required: true, name: pipelineId, description: Pipeline ID,    schema: {type: string}}
      requestBody:
        required: true
        description: Package variables that need to be mapped.
        content:
          application/json: {schema: {$ref: "#/components/schemas/CmdPkgVariables"}}
      responses:
        "200":
          description: Mappable variables
          content:
            application/json: {schema: {type: array, items: {$ref: "#/components/schemas/MappableVariable"}}}
        "400": {$ref: "#/components/responses/BadRequest"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "403": {$ref: "#/components/responses/Forbidden"}
        "500": {$ref: "#/components/responses/InternalServerError"}

  /agents/map-variables:

    post:
      summary: Map agent variables
      operationId: PostAgentMapVariables
      description:  |
        **Authorized roles:** `Admin`, `AppAdmin`, `Operator`, `Viewer`

        Obtains the patch variables for a list of mappable variables
      tags: [Packages]
      parameters:
      - {in: query, required: true, name: devId, description: Device ID,      schema: {type: string}}
      - {in: query, required: true, name: appId, description: Application ID, schema: {type: string}}
      requestBody:
        required: true
        description: Mappable variables.
        content:
          application/json: {schema: {$ref: "#/components/schemas/CmdMapVariables"}}
      responses:
        "200":
          description: Patch variables
          content:
            application/json: {schema: {type: array, items: {$ref: "#/components/schemas/PatchVariable"}}}
        "400": {$ref: "#/components/responses/BadRequest"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "403": {$ref: "#/components/responses/Forbidden"}
        "500": {$ref: "#/components/responses/InternalServerError"}

  /apps/{devId}/{appId}/aiis:

    get:
      tags: [Edge Apps]
      summary: Get AI Inference Server Information and Status
      operationId: GetEdgeApp
      description: |
        **Authorized roles:** `Admin`, `AppAdmin`, `Operator`, `Viewer`

        Returns information about an AI Inference Server app running on the specified device.
      parameters:
      - {in: path, required: true, name: devId, description: Device ID, schema: {type: string}}
      - {in: path, required: true, name: appId, description: Application ID, schema: {type: string}}
      responses:
        "200":
          description: AI Inference Server details
          content:
            application/json: {schema: {$ref: "#/components/schemas/AIISDetails"}}
        "400": {$ref: "#/components/responses/BadRequest"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "403": {$ref: "#/components/responses/Forbidden"}
        "500": {$ref: "#/components/responses/InternalServerError"}