API EndpointsCommentsCreate Comment

Create Comment

Endpoint

URL: /:projectId/comments

Method: POST

Authentication Required: Yes

Description

Creates a new comment or reply on a specific entity.

  • Comments can include text, a GIF, mentions, attachments, and metadata.
  • Only authenticated users (or master clients) may create comments.
  • Automatically handles reputation and notification logic.

Request

Headers

HeaderTypeRequiredDescription
AuthorizationstringYesBearer token for authenticated users.

Body Parameters

FieldTypeRequiredDescription
entityIdstringYesID of the entity to attach the comment to.
contentstringNo*Text content of the comment. Required unless gif is provided.
gifIGifNo*GIF object. Required unless content is provided.
mentionsIMention[]NoList of mentioned users.
parentIdstringNoID of the parent comment (for replies).
referencedCommentIdstringNoID of a referenced (quoted) comment.
foreignIdstringNoOptional external reference ID.
attachmentsRecord<string, any>[]NoList of attached files or resources.
metadataRecord<string, any>NoCustom metadata for this comment.
userIdstringNoAllowed only for master clients. Posts the comment on behalf of a user.

Example Request

{
  "entityId": "a1b2c3d4",
  "content": "Great article!",
  "mentions": [{ "id": "user-123", "username": "alex" }],
  "gif": null,
  "parentId": "comment-456",
  "attachments": [],
  "metadata": { "source": "web" }
}

Response

Success Response (201 Created)

Returns the newly created comment object:

{
  "id": "comment-789",
  "entityId": "a1b2c3d4",
  "userId": "user-456",
  "content": "Great article!",
  "mentions": [{ "id": "user-123", "username": "alex" }],
  "gif": null,
  "attachments": [],
  "metadata": { "source": "web" },
  "createdAt": "2025-05-11T10:00:00.000Z",
  "updatedAt": "2025-05-11T10:00:00.000Z"
}

Error Responses

Missing Entity ID (400 Bad Request)

{
  "error": "Missing entity ID",
  "code": "comment/missing-entity-id"
}

Missing Content (400 Bad Request)

{
  "error": "Missing required comment content",
  "code": "comment/missing-content"
}

Missing User ID (400 Bad Request)

{
  "error": "Missing user ID",
  "code": "comment/missing-user-id"
}

Entity Not Found (404 Not Found)

{
  "error": "Entity not found",
  "code": "comment/entity-not-found"
}

Server Error (500 Internal Server Error)

{
  "error": "Internal server error",
  "code": "comment/server-error",
  "details": "[error message]"
}

Notes

  • Either content or gif must be present.

  • If userId is provided, the request must come from a master client.

  • Reputation is awarded to the user who posts the comment.

  • Notifications are triggered automatically:

    • To the entity author
    • To the parent comment author (for replies)
    • To each mentioned user (excluding duplicates)

  • API usage for comments is tracked via Redis.

Gif Structure

interface IGif {
  altText: string;
  gifPreviewUrl: string;
  gifUrl: string;
  id: string;
  url: string;
  aspectRatio: string;
}

Mention Structure

interface IMention {
  id: string; // User ID
  username: string; // Username at time of mention
}
Delete EntityFetch Comment