Comments API Calls

Task items and Milestones are all the same when it comes to the comments API, you only have to adjust the URL prefix. i.e: ; links, milestones, files, notebooks or tasks.

Retreiving Recent Comments

GET /{resource}/{resource_id}/comments.json

So, to return the recent comments for task item; ID 7, just use:

/tasks/7/comments.json.

By default 20 records are returned at a time. You can pass "page" and "pageSize" to change this:
eg. GET /tasks/7/comments.json?page=2&pageSize=50.

The following headers are returned:

  • X-Records - The total number of replies
  • X-Pages - The total number of pages
  • X-Page - The page you requested

Important Note

When returned comments on a file, the returned commentable_type field is file but the commentable-id field relates to the File Version ID

Response

{
    "comments": [
        {
            "project-id": "999",
            "attachments_count": "0",
            "author-lastname": "User",
            "commentable-id": "999",
            "commentable_type": "todo_items",
            "emailed-from": "",
            "isRead": "1",
            "private": "0",
            "lockdown-id": "",
            "datetime": "2014-03-31T13:03:29Z",
            "author-avatar-url": "https://s3.amazonaws.com/TWFiles/2/users/999.avatar",
            "author_id": "999",
            "id": "999",
            "company-name": "Demo 1 Company",
            "last-changed-on": "",
            "content-type": "HTML",
            "nr-notified-people": "0",
            "type": "task",
            "item-name": "Test Task",
            "attachments-count": "0",
            "_author_id": {
                "deprecated": true
            },
            "company-id": "999",
            "html-body": "A test comment",
            "project-name": "demo",
            "body": "A test comment",
            "commentNo": "1",
            "attachments": [],
            "author-firstname": "Demo",
            "comment-link": "tasks/436523?c=93",
            "author-id": "999"
        }
    ],
    "STATUS": "OK"
}

See Comments in Data Reference Section


Retrieving a Specific Comment

GET /comments/{comment_id}.json

This will get a comment based on the comment's ID

Response

{
    "comment": {
        "project-id": "999",
        "attachments_count": "0",
        "author-lastname": "User",
        "commentable-id": "999",
        "commentable_type": "todo_items",
        "emailed-from": "",
        "isRead": "1",
        "private": "0",
        "lockdown-id": "",
        "datetime": "2014-03-31T13:03:29Z",
        "author-avatar-url": "https://s3.amazonaws.com/TWFiles/2/users/999.avatar",
        "author_id": "999",
        "id": "999",
        "company-name": "Demo 1 Company",
        "content-type": "HTML",
        "last-changed-on": "",
        "nr-notified-people": "0",
        "type": "task",
        "item-name": "Test Task",
        "attachments-count": "0",
        "company-id": "999",
        "html-body": "A test comment",
        "project-name": "demo",
        "body": "A test comment",
        "attachments": [],
        "author-firstname": "Demo",
        "comment-link": "tasks/436523?c=93",
        "numLikes": "0",
        "author-id": "999"
    },
    "STATUS": "OK"
}

See Comments in Data Reference Section


Creating a Comment

POST /{resource}/{resource_id}/comments.json

Creates a new comment, associated with the particular resource. When named in the URL, it can be either posts, tasks, milestones, notebooks, links or fileversions.

Important Note

When creating a comment on a file, the {resource} is fileversions and the {resource_id} is the File Version ID

The notify parameter is set to "" in the example below so no one will be notified of your new comment. This parameter can be set to all to send an email to anyone assigned to the task or following it. You can also use a list of Teamwork User IDs to only notify certain people, but you can't notify yourself.

Request

{
  "comment": {
    "body": "Reply to earlier comment",
    "notify": "",
    "isprivate": false,
    "pendingFileAttachments": "",
    "content-type": "TEXT"
  }
}

See Comments in Data Reference Section

Attaching Files
To attach new files use the pendingFileAttachments option (see the uploading files section for more info).

Content Type

By default comments are created as plain text. To create a HTML comment, pass "content-type":"html" and put your HTML formatted content in the "body" field

Post as another user

You can pass "author-id" as a numeric userId to post the comment as another user if you are an administrator

Response

Returns HTTP status code 201 (“Created”) on success, with the Location header set to the URL for the new comment.

The new comment’s ID can be extracted from that URL. On failure, a non-200 status code will be returned, possibly with error information in JSON format as the response’s content.


Updating a comment

PUT /comments/{id}.json

Update a specific comment. This can be used to edit the content of an existing comment.

Request

{
  "comment": {
    "body": "Reply to earlier comment (edited)",
    "notify": "",
    "isprivate": false,
    "pendingFileAttachments": "",
    "content-type": "TEXT"
  }
}

Content Type

By default comments are created as plain text. To create a HTML comment, pass "content-type":"html" and put your HTML formatted content in the "body" field

See Comments in Data Reference Section

Response

Returns HTTP status code 200 on success, or any other code (and possibly error information in JSON format) on error.


Destroying a comment

DELETE /comments/{id}.json

Fairly self explanatory, deletes the comment from the given ID.

Response

Returns HTTP status code 200 on success.


Mark a comment as read

PUT /comments/{id}/markread.json

Marks a particular comment as read from the point of view of the authenticated user.

Response

Returns HTTP status code 200 on success.


Link to 'Comments' in Data Reference Section