Comments API calls

The comments API is identical for Messages, Milestones, Tasks, Notes, Writeboards, Links and Files, the only difference being the resource named in URL prefix. This can be one of "messages", "milestones", "tasks", "notes", "writeboards", "links" and "files", respectively. In the documentation that follows, the generic "#{resource}" should be replaced with the resource you are acting on.

Get comments (for a commentable resource)

GET /#{resource}/#{resource_id}/comments/#{page}

Return a list of the 50 most recent comments associated with the specified resource, where the resource named in the URL can be one of messages, milestones, tasks, notes, writeboards, links and files. The {page} parameter is optional. For example, to fetch the most recent comments for the task item with an id of 1, you would use the path: /tasks/1/comments.
The root element has a “count” attribute specifying the total number of comments for the resource. If there are older comments not included in the response, the root response element will also have a “continued-at” attribute specifying the path where the next oldest 50 comments can be retrieved.

Response

{
	"count":67,
	"continued-at":"/tasks/1/comments/2",
	"comments":[
		{
			"id":"96206006",
			"project-id":"136913055",
			...
		},
		{
			"id":"98934083",
			"project-id":"74130260",
			...
		},
		...
	]
}

Get comment

GET /comments/#{comment_id}

Retrieve a specific comment by its ID.

Response

{
	"comment":{
		"id":"96206006",
		"project-id":"136913055",
		...
	}
}

Create comment (for a commentable resource)

POST /#{resource}/#{resource_id}/comments

Create a new comment, associating it with a specific resource, where the resource named in the URL can be one of messages, milestones, tasks, notes, writeboards, links or files. For example, to create a comment for the milestone with an ID of 1, you would use the path: /milestones/1/comments. Note that you can also upload files using this function, but you need to upload the files first and then attach them.

Request

{
	"comment":{
		"body":"This is a comment",
		"is-private":"1", // 0 = public, 1 = private
		"attachments":["3478383", "94937493"],
		// Only post this field if you want to attach your comment to a 
		// specific revision of a writeboard
		"writeboard-revision-number":"3"
	}
}

Response

Returns HTTP status code 201 (“Created”) on success. The response contain the new comment ID. On failure, a non-200 status code will be returned, possibly with error information in JSON format as the response's content.

{
	"comment-id":"46899628"
}

Update comment

PUT /comments/#{id}

Update a specific comment. Note that you can also upload files using this function, but you need to upload the files first and then attach them.

Request

{
	"comment":{
		"body":"Updated comment",
		"is-private":"0", // 0 = public, 1 = private
		"attachments":["46897728"]
	}
}

Response

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

Destroy comment

DELETE /comments/#{id}

Delete the comment with the given ID.

Response

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