API чтения

Все эндпоинты чтения находятся под /api/v1 и требуют Bearer-токена со скоупом read.

История сущности

GET /api/v1/collections/{collection}/entities/{entityId}/history

Возвращает постраничный список событий для сущности (по умолчанию новейшие первые).

Параметры запроса

Параметр	Тип	По умолчанию	Описание
`from`	RFC3339	—	События, полученные с этого момента
`to`	RFC3339	—	События до этого момента
`author_id`	string	—	Фильтр по автору
`op`	string	—	Фильтр по операции: `create`, `update`, `delete`
`path`	string	—	Фильтр по пути поля
`limit`	integer	100	Размер страницы (1–1000)
`cursor`	string	—	Токен пагинации из предыдущего ответа
`order`	string	`desc`	`asc` или `desc`
`format`	string	`native`	Формат диффа: `native` или `json-patch` (RFC 6902)

Ответ (200):

{
  "entity_id": "deal-1",
  "next_cursor": "eyJ2IjoxMH0=",
  "events": [
    {
      "version": 4,
      "op": "update",
      "ts_received": "2026-06-02T09:00:01Z",
      "author_id": "user-42",
      "integrity": {
        "hash":      "sha256:9f86d0...",
        "prev_hash": "sha256:2c2640..."
      },
      "changes": [
        {"path": "amount", "op": "change", "old": 50000, "new": 75000}
      ]
    }
  ]
}

Поле integrity присутствует только когда включён плагин hash_chain.

Текущее состояние

GET /api/v1/collections/{collection}/entities/{entityId}/state

{
  "entity_id": "deal-1",
  "version": 4,
  "ts": "2026-06-02T09:00:01Z",
  "deleted": false,
  "state": {
    "title": "ООО Ромашка",
    "amount": 75000,
    "stage": "qualified"
  }
}

Возвращает 404 если сущность никогда не записывалась или была purge-удалена.

Point-in-time состояние

GET /api/v1/collections/{collection}/entities/{entityId}/state?version=3
GET /api/v1/collections/{collection}/entities/{entityId}/state?ts=2026-05-01T00:00:00Z

Восстанавливает состояние сущности на конкретную версию или момент времени. Letopis использует ближайший слепок + хвостовую перезагрузку.

Верификация хэш-цепи

GET /api/v1/collections/{collection}/entities/{entityId}/verify

Проверяет SHA-256 хэш-цепь для сущности. Возвращает первое расхождение или {"ok": true} при целостности цепи.

Список сущностей

GET /api/v1/collections/{collection}/entities

Постраничный список ID сущностей в коллекции. Параметры: limit, cursor, order_by (entity_id или ts), order.

Бизнес-потоки

GET /api/v1/flows/{flowId}

Возвращает полный причинно-следственный DAG бизнес-потока: все активности и связи caused_by.

{
  "flow_id": "flow-deal-onboarding",
  "activities": [
    {
      "activity_id": "act-111",
      "collection": "crm.deals",
      "entity_id": "deal-1",
      "version": 2,
      "step": "qualification",
      "caused_by": []
    }
  ]
}

Edit this page on GitHub ↗