openapi: 3.0.3
info:
  title: DotAAS Part 2 | HTTP/REST | Discovery Service Specification
  description: >-
    The entire Full Profile of the Discovery Service Specification as part of the [Specification of the Asset Administration Shell - Part 2: API](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/DiscoveryServiceSpecification/SSP-001
servers:
- url: 'https://admin-shell.io/api/v3/'
- url: 'https://example.com/'

paths:
  /lookup/shells:
    get:
      deprecated: true
      tags:
        - Asset Administration Shell Basic Discovery API
      summary: Returns a list of Asset Administration Shell IDs linked to specific asset identifiers or the global asset ID
      operationId: GetAllAssetAdministrationShellIdsByAssetLink
      x-semanticIds:
        - https://admin-shell.io/aas/API/GetAllAssetAdministrationShellIdsByAssetLink/3/2
      parameters:
        - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/AssetIds'
        - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/Limit'
        - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/Cursor'
      responses:
        '200':
          description: Requested Asset Administration Shell IDs
          content:
            application/json:
              schema:
                allOf:
                - $ref: '../Part2-API-Schemas/openapi.yaml#/components/schemas/PagedResult'
                - type: object
                  properties:
                    result:
                      type: array
                      items:
                        type: string
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
  /lookup/shellsByAssetLink:
    post:
      tags:
        - Asset Administration Shell Basic Discovery API
      summary: Returns a list of Asset Administration Shell IDs linked to specific asset identifiers or the global asset ID
      operationId: SearchAllAssetAdministrationShellIdsByAssetLink
      x-semanticIds:
        - https://admin-shell.io/aas/API/SearchAllAssetAdministrationShellIdsByAssetLink/3/2
      parameters:
        - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/Limit'
        - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/Cursor'
      requestBody:
        description: A list of specific asset identifiers. Search for the global asset ID is supported by setting "name"  to "globalAssetId" (see Constraint AASd-116).
        content:
          application/json:
            schema:
              type: array
              items:
                '$ref': '../Part2-API-Schemas/openapi.yaml#/components/schemas/AssetLink'
      responses:
        '200':
          description: Requested Asset Administration Shell IDs
          content:
            application/json:
              schema:
                allOf:
                - $ref: '../Part2-API-Schemas/openapi.yaml#/components/schemas/PagedResult'
                - type: object
                  properties:
                    result:
                      type: array
                      items:
                        type: string
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'

  /lookup/shells/{aasIdentifier}:
    parameters:
      - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/AssetAdministrationShellIdentifier'
    get:
      tags:
        - Asset Administration Shell Basic Discovery API
      summary: Returns a list of specific asset identifiers based on an Asset Administration Shell ID to edit discoverable content. The global asset ID is returned as specific asset ID with "name" equal to "globalAssetId" (see Constraint AASd-116).
      operationId: GetAllAssetLinksById
      x-semanticIds:
        - https://admin-shell.io/aas/API/GetAllAssetLinksById/3/2
      responses:
        '200':
          description: Requested specific Asset identifiers (including the global asset ID represented by a specific asset ID)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '../Part1-MetaModel-Schemas/openapi.yaml#/components/schemas/SpecificAssetId'
        '404':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/not-found'
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
    post:
      tags:
        - Asset Administration Shell Basic Discovery API
      summary: Creates or replaces all asset links associated to the Asset Administration Shell.
      operationId: PostAllAssetLinksById
      x-semanticIds:
        - https://admin-shell.io/aas/API/PostAllAssetLinksById/3/2
      requestBody:
        description: A set of specific asset identifiers
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '../Part1-MetaModel-Schemas/openapi.yaml#/components/schemas/SpecificAssetId'
        required: true
      responses:
        '201':
          description: Specific asset identifiers created successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '../Part1-MetaModel-Schemas/openapi.yaml#/components/schemas/SpecificAssetId'
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
    delete:
      tags:
        - Asset Administration Shell Basic Discovery API
      summary: "Deletes specified specific asset identifiers linked to an Asset Administration Shell: discovery via these specific asset IDs shall not be supported any longer"
      operationId: DeleteAllAssetLinksById
      x-semanticIds:
        - https://admin-shell.io/aas/API/DeleteAllAssetLinksById/3/2
      responses:
        '204':
          description: Specific asset identifiers deleted successfully
        '404':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/not-found'
        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'
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'