{ "swagger": "2.0", "info": { "title": "Comments service", "version": "0.1507.0", "description": "Send your API key as a bearer token: `Authorization: Bearer `." }, "tags": [ { "name": "CommentsService", "x-displayName": "Comments service", "description": "Comments service manages conversations about resources.", "x-errors": [ { "status": 404, "errorCode": "NOT_FOUND", "errorName": "NominalCommentsV1:CommentsErrorCommentNotFound", "message": "CommentNotFound" }, { "status": 400, "errorCode": "INVALID_ARGUMENT", "errorName": "NominalCommentsV1:CommentsErrorContentTooLong", "message": "ContentTooLong" }, { "status": 400, "errorCode": "INVALID_ARGUMENT", "errorName": "NominalCommentsV1:CommentsErrorEmptyCommentContent", "message": "EmptyCommentContent" }, { "status": 400, "errorCode": "INVALID_ARGUMENT", "errorName": "NominalCommentsV1:CommentsErrorInvalidAttachment", "message": "InvalidAttachment" }, { "status": 400, "errorCode": "INVALID_ARGUMENT", "errorName": "NominalCommentsV1:CommentsErrorMaxNestingDepthExceeded", "message": "MaxNestingDepthExceeded" }, { "status": 403, "errorCode": "PERMISSION_DENIED", "errorName": "NominalCommentsV1:CommentsErrorUnauthorized", "message": "Unauthorized" }, { "status": 400, "errorCode": "INVALID_ARGUMENT", "errorName": "NominalCommentsV1:CommentsErrorInvalidArgument", "message": "InvalidArgument" } ] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/comments/v2/comments": { "post": { "operationId": "CommentsService_CreateComment", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/CreateCommentResponse" }, "x-example": { "comment": { "rid": "", "parent": { "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": [ "" ] } } } }, "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/CreateCommentRequest" }, "x-example": { "parent": { "resource": { "resourceType": "RUN", "resourceRid": "" } }, "content": "", "attachments": [ "" ] } } ], "tags": [ "CommentsService" ], "summary": "Create comment", "description": "Create a comment on a resource" } }, "/comments/v2/comments/{commentRid}": { "get": { "operationId": "CommentsService_GetComment", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/GetCommentResponse" }, "x-example": { "comment": { "rid": "", "parent": { "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": [ "" ] } } } }, "parameters": [ { "name": "commentRid", "description": "The RID of comment to fetch", "in": "path", "required": true, "type": "string" } ], "tags": [ "CommentsService" ], "summary": "Get comment", "description": "Get a comment identified by its RID" }, "delete": { "operationId": "CommentsService_DeleteComment", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/DeleteCommentResponse" }, "x-example": { "comment": { "rid": "", "parent": { "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": [ "" ] } } } }, "parameters": [ { "name": "commentRid", "description": "The RID of comment to delete", "in": "path", "required": true, "type": "string" } ], "tags": [ "CommentsService" ], "summary": "Delete comment", "description": "Delete an existing comment" }, "put": { "operationId": "CommentsService_EditComment", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/EditCommentResponse" }, "x-example": { "comment": { "rid": "", "parent": { "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": [ "" ] } } } }, "parameters": [ { "name": "commentRid", "description": "The RID of comment to edit", "in": "path", "required": true, "type": "string" }, { "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/EditCommentRequest" }, "x-example": { "content": "", "attachments": [ "" ] } } ], "tags": [ "CommentsService" ], "summary": "Edit comment", "description": "Edit an existing comment" } }, "/comments/v2/comments/{commentRid}/pin": { "post": { "operationId": "CommentsService_PinComment", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/PinCommentResponse" }, "x-example": { "comment": { "rid": "", "parent": { "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": [ "" ] } } } }, "parameters": [ { "name": "commentRid", "description": "The RID of comment to pin", "in": "path", "required": true, "type": "string" } ], "tags": [ "CommentsService" ], "summary": "Pin comment", "description": "Pin a comment to the top of the conversation" } }, "/comments/v2/comments/{commentRid}/reactions/{type}": { "delete": { "operationId": "CommentsService_RemoveReaction", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/RemoveReactionResponse" }, "x-example": { "comment": { "rid": "", "parent": { "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": [ "" ] } } } }, "parameters": [ { "name": "commentRid", "description": "The RID of comment to delete", "in": "path", "required": true, "type": "string" }, { "name": "type", "description": "The type of reaction", "in": "path", "required": true, "type": "string", "enum": [ "REACTION_TYPE_UNSPECIFIED", "LIKE", "DISLIKE", "HEART", "HOORAY", "ROCKET", "EYES" ] } ], "tags": [ "CommentsService" ], "summary": "Remove reaction", "description": "Create a reaction on a comment" }, "post": { "operationId": "CommentsService_AddReaction", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/AddReactionResponse" }, "x-example": { "comment": { "rid": "", "parent": { "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": [ "" ] } } } }, "parameters": [ { "name": "commentRid", "description": "The RID of comment to delete", "in": "path", "required": true, "type": "string" }, { "name": "type", "description": "The type of reaction", "in": "path", "required": true, "type": "string", "enum": [ "REACTION_TYPE_UNSPECIFIED", "LIKE", "DISLIKE", "HEART", "HOORAY", "ROCKET", "EYES" ] } ], "tags": [ "CommentsService" ], "summary": "Add reaction", "description": "Create a reaction on a comment" } }, "/comments/v2/comments/{commentRid}/unpin": { "post": { "operationId": "CommentsService_UnpinComment", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/UnpinCommentResponse" }, "x-example": { "comment": { "rid": "", "parent": { "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": [ "" ] } } } }, "parameters": [ { "name": "commentRid", "description": "The RID of comment to unpin", "in": "path", "required": true, "type": "string" } ], "tags": [ "CommentsService" ], "summary": "Unpin comment", "description": "Unpin a comment from the top of the conversation" } }, "/comments/v2/conversations/{resourceType}/{resourceRid}": { "get": { "operationId": "CommentsService_GetConversation", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/GetConversationResponse" }, "x-example": { "conversation": { "resourceRid": "", "resourceType": "RUN", "comments": [ { "comment": { "rid": "", "parent": { "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": [] } ] } } } }, "parameters": [ { "name": "resourceType", "description": "The type of resource that the comments are associated with", "in": "path", "required": true, "type": "string", "enum": [ "RESOURCE_TYPE_UNSPECIFIED", "RUN", "EVENT" ] }, { "name": "resourceRid", "description": "The RID of resource that the comments are associated with", "in": "path", "required": true, "type": "string" } ], "tags": [ "CommentsService" ], "summary": "Get conversation", "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." } }, "/comments/v2/conversations/{resourceType}/{resourceRid}/count": { "get": { "operationId": "CommentsService_GetConversationCount", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/GetConversationCountResponse" }, "x-example": { "count": 1 } } }, "parameters": [ { "name": "resourceType", "description": "The type of resource that the comments are associated with", "in": "path", "required": true, "type": "string", "enum": [ "RESOURCE_TYPE_UNSPECIFIED", "RUN", "EVENT" ] }, { "name": "resourceRid", "description": "The RID of resource that the comments are associated with", "in": "path", "required": true, "type": "string" }, { "name": "includeDeleted", "description": "Whether to include deleted comments in the count", "in": "query", "required": false, "type": "boolean" } ], "tags": [ "CommentsService" ], "summary": "Get conversation count", "description": "Returns the number of comments in a conversation." } } }, "definitions": { "AddReactionResponse": { "type": "object", "properties": { "comment": { "$ref": "#/definitions/Comment" } } }, "Comment": { "type": "object", "properties": { "rid": { "type": "string", "title": "Unique resource identifier for the comment" }, "parent": { "$ref": "#/definitions/CommentParent", "description": "The parent of the comment. It can be a resource or another comment." }, "authorRid": { "type": "string", "title": "The user who authored the comment" }, "createdAt": { "type": "string", "format": "date-time", "title": "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", "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": { "type": "object", "$ref": "#/definitions/Reaction" }, "title": "The reactions on the comment" }, "attachments": { "type": "array", "items": { "type": "string" }, "title": "The comment's attachments" } } }, "CommentParent": { "type": "object", "properties": { "resource": { "$ref": "#/definitions/CommentParentResource" }, "comment": { "$ref": "#/definitions/CommentParentComment" } }, "description": "The parent of a comment. It can be a resource or another comment in the case of a reply.\n\nSet exactly one of the fields below.", "x-oneofs": [ { "fields": [ "resource", "comment" ], "required": true } ], "example": { "resource": { "resourceType": "RUN", "resourceRid": "string" } } }, "CommentParentComment": { "type": "object", "properties": { "commentRid": { "type": "string", "title": "The resource identifier for the comment that the comment is replying to" } } }, "CommentParentResource": { "type": "object", "properties": { "resourceType": { "$ref": "#/definitions/ResourceType", "title": "The type of resource that the comment is associated with" }, "resourceRid": { "type": "string", "description": "The resource identifier for the resource that the comment is associated with. For example, a run or a workbook." } } }, "Conversation": { "type": "object", "properties": { "resourceRid": { "type": "string", "description": "RID for the resource that the conversation is associated with." }, "resourceType": { "$ref": "#/definitions/ResourceType", "description": "The type of the resource that the conversation is associated with." }, "comments": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/ConversationNode" }, "description": "The comments on the conversation ordered by creation time. Empty if the comment has no replies." } } }, "ConversationNode": { "type": "object", "properties": { "comment": { "$ref": "#/definitions/Comment", "title": "The comment" }, "replies": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/ConversationNode" }, "description": "The comments on (aka replies to) the comment ordered by creation time. Empty if the comment has no replies." } } }, "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" }, "description": "Attachments to the comment." } }, "example": { "parent": { "resource": { "resourceType": "RUN", "resourceRid": "" } }, "content": "", "attachments": [ "" ] } }, "CreateCommentResponse": { "type": "object", "properties": { "comment": { "$ref": "#/definitions/Comment" } } }, "DeleteCommentResponse": { "type": "object", "properties": { "comment": { "$ref": "#/definitions/Comment" } } }, "EditCommentRequest": { "type": "object", "properties": { "content": { "type": "string", "description": "The content of the comment. Markdown supported." }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "Attachments to the comment." } }, "example": { "content": "", "attachments": [ "" ] } }, "EditCommentResponse": { "type": "object", "properties": { "comment": { "$ref": "#/definitions/Comment" } } }, "GetCommentResponse": { "type": "object", "properties": { "comment": { "$ref": "#/definitions/Comment" } } }, "GetConversationCountResponse": { "type": "object", "properties": { "count": { "type": "integer", "format": "int32" } } }, "GetConversationResponse": { "type": "object", "properties": { "conversation": { "$ref": "#/definitions/Conversation" } } }, "PinCommentResponse": { "type": "object", "properties": { "comment": { "$ref": "#/definitions/Comment" } } }, "Reaction": { "type": "object", "properties": { "rid": { "type": "string", "title": "Unique resource identifier for the reaction" }, "userRid": { "type": "string", "title": "The user who authored the reaction" }, "createdAt": { "type": "string", "format": "date-time", "title": "The time the reaction was created" }, "type": { "$ref": "#/definitions/ReactionType", "title": "The type of reaction" } } }, "ReactionType": { "type": "string", "enum": [ "REACTION_TYPE_UNSPECIFIED", "LIKE", "DISLIKE", "HEART", "HOORAY", "ROCKET", "EYES" ], "default": "REACTION_TYPE_UNSPECIFIED", "example": "LIKE" }, "RemoveReactionResponse": { "type": "object", "properties": { "comment": { "$ref": "#/definitions/Comment" } } }, "ResourceType": { "type": "string", "enum": [ "RESOURCE_TYPE_UNSPECIFIED", "RUN", "EVENT" ], "default": "RESOURCE_TYPE_UNSPECIFIED", "example": "RUN" }, "UnpinCommentResponse": { "type": "object", "properties": { "comment": { "$ref": "#/definitions/Comment" } } } }, "securityDefinitions": { "ApiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Your API key as a bearer token: `Authorization: Bearer `." } }, "security": [ { "ApiKey": [] } ] }