---
agentTools:
  projectIndex: https://uspacy.readme.io/llms.txt
---

# Create a comment

Creates a new comment on an entity. Supports mentions of users, groups, and departments, as well as file attachments. Optionally, you can specify notification recipients and provide parent entity information for enhanced notification context.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "components": {
    "schemas": {
      "errorMessage": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        }
      },
      "Date": {
        "type": "number",
        "description": "timestamp in seconds",
        "default": 0,
        "example": 1654180120
      },
      "EntityTypes": {
        "oneOf": [
          {
            "type": "string",
            "enum": [
              "comment",
              "post",
              "task"
            ]
          },
          {
            "type": "string",
            "pattern": "^[a-zA-Z0-9_\\-]+$"
          }
        ],
        "description": "Entity type name. You can use one of the predefined values (comment, post, task) or provide any custom string value matching the pattern.\n"
      },
      "CommentServiceDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "example": 1
          },
          "entityType": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EntityTypes"
              },
              {
                "example": "post"
              }
            ]
          },
          "entityId": {
            "type": "integer",
            "format": "int64",
            "example": 1
          },
          "message": {
            "type": "string",
            "example": "Message comment"
          },
          "authorId": {
            "type": "string",
            "example": 1
          },
          "date": {
            "$ref": "#/components/schemas/Date"
          },
          "mentioned": {
            "$ref": "#/components/schemas/MentionedDto"
          },
          "notify": {
            "$ref": "#/components/schemas/NotifyDto"
          }
        }
      },
      "CreateCommentServiceDto": {
        "type": "object",
        "properties": {
          "entityType": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EntityTypes"
              },
              {
                "example": "post"
              }
            ]
          },
          "entityId": {
            "type": "integer",
            "format": "int64",
            "example": 1
          },
          "message": {
            "type": "string",
            "example": "Message post"
          },
          "authorId": {
            "type": "integer",
            "example": 1
          },
          "date": {
            "type": "integer",
            "example": 1627862400
          },
          "upload_id": {
            "type": "string",
            "example": null
          },
          "file_ids": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "example": []
          },
          "mentioned": {
            "$ref": "#/components/schemas/MentionedDto"
          },
          "notify": {
            "$ref": "#/components/schemas/NotifyDto"
          },
          "rootParent": {
            "$ref": "#/components/schemas/RootParentDto"
          },
          "root_parent": {
            "$ref": "#/components/schemas/RootParentDto"
          }
        },
        "required": [
          "entityType",
          "entityId",
          "message"
        ]
      },
      "RootParentDto": {
        "type": "object",
        "description": "Optional parameter for notification of comment creation. Can be sent as 'rootParent' (camelCase) or 'root_parent' (snake_case).",
        "properties": {
          "type": {
            "type": "string",
            "description": "Type of parent entity",
            "example": "post"
          },
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "integer"
                  }
                ],
                "description": "Parent entity id (can be string or integer)",
                "example": 732
              },
              "title": {
                "type": "string",
                "example": "Entity title",
                "description": "Parent entity title"
              }
            }
          },
          "service": {
            "type": "string",
            "description": "Service name (e.g., 'news_feed', 'crm')",
            "example": "news_feed"
          },
          "table_name": {
            "type": "string",
            "description": "Table name for CRM entities (e.g., 'leads', 'deals')",
            "example": "leads"
          }
        },
        "required": [
          "type",
          "data",
          "service"
        ]
      },
      "MentionedDto": {
        "type": "object",
        "properties": {
          "users": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "example": [
              32,
              85
            ]
          },
          "groups": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "example": [
              43,
              12,
              2
            ]
          },
          "departments": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "example": []
          }
        }
      },
      "NotifyDto": {
        "type": "object",
        "properties": {
          "users": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "example": [
              32,
              85
            ]
          },
          "groups": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "example": [
              43,
              12,
              2
            ]
          },
          "departments": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "example": []
          }
        }
      }
    },
    "responses": {
      "UnauthorizedError": {
        "description": "Unauthorized",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/errorMessage"
            }
          }
        }
      },
      "ValidationError": {
        "description": "Validation error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/errorMessage"
            }
          }
        }
      }
    }
  },
  "info": {
    "title": "Comments service",
    "description": "API for managing comments on various entities such as posts, tasks, and other content types. Supports threaded comments, mentions, reactions, and notifications.",
    "version": "1.0.0"
  },
  "tags": [
    {
      "name": "comments",
      "description": "Operations for managing comments on entities"
    }
  ],
  "servers": [
    {
      "url": "https://{domain}.uspacy.ua",
      "description": "Ukrainian server"
    },
    {
      "url": "https://{domain}.uspacy.eu",
      "description": "EU server"
    },
    {
      "url": "https://{domain}.uspacy.com.br",
      "description": "Brazilian server"
    },
    {
      "url": "https://{domain}.uspacy.com",
      "description": "International server"
    }
  ],
  "paths": {
    "/comments/v1/comments": {
      "post": {
        "operationId": "CommentsController_createComment",
        "summary": "Create a comment",
        "description": "Creates a new comment on an entity. Supports mentions of users, groups, and departments, as well as file attachments. Optionally, you can specify notification recipients and provide parent entity information for enhanced notification context.\n",
        "requestBody": {
          "required": true,
          "description": "Comment data including the target entity, message content, and optional mentions",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCommentServiceDto"
              },
              "example": {
                "entityType": "post",
                "entityId": 123,
                "message": "Great work on this! @John please review.",
                "authorId": 7,
                "date": 1654180120,
                "mentioned": {
                  "users": [
                    32,
                    85
                  ],
                  "groups": [],
                  "departments": []
                },
                "notify": {
                  "users": [
                    32
                  ],
                  "groups": [],
                  "departments": []
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Comment created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommentServiceDto"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        },
        "tags": [
          "comments"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 104,
      "1": 104,
      "2": 244,
      "3": 177,
      "4": 218,
      "5": 104,
      "6": 82,
      "7": 0,
      "8": 18,
      "9": 32,
      "10": 73,
      "11": 78
    }
  }
}
```