لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/timeline-logs.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

CRM Timeline

12 REST endpoints for logging actions in the timeline of CRM entities: creating log entries, notes on them, pinning, binding to multiple entities at once. Entries are written by AI agents, background integrations, and automation scenarios when an action must leave a structured trail in a deal or contact card.

Scope: crm | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

Quick start | An AI agent logs its actions (full example) | Error codes | Endpoint reference

Documentation sections

Log entries — create, view, delete log entries
Notes — a note attached to a log entry
Pins — pin or unpin an entry at the top of the timeline
Bindings — link one entry to multiple CRM entities

When to use

Record an AI agent's action: analyzed the client, prepared a quote, sent a notification.
Capture an event from an external system: payment succeeded, order packed, document signed.
Build an audit trail of an integration: what data it processed, what it based its decision on.
Pin a key deal event at the top of the timeline so the manager sees the context right away.

For text comments from users (not system events), use /v1/timelines — a separate API over crm.timeline.comment.*.

Quick start

1. Create an entry in a deal's timeline

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": "Client data analyzed. Recommendation: offer the Enterprise plan."
  }'

Response:

JSON

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

2. Pin the entry at the top of the timeline

Terminal

curl -X POST https://vibecode.bitrix24.com/v1/timeline-logs/5012/pin \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entityTypeId": 2, "entityId": 100 }'

3. Attach an internal note

Terminal

curl -X POST https://vibecode.bitrix24.com/v1/timeline-logs/5012/note \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entityTypeId": 2, "entityId": 100, "text": "The client usually responds within 2 days." }'

Full example: an AI agent logs its actions

Scenario: an AI agent analyzes a deal, leaves a log entry with the result, binds it to a contact and a company, attaches a note for the manager, and pins it in the timeline.

javascript

const VIBE_KEY = process.env.VIBE_KEY
const BASE = 'https://vibecode.bitrix24.com/v1'

async function api(method, path, body = null) {
  const opts = { method, headers: { 'X-Api-Key': VIBE_KEY } }
  if (body) {
    opts.headers['Content-Type'] = 'application/json'
    opts.body = JSON.stringify(body)
  }
  const res = await fetch(`${BASE}${path}`, opts)
  return res.json()
}

const dealId = 100
const contactId = 50
const companyId = 10

// 1. Record that work has started
const start = await api('POST', '/timeline-logs', {
  entityTypeId: 2,
  entityId: dealId,
  title: 'AI agent started processing',
  text: 'Client data analysis, credit-limit check, quote preparation.',
})
const startId = start.data.id

// 2. Bind the entry to the contact and the company — managers of both will see
//    the same event in their timelines
await api('POST', `/timeline-logs/${startId}/bind`, { entityTypeId: 3, entityId: contactId })
await api('POST', `/timeline-logs/${startId}/bind`, { entityTypeId: 4, entityId: companyId })

// ... the AI agent does its work ...

// 3. Record the result as a separate log entry
const result = await api('POST', '/timeline-logs', {
  entityTypeId: 2,
  entityId: dealId,
  title: 'AI agent finished processing',
  text: [
    '[b]Analysis results:[/b]',
    '- Credit limit: OK (500,000 USD)',
    '- Recommended plan: Enterprise',
    '- Discount: 10% (returning client)',
    '- Quote generated and sent by email',
  ].join('\n'),
})
const resultId = result.data.id

// 4. Pin the final entry at the top of the timeline
await api('POST', `/timeline-logs/${resultId}/pin`, { entityTypeId: 2, entityId: dealId })

// 5. Leave an internal note for the manager
await api('POST', `/timeline-logs/${resultId}/note`, {
  entityTypeId: 2,
  entityId: dealId,
  text: 'The client usually responds within 2 days. Remind the manager if there is no reply.',
})

console.log('AI agent finished, all actions logged')

Which key to use

CRUD operations work with any key type — a personal key (vibe_api_*) or an OAuth application key (vibe_app_*). However, DELETE /v1/timeline-logs/:id imposes a restriction: Bitrix24 allows a log entry to be deleted only by the same app that created it.

OAuth application (vibe_app_* + Authorization: Bearer ...) — stable client_id, you can delete your own entries. If you plan to delete the entries you create via the API, use this key type.
Personal key (vibe_api_*) — Vibecode rotates tokens between calls, so to Bitrix24 each call looks like a separate app. DELETE always returns 403 CROSS_APP_DELETE_FORBIDDEN, including for freshly created entries.

If the app that created the entry is unavailable, there is no way to delete it at all. Bitrix24 does not provide a UI delete button for a log entry in the entity card. Keep this in mind when designing audit scenarios.

For details, see Delete an entry.

Parent entity types

