Add work-item comment

Adds one attributable comment. For Jira-backed work items, DigitalStack validates the request and passes the comment through to Jira before recording the local audit/result.

POST/api/v1/work-items/:id/comments

Authorization

work-items:commentapi key scoperequired

Required scope when calling with an API key.

Path parameters

idstringrequired

Canonical work-item ID

Example: work_01k2...

Request body

bodystringrequired

Comment body

expected_versionnumberoptional

Optimistic work-item version guard

mentionsarrayoptional

Mentioned DigitalStack user IDs

confirmbooleanrequired

Must be true

Example request

{
  "body": "Implementation started. I will attach the PR when ready.",
  "expected_version": 7,
  "mentions": [
    "user_jordan"
  ],
  "confirm": true
}

Request

POST /api/v1/work-items/:id/comments

curl -X POST "https://www.digitalstack360.com/api/v1/work-items/work_01k2.../comments" \
  -H "Authorization: Bearer $DS_API_KEY" \
  -H "Idempotency-Key: work-42-comment-20260715" \
  -H "Content-Type: application/json" \
  -d '{"body":"Implementation started. I will attach the PR when ready.","expected_version":7,"mentions":["user_jordan"],"confirm":true}'

Examples use a placeholder key from your environment. Store your key in $DS_API_KEY — never commit it.

Response

200 OK

{
  "data": {
    "work_item": {
      "id": "work_01k2...",
      "key": "DSN-42",
      "version": 7
    },
    "comment": {
      "id": "comment_01k7...",
      "body_preview": "Implementation started...",
      "created_at": "2026-07-15T18:22:04Z"
    },
    "source_writeback": {
      "mode": "provider_passthrough",
      "source_system": "jira",
      "provider_operation": "jira.addComment",
      "provider_result": "applied"
    }
  },
  "meta": {
    "idempotency_replayed": false
  }
}

Errors

401

missing_auth

No credentials provided

401

invalid_api_key

API key is invalid or revoked

400

bad_request

Missing or invalid request fields

403

scope_insufficient

Key lacks the required write scope

403

scope_insufficient

Key lacks work-items:comment scope

400

comment_body_required

body is required

409

stale_work_item_version

expected_version does not match the current work item version

409

provider_writeback_unavailable

The source provider cannot accept this command