EntityAttachment

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.

Version: 2.0.0
OpenAPI version: 3.0.0

Authentication

OAuth2

Security scheme type: oauth2

Flow type: password

Token URL: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token

AccessToken

Security scheme type: apiKey

Query parameter name: access-token

Operations

index

POST

/v2/entity-attachment/index

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.

Authorizations

OAuth2
AccessToken

Query Parameters

entity_id

required

string format: uuid

The ID of the entity to retrieve linked files for. Required.

Request Body

Parameters for searching entity attachments

object

filter

object

entity_attachment_id

Unique identifier of the link. Auto-generated if not provided on creation.

string format: uuid

entity_id

required

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.

string format: uuid

attachment_id

MD5 hash of the file path. Can be omitted on creation — derived automatically from attachment_path.

string

<= 50 characters

attachment_path

required

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

string

<= 1024 characters

per-page

integer

default: 100 >= 1

page

integer

default: 1 >= 1

sort

Field to sort by. Prefix with minus for descending order.

string

Allowed values: attachment_path

Example

{
  "filter": {
    "attachment_path": "fire-safety-certificate.pdf"
  },
  "per-page": 50,
  "page": 1,
  "sort": "attachment_path"
}

Responses

200

List of entity attachments

Array<object>

object

entity_attachment_id

Unique identifier of the link. Auto-generated if not provided on creation.

string format: uuid

entity_id

required

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.

string format: uuid

attachment_id

MD5 hash of the file path. Can be omitted on creation — derived automatically from attachment_path.

string

<= 50 characters

attachment_path

required

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

string

<= 1024 characters

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

integer

Current page

X-Pagination-Page-Count

integer

Total number of pages

X-Pagination-Per-Page

integer

Number of items per page

X-Pagination-Total-Count

integer

Total number of items

view

GET

/v2/entity-attachment/view/{id}

Retrieves a single file-entity link by its ID.

Authorizations

OAuth2
AccessToken

Path Parameters

required

string format: uuid

The entity_attachment_id to retrieve.

Responses

200

Entity attachment found

object

entity_attachment_id

Unique identifier of the link. Auto-generated if not provided on creation.

string format: uuid

entity_id

required

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.

string format: uuid

attachment_id

MD5 hash of the file path. Can be omitted on creation — derived automatically from attachment_path.

string

<= 50 characters

attachment_path

required

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

string

<= 1024 characters

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

Entity attachment not found

create

POST

/v2/entity-attachment/create

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.

Authorizations

OAuth2
AccessToken

Request Body^required

Entity attachment to create

object

entity_attachment_id

Unique identifier of the link. Auto-generated if not provided on creation.

string format: uuid

entity_id

required

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.

string format: uuid

attachment_id

MD5 hash of the file path. Can be omitted on creation — derived automatically from attachment_path.

string

<= 50 characters

attachment_path

required

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

string

<= 1024 characters

Example

{
  "entity_id": "f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c",
  "attachment_path": "/projects/b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01/fire-safety-certificate.pdf"
}

Responses

201

Entity attachment created successfully

object

entity_attachment_id

Unique identifier of the link. Auto-generated if not provided on creation.

string format: uuid

entity_id

required

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.

string format: uuid

attachment_id

MD5 hash of the file path. Can be omitted on creation — derived automatically from attachment_path.

string

<= 50 characters

attachment_path

required

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

string

<= 1024 characters

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"
}

update

PUT

/v2/entity-attachment/update/{id}

Updates an existing file-entity link.

Authorizations

OAuth2
AccessToken

Path Parameters

required

string format: uuid

The entity_attachment_id to update.

Request Body^required

Fields to update

object

entity_attachment_id

Unique identifier of the link. Auto-generated if not provided on creation.

string format: uuid

entity_id

required

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.

string format: uuid

attachment_id

MD5 hash of the file path. Can be omitted on creation — derived automatically from attachment_path.

string

<= 50 characters

attachment_path

required

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

string

<= 1024 characters

Example

{
  "attachment_path": "/projects/b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01/updated-certificate.pdf"
}

Responses

200

Entity attachment updated successfully

object

entity_attachment_id

Unique identifier of the link. Auto-generated if not provided on creation.

string format: uuid

entity_id

required

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.

string format: uuid

attachment_id

MD5 hash of the file path. Can be omitted on creation — derived automatically from attachment_path.

string

<= 50 characters

attachment_path

required

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

string

<= 1024 characters

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

Entity attachment not found

delete

DELETE

/v2/entity-attachment/delete/{id}

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.

Authorizations

OAuth2
AccessToken

Path Parameters

required

string format: uuid

The entity_attachment_id to delete.

Query Parameters

force

boolean

If true, deletes the link. If false, returns a preview of affected entities.

Responses

204

Entity attachment deleted successfully

400

Preview of affected entities (returned when force=false)

EntityAttachment

Authentication

OAuth2

AccessToken

Operations

index

Authorizations

Query Parameters

Request Body

Example

Responses

200

Example

Headers

view

Authorizations

Path Parameters

Responses

200

Example

404

create

Authorizations

Request Body required

Example

Responses

201

Example

update

Authorizations

Path Parameters

Request Body required

Example

Responses

200

Example

404

delete

Authorizations

Path Parameters

Query Parameters

Responses

204

400

Request Body^required

Request Body^required