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

Comment fields

GET /v1/timelines/fields

Returns the field schema of a timeline comment.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/timelines/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/timelines/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/timelines/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Fields:', Object.keys(data.fields))

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/timelines/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

The label and description field captions are returned in English, while the ones the platform takes straight from the Bitrix24 account come in the account language. Request headers do not switch the language.

Field Bitrix24 Type RO Description
Fieldid Bitrix24ID Typenumber ROyes DescriptionComment ID
FieldentityType Bitrix24ENTITY_TYPE Typestring RO DescriptionType of the parent CRM record: deal, lead, contact, company or DYNAMIC_<entityTypeId> for smart processes (e.g. DYNAMIC_174). In the response it is returned in lowercase (dynamic_174). Can only be set when creating a comment and cannot be changed later
FieldentityId Bitrix24ENTITY_ID Typenumber RO DescriptionParent record ID. Can only be set when creating a comment and cannot be changed later. Source: GET /v1/deals, GET /v1/leads, GET /v1/contacts, GET /v1/companies, GET /v1/items/:entityTypeId (smart process items)
Fieldcomment Bitrix24COMMENT Typestring RO DescriptionComment text. Required on creation
FieldauthorId Bitrix24AUTHOR_ID Typenumber ROyes DescriptionComment author ID. Bitrix24 derives the author from the credentials the call is made with — it cannot be set on update or on create. User data by ID: GET /v1/users/:id
FieldcreatedAt Bitrix24CREATED Typedatetime ROyes DescriptionCreation date, ISO 8601 in UTC
FieldFILES Bitrix24FILES Typeattached_diskfile RO DescriptionAttachments. On write — an array of [[fileName, base64Content]] pairs, on read — an object where the key is the Drive file ID. See: Add comment

Response example

GET /v1/timelines/fields returns field descriptions under the data.fields key, where each field is { type, readonly, label, description }. The label of the FILES field comes from Bitrix24 and depends on the account language.

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true, "label": "ID", "description": "Unique numeric identifier of the timeline comment." },
      "entityType": { "type": "string", "readonly": false, "createOnly": true, "label": "Entity type", "description": "Type of the parent CRM record: deal, lead, contact, company, or DYNAMIC_<entityTypeId> for smart processes. Set only on create." },
      "entityId": { "type": "number", "readonly": false, "createOnly": true, "label": "Entity ID", "description": "ID of the parent CRM record the comment belongs to. Set only on create." },
      "comment": { "type": "string", "readonly": false, "label": "Comment", "description": "Comment text. Required on create." },
      "authorId": { "type": "number", "readonly": true, "label": "Author", "description": "ID of the user who wrote the comment. Read-only: Bitrix24 derives the author from the credentials the call is made with." },
      "createdAt": { "type": "datetime", "readonly": true, "label": "Created at", "description": "Date and time the comment was created (ISO 8601, UTC)." },
      "FILES": { "type": "attached_diskfile", "readonly": false, "label": "File list", "description": "Files attached to the comment. On write pass an array of [file name, file content in base64] pairs; on read the field comes back as an object keyed by the Bitrix24 Drive file id." }
    }
  }
}

Error response example

403 — no scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}

Errors

HTTP Code Description
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

For the full list of common API errors, see Errors.

Known specifics

Three comment fields cannot be changed, and /fields marks them differently because the reasons differ. entityType and entityId carry createOnly: true: a comment is bound to its record at creation time and cannot be moved to another one. authorId carries readonly: true: Bitrix24 derives the author from the credentials the call is made with, so the value cannot be set on update or on create — to have the comment come from a specific user, make the call on that user's behalf. PATCH /v1/timelines/:id returns 400 READONLY_FIELD if the request includes any of the three fields. comment stays writable.

See also