Documentation (2024.2 Enterprise)

# Attachment

Attachments are files related to other objects. Currently only Tasks, Code Reviews, Multi-Repo Code Reviews, and Comments can have attachments.

- Attributes
- Request Parameters
- Operations
  - `GET /attachments`
  - `GET /attachments/:id`
  - `POST /attachments`
  - PUT /attachments/:id
  - `DELETE /attachments/:id`

## Attributes

### id

Universally unique identifier (UUID).

- Type: `string`
- Immutable: `true`
- Unique: `true`

### name

Original filename of the attachment.

- Type: `string`

### mime

Detected MIME-type of the attachment.

- Type: `string`

### size

Size of the attachment in bytes.

- Type: `integer`

### path

Full URL for accessing the content of the attachment.

- Type: `string`

### versions

List of available versions of the attachment.

- Type: array

### creator

Creator of the attachment. Can be expanded to get the full User or Collaborator object by including the query parameter `expand=creator` in the request.

- Type: `string` / `object`

## Request Parameters

### content

The content of the image.

- Type: `multipart/form-data` or Base64 encoded attachment
- Required: `true`

### name

The image filename.

- Type: `string`
- Required: `true` with Base64 encoded attachment, `false` with `multipart/form-data`

### encoding

The encoding of `content`.

- Type: `string`
- Required: `true` with Base64 encoded attachment, `false` with `multipart/form-data`
- Allowed values: `"base64"`

## Operations

### GET /attachments

Returns metadata for attachments within the company scope, with optional limit and offset parameters, as a metadata-results object. The scope of the result set can be limited to a specific resource called attachable by adding attachable_type and attachable_id query params. The attachable can be defined by attachable_type (one of: task, code_review, multi_code_review, or comment) and identified by the uuid attribute (id for Comments).

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/attachments

#### Example Response

    {
       "metadata": {
           "more_results": false,
           "next_offset": 3,
           "total_count": null,
           "count": 3
       },
       "results": [
           {
               "api_status": 200,
               "api_timestamp": "2019-03-08T10:35:27Z",
               "id": "2dbd4ceb-aec7-416b-8db6-b9d84174e7a7",
               "created_at": "2019-02-18T10:09:05Z",
               "updated_at": "2019-02-18T10:09:05Z",
               "name": "Screen Shot 2019-01-31 at 16.17.46.png",
               "mime": "image/png",
               "size": 377776,
               "path": "https://helixteamhub.cloud/api/attachments/2dbd4ceb-aec7-416b-8db6-b9d84174e7a7",
               "versions": [
                   "thumb"
               ],
               "attachable": {
                   "id": 1,
                   "uuid": "b98d1709-22b0-42af-b8ef-460e5f5712a2"
               },
               "attachable_type": "task",
               "creator": {
                   "id": "admin",
                   "uuid": "eaa8f420-0538-43ac-8440-10e22f2d2ba5",
                   "type": "user"
               }
           },
           {
               "api_status": 200,
               "api_timestamp": "2019-03-08T10:35:27Z",
               "id": "13fc0634-b196-4f09-a205-8f1292daa7f6",
               "created_at": "2019-02-21T19:12:39Z",
               "updated_at": "2019-02-21T19:12:39Z",
               "name": "Screen Shot 2019-02-20 at 14.16.04.png",
               "mime": "image/png",
               "size": 206154,
               "path": "https://helixteamhub.cloud/api/attachments/13fc0634-b196-4f09-a205-8f1292daa7f6",
               "versions": [
                   "thumb"
               ],
               "attachable": null,
               "attachable_type": null,
               "creator": {
                   "id": "admin",
                   "uuid": "eaa8f420-0538-43ac-8440-10e22f2d2ba5",
                   "type": "user"
               }
           },
           {
               "api_status": 200,
               "api_timestamp": "2019-03-08T10:35:27Z",
               "id": "c1a4ff95-add5-4b76-905f-de453059da1d",
               "created_at": "2019-02-26T22:19:02Z",
               "updated_at": "2019-02-27T00:04:12Z",
               "name": "Screen Shot 2019-02-26 at 21.31.25.png",
               "mime": "image/png",
               "size": 168657,
               "path": "https://helixteamhub.cloud/api/attachments/c1a4ff95-add5-4b76-905f-de453059da1d",
               "versions": [
                   "thumb"
               ],
               "attachable": {
                   "id": "5c75bb5a222b8044636224a5"
               },
               "attachable_type": "comment",
               "creator": {
                   "id": "admin",
                   "uuid": "eaa8f420-0538-43ac-8440-10e22f2d2ba5",
                   "type": "user"
               }
           }
        ]

    }

