Issue Mutations

Every endpoint on this page requires issues:write.

POST `/v1/issues`

Creates an issue.

Request body

Field	Type	Required
`teamId`	string	yes
`parentIssueId`	string	no
`projectId`	string	no
`deliveryId`	string	no
`title`	string	yes
`description`	string	yes
`initialStatusId`	string	no
`priority`	integer	yes
`estimateValue`	integer	no
`primaryAssigneeUserAccountId`	string	no
`labelIds`	string array	no

Example

curl -X POST "$API_BASE_URL/v1/issues" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "team_platform",
    "projectId": "proj_docs",
    "deliveryId": "del_sprint_18",
    "title": "Document every public API endpoint",
    "description": "Create a complete docs experience for the public API.",
    "initialStatusId": "iss-status_open",
    "priority": 2,
    "estimateValue": 3,
    "primaryAssigneeUserAccountId": "usr_01SAM",
    "labelIds": [
      "label_docs"
    ]
  }'

Response 201 Created:

{
  "id": "issue_plat_142",
  "key": "PLAT-142",
  "title": "Document every public API endpoint",
  "description": "Create a complete docs experience for the public API.",
  "teamId": "team_platform",
  "teamCode": "PLAT",
  "teamName": "Platform",
  "teamIconCss": "fa-solid fa-layer-group",
  "teamColor": "#2563eb",
  "reporterUserAccountId": "usr_01EXAMPLE",
  "reporterDisplayName": "Alex Morgan",
  "reporterAvatarUrl": "https://cdn.example.com/avatars/alex.png",
  "parentIssueId": null,
  "statusId": "iss-status_open",
  "priority": 2,
  "primaryAssigneeUserAccountId": "usr_01SAM",
  "projectId": "proj_docs",
  "deliveryId": "del_sprint_18",
  "assigneeUserAccountIds": [
    "usr_01SAM"
  ],
  "labelIds": [
    "label_docs"
  ],
  "status": {
    "statusId": "iss-status_open",
    "id": "iss-status_open",
    "name": "Open",
    "description": "Ready for work.",
    "color": "#2563eb",
    "category": "open",
    "position": 1,
    "isInitial": true,
    "isTerminal": false
  },
  "project": {
    "projectId": "proj_docs",
    "id": "proj_docs",
    "teamId": "team_platform",
    "name": "Public API Docs",
    "key": "DOCS",
    "iconCss": "fa-regular fa-book-open",
    "color": "#0f766e"
  },
  "delivery": {
    "deliveryId": "del_sprint_18",
    "teamId": "team_platform",
    "number": 18,
    "name": "Sprint 18",
    "description": "API launch sprint.",
    "startsOn": "2025-02-17",
    "endsOn": "2025-02-28",
    "state": "active",
    "issueCount": 24,
    "closedIssueCount": 11,
    "estimatedScope": 56,
    "closedEstimate": 21,
    "isCurrent": true,
    "isUpcoming": false
  },
  "assignees": [
    {
      "userAccountId": "usr_01SAM",
      "displayName": "Sam Patel",
      "avatarUrl": "https://cdn.example.com/avatars/sam.png",
      "principalKind": 0
    }
  ],
  "roleAssignments": [],
  "labels": [
    {
      "labelId": "label_docs",
      "id": "label_docs",
      "isGroup": false,
      "name": "documentation",
      "description": "Documentation work",
      "color": "#8b5cf6",
      "teamId": "team_platform",
      "groupId": "label-group_area",
      "groupName": "Area"
    }
  ],
  "commentCount": 0,
  "subIssueCount": 0,
  "linkCount": 0,
  "estimateValue": 3,
  "dueDate": null,
  "createdUtc": "2025-02-24T16:30:00Z",
  "updatedUtc": "2025-02-24T16:30:00Z",
  "lastActivityUtc": null,
  "lastCommentUtc": null,
  "closedUtc": null,
  "isSubscribed": true
}

PATCH `/v1/issues/{issueKey}`

Updates an issue.

Request body

All fields are optional, but at least one writable field must be present.

Field	Type	Notes
`title`	string	Update title
`description`	string	Plain text description
`issueStatusId`	string	Update status
`priority`	integer	Update priority
`primaryAssigneeUserAccountId`	string	Set primary assignee
`clearPrimaryAssignee`	boolean	Clear assignee
`projectId`	string	Set project
`clearProject`	boolean	Clear project
`deliveryId`	string	Set delivery
`clearDelivery`	boolean	Clear delivery
`estimateValue`	integer	Set estimate
`clearEstimate`	boolean	Clear estimate
`dueDate`	date	Set due date
`clearDueDate`	boolean	Clear due date
`labelIds`	string array	Replace labels

