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

Timeline entries

Create, read, and delete log entries in a CRM entity's timeline. A log entry is a structured event that appears in a card's history (deal, lead, contact, company, smart process) as a message from an application with a title and text.

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

Create an entry

POST /v1/timeline-logs

Creates a new entry in a CRM entity's log (timeline). The entry will appear in the card history of a deal, lead, contact, company, or smart process as a message from an application.

Request fields (body)

Field Type Required Description
entityTypeId number yes Parent CRM entity type: 1=lead, 2=deal, 3=contact, 4=company, 7=quote, 14=order, 31=invoice, ≥128=smart process. See Entity types
entityId number yes Parent record ID. Source: GET /v1/deals, GET /v1/leads, GET /v1/contacts, GET /v1/companies, GET /v1/items/:entityTypeId
title string yes Entry title. Displayed in bold in the timeline card
text string yes Main entry text. An empty string is allowed ("")
iconCode string no Icon code next to the title. Example values: info, circle-check, document, link, unlink, view, stage-change, sum, store, relation, IM, call, call-incoming, call-completed. Defaults to the empty string "" (no icon)

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/timeline-logs \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityTypeId": 2,
    "entityId": 100,
    "title": "AI agent processed the request",
    "text": "Customer data analyzed. Recommendation: Enterprise plan."
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/timeline-logs \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityTypeId": 2,
    "entityId": 100,
    "title": "AI agent processed the request",
    "text": "Customer data analyzed. Recommendation: Enterprise plan."
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/timeline-logs', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entityTypeId: 2,
    entityId: 100,
    title: 'AI agent processed the request',
    text: 'Customer data analyzed. Recommendation: Enterprise plan.',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/timeline-logs', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entityTypeId: 2,
    entityId: 100,
    title: 'AI agent processed the request',
    text: 'Customer data analyzed. Recommendation: Enterprise plan.',
  }),
})

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

Response fields

Field Type Description
success boolean Always true on success
data object The created log entry
data.id number ID of the created log entry
data.created datetime Creation date, ISO 8601 with the Bitrix24 account timezone
data.authorId number Author ID. When created via the API, it matches the API key's user
data.title string Title
data.text string Entry text
data.iconCode string Icon code. Always present: the empty string "" if it was not passed on creation

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 5012,
    "created": "2026-04-27T10:00:00+00:00",
    "authorId": 1,
    "title": "AI agent processed the request",
    "text": "Customer data analyzed. Recommendation: Enterprise plan.",
    "iconCode": ""
  }
}

Error response example

400 — a required field is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Required: entityTypeId (positive int), entityId (positive int), title (string), text (string). Optional: iconCode (string, default \"\")"
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS entityTypeId, entityId, title, text not provided or invalid, or iconCode type is not a string
422 BITRIX_ERROR Bitrix24 rejected the request, for example, because the parent entity does not exist
403 SCOPE_DENIED The API key does not have the crm scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only — see access rights
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

Only the application that created an entry can delete it. Bitrix24 forbids deleting a log entry through an application other than the one that created it. Personal keys (vibe_api_*) rotate OAuth tokens, so DELETE through them always returns 403 CROSS_APP_DELETE_FORBIDDEN. For the full "create → delete via API" lifecycle, use an OAuth application (vibe_app_* + Authorization: Bearer ...). See Delete an entry.

The text field is required but allows an empty string. Bitrix24 accepts text: "", and the title is still displayed. To leave an entry without a description, pass an empty string, not null.

See also