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

Timeline comments

Manage CRM timeline comments: recording operator notes, negotiation history and other context for deals, leads, contacts, companies and other entities. Each comment is attached to a specific CRM record via the entityType + entityId pair.

Bitrix24 API: crm.timeline.comment.* Scope: crm

Add comment

POST /v1/timelines

Creates a new timeline comment attached to a CRM record. Used to record notes on deals, leads, contacts and companies.

Request fields (body)

Field Type Req. Description
entityType string yes Type of the parent CRM record: deal, lead, contact, company or DYNAMIC_<entityTypeId> for smart processes (e.g. DYNAMIC_174 for a smart process with entityTypeId: 174 from GET /v1/smart-processes)
entityId number yes Parent record ID. The source depends on the type: GET /v1/deals, GET /v1/leads, GET /v1/contacts, GET /v1/companies, GET /v1/items/:entityTypeId (smart-process items)
comment string yes Comment text. An empty string is rejected with the error BITRIX_ERROR Empty comment message
FILES array no Comment attachments. Each element is a two-string array [fileName, base64Content]. The field type in the Bitrix24 schema is attached_diskfile

When created via the API, the author (authorId) is set from the API key owner, and the creation date (createdAt) by the server.

Attaching files. The FILES field is an array of [fileName, base64Content] pairs, one pair per file. The file content is passed as a base64-encoded string, the file is uploaded to Bitrix24 Drive and linked to the comment.

When reading the comment (GET /v1/timelines/:id), attached files are returned in the FILES field — an object where the key is the Drive file ID and the value holds the metadata:

JSON 
"FILES": {
  "9317": {
    "id": 9317,
    "name": "report.pdf",
    "size": 11,
    "type": "file",
    "urlDownload": "https://vibecode.bitrix24.com/disk/downloadFile/9317/?filename=report.pdf"
  }
}

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/timelines \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "deal",
    "entityId": 741,
    "comment": "First contact: the client showed interest in the offer"
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/timelines \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "deal",
    "entityId": 741,
    "comment": "First contact: the client showed interest in the offer"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/timelines', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entityType: 'deal',
    entityId: 741,
    comment: 'First contact: the client showed interest in the offer',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/timelines', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entityType: 'deal',
    entityId: 741,
    comment: 'First contact: the client showed interest in the offer',
  }),
})

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

curl — comment with a file

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/timelines \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "deal",
    "entityId": 741,
    "comment": "Report attached",
    "FILES": [["report.pdf", "JVBERi0xLjQKJ..."]]
  }'

Response fields

Field Type Description
id number ID of the created comment
entityType string Type of the parent record
entityId number Parent record ID
comment string Comment text
authorId number Author ID — when created via the API, matches the key owner
createdAt datetime Creation date (ISO 8601, UTC)
FILES object Attached files — only if any were passed. The key is the Drive file ID, the value holds the metadata: name, size, type, urlDownload

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 66303,
    "entityId": 741,
    "entityType": "deal",
    "comment": "First contact: the client showed interest in the offer",
    "authorId": 1,
    "createdAt": "2026-04-24T12:34:05.000Z"
  }
}

Error response example

422 — the required comment was not provided:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Empty comment message"
  }
}

Errors

HTTP Code Description
400 INVALID_FILES_SHAPE The FILES field was not an array of [[fileName, base64Content]] pairs
422 BITRIX_ERROR Requirement violation: empty comment, invalid entityType
403 SCOPE_DENIED The API key lacks the crm scope
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

See also