Validation rules

primaryAssigneeUserAccountId and clearPrimaryAssignee cannot be combined
projectId and clearProject cannot be combined
deliveryId and clearDelivery cannot be combined
estimateValue and clearEstimate cannot be combined
dueDate and clearDueDate cannot be combined

Example

curl -X PATCH "$API_BASE_URL/v1/issues/PLAT-142" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "issueStatusId": "iss-status_in-progress",
    "priority": 1,
    "dueDate": "2025-03-05",
    "labelIds": [
      "label_docs"
    ]
  }'

Response 200 OK:

{
  "id": "issue_plat_142",
  "key": "PLAT-142",
  "title": "Document every public API endpoint",
  "description": "Create a complete docs experience for the public API.",
  "teamId": "team_platform",
  "teamCode": "PLAT",
  "teamName": "Platform",
  "teamIconCss": "fa-solid fa-layer-group",
  "teamColor": "#2563eb",
  "reporterUserAccountId": "usr_01EXAMPLE",
  "reporterDisplayName": "Alex Morgan",
  "reporterAvatarUrl": "https://cdn.example.com/avatars/alex.png",
  "parentIssueId": null,
  "statusId": "iss-status_in-progress",
  "priority": 1,
  "primaryAssigneeUserAccountId": "usr_01SAM",
  "projectId": "proj_docs",
  "deliveryId": "del_sprint_18",
  "assigneeUserAccountIds": [
    "usr_01SAM"
  ],
  "labelIds": [
    "label_docs"
  ],
  "status": {
    "statusId": "iss-status_in-progress",
    "id": "iss-status_in-progress",
    "name": "In Progress",
    "description": "Work is actively underway.",
    "color": "#f59e0b",
    "category": "active",
    "position": 2,
    "isInitial": false,
    "isTerminal": false
  },
  "project": {
    "projectId": "proj_docs",
    "id": "proj_docs",
    "teamId": "team_platform",
    "name": "Public API Docs",
    "key": "DOCS",
    "iconCss": "fa-regular fa-book-open",
    "color": "#0f766e"
  },
  "delivery": {
    "deliveryId": "del_sprint_18",
    "teamId": "team_platform",
    "number": 18,
    "name": "Sprint 18",
    "description": "API launch sprint.",
    "startsOn": "2025-02-17",
    "endsOn": "2025-02-28",
    "state": "active",
    "issueCount": 24,
    "closedIssueCount": 11,
    "estimatedScope": 56,
    "closedEstimate": 21,
    "isCurrent": true,
    "isUpcoming": false
  },
  "assignees": [
    {
      "userAccountId": "usr_01SAM",
      "displayName": "Sam Patel",
      "avatarUrl": "https://cdn.example.com/avatars/sam.png",
      "principalKind": 0
    }
  ],
  "roleAssignments": [],
  "labels": [
    {
      "labelId": "label_docs",
      "id": "label_docs",
      "isGroup": false,
      "name": "documentation",
      "description": "Documentation work",
      "color": "#8b5cf6",
      "teamId": "team_platform",
      "groupId": "label-group_area",
      "groupName": "Area"
    }
  ],
  "commentCount": 0,
  "subIssueCount": 0,
  "linkCount": 0,
  "estimateValue": 3,
  "dueDate": "2025-03-05",
  "createdUtc": "2025-02-24T16:30:00Z",
  "updatedUtc": "2025-02-24T16:45:00Z",
  "lastActivityUtc": "2025-02-24T16:45:00Z",
  "lastCommentUtc": null,
  "closedUtc": null,
  "isSubscribed": true
}

DELETE `/v1/issues/{issueKey}`

Deletes an issue.

curl -X DELETE "$API_BASE_URL/v1/issues/PLAT-142" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response 204 No Content.

Error notes

Invalid payloads return 400 validation_failed
Unknown issues return 404 not_found

Issue Mutations

POST /v1/issues

Request body

Example

PATCH /v1/issues/{issueKey}

Request body

Validation rules

Example

DELETE /v1/issues/{issueKey}

Error notes

POST `/v1/issues`

PATCH `/v1/issues/{issueKey}`

DELETE `/v1/issues/{issueKey}`