Comment Endpoint

The Comment endpoint allows you to add comments to entities in the ThreatWinds platform.

Insert Comment

This endpoint allows you to insert a comment for an entity.

Endpoint 

POST /api/ingest/v1/comment

Request Headers

Header Description
Authorization Bearer token from an active session.
api-key API key.
api-secret API secret.

Note: The user-id and groups headers are added automatically by the API gateway when required and should not be provided by the client.

Required Roles

Access to this endpoint is controlled by role-based permissions defined in the gateway. Users must have at least one of the required roles assigned to their account to access this endpoint.

Required role: reporter

This endpoint requires the reporter role, which allows users to submit threat intelligence data to the platform.

Request Body

The request body should be a JSON object with the following structure:

{
  "entityID": "string",
  "comment": "string",
  "parentID": "string",
  "visibleBy": [
    "string"
  ]
}

Note: You need to provide valid entity IDs that already exist in the system. Entity IDs in ThreatWinds follow a deterministic format based on the entity type and its main attribute value. You can obtain entity IDs by first creating entities using the /entity endpoint and/or by querying entities through the Search API.

Parameters

Parameter Type Description
entityID string The ID of the entity to which the comment is attached
comment string The comment text. Sanitization truncates to 10000 runes first, then strips control characters (except newline and tab), then HTML-escapes special characters (<, >, &, ', "), then trims spaces. Content must not be empty after sanitization.
parentID string (UUID) Optional ID of a parent comment (for threaded comments)
visibleBy array Optional array of groups that can see the comment (defaults to user’s groups if not provided)

Response

Success Response (202 Accepted) 

{
  "message": "acknowledged"
}

Error Responses

Status Code Description
400 Bad Request - Invalid input data
401 Unauthorized - Authentication failed
403 Forbidden - Insufficient permissions or group mismatch
500 Internal Server Error - Malformed user-id header value

Error Response Headers

For responses with status codes other than 200 and 202, the following headers are included:

Header Description
x-error Human-readable error message describing what went wrong
x-error-id Unique identifier for error tracking and support

Error Codes

Status Code Description Possible Cause
400 Bad Request Invalid request parameters or malformed JSON
400 Comment cannot be empty Comment field is empty or whitespace-only
400 Comment contains no valid text after sanitization Comment contains only HTML tags or exceeds length limit
404 Not Found Entity ID references a non-existent entity
401 Unauthorized Missing or invalid authentication credentials
403 Forbidden Authenticated user lacks permission for this operation, or visibleBy contains groups the user is not a member of
500 Internal Server Error Malformed user-id header value

Example 

curl -X POST "https://apis.threatwinds.com/api/ingest/v1/comment" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API_KEY>" \
  -H "api-secret: <YOUR_API_SECRET>" \
  -d '{
    "entityID": "ip-abc123",
    "comment": "This IP has been observed in multiple phishing campaigns.",
    "visibleBy": ["group1", "group2"]
  }'

Use Cases

Comments can be used for various purposes in threat intelligence:

  1. Analyst Notes: add observations or analysis of an entity
  2. Context Information: provide additional context that might not fit in standard attributes
  3. Investigation Updates: document findings during an investigation
  4. Collaboration: share insights with team members