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
Parameterid (path) Typenumber Requiredyes DescriptionEpic 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
Fieldname Typestring Requiredno DescriptionNew epic name. Up to 65,535 characters
FieldgroupId Typenumber Requiredno DescriptionNew scrum project ID. List: GET /v1/workgroups
Fielddescription Typestring Requiredno DescriptionNew description. Up to 65,535 characters
Fieldcolor Typestring Requiredno DescriptionNew epic color, for example "#5eead4". Up to 64 characters
FieldmodifiedBy Typenumber Requiredno DescriptionID 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe epic after the update
Fielddata.id Typenumber DescriptionEpic ID
Fielddata.groupId Typenumber DescriptionScrum project ID
Fielddata.name Typestring DescriptionEpic name
Fielddata.description Typestring DescriptionEpic description
Fielddata.color Typestring DescriptionEpic color
Fielddata.createdBy Typenumber DescriptionAuthor ID
Fielddata.modifiedBy Typenumber DescriptionID 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
HTTP400 CodeINVALID_PARAMS DescriptionEmpty body, non-numeric id, wrong field type, or createdBy passed
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo epic exists with the given id
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error while updating the epic
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the task scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only
HTTP401 CodeTOKEN_MISSING DescriptionThe 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