Add a new comment (with optional file attachments)
POST /task/v1/comments/add
Operation id: addComment
Description
Adds a new comment to a feed/cluster. Required parameters depend on message_type. Both snake_case and camelCase names are accepted (e.g. feed_key or feedKey).
Always required (all message types):
comment— mandatory (E122 if blank or absent)message_type— allowed:M,R,RA,F; defaults toMif omitted (E161 if invalid)link— must be a valid URL if provided (E164)- Attachments — count and type validated against domain limits (E162, E125)
Required for message_type=M (new message):
reason_code/reason_text— mandatory (E113); existence-only check, no catalog validationassign_store,assign_user,assign_profile,assign_dept— mandatory (E113)assign_text— mandatory (E113); display name for the recipient
Required for message_type=F (reassign):
cluster_id— mandatory and must not be-1(E113); scopesreassignMessages()to the correct threadassign_store,assign_user,assign_profile,assign_dept— mandatory (E113)assign_text— mandatory (E113); display name for the new assigneemsg_parent_id/msg_main_id— at least one must be non-zero (E111)- Note:
reason_code/reason_textare not required forF; inherited from the parent message
Required for message_type=R (reply):
msg_parent_id/msg_main_id— at least one must be non-zero (E111)
Required for message_type=RA (reply-all):
msg_main_id— mandatory; comma-separated IDs for multiple threads (E111)
Always injected from session (do not send in body): domain_id, user_id, store_id, dept_id, profile_id, time_zone_long
Auth header: Use X-reflexis-csrf-token-X (NOT the legacy x-authtoken). Requires ROS_UNIT_DOMAIN line-of-sight authorization.
Tags: MyWorkComments
Security
- AuthTokenHeader (apiKey)
- Session authentication token validated server-side against the user session store.
Responses
200 — Success — {status: OK, comment_data[]} for normal add/reply.
For message_type=RA (reply-all) → {status: OK, message: "Message added successfully"}.
Content type: application/json
400 — E112 — missing CSRF header |
E122 — comment is mandatory | E161 — invalid message_type (allowed: M, R, RA, F; defaults to M if omitted) | E111 — msg_parent_id / msg_main_id missing or zero (required for R and F; msg_main_id required for RA) | E133 — msg_parent_id must be a valid integer | E141 — msg_main_id must be a valid integer | E113 — reason_code is mandatory (M only) | E113 — reason_text is mandatory (M only) | E113 — assign_text is mandatory (M and F) | E113 — cluster_id is mandatory for F and must not be -1 | E113 — assign_store / assign_user / assign_profile / assign_dept is mandatory (M and F) | E162 — attachment count exceeds configured maximum | E164 — invalid link URL | E125 — invalid attachment type (application-level check; response lists the allowed types) | E600 — file blocked by the kernel security filter before validation (unsafe/unsupported content) | E601 — request rejected by the kernel security filter (generic)
Content type: application/json
401 — Invalid or expired X-reflexis-csrf-token-X token (HTTP 401)
Content type: application/json
500 — Unexpected server-side error
Content type: application/json
Request body
Required: Yes
multipart/form-data
Schema
| Property | Type | Required | Description |
|---|---|---|---|
comment | string | Yes | HTML-formatted comment body (URL-encoded, e.g. %3Cp%3EText%3C%2Fp%3E) — mandatory for all message types. plain_text is derived server-side. |
assign_store | string | No | Target unit/store ID for the recipient. Mandatory for M and F (E113 if missing). Use -1 if not store-scoped. The controller builds assign_details server-side from the assign_* params; do not send assign_details directly. |
assign_user | string | No | Target user ID for the recipient. Mandatory for M and F (E113 if missing). Use -1 if targeting by store/profile. |
assign_profile | string | No | Target profile ID for the recipient. Mandatory for M and F (E113 if missing). Use -1 if not profile-scoped. |
assign_dept | string | No | Target department ID for the recipient. Mandatory for M and F (E113 if missing). Use -1 if not department-scoped. |
reason_code | string | No | Reason code key. Mandatory for M only (E113 if missing). Not required for F — inherited from the parent message. Existence-only check; no catalog validation. Values come from the getCommentCodes API dropdown. |
reason_text | string | No | Reason code display label. Mandatory for M only (E113 if missing). Not required for F — inherited from the parent message. Existence-only check; no catalog validation. Values come from the getCommentCodes API dropdown. |
assign_text | string | No | Display name for the recipient (e.g. 'Store 10' or 'Jane Smith'). Mandatory for M and F (E113 if missing). Sets the To label in key_description. For F, this is the new assignee display name. Values come from the getCommentCodes API dropdown. |
cluster_id | string | No | Feed cluster ID. Mandatory for F (reassign) and must not be -1 (E113 if missing or -1). Required because reassignMessages() scopes thread ownership updates by (domainId + msgMainId + clusterId) — without a real clusterId the target user never gains visibility. Optional for other message types; -1 = general (non-project) message. |
feed_key | integer | No | Feed/project key; 0 or absent = no specific feed |
message_type | string | No | Message type. Defaults to M if omitted or blank. - M — new message. Requires: reason_code, reason_text, assign_text, assign_store/user/profile/dept. No message IDs needed. - R — reply. Requires: at least one of msg_parent_id / msg_main_id (non-zero). - F — reassign. Requires: cluster_id (non -1), assign_text, assign_store/user/profile/dept, at least one of msg_parent_id / msg_main_id (non-zero). reason_code/reason_text inherited from parent. - RA — reply-all. Requires: msg_main_id (comma-separated IDs). Only on /add, not /reply. |
message_status | string | No | Initial read status: N=not-read, R=read |
inline_email | string | No | Inline email flag. If present, included in assign_details as INLINE_EMAIL. Defaults to 'N' when absent. |
user_info | string | No | JSON array string of user info objects for assign_details USER_INFO. If absent, defaults to empty array. |
msg_parent_id | integer | No | Parent message ID. Conditionally mandatory for R and F: must be present and non-zero when msg_main_id is also absent (E111). Ignored by the service for RA. |
msg_main_id | string | No | Root/thread message ID. Conditionally mandatory: - R / F: must be present and non-zero when msg_parent_id is also absent (E111). - RA: mandatory; provide a single ID or comma-separated IDs for multi-message reply-all (e.g. 129539,129540) (E111 if blank). |
link | string | No | URL to embed in the comment |
internal | string | No | Internal-only flag: Y=internal, -1=not set |
from_external | string | No | Source indicator for externally originated comments |
login_auth_token | string | No | Login auth token override |
{
"type": "object",
"required": [
"comment"
],
"properties": {
"comment": {
"type": "string",
"description": "HTML-formatted comment body (URL-encoded, e.g. %3Cp%3EText%3C%2Fp%3E) — mandatory for all message types. plain_text is derived server-side."
},
"assign_store": {
"type": "string",
"description": "Target unit/store ID for the recipient. **Mandatory for `M` and `F`** (E113 if missing). Use `-1` if not store-scoped. The controller builds assign_details server-side from the assign_* params; do not send assign_details directly."
},
"assign_user": {
"type": "string",
"description": "Target user ID for the recipient. **Mandatory for `M` and `F`** (E113 if missing). Use `-1` if targeting by store/profile."
},
"assign_profile": {
"type": "string",
"description": "Target profile ID for the recipient. **Mandatory for `M` and `F`** (E113 if missing). Use `-1` if not profile-scoped."
},
"assign_dept": {
"type": "string",
"description": "Target department ID for the recipient. **Mandatory for `M` and `F`** (E113 if missing). Use `-1` if not department-scoped."
},
"reason_code": {
"type": "string",
"description": "Reason code key. **Mandatory for `M` only** (E113 if missing). Not required for `F` — inherited from the parent message. Existence-only check; no catalog validation. Values come from the `getCommentCodes` API dropdown."
},
"reason_text": {
"type": "string",
"description": "Reason code display label. **Mandatory for `M` only** (E113 if missing). Not required for `F` — inherited from the parent message. Existence-only check; no catalog validation. Values come from the `getCommentCodes` API dropdown."
},
"assign_text": {
"type": "string",
"description": "Display name for the recipient (e.g. 'Store 10' or 'Jane Smith'). **Mandatory for `M` and `F`** (E113 if missing). Sets the To label in key_description. For `F`, this is the new assignee display name. Values come from the `getCommentCodes` API dropdown."
},
"cluster_id": {
"type": "string",
"description": "Feed cluster ID. **Mandatory for `F` (reassign) and must not be `-1`** (E113 if missing or `-1`). Required because reassignMessages() scopes thread ownership updates by (domainId + msgMainId + clusterId) — without a real clusterId the target user never gains visibility. Optional for other message types; `-1` = general (non-project) message.",
"default": "-1"
},
"feed_key": {
"type": "integer",
"description": "Feed/project key; 0 or absent = no specific feed",
"default": 0
},
"message_type": {
"type": "string",
"description": "Message type. Defaults to `M` if omitted or blank.\n- `M` — new message. Requires: reason_code, reason_text, assign_text, assign_store/user/profile/dept. No message IDs needed.\n- `R` — reply. Requires: at least one of msg_parent_id / msg_main_id (non-zero).\n- `F` — reassign. Requires: cluster_id (non -1), assign_text, assign_store/user/profile/dept, at least one of msg_parent_id / msg_main_id (non-zero). reason_code/reason_text inherited from parent.\n- `RA` — reply-all. Requires: msg_main_id (comma-separated IDs). Only on /add, not /reply.\n",
"enum": [
"M",
"R",
"F",
"RA"
],
"default": "M"
},
"message_status": {
"type": "string",
"description": "Initial read status: N=not-read, R=read",
"enum": [
"N",
"R"
],
"default": "N"
},
"inline_email": {
"type": "string",
"description": "Inline email flag. If present, included in assign_details as INLINE_EMAIL. Defaults to 'N' when absent."
},
"user_info": {
"type": "string",
"description": "JSON array string of user info objects for assign_details USER_INFO. If absent, defaults to empty array."
},
"msg_parent_id": {
"type": "integer",
"description": "Parent message ID.\n**Conditionally mandatory for `R` and `F`:** must be present and non-zero when `msg_main_id` is also absent (E111).\nIgnored by the service for `RA`.\n",
"default": 0
},
"msg_main_id": {
"type": "string",
"description": "Root/thread message ID.\n**Conditionally mandatory:**\n- `R` / `F`: must be present and non-zero when `msg_parent_id` is also absent (E111).\n- `RA`: **mandatory**; provide a single ID or comma-separated IDs for multi-message reply-all (e.g. `129539,129540`) (E111 if blank).\n",
"default": "0"
},
"link": {
"type": "string",
"description": "URL to embed in the comment"
},
"internal": {
"type": "string",
"description": "Internal-only flag: Y=internal, -1=not set",
"default": "-1"
},
"from_external": {
"type": "string",
"description": "Source indicator for externally originated comments"
},
"login_auth_token": {
"type": "string",
"description": "Login auth token override",
"default": "-1"
}
}
}
Response models
200 — Success — {status: OK, comment_data[]} for normal add/reply.
For message_type=RA (reply-all) → {status: OK, message: "Message added successfully"}.
Content type: application/json
Schema
JSON object (structure varies by endpoint).
{
"type": "object",
"description": "JSON object (structure varies by endpoint)."
}
400 — E112 — missing CSRF header |
E122 — comment is mandatory | E161 — invalid message_type (allowed: M, R, RA, F; defaults to M if omitted) | E111 — msg_parent_id / msg_main_id missing or zero (required for R and F; msg_main_id required for RA) | E133 — msg_parent_id must be a valid integer | E141 — msg_main_id must be a valid integer | E113 — reason_code is mandatory (M only) | E113 — reason_text is mandatory (M only) | E113 — assign_text is mandatory (M and F) | E113 — cluster_id is mandatory for F and must not be -1 | E113 — assign_store / assign_user / assign_profile / assign_dept is mandatory (M and F) | E162 — attachment count exceeds configured maximum | E164 — invalid link URL | E125 — invalid attachment type (application-level check; response lists the allowed types) | E600 — file blocked by the kernel security filter before validation (unsafe/unsupported content) | E601 — request rejected by the kernel security filter (generic)
Content type: application/json
Schema
| Property | Type | Required | Description |
|---|---|---|---|
status | string | Yes | Always "ER" for error responses |
errorCode | string | Yes | Application-level error code (e.g. E204, E112, E302) |
response | string | Yes | Human-readable error message |
{
"type": "object",
"example": {
"status": "ER",
"errorCode": "E204",
"response": "Invalid or expired token"
},
"required": [
"status",
"errorCode",
"response"
],
"properties": {
"status": {
"type": "string",
"description": "Always \"ER\" for error responses",
"enum": [
"ER"
]
},
"errorCode": {
"type": "string",
"description": "Application-level error code (e.g. E204, E112, E302)"
},
"response": {
"type": "string",
"description": "Human-readable error message"
}
}
}
401 — Invalid or expired X-reflexis-csrf-token-X token (HTTP 401)
Content type: application/json
Schema
| Property | Type | Required | Description |
|---|---|---|---|
status | string | Yes | Always "ER" for error responses |
errorCode | string | Yes | Application-level error code (e.g. E204, E112, E302) |
response | string | Yes | Human-readable error message |
{
"type": "object",
"example": {
"status": "ER",
"errorCode": "E204",
"response": "Invalid or expired token"
},
"required": [
"status",
"errorCode",
"response"
],
"properties": {
"status": {
"type": "string",
"description": "Always \"ER\" for error responses",
"enum": [
"ER"
]
},
"errorCode": {
"type": "string",
"description": "Application-level error code (e.g. E204, E112, E302)"
},
"response": {
"type": "string",
"description": "Human-readable error message"
}
}
}
Example:
{
"status": "ER",
"errorCode": "E204",
"response": "Invalid or expired token"
}
500 — Unexpected server-side error
Content type: application/json
Schema
| Property | Type | Required | Description |
|---|---|---|---|
status | string | Yes | Always "ER" for error responses |
errorCode | string | Yes | Application-level error code (e.g. E204, E112, E302) |
response | string | Yes | Human-readable error message |
{
"type": "object",
"example": {
"status": "ER",
"errorCode": "E204",
"response": "Invalid or expired token"
},
"required": [
"status",
"errorCode",
"response"
],
"properties": {
"status": {
"type": "string",
"description": "Always \"ER\" for error responses",
"enum": [
"ER"
]
},
"errorCode": {
"type": "string",
"description": "Application-level error code (e.g. E204, E112, E302)"
},
"response": {
"type": "string",
"description": "Human-readable error message"
}
}
}
Example:
{
"status": "ER",
"errorCode": "E302",
"response": "Internal server error"
}