Table of contents

Comments API

Comments API allows users to comment on any item in the GrayMeta Platform. The target item is defined by the target_type and target_id fields, which together can refer to any item. The primary use case is for commenting on items, where target_type is "item".

Creating a comment

To create a comment, send a request:

POST /api/data/comments
{
    "target_type": "{target_type}",
    "target_id": "{target_id}",
    "body": "{body}",
    "time_marker": {time_marker}
}
  • {target_type} - (string) Type of the target (e.g. item)
  • {target_id} - (string) ID of the target
  • {body} - (string) Body of the comment to add
  • {time_marker} (string) Optional time marker in hh:mm:ss:ms format

Both target_type and target_id cannot be longer than 32 characters. Field body can be various size. Markdown is an acceptable input for body, although some HTML tags could be stripped if considered dangerous. Time marker can range from 00:00:00:00 to 99:59:59:99.

The response will be a JSON document with single comment created, e.g.:

{
	"id": "58bf31b6dd76f671d748346e2d701f60",
	"target_type": "item",
	"target_id": "07690219bd7a33d2671531daa46c2b2d",
	"body": "Comment with time marker!",
	"ctime": "2017-03-07T22:18:30.99403Z",
	"author": {
		"id": "58bf3103d9eb050f98c9c0ec6f177111",
		"email": "jdoe@example.com",
		"first_name": "John",
		"last_name": "Doe",
		"enabled": true,
		"company_uid": ""
	},
	"deleted": false,
	"time_marker": "00:04:23:87"
}

Getting comments

To get list of comments for specific target type and ID:

GET /api/data/comments?target_type={target_type}&target_id={target_id}&page={page_number}
  • {target_type} - (string) Type of target (e.g. item)
  • {target_id} - (string) ID of the target (usually UUID type)
  • {page_number} - (int) Zero-indexed page number

The response will be a JSON document containing the page number, comments and author information for each comment, e.g.:

{
	"page": 0,
	"comments": [
		{
			"id": "58bf31b6dd76f671d748346e2d701f60",
			"target_type": "item",
			"target_id": "07690219bd7a33d2671531daa46c2b2d",
			"body": "Comment with time marker!",
			"ctime": "2017-03-07T22:18:30.99403Z",
			"author": {
				"id": "58bf3103d9eb050f98c9c0ec6f177111",
				"email": "jdoe@example.com",
				"first_name": "John",
				"last_name": "Doe",
				"enabled": true,
				"company_uid": ""
			},
			"deleted": false,
			"time_marker": "00:04:23:87"
		},
		{
			"id": "58bf31ef481ccf895a85a0e6eca63d54",
			"target_type": "item",
			"target_id": "07690219bd7a33d2671531daa46c2b2d",
			"body": "Another comment...",
			"ctime": "2017-03-07T22:19:27.676069Z",
			"author": {
				"id": "58bf3103d9eb050f98c9c0ec6f177111",
				"email": "jdoe@example.com",
				"first_name": "John",
				"last_name": "Doe",
				"enabled": true,
				"company_uid": ""
			},
			"deleted": false,
			"time_marker": ""
		}
	]
}

Deleting a comment

To delete a comment:

DELETE /api/data/comments/{comment_id}
  • {comment_id} - (string) A comment ID to be deleted

Response will contain HTTP status 200 if deleting a comment is successful. Only the comment author and admins can remove comments.

Updating a comment

To update a comment, send a request containing fields from original comment with new body:

PUT /api/data/comments
{
    "id": "{id}",
    "body": "{new_body}",
    "target_type": "{target_type}",
    "target_id": "{target_id}",
    "author": {
        "id": "{author_id}"
    }
}
  • {id} - (string) ID of original comment to update
  • {new_body} - (string) Updated body of comment
  • {target_type} - (string) Type of the target
  • {target_id} - (string) ID of the target
  • {author_id} - (string) The only required field from original author JSON field

Only the comment author and admins can do that operation.

Sample response:

{
	"id": "58bf328ab55f8b7b299d9734714aa1ba",
	"parent_id": "58bf31ef481ccf895a85a0e6eca63d54",
	"target_type": "item",
	"target_id": "07690219bd7a33d2671531daa46c2b2d",
	"body": "Modified comment.",
	"ctime": "2017-03-07T22:22:02.851359Z",
	"author": {
		"id": "58bf3103d9eb050f98c9c0ec6f177111",
		"email": "jdoe@example.com",
		"first_name": "John",
		"last_name": "Doe",
		"enabled": true,
		"company_uid": ""
	},
	"deleted": false,
	"time_marker": ""
}

Getting the edit history of a comment

To get the comment history for modified comment, send a request:

GET /api/data/comments/{comment_id}/history
  • {comment_id} - ID of the comment to get the edit history from

The response will be a JSON document with all comment modifications, sorted by date; e.g.:

{
	"page": 0,
	"comments": [
		{
			"id": "58bf31ef481ccf895a85a0e6eca63d54",
			"target_type": "item",
			"target_id": "07690219bd7a33d2671531daa46c2b2d",
			"body": "Another comment...",
			"ctime": "2017-03-07T22:19:27.676069Z",
			"author": {
				"id": "58bf3103d9eb050f98c9c0ec6f177111",
				"email": "jdoe@example.com",
				"first_name": "John",
				"last_name": "Doe",
				"enabled": true,
				"company_uid": ""
			},
			"deleted": true,
			"time_marker": ""
		},
		{
			"id": "58bf328ab55f8b7b299d9734714aa1ba",
			"target_type": "item",
			"target_id": "07690219bd7a33d2671531daa46c2b2d",
			"body": "Modified comment.",
			"ctime": "2017-03-07T22:22:02.851359Z",
			"author": {
				"id": "58bf3103d9eb050f98c9c0ec6f177111",
				"email": "jdoe@example.com",
				"first_name": "John",
				"last_name": "Doe",
				"enabled": true,
				"company_uid": ""
			},
			"deleted": true,
			"time_marker": ""
		}
	]
}

This documentation is generated from the latest version of GrayMeta Platform. For documentation relevant to your own deployed version, please use the documentation inside the application.