---
title: "Attachment"
url: "https://dev.4hse.com/api/attachment"
---

# 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

[Section titled “ Authentication ”](#authentication)

### OAuth2

[Section titled “OAuth2 ”](#oauth2)

**Security scheme type:** oauth2

**Flow type:** password

**Token URL:** [https://auth.4hse.com/realms/4hse/protocol/openid-connect/token](https://auth.4hse.com/realms/4hse/protocol/openid-connect/token)

### AccessToken

[Section titled “AccessToken ”](#accesstoken)

**Security scheme type:** apiKey

**Query parameter name:** access-token

## Operations

[Section titled “Operations”](#operations)

### index

[Section titled “index”](#operation-indexAttachment-post)

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

[Section titled “Authorizations ”](#authorizations)

-   **[OAuth2](/api/attachment/#oauth2)**
-   **[AccessToken](/api/attachment/#accesstoken)**

#### Request Body

[Section titled “Request Body ”](#request-body)

Parameters for searching attachments

Select media typeapplication/json

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

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

List of attachments

Select media typeapplication/json

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

[Section titled “Headers ”](#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

[Section titled “view”](#operation-viewAttachment-get)

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

[Section titled “Authorizations ”](#authorizations)

-   **[OAuth2](/api/attachment/#oauth2)**
-   **[AccessToken](/api/attachment/#accesstoken)**

#### Path Parameters

[Section titled “Path Parameters ”](#path-parameters)

**id**

required

string

File path or attachment\_id (MD5 hash of the path).

#### Query Parameters

[Section titled “Query Parameters ”](#query-parameters)

**mode**

string

default: download

Allowed values: download inline

Delivery mode for the file.

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Attachment found

Select media typeapplication/json

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

[Section titled “404 ”](#404)

Attachment not found

### create

[Section titled “create”](#operation-createAttachment-post)

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

[Section titled “Authorizations ”](#authorizations)

-   **[OAuth2](/api/attachment/#oauth2)**
-   **[AccessToken](/api/attachment/#accesstoken)**

#### Path Parameters

[Section titled “Path Parameters ”](#path-parameters)

**id**

required

string

Destination folder path (e.g. /projects/{project\_id}/offices/{office\_name}/).

#### Request Body

[Section titled “Request Body ”](#request-body)

Select media typemultipart/form-data

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

0

**file**

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

string format: binary

#### Responses

[Section titled “ Responses ”](#responses)

##### 201

[Section titled “201 ”](#201)

Attachment created successfully

Select media typeapplication/json

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

[Section titled “400 ”](#400)

Bad request

##### 409

[Section titled “409 ”](#409)

Destination path already exists

##### 413

[Section titled “413 ”](#413)

File size is too large

##### 500

[Section titled “500 ”](#500)

Failed to create for unknown reason

### update

[Section titled “update”](#operation-updateAttachment-put)

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

[Section titled “Authorizations ”](#authorizations)

-   **[OAuth2](/api/attachment/#oauth2)**
-   **[AccessToken](/api/attachment/#accesstoken)**

#### Path Parameters

[Section titled “Path Parameters ”](#path-parameters)

**id**

required

string

Current file or folder path.

#### Request Body required

[Section titled “Request Body required ”](#request-body)

New path for the file or folder

Select media typeapplication/json

object

**path**

The new file or folder path.

string

##### Example

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

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Attachment updated successfully

Select media typeapplication/json

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

[Section titled “400 ”](#400)

Bad request

##### 404

[Section titled “404 ”](#404)

Attachment not found

##### 409

[Section titled “409 ”](#409)

Destination path already exists

##### 500

[Section titled “500 ”](#500)

Unable to rename file or folder

### delete

[Section titled “delete”](#operation-deleteAttachment-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

[Section titled “Authorizations ”](#authorizations)

-   **[OAuth2](/api/attachment/#oauth2)**
-   **[AccessToken](/api/attachment/#accesstoken)**

#### Path Parameters

[Section titled “Path Parameters ”](#path-parameters)

**id**

required

string

File or folder path to delete.

#### Query Parameters

[Section titled “Query Parameters ”](#query-parameters)

**force**

boolean

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

#### Responses

[Section titled “ Responses ”](#responses)

##### 204

[Section titled “204 ”](#204)

Attachment deleted successfully

##### 400

[Section titled “400 ”](#400)

Preview of linked entities (returned when force=false)

This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply.