openapi: 3.0.0
info:
  title: EntityAttachment
  version: 2.0.0
  description: >
    An **EntityAttachment** links an uploaded file to an entity (certificate,
    action, office,

    person assignment, equipment, or any other entity on the platform).


    Use this API to:

    - Link an uploaded file (via the Attachment API) to a certificate or other
    entity

    - Find all files linked to an entity (filter by `entity_id`)

    - Remove the link between a file and an entity


    The file must already exist in the storage system (uploaded via the
    Attachment API).

    This endpoint does **not** upload files — it only creates the link.


    The `attachment_id` field can be omitted: if only `attachment_path` is
    provided,

    the `attachment_id` is derived automatically from the path.
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/entity-attachment/index:
    post:
      summary: index
      operationId: indexEntityAttachment
      tags:
        - EntityAttachments
      description: >
        Returns a paginated list of files linked to an entity.


        The `entity_id` parameter is required (as a query parameter or in the
        body).

        Returns all files linked to that specific entity.
      parameters:
        - name: entity_id
          in: query
          description: The ID of the entity to retrieve linked files for. Required.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Parameters for searching entity attachments
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EntityAttachmentIndexParams"
            example:
              filter:
                attachment_path: fire-safety-certificate.pdf
              per-page: 50
              page: 1
              sort: attachment_path
      responses:
        "200":
          description: List of entity attachments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/EntityAttachment"
              example:
                - entity_attachment_id: 576331b6-fee8-4949-8bd9-d839202fb6e0
                  entity_id: f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c
                  attachment_id: 452b7448dce72057574d59f93d456ed0
                  attachment_path: /projects/b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01/fire-safety-certificate.pdf
          headers:
            X-Pagination-Current-Page:
              schema:
                type: integer
              description: Current page
            X-Pagination-Page-Count:
              schema:
                type: integer
              description: Total number of pages
            X-Pagination-Per-Page:
              schema:
                type: integer
              description: Number of items per page
            X-Pagination-Total-Count:
              schema:
                type: integer
              description: Total number of items
  /v2/entity-attachment/view/{id}:
    get:
      summary: view
      operationId: viewEntityAttachment
      tags:
        - EntityAttachments
      description: |
        Retrieves a single file-entity link by its ID.
      parameters:
        - name: id
          in: path
          description: The entity_attachment_id to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Entity attachment found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EntityAttachment"
              example:
                entity_attachment_id: 576331b6-fee8-4949-8bd9-d839202fb6e0
                entity_id: f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c
                attachment_id: 452b7448dce72057574d59f93d456ed0
                attachment_path: /projects/b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01/fire-safety-certificate.pdf
        "404":
          description: Entity attachment not found
  /v2/entity-attachment/create:
    post:
      summary: create
      operationId: createEntityAttachment
      tags:
        - EntityAttachments
      description: >
        Creates a new link between an uploaded file and an entity.


        Requires `entity_id` and `attachment_path`. The `attachment_id` can be
        omitted —

        it is derived automatically from the path.

        The `entity_attachment_id` is auto-generated if not provided.


        The `entity_id` is the ID of the entity to link the file to. It can be
        any entity:

        - A `certificate_id` to attach a file to a certificate

        - An `action_id` to attach a file to an action

        - A `person_office_id` to attach a file to a person-office assignment

        - An `office_id`, `office_equipment_id`, `office_work_environment_id`,
        etc.


        The file must already exist (uploaded via the Attachment API).

        The combination of `entity_id` + `attachment_path` must be unique.
      requestBody:
        description: Entity attachment to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EntityAttachment"
            example:
              entity_id: f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c
              attachment_path: /projects/b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01/fire-safety-certificate.pdf
      responses:
        "201":
          description: Entity attachment created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EntityAttachment"
              example:
                entity_attachment_id: 576331b6-fee8-4949-8bd9-d839202fb6e0
                entity_id: f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c
                attachment_id: 452b7448dce72057574d59f93d456ed0
                attachment_path: /projects/b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01/fire-safety-certificate.pdf
  /v2/entity-attachment/update/{id}:
    put:
      summary: update
      operationId: updateEntityAttachment
      tags:
        - EntityAttachments
      description: |
        Updates an existing file-entity link.
      parameters:
        - name: id
          in: path
          description: The entity_attachment_id to update.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EntityAttachment"
            example:
              attachment_path: /projects/b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01/updated-certificate.pdf
      responses:
        "200":
          description: Entity attachment updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EntityAttachment"
              example:
                entity_attachment_id: 576331b6-fee8-4949-8bd9-d839202fb6e0
                entity_id: f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c
                attachment_path: /projects/b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01/updated-certificate.pdf
        "404":
          description: Entity attachment not found
  /v2/entity-attachment/delete/{id}:
    delete:
      summary: delete
      operationId: deleteEntityAttachment
      tags:
        - EntityAttachments
      description: >
        Deletes a file-entity link. The file itself is not deleted — only the
        link.


        If `force=false` (default), the response lists related entities.

        If `force=true`, the link is deleted.
      parameters:
        - name: id
          in: path
          description: The entity_attachment_id to delete.
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: If true, deletes the link. If false, returns a preview of affected
            entities.
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Entity attachment deleted successfully
        "400":
          description: Preview of affected entities (returned when force=false)
components:
  schemas:
    EntityAttachment:
      type: object
      properties:
        entity_attachment_id:
          type: string
          format: uuid
          description: Unique identifier of the link. Auto-generated if not provided on
            creation.
        entity_id:
          type: string
          format: uuid
          description: >
            The entity this file is linked to. Can be any entity on the
            platform:

            - A `certificate_id` to attach a file to a certificate

            - An `action_id` to attach a file to an action

            - A `person_office_id` to attach a file to a person-office
            assignment

            - An `office_id`, `office_equipment_id`,
            `office_work_environment_id`, etc.
        attachment_id:
          type: string
          maxLength: 50
          description: MD5 hash of the file path. Can be omitted on creation — derived
            automatically from `attachment_path`.
        attachment_path:
          type: string
          maxLength: 1024
          description: Full path of the file in the storage system. The file must already
            exist (uploaded via the Attachment API).
      required:
        - entity_id
        - attachment_path
    EntityAttachmentIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/EntityAttachment"
        per-page:
          type: integer
          minimum: 1
          default: 100
        page:
          type: integer
          minimum: 1
          default: 1
        sort:
          type: string
          description: Field to sort by. Prefix with minus for descending order.
          enum:
            - attachment_path
      example:
        filter:
          attachment_path: fire-safety-certificate.pdf
        per-page: 50
        page: 1
        sort: attachment_path
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        password:
          tokenUrl: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token
          scopes: {}
    AccessToken:
      type: apiKey
      in: query
      name: access-token
