Documentation (2024.2 Enterprise)

# Comment

Comments are snippets of user-created content that are linked to other objects. They are used for discussing and remarking on things that happen in Helix TeamHub.

- Attributes
- Operations
  - `GET /comments`
  - `GET /comments/:id`
  - `POST /comments`
  - `PUT /comments/:id`
  - `DELETE /comments/:id`

## Attributes

### id

A URL-friendly identifier for the comment.

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

### type

The type of the object(s) this comment is targeted.

- Type: `string`
- Required: `true`
- Allowed values: `task`, `comment`

Type defines the target objects for the comment:

Type | Target Object(s)
--- | ---
`comment` | comment
`task` | project, task

### author

The author of the comment. Contains the identifier of a User or a Collaborator.

To get the full object representation of the author instead of just their id, expand it in your request by including the query parameter `expand=author`.

- Type: `string` / `object`

### content

The body of the comment.

- Type: `string`
- Required: `true`
- Minimum length: `1`
- Maximum length: `50000`

### objects

Only used when reading. A hash of object references, showing the target object(s) of the comment. For example: `{"project": "luotsi", "task": 123, ...}`.

- Type: `object`

### project

Only used when writing. If the comment is targeted at a Task (comment `type` is `task`), specify the project's identifier.

- Type: `string`

### task

Only used when writing. If the comment is targeted at a Task (comment `type` is `task`), specify the task's identifier.

- Type: `integer`

### comment

Only used when writing. If the comment is a response to another comment (`type` is `comment`), specify the other comment's identifier. Only one level of nested replies is supported.

- Type: `string`

### timestamp

The date and time when the comment was posted, in ISO-8601 format.

- Type: `timestamp`

## Operations

### GET /comments

Get all comments for the company. Results may be limited with query parameters. Returned as a metadata-results object.

#### Example Request

Get 2 latest comments for a task.

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/comments?project=luotsi&task=1&limit=2

#### Example Response

    {
      "metadata": {
        "more_results": true,
        "next_offset": 2,
        "total_count": null,
        "count": 2
      },
      "results": [
        {
          "api_status": 200,
          "api_timestamp": "2012-10-25T10:19:24Z",
          "id": "5087f00b1229c02952000034",
          "created_at": "2012-10-24T13:41:31Z",
          "updated_at": "2012-10-24T13:41:31Z",
          "type": "task",
          "author": {
            "id": "avesalainen"
          },
          "content": "fiifoo",
          "objects": {
            "task": {
              "id": 1
            },
            "project": {
              "id": "luotsi"
            }
          },
          "timestamp": "2012-10-24T13:41:31Z"
        },
        {
          "api_status": 200,
          "api_timestamp": "2012-10-25T10:19:24Z",
          "id": "5367a96234be9557910001bc",
          "created_at": "2012-09-24T08:42:10Z",
          "updated_at": "2012-09-24T08:42:10Z",
          "type": "task",
          "author": {
            "id": "jp"
          },
          "content": "This has now been fixed.",
          "objects": {
            "task": {
              "id": 1
            },
            "project": {
              "id": "luotsi"
            }
          },
          "timestamp": "2012-09-24T08:42:10Z"
        }
      ]
    }

### GET /comments/:comment_id

Get a specific comment.

### POST /comments

Create a new comment.

#### Example Request

Create a comment for an Task.

    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 '{ "content": "This has now been fixed.", "project": "luotsi", "task": "1", "type": "task" }' \
      https://helixteamhub.cloud/api/comments

#### Example Response

    {
      "api_status": 201,
      "api_timestamp": "2012-09-24T08:42:10Z",
      "id": "5367a96234be9557910001bc",
      "created_at": "2012-09-24T08:42:10Z",
      "updated_at": "2012-09-24T08:42:10Z",
      "type": "task",
      "author": {
        "id": "jp"
      },
      "content": "This has now been fixed.",
      "objects": {
        "task": {
          "id": 1
        },
        "project": {
          "id": "luotsi"
        }
      },
      "timestamp": "2012-09-24T08:42:10Z"
    }

### PUT /comments/:id

Updates a comment. Returns the updated comment object.

#### Example Request

    curl -X PUT \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "content": "hello" }' \
      https://helixteamhub.cloud/api/comments/5367a96234be9557910001bc

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2012-10-25T10:24:55Z",
      "id": "5367a96234be9557910001bc",
      "created_at": "2012-10-25T10:24:55Z",
      "updated_at": "2012-10-25T10:32:21Z",
      "type": "task",
      "author": {
        "id": "jp"
      },
      "content": "hello",
      "objects": {
        "task": {
          "id": 1
        },
        "project": {
          "id": "luotsi"
        }
      },
      "timestamp": "2012-10-25T10:24:55Z"
    }

### DELETE /comments/:id

Deletes a comment. Returns the deleted comment object.

#### Example Request

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

Your search for returned results

Your search for returned results