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 to M if 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 validation
  • assign_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); scopes reassignMessages() to the correct thread
  • assign_store, assign_user, assign_profile, assign_dept — mandatory (E113)
  • assign_text — mandatory (E113); display name for the new assignee
  • msg_parent_id / msg_main_id — at least one must be non-zero (E111)
  • Note: reason_code / reason_text are not required for F; 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

  • ApiKeyHeader (apiKey)
    • APIGEE API key header validated by VerifyAPIKey policy.
  • 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

PropertyTypeRequiredDescription
commentstringYesHTML-formatted comment body (URL-encoded, e.g. %3Cp%3EText%3C%2Fp%3E) — mandatory for all message types. plain_text is derived server-side.
assign_storestringNoTarget 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_userstringNoTarget user ID for the recipient. Mandatory for M and F (E113 if missing). Use -1 if targeting by store/profile.
assign_profilestringNoTarget profile ID for the recipient. Mandatory for M and F (E113 if missing). Use -1 if not profile-scoped.
assign_deptstringNoTarget department ID for the recipient. Mandatory for M and F (E113 if missing). Use -1 if not department-scoped.
reason_codestringNoReason 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_textstringNoReason 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_textstringNoDisplay 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_idstringNoFeed 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_keyintegerNoFeed/project key; 0 or absent = no specific feed
message_typestringNoMessage 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_statusstringNoInitial read status: N=not-read, R=read
inline_emailstringNoInline email flag. If present, included in assign_details as INLINE_EMAIL. Defaults to 'N' when absent.
user_infostringNoJSON array string of user info objects for assign_details USER_INFO. If absent, defaults to empty array.
msg_parent_idintegerNoParent 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_idstringNoRoot/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).
linkstringNoURL to embed in the comment
internalstringNoInternal-only flag: Y=internal, -1=not set
from_externalstringNoSource indicator for externally originated comments
login_auth_tokenstringNoLogin 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

PropertyTypeRequiredDescription
statusstringYesAlways "ER" for error responses
errorCodestringYesApplication-level error code (e.g. E204, E112, E302)
responsestringYesHuman-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

PropertyTypeRequiredDescription
statusstringYesAlways "ER" for error responses
errorCodestringYesApplication-level error code (e.g. E204, E112, E302)
responsestringYesHuman-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

PropertyTypeRequiredDescription
statusstringYesAlways "ER" for error responses
errorCodestringYesApplication-level error code (e.g. E204, E112, E302)
responsestringYesHuman-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"
}