API Reference/Comments

Comments API

Create, read, update, and delete comments on tasks and goals. Comments support @mentions for team collaboration.

List Comments

GET/api/v1/commentsread:comments

Retrieve comments for a specific task or goal.

Query Parameters

task_iduuidFilter by task ID

goal_iduuidFilter by goal ID

pageintegerPage number (default: 1)

limitintegerItems per page (default: 50, max: 100)

sort_orderstringSort direction: asc or desc (default: asc)

Request Example

curl -X GET "https://gateway.thekairos.app/v1/comments?task_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "abc12345-e29b-41d4-a716-446655440000",
      "team_id": "123e4567-e89b-12d3-a456-426614174000",
      "task_id": "550e8400-e29b-41d4-a716-446655440000",
      "goal_id": null,
      "user_id": "456e7890-e12b-34d5-a678-901234567000",
      "content": "Great progress! @[John Doe](user-123) can you review this?",
      "mentions": ["user-123"],
      "created_at": "2024-01-10T14:30:00Z",
      "updated_at": "2024-01-10T14:30:00Z",
      "user": {
        "id": "456e7890-e12b-34d5-a678-901234567000",
        "full_name": "Jane Smith",
        "avatar_url": "https://..."
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 5,
    "has_more": false
  }
}

Filter Required

You must provide either task_id or goal_id to list comments. Listing all comments without a filter is not supported.

Get Comment

GET/api/v1/comments/:idread:comments

Retrieve a single comment by ID.

Request Example

curl -X GET "https://gateway.thekairos.app/v1/comments/abc12345-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "id": "abc12345-e29b-41d4-a716-446655440000",
    "team_id": "123e4567-e89b-12d3-a456-426614174000",
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "goal_id": null,
    "user_id": "456e7890-e12b-34d5-a678-901234567000",
    "content": "Great progress! @[John Doe](user-123) can you review this?",
    "mentions": ["user-123"],
    "created_at": "2024-01-10T14:30:00Z",
    "updated_at": "2024-01-10T14:30:00Z",
    "user": {
      "id": "456e7890-e12b-34d5-a678-901234567000",
      "full_name": "Jane Smith",
      "avatar_url": "https://..."
    }
  }
}

Create Comment

POST/api/v1/commentswrite:comments

Create a new comment on a task or goal.

Request Body

contentstringrequiredComment content (supports @mentions)

task_iduuidTask ID to comment on

goal_iduuidGoal ID to comment on

Request Example

curl -X POST "https://gateway.thekairos.app/v1/comments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "content": "Looks good! @[John Doe](user-123) please review when you have time."
  }'

Response

{
  "data": {
    "id": "def67890-e29b-41d4-a716-446655440000",
    "team_id": "123e4567-e89b-12d3-a456-426614174000",
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "goal_id": null,
    "user_id": "456e7890-e12b-34d5-a678-901234567000",
    "content": "Looks good! @[John Doe](user-123) please review when you have time.",
    "mentions": ["user-123"],
    "created_at": "2024-01-10T15:00:00Z",
    "updated_at": "2024-01-10T15:00:00Z"
  }
}

Task or Goal Required

You must provide either task_id or goal_id when creating a comment. A comment cannot exist without being attached to a task or goal.

Update Comment

PATCH/api/v1/comments/:idwrite:comments

Update an existing comment. Only the comment author can update it.

Request Body

contentstringrequiredUpdated comment content

Request Example

curl -X PATCH "https://gateway.thekairos.app/v1/comments/abc12345-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated: This looks great! Ready for deployment."
  }'

Response

{
  "data": {
    "id": "abc12345-e29b-41d4-a716-446655440000",
    "content": "Updated: This looks great! Ready for deployment.",
    "mentions": [],
    "updated_at": "2024-01-10T16:00:00Z"
  }
}

Author Only

Only the original author of a comment can update it. Attempting to update another user's comment will return a 403 Forbidden error.

Delete Comment

DELETE/api/v1/comments/:idwrite:comments

Delete a comment. Only the comment author or team admins can delete comments.

Request Example

curl -X DELETE "https://gateway.thekairos.app/v1/comments/abc12345-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "deleted": true
  }
}

@Mentions

Comments support @mentions to notify team members. Use the following format:

@[Display Name](user-id)

When a comment with mentions is created, the mentioned users will receive notifications. The mentions array in the response contains the user IDs that were mentioned.

Example

{
  "content": "Hey @[John Doe](456e7890-e12b-34d5-a678-901234567000) can you take a look?",
  "task_id": "550e8400-e29b-41d4-a716-446655440000"
}

Getting User IDs

You can retrieve user IDs from the Team Members API endpoint at/api/v1/team/members.

Goals API Team API

