openapi: 3.1.0
info:
  title: Idp core API
  description: API dedicated to idp core functionalities
  version: v1
servers:
  - url: http://localhost:8084
security:
  - clientId: []
  - bearer: []
tags:
  - name: Entity Graph
    description: Entity relationship graph operations
  - name: Inbound Webhook Management
    description: Operations for managing inbound webhook connector configurations
  - name: Entities Management
    description: Operations related to entity management
  - name: Audit
    description: Operations related to audit history
  - name: Entities Templates Management
    description: Operations related to entity template management
  - name: Entity dynamic mapping
    description: Operations related to entity dynamic mapping management
paths:
  /api/v1/inbound_webhooks/{identifier}:
    get:
      tags:
        - Inbound Webhook Management
      summary: Get a webhook connector by identifier
      description: Retrieve a specific webhook connector using its string identifier
      operationId: getWebhookConnectorByIdentifier
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Webhook connector found
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/InboundWebhookDtoOut"
        "404":
          description: Webhook connector not found with the provided identifier
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    put:
      tags:
        - Inbound Webhook Management
      summary: Update an existing webhook connector by identifier
      description: Update the details of an existing webhook connector identified by
        its unique string identifier
      operationId: putWebhookConnector
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InboundWebhookUpdateDtoIn"
        required: true
      responses:
        "200":
          description: Webhook connector updated successfully
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/InboundWebhookDtoOut"
        "400":
          description: Invalid request payload
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Webhook connector not found with the provided identifier
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: Webhook connector name already exists
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    delete:
      tags:
        - Inbound Webhook Management
      summary: Delete a webhook connector by identifier
      description: Remove a webhook connector from the system using its unique identifier
      operationId: deleteWebhookConnector
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Webhook connector deleted successfully
        "404":
          description: Webhook connector not found with the provided identifier
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/entity_dynamic_mappings/{identifier}:
    get:
      tags:
        - Entity dynamic mapping
      summary: Get an entity dynamic mapping by identifier
      description: Retrieve an entity dynamic mapping using its string identifier
      operationId: getEntityDynamicMappingByIdentifier
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Entity dynamic mapping found
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/EntityDynamicMappingDtoOut"
        "404":
          description: Entity dynamic mapping not found with the provided identifier
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    put:
      tags:
        - Entity dynamic mapping
      summary: Update an existing entity dynamic mapping by identifier
      description: Update the details of an existing entity dynamic
        mapping  identified by its unique string identifier
      operationId: updateEntityDynamicMapping
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EntityDynamicMappingUpdateDtoIn"
        required: true
      responses:
        "200":
          description: Entity dynamic mapping updated successfully
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/EntityDynamicMappingDtoOut"
        "400":
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Entity dynamic mapping not found with the provided identifier
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: Conflict
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    delete:
      tags:
        - Entity dynamic mapping
      summary: Delete an entity dynamic mapping by identifier
      description: Remove an entity dynamic from the system using its unique identifier
      operationId: deleteEntityDynamicMapping
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Entity dynamic mapping deleted successfully
        "404":
          description: Entity dynamic mapping not found with the provided identifier
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/entity-templates/{identifier}:
    get:
      tags:
        - Entities Templates Management
      summary: Get template by identifier
      description: Retrieve a specific template using its string identifier
      operationId: getTemplateByIdentifier
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Template found
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/EntityTemplateDtoOut"
        "404":
          description: Template not found with the provided identifier
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    put:
      tags:
        - Entities Templates Management
      summary: Update an existing template by template identifier
      description: Update the details of an existing template identified by its unique
        string identifier
      operationId: updateTemplate
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EntityTemplateUpdateDtoIn"
        required: true
      responses:
        "200":
          description: Template update successfully
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/EntityTemplateDtoOut"
        "404":
          description: Template not found with the provided identifier
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    delete:
      tags:
        - Entities Templates Management
      summary: Delete template by identifier
      description: Remove a template from the system using its unique identifier
      operationId: deleteTemplate
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Template deleted successfully
        "404":
          description: Template not found with the provided identifier
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/entities/{templateIdentifier}/{entityIdentifier}:
    get:
      tags:
        - Entities Management
      summary: Get entity by entity template and identifier
      description: Retrieve a specific entity using its string identifier and its
        template identifier
      operationId: getEntity
      parameters:
        - name: templateIdentifier
          in: path
          required: true
          schema:
            type: string
        - name: entityIdentifier
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Entity found
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/EntityDtoOut"
        "404":
          description: Entity not found with the provided identifier
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    put:
      tags:
        - Entities Management
      summary: Update an existing entity
      description: Update an existing entity in the system with the provided information
      operationId: updateEntity
      parameters:
        - name: templateIdentifier
          in: path
          required: true
          schema:
            type: string
            minLength: 1
        - name: entityIdentifier
          in: path
          required: true
          schema:
            type: string
            minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EntityUpdateDtoIn"
        required: true
      responses:
        "200":
          description: Entity updated successfully
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/EntityDtoOut"
        "400":
          description: Invalid entity data provided
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized - Missing or invalid token
        "403":
          description: Insufficient rights
        "404":
          description: Entity not found with the provided identifier
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Unexpected server-side failure
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    delete:
      tags:
        - Entities Management
      summary: Delete an existing entity
      description: Delete an entity from the system using its template and entity
        identifiers. This operation removes the entity and automatically cleans
        up any relations from other entities that reference it.
      operationId: deleteEntity
      parameters:
        - name: templateIdentifier
          in: path
          required: true
          schema:
            type: string
            minLength: 1
        - name: entityIdentifier
          in: path
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        "204":
          description: Entity deleted successfully
        "400":
          description: Invalid entity data provided
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized - Missing or invalid token
        "403":
          description: Insufficient rights
        "404":
          description: Entity not found with the provided identifier
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: Target entity has required relations
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Unexpected server-side failure
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/inbound_webhooks:
    get:
      tags:
        - Inbound Webhook Management
      summary: Get paginated Webhook connectors
      description: Retrieve a paginated list of webhook connectors with optional sorting
      operationId: getWebhooksPaginated
      parameters:
        - name: page
          in: query
          description: Page number for pagination. Defaults to 0.
          content:
            "*/*":
              schema:
                type: integer
                default: "0"
        - name: size
          in: query
          description: Number of items per page. Defaults to 20.
          content:
            "*/*":
              schema:
                type: integer
                default: "20"
        - name: sort
          in: query
          description: "Sorting criteria in the format: property(,asc|desc). Defaults to
            identifier,asc."
          content:
            "*/*":
              schema:
                type: string
                default: identifier,asc
      responses:
        "200":
          description: Paginated webhook connector retrieved successfully
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/WebhookConnectorPageResponse"
        "400":
          description: Invalid pagination parameters
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    post:
      tags:
        - Inbound Webhook Management
      summary: Create a new webhook connector configuration
      description: Creates a webhook connector configuration used by the generic
        inbound webhook endpoint
      operationId: createInboundWebhook
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InboundWebhookCreateDtoIn"
        required: true
      responses:
        "201":
          description: Webhook connector created
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/InboundWebhookDtoOut"
        "400":
          description: Invalid webhook connector data provided
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/InboundWebhookDtoOut"
        "409":
          description: Webhook connector already exists in this entityTemplateIdentifier
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/InboundWebhookDtoOut"
  /api/v1/entity_dynamic_mappings:
    get:
      tags:
        - Entity dynamic mapping
      summary: Get paginated entity dynamic mappings
      description: Retrieve a paginated list of entity dynamic mappings with optional
        sorting
      operationId: getEntityDynamicMappingPaginated
      parameters:
        - name: page
          in: query
          description: Page number for pagination. Defaults to 0.
          content:
            "*/*":
              schema:
                type: integer
                default: "0"
        - name: size
          in: query
          description: Number of items per page. Defaults to 20.
          content:
            "*/*":
              schema:
                type: integer
                default: "20"
        - name: sort
          in: query
          description: "Sorting criteria in the format: property(,asc|desc). Defaults to
            identifier,asc."
          content:
            "*/*":
              schema:
                type: string
                default: identifier,asc
      responses:
        "200":
          description: Paginated entity dynamic mapping retrieved successfully
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/EntityDynamicMappingPageResponse"
        "400":
          description: Invalid pagination parameters
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    post:
      tags:
        - Entity dynamic mapping
      summary: Create entity dynamic mapping
      description: Creates a new entity dynamic mapping used by the generic inbound
        webhook endpoint
      operationId: createDynamicMapping
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EntityDynamicMappingCreateDtoIn"
        required: true
      responses:
        "201":
          description: Entity dynamic mapping created
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/EntityDynamicMappingDtoOut"
        "400":
          description: Invalid entity dynamic mapping data provided
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/EntityDynamicMappingDtoOut"
        "409":
          description: Identifier already exists
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/EntityDynamicMappingDtoOut"
  /api/v1/entity-templates:
    get:
      tags:
        - Entities Templates Management
      summary: Get paginated templates
      description: Retrieve a paginated list of templates with optional sorting
      operationId: getTemplatesPaginated
      parameters:
        - name: page
          in: query
          description: Page number for pagination. Defaults to 0.
          content:
            "*/*":
              schema:
                type: integer
                default: "0"
        - name: size
          in: query
          description: Number of items per page. Defaults to 20.
          content:
            "*/*":
              schema:
                type: integer
                default: "20"
        - name: sort
          in: query
          description: "Sorting criteria in the format: property(,asc|desc). Defaults to
            identifier,asc."
          content:
            "*/*":
              schema:
                type: string
                default: identifier,asc
      responses:
        "200":
          description: Paginated templates retrieved successfully
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/TemplatePageResponse"
        "400":
          description: Invalid pagination parameters
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    post:
      tags:
        - Entities Templates Management
      summary: Create a new template
      description: Create a new template in the system with the provided information
      operationId: createTemplate
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EntityTemplateCreateDtoIn"
        required: true
      responses:
        "201":
          description: Template created successfully
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/EntityTemplateDtoOut"
        "400":
          description: Invalid template data provided
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/entities/{templateIdentifier}:
    get:
      tags:
        - Entities Management
      summary: Get entities by template identifier
      description: Retrieve a paginated list of entities with optional sorting
      operationId: getEntities
      parameters:
        - name: page
          in: query
          description: Page number for pagination. Defaults to 0.
          required: false
          content:
            "*/*":
              schema:
                type: integer
                default: "0"
        - name: size
          in: query
          description: Number of items per page. Defaults to 20.
          required: false
          content:
            "*/*":
              schema:
                type: integer
                default: "20"
        - name: templateIdentifier
          in: path
          required: true
          schema:
            type: string
        - name: q
          in: query
          description: >
            Optional filter query using a simple expression language. See more
            details in the API documentation. Example: `name:idp` for entities
            with names containing 'idp'.
          required: false
          content:
            "*/*":
              schema:
                type: string
        - name: sort
          in: query
          description: "Sorting criteria in the format: property(,asc|desc). Defaults to
            identifier,asc."
          content:
            "*/*":
              schema:
                type: string
                default: identifier,asc
      responses:
        "200":
          description: Paginated entities retrieved successfully
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/EntityPageResponse"
        "400":
          description: Invalid filter query syntax
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    post:
      tags:
        - Entities Management
      summary: Create a new entity
      description: Create a new entity in the system with the provided information
      operationId: createEntity
      parameters:
        - name: templateIdentifier
          in: path
          required: true
          schema:
            type: string
            minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EntityCreateDtoIn"
        required: true
      responses:
        "201":
          description: Entity created successfully
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/EntityDtoOut"
        "400":
          description: Invalid entity data provided
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized - Missing or invalid token
        "403":
          description: Insufficient rights
        "404":
          description: Template not found with the provided identifier
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: Entity already exists in this template
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Unexpected server-side failure
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/entities/search:
    post:
      tags:
        - Entities Management
      summary: Search entities
      description: Search for entities across all templates using nested filter
        queries. Supports complex logical compositions (AND / OR) of filter
        criteria on template, identifier, name, properties, relations, and
        reverse relations.
      operationId: searchEntities
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EntitySearchRequestDtoIn"
        required: true
      responses:
        "200":
          description: Entities retrieved successfully
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/EntityPageResponse"
        "400":
          description: Invalid search filter
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/entities/{templateIdentifier}/{entityIdentifier}/graph:
    get:
      tags:
        - Entity Graph
      summary: Get entity relationship graph as flat nodes and edges
      description: Retrieves the entity relationship graph as a flat nodes-and-edges
        structure, suitable for frontend visualization tools such as React Flow,
        Vis.js, and Cytoscape.
      operationId: getEntityGraph
      parameters:
        - name: templateIdentifier
          in: path
          required: true
          schema:
            type: string
            minLength: 1
        - name: entityIdentifier
          in: path
          required: true
          schema:
            type: string
            minLength: 1
        - name: depth
          in: query
          description: Maximum traversal depth for relationship resolution. Clamped
            between 1 and 6.
          required: false
          schema:
            type: integer
            format: int32
            default: 1
        - name: include_data
          in: query
          description: When true, each graph node includes a data object containing the
            entity's property values. Defaults to false.
          required: false
          schema:
            type: boolean
            default: false
        - name: traversal_mode
          in: query
          description: Specifies the traversal mode for the entity graph. Defaults to
            DIRECT_LINEAGE.
          required: false
          schema:
            type: string
            default: DIRECT_LINEAGE
            enum:
              - DIRECT_LINEAGE
              - BIDIRECTIONAL
              - OUTBOUND_ONLY
        - name: relations
          in: query
          description: When provided, only relations whose name matches one of the listed
            values are traversed and included. Omit to include all relations.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: properties
          in: query
          description: When provided, each node's data object is restricted to the listed
            property names. Requires include_data=true to have any effect. Omit
            to include all properties.
          required: false
          schema:
            type: array
            items:
              type: string
      responses:
        "200":
          description: Flat entity graph successfully retrieved
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/EntityGraphFlatDtoOut"
        "404":
          description: Entity not found with the provided identifier
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/audit/entities/{templateIdentifier}/{entityIdentifier}:
    get:
      tags:
        - Audit
      summary: Get entity audit history
      description: Retrieve the complete audit history for a specific entity,
        including all revisions with timestamps and modification types
      operationId: getEntityAuditHistory
      parameters:
        - name: templateIdentifier
          in: path
          required: true
          schema:
            type: string
            minLength: 1
        - name: entityIdentifier
          in: path
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        "200":
          description: Successfully retrieved entity audit history
          content:
            "*/*":
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/EntityAuditDtoOut"
        "400":
          description: Invalid template or entity identifier
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized - Missing or invalid token
        "403":
          description: Insufficient rights
        "404":
          description: Template not found with the provided identifier or Entity not found
            with the provided identifier
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Unexpected server-side failure
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
components:
  schemas:
    InboundWebhookSecurityContractDtoIn:
      type: object
      properties:
        type:
          type: string
          minLength: 1
        config:
          type: object
          additionalProperties:
            type: string
      required:
        - config
        - type
    InboundWebhookUpdateDtoIn:
      type: object
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 0
        description:
          type: string
        enabled:
          type: boolean
        mapping_identifiers:
          type: array
          items:
            type: string
        security:
          $ref: "#/components/schemas/InboundWebhookSecurityContractDtoIn"
      required:
        - name
    EntityDynamicMappingDtoOut:
      type: object
      properties:
        identifier:
          type: string
        entityTemplateIdentifier:
          type: string
        filter:
          type: string
        name:
          type: string
        description:
          type: string
        entity:
          $ref: "#/components/schemas/InboundWebhookEntityMappingDtoOut"
    InboundWebhookDtoOut:
      type: object
      properties:
        identifier:
          type: string
        name:
          type: string
        description:
          type: string
        enabled:
          type: boolean
        mappings:
          type: array
          items:
            $ref: "#/components/schemas/EntityDynamicMappingDtoOut"
        security:
          $ref: "#/components/schemas/InboundWebhookSecurityDtoOut"
    InboundWebhookEntityMappingDtoOut:
      type: object
      properties:
        identifier:
          type: string
        name:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string
        relations:
          type: object
          additionalProperties:
            type: string
    InboundWebhookSecurityDtoOut:
      type: object
      properties:
        type:
          type: string
        config:
          type: object
          additionalProperties:
            type: string
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        errorDescription:
          type: string
    EntityDynamicMappingUpdateDtoIn:
      type: object
      properties:
        entity_template_identifier:
          type: string
          minLength: 1
        filter:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
        description:
          type: string
        entity:
          $ref: "#/components/schemas/EntityMappingDtoIn"
      required:
        - entity
        - entity_template_identifier
        - filter
        - name
    EntityMappingDtoIn:
      type: object
      properties:
        identifier:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
        properties:
          type: object
          additionalProperties:
            type: string
        relations:
          type: object
          additionalProperties:
            type: string
      required:
        - identifier
        - name
        - properties
        - relations
    EntityTemplateUpdateDtoIn:
      type: object
      description: Input DTO for updating an entity template
      properties:
        name:
          type: string
          description: Unique Entity Template name
          example: Service
          maxLength: 255
          minLength: 0
          pattern: ^[a-zA-Z0-9 _-]+$
        description:
          type: string
          description: Entity Template description
          example: A comprehensive service template
        properties_definitions:
          type: array
          description: List of property definitions for this template
          items:
            $ref: "#/components/schemas/PropertyDefinitionDtoIn"
        relations_definitions:
          type: array
          description: List of relation definitions for this template
          items:
            $ref: "#/components/schemas/RelationDefinitionDtoIn"
      required:
        - name
    PropertyDefinitionDtoIn:
      type: object
      description: Input DTO for creating or updating a property definition
      properties:
        name:
          type: string
          description: Property name
          example: applicationName
          minLength: 1
        description:
          type: string
          description: Property description
          example: Name of the application
          minLength: 1
        type:
          type: string
          description: Property data type
          enum:
            - STRING
            - NUMBER
            - BOOLEAN
          example: STRING
        required:
          type: boolean
          default: false
          description: Whether this property is required
          example: true
        rules:
          $ref: "#/components/schemas/PropertyRulesDtoIn"
          description: Property validation rules
      required:
        - description
        - name
        - type
    PropertyRulesDtoIn:
      type: object
      description: Input DTO for creating or updating a property definition
      properties:
        format:
          type: string
          description: Property format validation
          enum:
            - URL
            - EMAIL
          example: EMAIL
        enum_values:
          type: array
          description: Enumeration values for enum properties
          example:
            - ACTIVE
            - INACTIVE
          items:
            type: string
        regex:
          type: string
          description: Regular expression pattern for validation
          example: ^[a-zA-Z0-9]+$
        max_length:
          type: integer
          format: int32
          description: Maximum length for string properties
          example: 255
        min_length:
          type: integer
          format: int32
          description: Minimum length for string properties
          example: 1
        max_value:
          type: integer
          format: int32
          description: Maximum value for numeric properties
          example: 100
        min_value:
          type: integer
          format: int32
          description: Minimum value for numeric properties
          example: 0
    RelationDefinitionDtoIn:
      type: object
      description: Input DTO for creating or updating a relation definition
      properties:
        name:
          type: string
          description: Name of the relation
          example: dependencies
          minLength: 1
        target_template_identifier:
          type: string
          description: Identifier of the target template
          example: service
          minLength: 1
        required:
          type: boolean
          default: false
          description: Whether this relation is required
          example: false
        to_many:
          type: boolean
          default: false
          description: Whether this relation can have multiple targets
          example: true
      required:
        - name
        - target_template_identifier
    EntityTemplateDtoOut:
      type: object
      description: Output for entity template
      properties:
        identifier:
          type: string
          description: Unique Entity Template identifier
          example: service
        name:
          type: string
          description: Unique Entity Template name
          example: Service
        description:
          type: string
          description: Entity Template description
          example: A comprehensive service template
        properties_definitions:
          type: array
          description: List of property definitions for this template
          items:
            $ref: "#/components/schemas/PropertyDefinitionDtoOut"
        relations_definitions:
          type: array
          description: List of relation definitions for this template
          items:
            $ref: "#/components/schemas/RelationDefinitionDtoOut"
    PropertyDefinitionDtoOut:
      type: object
      description: Output DTO for property definition
      properties:
        name:
          type: string
          description: Property name
          example: applicationName
        description:
          type: string
          description: Property description
          example: Name of the application
        type:
          type: string
          description: Property data type
          enum:
            - STRING
            - NUMBER
            - BOOLEAN
          example: STRING
        required:
          type: boolean
          description: Whether this property is required
          example: true
        rules:
          $ref: "#/components/schemas/PropertyRulesDtoOut"
          description: Property validation rules
          example: Property validation rules
    PropertyRulesDtoOut:
      type: object
      description: Output DTO for property validation rules
      properties:
        format:
          type: string
          description: Format of the property
          enum:
            - URL
            - EMAIL
          example: STRING
        enum_values:
          type: array
          description: Allowed enum values for the property
          example:
            - VALUE1
            - VALUE2
          items:
            type: string
        regex:
          type: string
          description: Regular expression for property validation
          example: ^[A-Za-z0-9]+$
        max_length:
          type: integer
          format: int32
          description: Maximum length of the property
          example: 255
        min_length:
          type: integer
          format: int32
          description: Minimum length of the property
          example: 1
        max_value:
          type: integer
          format: int32
          description: Maximum value for the property
          example: 100
        min_value:
          type: integer
          format: int32
          description: Minimum value for the property
          example: 0
    RelationDefinitionDtoOut:
      type: object
      description: Output DTO for relation definition
      properties:
        name:
          type: string
          description: Name of the relation
          example: dependencies
        target_template_identifier:
          type: string
          description: Identifier of the target template
          example: component-template
        required:
          type: boolean
          description: Whether this relation is required
          example: false
        to_many:
          type: boolean
          description: Whether this relation can have multiple targets
          example: true
    EntityUpdateDtoIn:
      type: object
      description: Input DTO for updating an entity
      properties:
        name:
          type: string
          description: Name of the entity
          example: my-web-service
          minLength: 1
        properties:
          type: object
          additionalProperties:
            type: string
          description: Map of property name to value for this entity
          example:
            port: "8080"
            environment: dev
        relations:
          type: array
          description: List of relations for this entity
          items:
            $ref: "#/components/schemas/RelationDtoIn"
      required:
        - name
    RelationDtoIn:
      type: object
      description: Input DTO for an entity relation instance
      properties:
        name:
          type: string
          description: Name of the relation (must match a template relation definition)
          example: depends-on
          minLength: 1
        target_entity_identifiers:
          type: array
          description: List of target entity identifiers for this relation
          example:
            - web-api-1
            - web-api-2
          items:
            type: string
      required:
        - name
        - target_entity_identifiers
    EntityDtoOut:
      type: object
      properties:
        template_identifier:
          type: string
        name:
          type: string
        identifier:
          type: string
        properties:
          type: object
          additionalProperties: {}
        relations:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: "#/components/schemas/EntitySummaryDto"
        relations_as_target:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: "#/components/schemas/EntitySummaryDto"
    EntitySummaryDto:
      type: object
      properties:
        identifier:
          type: string
        name:
          type: string
    InboundWebhookCreateDtoIn:
      type: object
      properties:
        identifier:
          type: string
          maxLength: 255
          minLength: 0
        name:
          type: string
          maxLength: 255
          minLength: 0
        description:
          type: string
        enabled:
          type: boolean
        mapping_identifiers:
          type: array
          items:
            type: string
        security:
          $ref: "#/components/schemas/InboundWebhookSecurityContractDtoIn"
      required:
        - identifier
        - name
    EntityDynamicMappingCreateDtoIn:
      type: object
      properties:
        identifier:
          type: string
          minLength: 1
        entity_template_identifier:
          type: string
          minLength: 1
        filter:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
        description:
          type: string
        entity:
          $ref: "#/components/schemas/EntityMappingDtoIn"
      required:
        - entity
        - entity_template_identifier
        - filter
        - identifier
        - name
    EntityTemplateCreateDtoIn:
      type: object
      description: Input DTO for creating an entity template
      properties:
        identifier:
          type: string
          description: Unique Entity Template identifier
          example: service
          minLength: 1
        name:
          type: string
          description: Unique Entity Template name
          example: Service
          maxLength: 255
          minLength: 0
          pattern: ^[a-zA-Z0-9 _-]+$
        description:
          type: string
          description: Entity Template description
          example: A comprehensive service template
        properties_definitions:
          type: array
          description: List of property definitions for this template
          items:
            $ref: "#/components/schemas/PropertyDefinitionDtoIn"
        relations_definitions:
          type: array
          description: List of relation definitions for this template
          items:
            $ref: "#/components/schemas/RelationDefinitionDtoIn"
      required:
        - identifier
        - name
    EntityCreateDtoIn:
      type: object
      description: Input DTO for creating an entity
      properties:
        identifier:
          type: string
          description: Unique identifier of the entity within the template scope
          example: my-web-service
          minLength: 1
        name:
          type: string
          description: Name of the entity
          example: my-web-service
          minLength: 1
        properties:
          type: object
          additionalProperties:
            type: string
          description: Map of property name to value for this entity
          example:
            port: "8080"
            environment: dev
        relations:
          type: array
          description: List of relations for this entity
          items:
            $ref: "#/components/schemas/RelationDtoIn"
      required:
        - identifier
        - name
    EntitySearchRequestDtoIn:
      type: object
      description: Request body for the POST /api/v1/entities/search endpoint
      properties:
        query:
          type: string
          description: Free-text search string. When present, returns entities whose
            identifier, name, templateIdentifier, or any property value contains
            this string (case-insensitive). Can be combined with filter.
          example: checkout
        filter:
          $ref: "#/components/schemas/FilterNodeDtoIn"
          description: Root node of the search filter tree. May be omitted or null to
            return all entities.
        page:
          type: integer
          format: int32
          default: 0
          description: Page number for pagination. Defaults to 0.
          example: 0
        size:
          type: integer
          format: int32
          default: 20
          description: Number of items per page. Defaults to 20.
          example: 20
        sort:
          type: string
          description: "Sorting criteria in the format: property(,asc|desc). Defaults to
            identifier,asc."
          example: identifier:asc
    FilterNodeDtoIn:
      type: object
      description: A node in the search filter tree. Either a logical group (connector
        + criteria) or a leaf criterion (field + operation + value).
      properties:
        connector:
          type: string
          description: "Logical connector for a group node. One of: AND, OR. Required for
            group nodes."
          example: AND
        criteria:
          type: array
          description: Child filter nodes for a group node. Required for group nodes (must
            be non-empty).
          items:
            $ref: "#/components/schemas/FilterNodeDtoIn"
        field:
          type: string
          description: "Field to filter on for a criterion node. Required for leaf nodes.
            Examples: template, identifier, name, relation, property.language,
            relation.api-link, relation.api-link.identifier,
            relations_as_target.api-link.name"
          example: template
        operation:
          type: string
          description: "Filter operation for a criterion node. One of: EQ, NEQ, CONTAINS,
            NOT_CONTAINS, STARTS_WITH, ENDS_WITH, GT, GTE, LT, LTE. Required for
            leaf nodes."
          example: EQ
        value:
          type: string
          description: Value to compare against for a criterion node. Required for leaf
            nodes.
          example: microservice
    EntityPageResponse:
      type: object
      description: Paginated response containing Entity objects
      properties:
        content:
          type: array
          items:
            $ref: "#/components/schemas/EntityDtoOut"
        pageable:
          $ref: "#/components/schemas/PageableObject"
        totalElements:
          type: integer
          format: int64
        totalPages:
          type: integer
          format: int32
        last:
          type: boolean
        sort:
          $ref: "#/components/schemas/SortObject"
        first:
          type: boolean
        numberOfElements:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        number:
          type: integer
          format: int32
        empty:
          type: boolean
    PageableObject:
      type: object
      properties:
        paged:
          type: boolean
        pageNumber:
          type: integer
          format: int32
        pageSize:
          type: integer
          format: int32
        unpaged:
          type: boolean
        sort:
          $ref: "#/components/schemas/SortObject"
        offset:
          type: integer
          format: int64
    SortObject:
      type: object
      properties:
        sorted:
          type: boolean
        unsorted:
          type: boolean
        empty:
          type: boolean
    WebhookConnectorPageResponse:
      type: object
      description: Paginated response containing Inbound Webhook Connector objects
      properties:
        content:
          type: array
          items:
            $ref: "#/components/schemas/InboundWebhookDtoOut"
        pageable:
          $ref: "#/components/schemas/PageableObject"
        totalElements:
          type: integer
          format: int64
        totalPages:
          type: integer
          format: int32
        last:
          type: boolean
        sort:
          $ref: "#/components/schemas/SortObject"
        first:
          type: boolean
        numberOfElements:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        number:
          type: integer
          format: int32
        empty:
          type: boolean
    EntityDynamicMappingPageResponse:
      type: object
      description: Paginated response containing Entity Dynamic Mapping objects
      properties:
        content:
          type: array
          items:
            $ref: "#/components/schemas/EntityDynamicMappingDtoOut"
        pageable:
          $ref: "#/components/schemas/PageableObject"
        totalElements:
          type: integer
          format: int64
        totalPages:
          type: integer
          format: int32
        last:
          type: boolean
        sort:
          $ref: "#/components/schemas/SortObject"
        first:
          type: boolean
        numberOfElements:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        number:
          type: integer
          format: int32
        empty:
          type: boolean
    TemplatePageResponse:
      type: object
      description: Paginated response containing Template objects
      properties:
        content:
          type: array
          items:
            $ref: "#/components/schemas/EntityTemplateDtoOut"
        pageable:
          $ref: "#/components/schemas/PageableObject"
        totalElements:
          type: integer
          format: int64
        totalPages:
          type: integer
          format: int32
        last:
          type: boolean
        sort:
          $ref: "#/components/schemas/SortObject"
        first:
          type: boolean
        numberOfElements:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        number:
          type: integer
          format: int32
        empty:
          type: boolean
    EntityGraphEdgeDtoOut:
      type: object
      properties:
        id:
          type: string
          description: Unique edge identifier
        source:
          type: string
          description: Node id of the source entity
        target:
          type: string
          description: Node id of the target entity
        type:
          type: string
          description: Relation name as defined in the entity template
    EntityGraphFlatDtoOut:
      type: object
      properties:
        nodes:
          type: array
          description: All entity nodes in the graph
          items:
            $ref: "#/components/schemas/EntityGraphNodeFlatDtoOut"
        edges:
          type: array
          description: All directed relation edges in the graph
          items:
            $ref: "#/components/schemas/EntityGraphEdgeDtoOut"
    EntityGraphNodeFlatDtoOut:
      type: object
      properties:
        id:
          type: string
          description: Unique node identifier composed of templateIdentifier:identifier
        label:
          type: string
          description: Human-readable entity name
        template_identifier:
          type: string
          description: Template identifier this entity belongs to
        identifier:
          type: string
          description: Business identifier of the entity within its template
        data:
          type: object
          additionalProperties: {}
          description: Entity property values keyed by property name; present only when
            include_data=true is requested
    EntityAuditDtoOut:
      type: object
      description: Audit information for an entity revision
      properties:
        revision_number:
          type: number
          description: Unique revision number in the audit log
          example: 42
        revision_date:
          type: string
          format: date-time
          description: Timestamp when the revision was created
          example: 2026-06-08T14:37:27.743Z
        revision_type:
          type: string
          description: Type of operation performed (CREATED, UPDATED, DELETED)
          example: UPDATED
        modified_by:
          type: string
          description: Identifier of the user who performed the modification
          example: user@example.com
        snapshot:
          $ref: "#/components/schemas/EntitySnapshotDtoOut"
          description: Snapshot of the entity state at this revision
    EntitySnapshotDtoOut:
      type: object
      description: Snapshot of entity state at a specific audit revision
      properties:
        template_identifier:
          type: string
          description: Template identifier
          example: web-service
        name:
          type: string
          description: Entity name
          example: My Service
        identifier:
          type: string
          description: Entity identifier
          example: my-service-api
        properties:
          type: array
          description: Properties of the entity at this revision
          items:
            $ref: "#/components/schemas/PropertySnapshotDtoOut"
        relations:
          type: array
          description: Relations of the entity at this revision
          items:
            $ref: "#/components/schemas/RelationSnapshotDtoOut"
    PropertySnapshotDtoOut:
      type: object
      description: Snapshot of a property at a specific audit revision
      properties:
        name:
          type: string
          description: Name of the property matching a PropertyDefinition
          example: description
        value:
          type: string
          description: Value of the property at this revision
          example: My service description
    RelationSnapshotDtoOut:
      type: object
      description: Snapshot of a relation at a specific audit revision
      properties:
        name:
          type: string
          description: Name of the relation matching a RelationDefinition
          example: deployed-on
        target_template_identifier:
          type: string
          description: Identifier of the target entity template
          example: infrastructure
        target_entity_identifiers:
          type: array
          description: Business identifiers of target entities
          example:
            - prod-cluster
            - staging-cluster
          items:
            type: string
  securitySchemes:
    clientId:
      type: oauth2
      description: clientId authentication
      name: clientId
      flows:
        clientCredentials:
          tokenUrl: https://example.com/as/token.oauth2
    bearer:
      type: http
      description: bearer authentication
      name: bearer
      scheme: bearer
      bearerFormat: JWT