For AI agents: markdown of this page — /docs-content-en/entities/tasks/favorite.md documentation index — /llms.txt

Add a task to favorites

POST /v1/tasks/:taskId/favorite

Adds a task to the personal favorites list of the user the key acts on behalf of. The action is available to a participant with view access to the task — edit rights on the task are not required, unlike PATCH /v1/tasks/:id.

Parameters

Parameter In Type Required Description
ParametertaskId Inpath Typeinteger Requiredyes DescriptionTask ID. List: GET /v1/tasks

The request body is empty.

Examples

curl — personal key

Terminal 
curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/tasks/289/favorite

curl — OAuth application

Terminal 
curl -X POST -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.com/v1/tasks/289/favorite

JavaScript — personal key

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/tasks/${taskId}/favorite`,
  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const body = await res.json()
console.log(body.data.favorite) // true

JavaScript — OAuth application

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/tasks/${taskId}/favorite`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on successful addition
Fielddata.taskId Typeinteger DescriptionTask ID
Fielddata.favorite Typeboolean Descriptiontrue — the task is in favorites

Response example

JSON 
{
  "success": true,
  "data": {
    "taskId": 289,
    "favorite": true
  }
}

Error response example

404 — the task was not found or is inaccessible:

JSON 
{
  "success": false,
  "error": {
    "code": "TASK_NOT_FOUND",
    "message": "Task 99999999 not found or not accessible."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptiontaskId in the path is not a positive integer
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not provided
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no linked authorization tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the task scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionA read-only key — the action changes data and is blocked
HTTP404 CodeTASK_NOT_FOUND DescriptionThe task was not found or is inaccessible to the user

Full list of common API errors — Errors.

Known specifics

  • Each user has their own list. Favorites are tied to the user the key acts on behalf of. The same task can be in one employee's favorites and absent from another's.
  • The response is a slim confirmation, not the full task. Read the full task fields via GET /v1/tasks/:id.
  • The task's existence is checked before the action. Bitrix24 confirms the favorite even for a task that does not exist, so the service reads the task first and answers 404 TASK_NOT_FOUND when it is missing or inaccessible to the key. That case used to answer 200 with favorite: true while nothing was saved. The cost is one extra Bitrix24 call per request.

See also