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

Add a time-tracking entry

POST /v1/tasks/:taskId/time

Creates a new time-tracking entry for a task — records the seconds spent and, optionally, the author of the entry and a comment on it.

Parameters

Parameter Type Required Description
taskId (path) number yes Task ID

Request fields (body)

Field Type Required Description
seconds number yes Duration in seconds
comment string no Comment for the entry. When the entry is read back, it is returned in the commentText field
userId number no Author ID. Defaults to the API-key user. Pass only existing employee IDs from GET /v1/users — see "Known specifics"
createdDate string no Date and time of the entry. Three formats are accepted: ISO 8601 with offset 2026-07-13T14:30:00+00:00, ISO 8601 without offset 2026-07-13T14:30:00, and a date 2026-07-13. If the field is omitted, the entry is dated at the time it is created

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/289/time" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "seconds": 1800,
    "comment": "Draft preparation"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/289/time" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "seconds": 1800,
    "comment": "Draft preparation"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/289/time', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    seconds: 1800,
    comment: 'Draft preparation',
  }),
})

const { success, data } = await res.json()
console.log('New entry ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/289/time', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    seconds: 1800,
    comment: 'Draft preparation',
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data.id number ID of the created entry. Use it for GET / PATCH / DELETE

Response example

HTTP 201 Created:

JSON 
{
  "success": true,
  "data": {
    "id": 161
  }
}

Error response example

400 — the required seconds field was not provided:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "Required: seconds (number)"
  }
}

Errors

HTTP Code Description
400 MISSING_PARAMS The seconds field was not provided
422 BITRIX_ERROR Bitrix24 returned an error (e.g. the parent task is inaccessible)
403 SCOPE_DENIED The API key lacks the task scope
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

The existence of userId is not validated. The entry is saved with any userId, even a non-existent one, and the call returns 201. But such a "ghost" entry cannot then be read, updated, or deleted — GET, PATCH and DELETE /v1/tasks/:taskId/time/:itemId return 404 NOT_FOUND. It remains visible only in the lists GET /v1/tasks/:taskId/time and GET /v1/task-time, cluttering reports with no way to clean it up via the API. Pass only real employee IDs from GET /v1/users.

The response contains only id, without the other fields. Unlike creating a task or comment, this method returns only the identifier. To get the full entry with minutes, source, createdDate, dateStart and dateStop filled in by the system, call GET /v1/tasks/:taskId/time/:itemId.

See also