{ "swagger": "2.0", "info": { "title": "Comments service", "version": "0.1507.0", "description": "Send your API key as a bearer token: `Authorization: Bearer `." }, "consumes": [ "application/json" ], "produces": [ "application/json" ], "securityDefinitions": { "ApiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Your API key as a bearer token: `Authorization: Bearer `." } }, "security": [ { "ApiKey": [] } ], "paths": { "/comments/v1/conversations/{resourceType}/{resourceRid}": { "get": { "operationId": "CommentsService_getConversation", "summary": "Get conversation", "tags": [ "Comments Service" ], "description": "A conversation is a fully resolved comment tree. It includes all comments for the given resource and all the nested comments/replies to those comments.", "parameters": [ { "name": "resourceType", "in": "path", "type": "string", "enum": [ "RUN", "EVENT" ], "required": true, "description": "The type of resource that the comments are associated with" }, { "name": "resourceRid", "in": "path", "type": "string", "format": "rid", "required": true, "description": "The RID of resource that the comments are associated with" } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/Conversation" }, "x-example": { "resourceRid": "", "resourceType": "RUN", "comments": [ { "comment": { "rid": "", "parent": { "type": "resource", "resource": { "resourceType": "RUN", "resourceRid": "" } }, "authorRid": "", "createdAt": "2026-01-01T00:00:00Z", "editedAt": "2026-01-01T00:00:00Z", "deletedAt": "2026-01-01T00:00:00Z", "content": "", "pinnedBy": "", "pinnedAt": "2026-01-01T00:00:00Z", "reactions": [ { "rid": "", "userRid": "", "createdAt": "2026-01-01T00:00:00Z", "type": "LIKE" } ], "attachments": [ "" ] }, "replies": [] } ] } } } } }, "/comments/v1/conversations/{resourceType}/{resourceRid}/count": { "get": { "operationId": "CommentsService_getConversationCount", "summary": "Get conversation count", "tags": [ "Comments Service" ], "description": "Returns the number of comments in a conversation.", "parameters": [ { "name": "resourceType", "in": "path", "type": "string", "enum": [ "RUN", "EVENT" ], "required": true, "description": "The type of resource that the comments are associated with" }, { "name": "resourceRid", "in": "path", "type": "string", "format": "rid", "required": true, "description": "The RID of resource that the comments are associated with" }, { "name": "includeDeleted", "in": "query", "type": "boolean", "required": false, "description": "Whether to include deleted comments in the count" } ], "responses": { "200": { "description": "A successful response.", "schema": { "type": "integer", "format": "int32" }, "x-example": 1 } } } }, "/comments/v1/comments/{commentRid}": { "get": { "operationId": "CommentsService_getComment", "summary": "Get comment", "tags": [ "Comments Service" ], "description": "Get a comment identified by its RID", "parameters": [ { "name": "commentRid", "in": "path", "type": "string", "format": "rid", "x-alias": "CommentRid", "required": true, "description": "The RID of comment to fetch" } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/Comment" }, "x-example": { "rid": "", "parent": { "type": "resource", "resource": { "resourceType": "RUN", "resourceRid": "" } }, "authorRid": "", "createdAt": "2026-01-01T00:00:00Z", "editedAt": "2026-01-01T00:00:00Z", "deletedAt": "2026-01-01T00:00:00Z", "content": "", "pinnedBy": "", "pinnedAt": "2026-01-01T00:00:00Z", "reactions": [ { "rid": "", "userRid": "", "createdAt": "2026-01-01T00:00:00Z", "type": "LIKE" } ], "attachments": [ "" ] } } } }, "put": { "operationId": "CommentsService_editComment", "summary": "Edit comment", "tags": [ "Comments Service" ], "description": "Edit an existing comment", "parameters": [ { "name": "commentRid", "in": "path", "type": "string", "format": "rid", "x-alias": "CommentRid", "required": true, "description": "The RID of comment to edit" }, { "name": "request", "in": "body", "schema": { "$ref": "#/definitions/EditCommentRequest" }, "required": true, "x-example": { "content": "" } } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/Comment" }, "x-example": { "rid": "", "parent": { "type": "resource", "resource": { "resourceType": "RUN", "resourceRid": "" } }, "authorRid": "", "createdAt": "2026-01-01T00:00:00Z", "editedAt": "2026-01-01T00:00:00Z", "deletedAt": "2026-01-01T00:00:00Z", "content": "", "pinnedBy": "", "pinnedAt": "2026-01-01T00:00:00Z", "reactions": [ { "rid": "", "userRid": "", "createdAt": "2026-01-01T00:00:00Z", "type": "LIKE" } ], "attachments": [ "" ] } } } }, "delete": { "operationId": "CommentsService_deleteComment", "summary": "Delete comment", "tags": [ "Comments Service" ], "description": "Delete an existing comment", "parameters": [ { "name": "commentRid", "in": "path", "type": "string", "format": "rid", "x-alias": "CommentRid", "required": true, "description": "The RID of comment to delete" } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/Comment" }, "x-example": { "rid": "", "parent": { "type": "resource", "resource": { "resourceType": "RUN", "resourceRid": "" } }, "authorRid": "", "createdAt": "2026-01-01T00:00:00Z", "editedAt": "2026-01-01T00:00:00Z", "deletedAt": "2026-01-01T00:00:00Z", "content": "", "pinnedBy": "", "pinnedAt": "2026-01-01T00:00:00Z", "reactions": [ { "rid": "", "userRid": "", "createdAt": "2026-01-01T00:00:00Z", "type": "LIKE" } ], "attachments": [ "" ] } } } } }, "/comments/v1/comments": { "post": { "operationId": "CommentsService_createComment", "summary": "Create comment", "tags": [ "Comments Service" ], "description": "Create a comment on a resource", "parameters": [ { "name": "request", "in": "body", "schema": { "$ref": "#/definitions/CreateCommentRequest" }, "required": true, "x-example": { "parent": { "type": "resource", "resource": { "resourceType": "RUN", "resourceRid": "" } }, "content": "" } } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/Comment" }, "x-example": { "rid": "", "parent": { "type": "resource", "resource": { "resourceType": "RUN", "resourceRid": "" } }, "authorRid": "", "createdAt": "2026-01-01T00:00:00Z", "editedAt": "2026-01-01T00:00:00Z", "deletedAt": "2026-01-01T00:00:00Z", "content": "", "pinnedBy": "", "pinnedAt": "2026-01-01T00:00:00Z", "reactions": [ { "rid": "", "userRid": "", "createdAt": "2026-01-01T00:00:00Z", "type": "LIKE" } ], "attachments": [ "" ] } } } } }, "/comments/v1/comments/{commentRid}/pin": { "put": { "operationId": "CommentsService_pinComment", "summary": "Pin comment", "tags": [ "Comments Service" ], "description": "Pin a comment to the top of the conversation", "parameters": [ { "name": "commentRid", "in": "path", "type": "string", "format": "rid", "x-alias": "CommentRid", "required": true, "description": "The RID of comment to pin" } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/Comment" }, "x-example": { "rid": "", "parent": { "type": "resource", "resource": { "resourceType": "RUN", "resourceRid": "" } }, "authorRid": "", "createdAt": "2026-01-01T00:00:00Z", "editedAt": "2026-01-01T00:00:00Z", "deletedAt": "2026-01-01T00:00:00Z", "content": "", "pinnedBy": "", "pinnedAt": "2026-01-01T00:00:00Z", "reactions": [ { "rid": "", "userRid": "", "createdAt": "2026-01-01T00:00:00Z", "type": "LIKE" } ], "attachments": [ "" ] } } } }, "delete": { "operationId": "CommentsService_unpinComment", "summary": "Unpin comment", "tags": [ "Comments Service" ], "description": "Unpin a comment from the top of the conversation", "parameters": [ { "name": "commentRid", "in": "path", "type": "string", "format": "rid", "x-alias": "CommentRid", "required": true, "description": "The RID of comment to unpin" } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/Comment" }, "x-example": { "rid": "", "parent": { "type": "resource", "resource": { "resourceType": "RUN", "resourceRid": "" } }, "authorRid": "", "createdAt": "2026-01-01T00:00:00Z", "editedAt": "2026-01-01T00:00:00Z", "deletedAt": "2026-01-01T00:00:00Z", "content": "", "pinnedBy": "", "pinnedAt": "2026-01-01T00:00:00Z", "reactions": [ { "rid": "", "userRid": "", "createdAt": "2026-01-01T00:00:00Z", "type": "LIKE" } ], "attachments": [ "" ] } } } } }, "/comments/v1/comments/{commentRid}/reactions/{type}": { "put": { "operationId": "CommentsService_addReaction", "summary": "Add reaction", "tags": [ "Comments Service" ], "description": "Create a reaction on a comment", "parameters": [ { "name": "commentRid", "in": "path", "type": "string", "format": "rid", "x-alias": "CommentRid", "required": true, "description": "The RID of comment to delete" }, { "name": "type", "in": "path", "type": "string", "enum": [ "LIKE", "DISLIKE", "HEART", "HOORAY", "ROCKET", "EYES" ], "required": true, "description": "The type of reaction" } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/Comment" }, "x-example": { "rid": "", "parent": { "type": "resource", "resource": { "resourceType": "RUN", "resourceRid": "" } }, "authorRid": "", "createdAt": "2026-01-01T00:00:00Z", "editedAt": "2026-01-01T00:00:00Z", "deletedAt": "2026-01-01T00:00:00Z", "content": "", "pinnedBy": "", "pinnedAt": "2026-01-01T00:00:00Z", "reactions": [ { "rid": "", "userRid": "", "createdAt": "2026-01-01T00:00:00Z", "type": "LIKE" } ], "attachments": [ "" ] } } } }, "delete": { "operationId": "CommentsService_removeReaction", "summary": "Remove reaction", "tags": [ "Comments Service" ], "description": "Create a reaction on a comment", "parameters": [ { "name": "commentRid", "in": "path", "type": "string", "format": "rid", "x-alias": "CommentRid", "required": true, "description": "The RID of comment to delete" }, { "name": "type", "in": "path", "type": "string", "enum": [ "LIKE", "DISLIKE", "HEART", "HOORAY", "ROCKET", "EYES" ], "required": true, "description": "The type of reaction" } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/Comment" }, "x-example": { "rid": "", "parent": { "type": "resource", "resource": { "resourceType": "RUN", "resourceRid": "" } }, "authorRid": "", "createdAt": "2026-01-01T00:00:00Z", "editedAt": "2026-01-01T00:00:00Z", "deletedAt": "2026-01-01T00:00:00Z", "content": "", "pinnedBy": "", "pinnedAt": "2026-01-01T00:00:00Z", "reactions": [ { "rid": "", "userRid": "", "createdAt": "2026-01-01T00:00:00Z", "type": "LIKE" } ], "attachments": [ "" ] } } } } } }, "definitions": { "Comment": { "type": "object", "properties": { "rid": { "type": "string", "format": "rid", "x-alias": "CommentRid", "description": "Unique resource identifier for the comment" }, "parent": { "allOf": [ { "$ref": "#/definitions/CommentParent" } ], "description": "The parent of the comment. It can be a resource or another comment." }, "authorRid": { "type": "string", "format": "rid", "description": "The user who authored the comment" }, "createdAt": { "type": "string", "format": "date-time", "description": "The time the comment was created" }, "editedAt": { "type": "string", "format": "date-time", "description": "The time the comment was edited. Empty if the comment has not been edited." }, "deletedAt": { "type": "string", "format": "date-time", "description": "The time the comment was deleted. Empty if the comment has not been deleted." }, "content": { "type": "string", "description": "The markdown content of the comment." }, "pinnedBy": { "type": "string", "format": "rid", "description": "The user who pinned the comment. Empty if the comment is not pinned." }, "pinnedAt": { "type": "string", "format": "date-time", "description": "The time the comment was pinned. Empty if the comment is not pinned." }, "reactions": { "type": "array", "items": { "$ref": "#/definitions/Reaction" }, "description": "The reactions on the comment" }, "attachments": { "type": "array", "items": { "type": "string", "format": "rid", "x-alias": "AttachmentRid" }, "uniqueItems": true, "description": "The comment's attachments" } }, "required": [ "rid", "parent", "authorRid", "createdAt", "content" ] }, "CommentParent": { "description": "The parent of a comment. It can be a resource or another comment in the case of a reply.\n\nSet `type` to the name of one of the other fields, and set only that field.", "type": "object", "x-union": true, "properties": { "type": { "type": "string", "enum": [ "resource", "comment" ] }, "resource": { "$ref": "#/definitions/CommentParentResource" }, "comment": { "$ref": "#/definitions/CommentParentComment" } }, "required": [ "type" ], "example": { "type": "resource", "resource": { "resourceType": "RUN", "resourceRid": "string" } } }, "CommentParentComment": { "type": "object", "properties": { "commentRid": { "type": "string", "format": "rid", "x-alias": "CommentRid", "description": "The resource identifier for the comment that the comment is replying to" } }, "required": [ "commentRid" ] }, "CommentParentResource": { "type": "object", "properties": { "resourceType": { "allOf": [ { "$ref": "#/definitions/ResourceType" } ], "description": "The type of resource that the comment is associated with" }, "resourceRid": { "type": "string", "format": "rid", "description": "The resource identifier for the resource that the comment is associated with. For example, a run or a workbook." } }, "required": [ "resourceType", "resourceRid" ] }, "Conversation": { "type": "object", "properties": { "resourceRid": { "type": "string", "format": "rid", "description": "RID for the resource that the conversation is associated with." }, "resourceType": { "allOf": [ { "$ref": "#/definitions/ResourceType" } ], "description": "The type of the resource that the conversation is associated with." }, "comments": { "type": "array", "items": { "$ref": "#/definitions/ConversationNode" }, "description": "The comments on the conversation ordered by creation time. Empty if the comment has no replies." } }, "required": [ "resourceRid", "resourceType" ] }, "ConversationNode": { "type": "object", "properties": { "comment": { "allOf": [ { "$ref": "#/definitions/Comment" } ], "description": "The comment" }, "replies": { "type": "array", "items": { "$ref": "#/definitions/ConversationNode" }, "description": "The comments on (aka replies to) the comment ordered by creation time. Empty if the comment has no replies." } }, "required": [ "comment" ] }, "CreateCommentRequest": { "type": "object", "properties": { "parent": { "$ref": "#/definitions/CommentParent" }, "content": { "type": "string", "description": "The content of the comment. Markdown supported." }, "attachments": { "type": "array", "items": { "type": "string", "format": "rid", "x-alias": "AttachmentRid" }, "uniqueItems": true, "description": "Attachments to the comment." } }, "required": [ "parent", "content" ], "example": { "parent": { "type": "resource", "resource": { "resourceType": "RUN", "resourceRid": "" } }, "content": "" } }, "EditCommentRequest": { "type": "object", "properties": { "content": { "type": "string", "description": "The content of the comment. Markdown supported." }, "attachments": { "type": "array", "items": { "type": "string", "format": "rid", "x-alias": "AttachmentRid" }, "uniqueItems": true, "description": "Attachments to the comment." } }, "required": [ "content" ], "example": { "content": "" } }, "Reaction": { "type": "object", "properties": { "rid": { "type": "string", "format": "rid", "x-alias": "ReactionRid", "description": "Unique resource identifier for the reaction" }, "userRid": { "type": "string", "format": "rid", "description": "The user who authored the reaction" }, "createdAt": { "type": "string", "format": "date-time", "description": "The time the reaction was created" }, "type": { "allOf": [ { "$ref": "#/definitions/ReactionType" } ], "description": "The type of reaction" } }, "required": [ "rid", "userRid", "createdAt", "type" ] }, "ReactionType": { "type": "string", "enum": [ "LIKE", "DISLIKE", "HEART", "HOORAY", "ROCKET", "EYES" ] }, "ResourceType": { "type": "string", "enum": [ "RUN", "EVENT" ] } }, "tags": [ { "name": "Comments Service", "x-displayName": "Comments service", "description": "Comments service manages conversations about resources.", "x-errors": [ { "status": 404, "errorCode": "NOT_FOUND", "errorName": "Comments:CommentNotFound" }, { "status": 400, "errorCode": "INVALID_ARGUMENT", "errorName": "Comments:InvalidAttachment" }, { "status": 400, "errorCode": "INVALID_ARGUMENT", "errorName": "Comments:EmptyCommentContent" }, { "status": 400, "errorCode": "INVALID_ARGUMENT", "errorName": "Comments:MaxNestingDepthExceeded" }, { "status": 403, "errorCode": "PERMISSION_DENIED", "errorName": "Comments:Unauthorized" }, { "status": 400, "errorCode": "INVALID_ARGUMENT", "errorName": "Comments:ContentTooLong" } ] } ] }