API Reference/Comments

Comments API

Create, read, update, and delete comments on tasks and goals. Comments support @mentions for team collaboration.

List Comments

GET/api/v1/commentsread:comments

Retrieve comments for a specific task or goal.

Query Parameters

task_iduuidFilter by task ID

goal_iduuidFilter by goal ID

pageintegerPage number (default: 1)

limitintegerItems per page (default: 50, max: 100)

sort_orderstringSort direction: asc or desc (default: asc)

Request Example

curl -X GET "https://gateway.thekairos.app/v1/comments?task_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "abc12345-e29b-41d4-a716-446655440000",
      "team_id": "123e4567-e89b-12d3-a456-426614174000",
      "task_id": "550e8400-e29b-41d4-a716-446655440000",
      "goal_id": null,
      "user_id": "456e7890-e12b-34d5-a678-901234567000",
      "content": "Great progress! @[John Doe](user-123) can you review this?",
      "mentions": ["user-123"],
      "created_at": "2024-01-10T14:30:00Z",
      "updated_at": "2024-01-10T14:30:00Z",
      "user": {
        "id": "456e7890-e12b-34d5-a678-901234567000",
        "full_name": "Jane Smith",
        "avatar_url": "https://..."
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 5,
    "has_more": false
  }
}

Filter Required

You must provide either task_id or goal_id to list comments. Listing all comments without a filter is not supported.

Get Comment

GET/api/v1/comments/:idread:comments

Retrieve a single comment by ID.

Request Example

curl -X GET "https://gateway.thekairos.app/v1/comments/abc12345-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "id": "abc12345-e29b-41d4-a716-446655440000",
    "team_id": "123e4567-e89b-12d3-a456-426614174000",
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "goal_id": null,
    "user_id": "456e7890-e12b-34d5-a678-901234567000",
    "content": "Great progress! @[John Doe](user-123) can you review this?",
    "mentions": ["user-123"],
    "created_at": "2024-01-10T14:30:00Z",
    "updated_at": "2024-01-10T14:30:00Z",
    "user": {
      "id": "456e7890-e12b-34d5-a678-901234567000",
      "full_name": "Jane Smith",
      "avatar_url": "https://..."
    }
  }
}

Create Comment

POST/api/v1/commentswrite:comments

Create a new comment on a task or goal.

Request Body

contentstringrequiredComment content (supports @mentions)

task_iduuidTask ID to comment on

goal_iduuidGoal ID to comment on

Request Example

curl -X POST "https://gateway.thekairos.app/v1/comments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "content": "Looks good! @[John Doe](user-123) please review when you have time."
  }'

Response

{
  "data": {
    "id": "def67890-e29b-41d4-a716-446655440000",
    "team_id": "123e4567-e89b-12d3-a456-426614174000",
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "goal_id": null,
    "user_id": "456e7890-e12b-34d5-a678-901234567000",
    "content": "Looks good! @[John Doe](user-123) please review when you have time.",
    "mentions": ["user-123"],
    "created_at": "2024-01-10T15:00:00Z",
    "updated_at": "2024-01-10T15:00:00Z"
  }
}

Task or Goal Required

You must provide either task_id or goal_id when creating a comment. A comment cannot exist without being attached to a task or goal.

Update Comment

PATCH/api/v1/comments/:idwrite:comments

Update an existing comment. Only the comment author can update it.

Request Body

contentstringrequiredUpdated comment content

Request Example

curl -X PATCH "https://gateway.thekairos.app/v1/comments/abc12345-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated: This looks great! Ready for deployment."
  }'

Response

{
  "data": {
    "id": "abc12345-e29b-41d4-a716-446655440000",
    "content": "Updated: This looks great! Ready for deployment.",
    "mentions": [],
    "updated_at": "2024-01-10T16:00:00Z"
  }
}

Author Only

Only the original author of a comment can update it. Attempting to update another user's comment will return a 403 Forbidden error.

Delete Comment

DELETE/api/v1/comments/:idwrite:comments

Delete a comment. Only the comment author or team admins can delete comments.

Request Example

curl -X DELETE "https://gateway.thekairos.app/v1/comments/abc12345-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "deleted": true
  }
}

@Mentions

Comments support @mentions to notify team members. Use the following format:

@[Display Name](user-id)

When a comment with mentions is created, the mentioned users will receive notifications. The mentions array in the response contains the user IDs that were mentioned.

Example

{
  "content": "Hey @[John Doe](456e7890-e12b-34d5-a678-901234567000) can you take a look?",
  "task_id": "550e8400-e29b-41d4-a716-446655440000"
}

Getting User IDs

You can retrieve user IDs from the Team Members API endpoint at/api/v1/team/members.

Goals API Team API