Attachment

An Attachment represents a file or folder in the file storage system. Files are organized in a folder structure by project and office.

Use this API to:

Upload a file (e.g. a certificate PDF, a training document)
Create a folder
Search files by name, path, or metadata
Download or view a file

Uploading a file does not automatically associate it with any entity. To link an uploaded file to a certificate, action, or other entity, create an EntityAttachment after uploading the file.

Folder structure convention:

/projects/{project_id}/ — project root folder
/projects/{project_id}/offices/{office_name}/ — office folder

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/attachment/index

Searches files and folders in the file storage.

The index uses a metadata-based search system, different from other index endpoints. Search parameters:

key + value: search by specific metadata (e.g. key: "project_name", value: "Acme Construction Ltd")
searchText: full-text search in the file name
root_path: limit search to a root folder
parent_path: limit search to a parent folder

Authorizations

OAuth2
AccessToken

Request Body

Parameters for searching attachments

object

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

key

Metadata key to search by (e.g. “project_name”, “mimetype”).

string

value

Value to match for the specified key.

string

searchText

Full-text search in file names.

string

root_path

Limit search to files under this root path.

string

parent_path

Limit search to files directly inside this parent folder.

string

Example

{
  "key": "project_name",
  "value": "Acme Construction Ltd",
  "per-page": 10,
  "page": 1,
  "sort": "attachment_path"
}

Responses

200

List of attachments

Array<object>

object

attachment_id

required

MD5 hash of the file path. This is not a UUID — it is derived from the path.

string

<= 50 characters

attachment_path

required

Full path of the file or folder in the storage system (e.g. /projects/{project_id}/offices/{office_name}/document.pdf).

string

<= 1024 characters

data

File metadata including mimetype, size, and contextual information (project_id, project_name, etc.).

object

Example

[
  {
    "attachment_id": "452b7448dce72057574d59f93d456ed0",
    "attachment_path": "/projects/b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01/fire-safety-certificate.pdf",
    "data": {
      "mimetype": "application/pdf",
      "size": "137863",
      "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",
      "project_name": "Acme Construction Ltd"
    }
  }
]

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/attachment/view/{id}

Retrieves a file or its metadata.

The id parameter is the file path or the attachment_id (MD5 hash of the path). By default returns the file stream (download). Set Accept: application/json header to get file metadata instead. The mode parameter controls delivery: download (default) or inline.

Authorizations

OAuth2
AccessToken

Path Parameters

required

string

File path or attachment_id (MD5 hash of the path).

Query Parameters

mode

string

default: download

Allowed values: download inline

Delivery mode for the file.

Responses

200

Attachment found

object

attachment_id

required

MD5 hash of the file path. This is not a UUID — it is derived from the path.

string

<= 50 characters

attachment_path

required

Full path of the file or folder in the storage system (e.g. /projects/{project_id}/offices/{office_name}/document.pdf).

string

<= 1024 characters

data

File metadata including mimetype, size, and contextual information (project_id, project_name, etc.).

object

Example

{
  "attachment_id": "452b7448dce72057574d59f93d456ed0",
  "attachment_path": "/projects/b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01/fire-safety-certificate.pdf",
  "data": {
    "mimetype": "application/pdf",
    "size": "137863",
    "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",
    "project_name": "Acme Construction Ltd"
  }
}

404

Attachment not found

create

POST

/v2/attachment/{id}

Uploads a new file or creates a folder.

The id path parameter is the destination folder (e.g. /projects/{project_id}/offices/{office_name}/). The path body field is the file name. The file field is the binary file to upload. If omitted, a folder is created instead. The replace field (1 or 0) controls whether to overwrite an existing file with the same name.

After upload, the file exists but is not linked to any entity. To link it to a certificate or other entity, create an EntityAttachment.

Authorizations

OAuth2
AccessToken

Path Parameters

required

string

Destination folder path (e.g. /projects/{project_id}/offices/{office_name}/).

Request Body

object

path

required

The file name (e.g. “fire-safety-certificate.pdf”).

string

fire-safety-certificate.pdf

replace

If 1, replaces an existing file with the same name. Ignored when creating a folder.

integer

file

The file to upload. If omitted, a folder is created.

string format: binary

Responses

201

Attachment created successfully

object

attachment_id

required

MD5 hash of the file path. This is not a UUID — it is derived from the path.

string

<= 50 characters

attachment_path

required

Full path of the file or folder in the storage system (e.g. /projects/{project_id}/offices/{office_name}/document.pdf).

string

<= 1024 characters

data

File metadata including mimetype, size, and contextual information (project_id, project_name, etc.).

object

Example

{
  "attachment_id": "452b7448dce72057574d59f93d456ed0",
  "attachment_path": "/projects/b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01/fire-safety-certificate.pdf",
  "data": {
    "mimetype": "application/pdf",
    "size": "137863",
    "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",
    "project_name": "Acme Construction Ltd"
  }
}

400

Bad request

409

Destination path already exists

413

File size is too large

500

Failed to create for unknown reason

update

PUT

/v2/attachment/update/{id}

Renames or moves a file or folder.

The id parameter is the current path. The path body field is the new path.

Authorizations

OAuth2
AccessToken

Path Parameters

required

string

Current file or folder path.

Request Body^required

New path for the file or folder

object

path

The new file or folder path.

string

Example

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

Responses

200

Attachment updated successfully

object

attachment_id

required

MD5 hash of the file path. This is not a UUID — it is derived from the path.

string

<= 50 characters

attachment_path

required

Full path of the file or folder in the storage system (e.g. /projects/{project_id}/offices/{office_name}/document.pdf).

string

<= 1024 characters

data

File metadata including mimetype, size, and contextual information (project_id, project_name, etc.).

object

Example

{
  "attachment_id": "7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
  "attachment_path": "/projects/b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01/renamed-certificate.pdf"
}

400

Bad request

404

Attachment not found

409

Destination path already exists

500

Unable to rename file or folder

delete

DELETE

/v2/attachment/delete/{id}

Deletes a file or folder.

If force=false (default), the response lists linked entities (EntityAttachment links). If force=true, the file and all links are deleted.

Authorizations

OAuth2
AccessToken

Path Parameters

required

string

File or folder path to delete.

Query Parameters

force

boolean

If true, deletes the file and all entity links. If false, returns a preview of affected entities.

Attachment

Authentication

OAuth2

AccessToken

Operations

index

Authorizations

Request Body

Example

Responses

200

Example

Headers

view

Authorizations

Path Parameters

Query Parameters

Responses

200

Example

404

create

Authorizations

Path Parameters

Request Body

Responses

201

Example

400

409

413

500

update

Authorizations

Path Parameters

Request Body required

Example

Responses

200

Example

400

404

409

500

delete

Authorizations

Path Parameters

Query Parameters

Responses

204

400

Request Body^required