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 Required Description
id (path) number yes Epic ID

Request fields (body)

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

Field Type Required 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 who modified 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 application

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 application

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
success boolean Always true on success
data object The epic after the update
data.id number Epic ID
data.groupId number Scrum project ID
data.name string Epic name
data.description string Epic description
data.color string Epic color
data.createdBy number Author ID
data.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 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