For AI agents: markdown of this page — /docs-content-en/scrum/epics/update.md documentation index — /llms.txt

Update an epic

PATCH /v1/scrum/epics/:id

Partially updates a scrum-project epic: rename, recolor, change the description or the scrum project. The body is flat, with no fields wrapper.

Parameters

Parameter Type Req. Description
id (path) number yes Epic ID

Request fields (body)

Pass only the fields you want to change. At least one of those listed is required.

Field Type Req. Description
name string no New epic name. Up to 65,535 characters
groupId number no New scrum project ID. List: GET /v1/workgroups
description string no New description. Up to 65,535 characters
color string no New epic color, for example "#5eead4". Up to 64 characters
modifiedBy number no ID of the user editing the epic. List: GET /v1/users

Examples

curl — personal key

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/scrum/epics/9 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "doc-verify epic",
    "description": "x",
    "color": "#5eead4",
    "modifiedBy": 1
  }'

curl — OAuth app

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/scrum/epics/9 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "doc-verify epic",
    "description": "x",
    "color": "#5eead4",
    "modifiedBy": 1
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/scrum/epics/9', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'doc-verify epic',
    description: 'x',
    color: '#5eead4',
    modifiedBy: 1,
  }),
})

const { data } = await res.json()

JavaScript — OAuth app

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/scrum/epics/9', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'doc-verify epic',
    description: 'x',
    color: '#5eead4',
    modifiedBy: 1,
  }),
})

const { data } = await res.json()

Response fields

Field Type Description
id number Epic ID
groupId number Scrum project ID
name string Epic name
description string Epic description
color string Epic color
createdBy number Author ID
modifiedBy number ID of the last editor

Response example

JSON 
{
    "success": true,
    "data": {
        "id": 9,
        "groupId": 45,
        "name": "doc-verify epic",
        "description": "x",
        "createdBy": 1,
        "modifiedBy": 1,
        "color": "#5eead4"
    }
}

Error response example

400 — validation failed:

JSON 
{
    "success": false,
    "error": {
        "code": "INVALID_PARAMS",
        "message": "At least one of name, groupId, description, color, createdBy, modifiedBy is required"
    }
}

Errors

HTTP Code Description
400 INVALID_PARAMS Empty body, non-numeric id, wrong field type, or createdBy was passed
404 ENTITY_NOT_FOUND No epic exists with the given id
422 BITRIX_ERROR Bitrix24 returned an error while updating the epic
403 SCOPE_DENIED The key lacks the task scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only
401 TOKEN_MISSING The key has no configured tokens

Full list of common API errors — Errors.

Known specifics

createdBy is set only on creation. On update this field is rejected with 400 INVALID_PARAMS and the message "createdBy can only be set on create". Authorship cannot be transferred — to record who made the change, use modifiedBy.

See also