### GET /attachments/:id

Returns actual content for the attachment.

#### Example Request

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/attachments/40d7312d-1ed9-4559-b98a-60c6bcdb2e5b

### POST /attachments

Creates a new attachment. Returns metadata of the created attachment.

Content of the attachment can be UTF-8 (default) or Base64 encoded with optional data header. The endpoint also accepts multipart/form-data content-type, which may be needed when dealing with larger files.

#### Example Requests

##### JSON

    curl -X POST \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "content": "Fatal error", "name": "error.log" }' \
      https://helixteamhub.cloud/api/attachments

##### JSON with Base64 encoded content

    curl -X POST \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "encoding": "base64", "content": "RmF0YWwgZXJyb3I=", "name": "error.log" }' \
      https://helixteamhub.cloud/api/attachments

##### Multipart/form-data

    curl -X POST \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -F "content=@screenshot.jpg" \
      https://helixteamhub.cloud/api/attachments

#### Example Response

    {
       "api_status": 200,
       "api_timestamp": "2019-03-08T10:35:27Z",
       "id": "2dbd4ceb-aec7-416b-8db6-b9d84174e7a7",
       "created_at": "2019-02-18T10:09:05Z",
       "updated_at": "2019-02-18T10:09:05Z",
       "name": "Screen Shot 2019-01-31 at 16.17.46.png",
       "mime": "image/png",
       "size": 377776,
       "path": "https://helixteamhub.cloud/api/attachments/2dbd4ceb-aec7-416b-8db6-b9d84174e7a7",
       "versions": [
           "thumb"
       ],
       "attachable": {
           "id": 1,
           "uuid": "b98d1709-22b0-42af-b8ef-460e5f5712a2"
       },
       "attachable_type": "task",
       "creator": {
           "id": "admin",
           "uuid": "eaa8f420-0538-43ac-8440-10e22f2d2ba5",
           "type": "user"
       }
    }

### PUT /attachments/:id

Updates the attachment. Returns the updated attachment object.

#### Example Requests

##### JSON

    curl -X PUT \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "attachable_type": "code_review", "attachable_id": "4b67646b-7ee8-4302-a1e1-3ad2acef469a" }' \
      https://helixteamhub.cloud/api/attachments/1f1baf44-abf7-43b7-bd72-cc546cbfb094

#### Example Response

    {
       "api_status": 200,
       "api_timestamp": "2019-03-08T11:13:33Z",
       "id": "1f1baf44-abf7-43b7-bd72-cc546cbfb094",
       "created_at": "2019-02-28T02:04:29Z",
       "updated_at": "2019-03-08T11:13:33Z",
       "name": "Screen Shot 2019-02-25 at 10.19.35.png",
       "mime": "image/png",
       "size": 42371,
       "path": "https://helixteamhub.cloud/api/attachments/1f1baf44-abf7-43b7-bd72-cc546cbfb094",
       "versions": [
           "thumb"
       ],
       "attachable": {
           "id": 1,
           "uuid": "4b67646b-7ee8-4302-a1e1-3ad2acef469a"
       },
       "attachable_type": "code_review",
       "creator": {
           "id": "admin",
           "uuid": "eaa8f420-0538-43ac-8440-10e22f2d2ba5",
           "type": "user"
       }
    }

### DELETE /attachments/:id

Deletes an attachment. Returns metadata about the deleted attachment.

#### Example Request

    curl -X DELETE \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/attachments/40d7312d-1ed9-4559-b98a-60c6bcdb2e5

Your search for returned results

Your search for returned results