## Add comment `POST /v1/timelines` Creates a new timeline comment attached to a CRM record. Use it to record notes on deals, leads, contacts and companies. ## Request fields (body) | Field | Type | Required | Description | |------|-----|:-----:|---------| | **`entityType`** | string | yes | Type of the parent CRM record: `deal`, `lead`, `contact`, `company` or `DYNAMIC_` for smart processes. For example, `DYNAMIC_174` for a smart process with `entityTypeId: 174` from [`GET /v1/smart-processes`](/docs/entities/smart-processes/list) | | **`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 an array of two strings `[fileName, base64Content]`. The field type in the Bitrix24 schema is `attached_diskfile` | When created via the API, the author (`authorId`) is taken from the API key owner, and the creation date (`createdAt`) is set 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. In the create response and when reading the comment ([`GET /v1/timelines/:id`](/docs/entities/timelines/get)), 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, "date": "2026-04-24T12:34:05+00:00", "type": "file", "name": "report.pdf", "size": 11, "image": false, "authorId": 1, "authorName": "John Smith", "urlPreview": null, "urlShow": "https://example.bitrix24.com/disk/downloadFile/9317/?&ncc=1&filename=report.pdf", "urlDownload": "https://example.bitrix24.com/disk/downloadFile/9317/?&ncc=1&filename=report.pdf" } } ``` The `urlShow` and `urlDownload` addresses point to the Bitrix24 account's Drive and cannot be authorized with a key. Download the file through [`GET /v1/timelines/:commentId/files/:fileRef/download`](/docs/entities/timelines/file-download). ## Examples ### curl — personal key ```bash 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 ```bash 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 ```bash 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 | |------|-----|---------| | `success` | boolean | Always `true` on success | | `data` | object | The created comment | | `data.id` | number | ID of the created comment | | `data.entityType` | string | Type of the parent record | | `data.entityId` | number | Parent record ID | | `data.comment` | string | Comment text | | `data.authorId` | number | Author ID — when created via the API, matches the key owner | | `data.createdAt` | datetime | Creation date, ISO 8601 in UTC | | `data.FILES` | object | Attached files — only if any were passed. The key is the Drive file ID and the value holds the file metadata, shown in the "Attaching files" section above | | `meta.warnings` | array | Present when the body carries fields that are neither in the comment schema nor in the field list of [`GET /v1/timelines/fields`](/docs/entities/timelines/fields), for example a misspelled name. The warning code is `UNRECOGNIZED_WRITE_FIELD`: such a field may not have been stored. The response status is `201` On a route that wraps the field map itself, an object under `fields` is rejected with `400 NESTED_FIELDS_ENVELOPE` when the schema does not declare `fields`; pass fields flat at the JSON root. | ## 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 | `READONLY_FIELD` | The body carries a field that cannot be set on create: `authorId`, `id` or `createdAt`. Bitrix24 derives the author from the credentials the call is made with — to have the comment come from a specific user, make the call on that user's behalf | | 400 | `INVALID_FILES_SHAPE` | The `FILES` field was not an array of `[[fileName, base64Content]]` pairs | | 422 | `BITRIX_ERROR` | Validation failed: 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](/docs/errors). ## See also - [List comments](/docs/entities/timelines/list) - [Update comment](/docs/entities/timelines/update) - [Delete comment](/docs/entities/timelines/delete) - [Comment fields](/docs/entities/timelines/fields) - [Batch](/docs/batch) - [Limits and optimization](/docs/optimization)