openapi: 3.0.3
info:
  title: DotAAS Part 2 | HTTP/REST | AASX File Server Service Specification
  description: >-
    The File Server Service Specification as part of the [Specification of the Asset Administration Shell: Part 2](https://industrialdigitaltwin.org/en/content-hub/aasspecifications).

    Copyright: Industrial Digital Twin Association (IDTA) 2025
  contact:
    name: Industrial Digital Twin Association (IDTA)
    email: info@idtwin.org
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  version: V3.2.0_SSP-001
  x-profile-identifier: https://admin-shell.io/aas/API/3/2/AasxFileServerServiceSpecification/SSP-001
  termsOfService: https://github.com/admin-shell-io/aas-specs-metamodel
servers:
- url: 'https://admin-shell.io/api/v3'
- url: 'https://example.com/'
paths:
  /packages:
    get:
      tags:
        - AASX File Server API
      summary: Returns a list of available AASX packages at the server
      operationId: GetAllAASXPackageIds
      x-semanticIds:
        - https://admin-shell.io/aas/API/GetAllAASXPackageIds/3/2
      parameters:
        - name: aasId
          in: query
          description: The Asset Administration Shell’s unique id (UTF8-BASE64-URL-encoded)
          required: false
          style: form
          explode: true
          schema:
            type: string
        - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/Limit'
        - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/Cursor'
      responses:
        '200':
          description: Requested package list
          content:
            application/json:
              schema:
                $ref: '../Part2-API-Schemas/openapi.yaml#/components/schemas/GetPackageDescriptionsResult'
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        '401':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/unauthorized'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'
        '500':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/internal-server-error'
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
    post:
      tags:
        - AASX File Server API
      summary: Stores the AASX package at the server
      operationId: PostAASXPackage
      x-semanticIds:
        - https://admin-shell.io/aas/API/PostAASXPackage/3/2
      requestBody:
        description: AASX package
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                aasIds:
                  type: array
                  items:
                    type: string
                file:
                  type: string
                  format: binary
                fileName:
                  type: string
            encoding:
              file:
                contentType: application/asset-administration-shell-package
        required: true
      responses:
        '201':
          description: AASX package stored successfully
          headers:
            Location:
              description: URL of the newly created resource
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '../Part2-API-Schemas/openapi.yaml#/components/schemas/PackageDescription'
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        '401':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/unauthorized'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'
        '409':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/conflict'
        '500':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/internal-server-error'
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
  /packages/{packageId}:
    parameters:
      - name: packageId
        in: path
        description: The package Id (UTF8-BASE64-URL-encoded)
        required: true
        style: simple
        explode: true
        schema:
          type: string
    get:
      tags:
        - AASX File Server API
      summary: Returns a specific AASX package from the server
      operationId: GetAASXByPackageId
      x-semanticIds:
        - https://admin-shell.io/aas/API/GetAASXByPackageId/3/2
      responses:
        '200':
          description: Requested AASX package
          headers:
            X-FileName:
              schema:
                type: string
              description: Filename of the package
          content:
            application/asset-administration-shell-package:
              schema:
                type: string
                format: binary
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        '401':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/unauthorized'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'
        '404':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/not-found'
        '500':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/internal-server-error'
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
    put:
      tags:
        - AASX File Server API
      summary: Creates or updates the AASX package at the server
      operationId: PutAASXByPackageId
      x-semanticIds:
        - https://admin-shell.io/aas/API/PutAASXByPackageId/3/2
      requestBody:
        description: AASX package
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                aasIds:
                  type: array
                  items:
                    type: string
                file:
                  type: string
                  format: binary
                fileName:
                  type: string
            encoding:
              file:
                contentType: application/asset-administration-shell-package
        required: true
      responses:
        '201':
          description: AASX package stored successfully
          headers:
            Location:
              description: URL of the newly created resource
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '../Part2-API-Schemas/openapi.yaml#/components/schemas/PackageDescription'
        '204':
          description: AASX package updated successfully
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        '401':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/unauthorized'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'
        '500':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/internal-server-error'
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
    delete:
      tags:
        - AASX File Server API
      summary: Deletes a specific AASX package from the server
      operationId: DeleteAASXByPackageId
      x-semanticIds:
        - https://admin-shell.io/aas/API/DeleteAASXByPackageId/3/2
      responses:
        '204':
          description: Deleted successfully
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        '401':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/unauthorized'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'
        '404':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/not-found'
        '500':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/internal-server-error'
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
  /description:
    get:
      tags:
        - Description API
      summary: Returns the self-describing information of a network resource (ServiceDescription)
      operationId: GetSelfDescription
      x-semanticIds:
        - https://admin-shell.io/aas/API/GetSelfDescription/3/2
      responses:
        '200':
          description: Requested Description
          content:
            application/json:
              schema:
                $ref: '../Part2-API-Schemas/openapi.yaml#/components/schemas/ServiceDescription'
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'
        '404':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/not-found'
        '500':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/internal-server-error'
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'