The entityTypeId parameter (the CRM entity's numeric code) specifies whose timeline the entry is created in:

`entityTypeId`	Entity	Where to find the ID
entityTypeId1	EntityLead	Where to find the ID`GET /v1/leads`
entityTypeId2	EntityDeal	Where to find the ID`GET /v1/deals`
entityTypeId3	EntityContact	Where to find the ID`GET /v1/contacts`
entityTypeId4	EntityCompany	Where to find the ID`GET /v1/companies`
entityTypeId7	EntityQuote	Where to find the ID`GET /v1/quotes`
entityTypeId14	EntityOrder	Where to find the ID`GET /v1/orders`
entityTypeId31	EntityInvoice	Where to find the ID`GET /v1/invoices`
entityTypeId≥ 128	EntitySmart process	Where to find the ID`GET /v1/items/:entityTypeId`; list of processes — `GET /v1/smart-processes`

In bindings (bind/unbind) you can use either the numeric entityTypeId or the string entityType directly ("deal", "contact", "dynamic_174", etc.) — see Bind an entry.

Error codes

Timeline errors

HTTP	Code	Description
HTTP400	Code`INVALID_PARAMS`	DescriptionRequired parameters are missing or invalid (`entityTypeId`, `entityId`, `title`, `text`, `itemType`, etc. — the specific field is in `message`)
HTTP400	Code`INVALID_ENTITY_TYPE_ID`	DescriptionIn `bindings.bind`/`unbind`, an `entityTypeId` was passed that has no mapping to `ENTITY_TYPE` (`< 128` and not in the table above)
HTTP403	Code`CROSS_APP_DELETE_FORBIDDEN`	DescriptionAttempt to delete a log entry via a key other than the one it was created with
HTTP404	Code`ENTITY_NOT_FOUND`	DescriptionA log entry with the given `id` does not exist — Bitrix24 returned a `NOT_FOUND` error
HTTP404	Code`NOT_FOUND`	DescriptionOnly `GET /v1/timeline-logs/:id`: Bitrix24 returned a successful response but the entry object is empty
HTTP404	Code`NOTE_NOT_FOUND`	DescriptionOnly `GET /v1/timeline-logs/:id/note`: Bitrix24 answered without an error, but the response carries no note. For an item without a note, Bitrix24 returns an error, so that case returns `404 ENTITY_NOT_FOUND`

System errors

HTTP	Code	Description
HTTP401	Code`MISSING_API_KEY`	DescriptionMissing `X-Api-Key`
HTTP401	Code`INVALID_API_KEY`	DescriptionThe key is not recognized — no such key exists on the platform
HTTP401	Code`TOKEN_MISSING`	DescriptionThe API key has no configured tokens (a `vibe_app_*` key requires `Authorization: Bearer ...`)
HTTP403	Code`SCOPE_DENIED`	DescriptionThe API key lacks the `crm` scope
HTTP403	Code`WRITE_BLOCKED_READONLY_KEY`	DescriptionThe key is read-only and the request writes something — see access rights
HTTP422	Code`BITRIX_ERROR`	DescriptionBitrix24 returned an error (text in `message`)
HTTP429	Code`RATE_LIMITED`	DescriptionRequest rate limit exceeded. Wait 1–2 seconds and retry. Several calls can be combined into `POST /v1/batch`
HTTP429	Code`QUEUE_TIMEOUT`	DescriptionThe request to Bitrix24 did not get through the portal queue in time. The request was NOT sent to Bitrix24 — safe to retry (`Retry-After`). Narrow the filter or retry later
HTTP429	Code`ERROR_LOOP_DETECTED`	DescriptionA Vibecode-side block: many identical errors on one method in a row. Fix the cause first. Then retry reads with backoff; do not retry writes automatically — every Nth request may pass through, so read state first
HTTP502	Code`BITRIX_UNAVAILABLE`	DescriptionThe Bitrix24 portal is unavailable
HTTP503	Code`BITRIX_TIMEOUT`	DescriptionBitrix24 accepted the request but did not respond within 60 seconds. For write operations — re-read the entity first, as the change may have been applied
HTTP500	Code`INTERNAL_ERROR`	DescriptionInternal server error

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

Endpoint reference

All 12 endpoints:

Method	Path	Bitrix24 method	Description
MethodPOST	Path/v1/timeline-logs	Bitrix24 method`crm.timeline.logmessage.add`	DescriptionCreate a log entry
MethodGET	Path/v1/timeline-logs	Bitrix24 method`crm.timeline.logmessage.list`	DescriptionList log entries
MethodGET	Path/v1/timeline-logs/:id	Bitrix24 method`crm.timeline.logmessage.get`	DescriptionGet a single entry
MethodDELETE	Path/v1/timeline-logs/:id	Bitrix24 method`crm.timeline.logmessage.delete`	DescriptionDelete an entry
MethodPOST	Path/v1/timeline-logs/:id/note	Bitrix24 method`crm.timeline.note.save`	DescriptionSave or update a note
MethodGET	Path/v1/timeline-logs/:id/note	Bitrix24 method`crm.timeline.note.get`	DescriptionGet a note
MethodDELETE	Path/v1/timeline-logs/:id/note	Bitrix24 method`crm.timeline.note.delete`	DescriptionDelete a note
MethodPOST	Path/v1/timeline-logs/:id/pin	Bitrix24 method`crm.timeline.item.pin`	DescriptionPin an entry
MethodPOST	Path/v1/timeline-logs/:id/unpin	Bitrix24 method`crm.timeline.item.unpin`	DescriptionUnpin an entry
MethodPOST	Path/v1/timeline-logs/:id/bind	Bitrix24 method`crm.timeline.bindings.bind`	DescriptionBind to another entity
MethodPOST	Path/v1/timeline-logs/:id/unbind	Bitrix24 method`crm.timeline.bindings.unbind`	DescriptionUnbind from an entity
MethodGET	Path/v1/timeline-logs/:id/bindings	Bitrix24 method`crm.timeline.bindings.list`	DescriptionList all bindings of an entry

CRM Timeline

Documentation sections

When to use

Quick start

1. Create an entry in a deal's timeline

2. Pin the entry at the top of the timeline

3. Attach an internal note

Full example: an AI agent logs its actions

Which key to use

Parent entity types

Error codes

Timeline errors

System errors

Endpoint reference

See also