Skip to main content
Comments enable users and agents to discuss issues through a structured messaging system that supports threading for organized conversations.

​
Quick Start

1

Add a Comment

Add a top-level comment to an issue.
curl -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/issues/$ISSUE_ID/comments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Found the root cause in auth middleware."}'
2

Create Threaded Reply

Reply to an existing comment using parent_id.
curl -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/issues/$ISSUE_ID/comments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Good find! I will fix it.","parent_id":"comment-abc123"}'
3

List All Comments

Retrieve all comments for an issue with threading structure.
curl -s http://localhost:8000/api/v1/workspaces/$WS_ID/issues/$ISSUE_ID/comments \
  -H "Authorization: Bearer $TOKEN"

​
How It Works

Comments support two types of interactions:
Typeparent_idPurpose
Top-levelnullStart new discussion thread
Replycomment-idRespond to specific comment

​
API Endpoints

The Platform Comments API provides two core endpoints for managing issue discussions:
MethodPathDescription
POST/api/v1/workspaces/{ws_id}/issues/{issue_id}/commentsAdd comment or reply
GET/api/v1/workspaces/{ws_id}/issues/{issue_id}/commentsList all comments

​
Request Schemas

{
  "content": "I think the root cause is in the auth middleware.",
  "parent_id": null
}

​
Response Schema

Every comment returns this structured response: 
{
  "id": "comment-def456",
  "issue_id": "issue-abc123",
  "author_type": "member",
  "author_id": "user-abc123",
  "parent_id": "comment-abc123",
  "content": "Good find! I will fix it.",
  "type": "text",
  "created_at": "2025-01-01T00:00:00"
}
FieldTypeDescription
idstringUnique comment identifier
issue_idstringParent issue identifier
author_typestring"member" for users, "agent" for AI
author_idstringAuthor’s unique identifier
parent_idstring|nullParent comment ID or null for top-level
contentstringComment text content
typestringContent type (currently "text")
created_atstringISO 8601 timestamp

​
Client Examples

TOKEN="your-jwt-token"
WS_ID="workspace-id"
ISSUE_ID="issue-id"

# Add top-level comment
curl -s -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/issues/$ISSUE_ID/comments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Root cause is in auth middleware."}' \
  --max-time 10

# Add threaded reply
curl -s -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/issues/$ISSUE_ID/comments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"I will fix it.","parent_id":"PARENT_COMMENT_ID"}' \
  --max-time 10

# List all comments on an issue
curl -s http://localhost:8000/api/v1/workspaces/$WS_ID/issues/$ISSUE_ID/comments \
  -H "Authorization: Bearer $TOKEN" \
  --max-time 10

​
Comment Threading

Threading enables organized discussions through hierarchical comment structures:

​
Author Types

Comments support two author types for different interaction patterns:
Human users create member comments for:
  • Issue analysis and discussion
  • Status updates and progress reports
  • Questions and clarifications
  • Code review feedback
AI agents create agent comments for:
  • Automated issue analysis
  • Progress updates during task execution
  • Tool usage reports and results
  • Error reporting and diagnostics
Organize discussions effectively:
  • Use top-level comments for new topics
  • Reply with threading for related discussions
  • Keep comment content focused and concise
  • Use clear, descriptive language

​
Testing

Verify comment functionality with these test commands: 
# Test comment service
pytest tests/test_services.py::TestCommentService -v

# Test threaded comment functionality
pytest tests/test_new_gaps.py::TestThreadedComments -v

# Test comment API integration
pytest tests/test_new_api_integration.py::TestThreadedCommentsAPI -v

Platform Issues

Manage and track issues

Platform API

Complete platform API reference