---
title: "Довідник Context API"
description: "Маршрути, параметри, ліміти та коди помилок Context API для інтеграцій і MCP."
---

# Довідник Context API

Context API віддає стислий зріз про одну сутність: клієнта, тематику, оператора або скіл-групу. У відповіді — дозволені поля зараз і короткі уривки звернень, які це підтверджують. Розмір пакета обмежений, тож його можна передати в CRM або агенту без повної історії чатів.

Навіщо так зроблено і чим стан відрізняється від репліки в чаті — у поясненні [«Про те, як Context API збирає контекст»](/uk/integrations/explanation/what-is-context-api.md).

API сам не запускає Copilot чи інші AI-сценарії. Його викликає ваша інтеграція або MCP-інструмент. API бере інстанс і користувача з авторизованої сесії. Ідентифікатор інстансу в тілі запиту не дає доступу до чужих даних.

Авторизація — як у решти ConnectiveOne API. Див. [Як використовувати API](/uk/integrations/how-to/use-api.md).

## Єдиний контракт

Маршрут читання використовує одну форму запиту й відповіді для клієнта, тематики, оператора та скіл-групи. Поле `version` не передавайте: API відхиляє його як некоректний запит. Для читання потрібне готове сховище контексту; прихованого переходу на старий формат `facts` немає.

## Читання контексту

```http
POST /kw/chatrooms/context/retrieve
Authorization: Bearer <access-token>
Content-Type: application/json
```

API перевіряє права до складання відповіді і ще раз перед видачею. Якщо доступ зник під час запиту, API повертає помилку і не підставляє застарілі дані.

### Клієнт

Останні звернення:

```json
{
  "scope": { "entity": "client", "id": 10004 },
  "targets": ["previous_client_appeals"],
  "topK": 8
}
```

Останні та релевантні звернення:

```json
{
  "scope": { "entity": "client", "id": 10004 },
  "targets": ["previous_client_appeals", "relevant_appeals"],
  "query": "повернення коштів",
  "topK": 8
}
```

### Тематика

```json
{
  "scope": { "entity": "subject", "id": 3 },
  "targets": ["recent_subject_appeals", "relevant_subject_appeals"],
  "query": "доставка затримується"
}
```

Поле `query` обов’язкове, якщо серед `targets` є `relevant_appeals` або `relevant_subject_appeals`.

### Стан, дії та властивості

```json
{
  "scope": { "entity": "client", "id": 10004 },
  "sections": ["state", "actions", "properties", "evidence"],
  "targets": ["previous_client_appeals", "previous_client_conversations"],
  "actions": { "limit": 20, "actorTypes": ["client", "operator"] },
  "allowPartial": true
}
```

Якщо `sections` не передати, API бере типовий набір для сутності; явні `targets` або діапазон `from`/`to` додають `evidence`, а параметри `actions` — розділ дій клієнта. `query` можна передати лише разом із `targets`. Якщо в `sections` є `evidence`, а `targets` немає, API бере типовий напрям «останні» для цієї сутності.

| `scope.entity` | Дозволені `sections` | Типовий набір |
|---|---|---|
| `client` | `state`, `actions`, `properties`, `evidence` | `state`, `properties` |
| `subject` | `properties`, `evidence` | `properties`, `evidence` |
| `operator` | `state`, `properties`, `evidence` | `state`, `properties` |
| `skill_group` | `state`, `properties`, `evidence` | `state`, `properties` |

Якщо `sections` задано явно без `evidence`, API відхиляє параметри відбору звернень (`targets`, `query`, `from`, `to`, `maxSnippetsPerAppeal`). Невідому комбінацію `sections` теж.

Для оператора API бере звернення, у яких він брав участь. Для скіл-групи — звернення за покриттям тематик або участю учасників групи.

Якщо потрібне джерело недоступне: без `allowPartial` запит завершується помилкою; з `allowPartial: true` розділ приходить зі `status: "unavailable"` і причиною.

Окреме читання одного розділу клієнта:

| Метод | Маршрут | Що повертає |
|---|---|---|
| `GET` | `/kw/clients/:client_id/context/state` | Поточний стан |
| `GET` | `/kw/clients/:client_id/context/actions` | Сторінка зареєстрованих дій |
| `GET` | `/kw/clients/:client_id/context/properties` | Відомі властивості |

Ці маршрути використовують ту саму логіку і права, що й основний маршрут читання.

## Напрями `targets`

| Значення | Що відбирає |
|---|---|
| `previous_client_appeals` | Останні звернення клієнта |
| `relevant_appeals` | Звернення клієнта за текстом `query` |
| `previous_client_conversations` | Останні розмови зі сховища контексту |
| `recent_client_interactions` | Недавні взаємодії зі сховища контексту |
| `relevant_client_memory` | Пошук у пам’яті клієнта; потрібен `query`. Якщо індекс не готовий — розділ не успішний |
| `recent_subject_appeals` | Останні звернення тематики |
| `relevant_subject_appeals` | Звернення тематики за текстом `query` |
| `recent_operator_appeals` | Останні звернення за участю оператора |
| `relevant_operator_appeals` | Релевантні звернення оператора; потрібен `query` |
| `recent_skill_group_appeals` | Останні звернення скіл-групи |
| `relevant_skill_group_appeals` | Релевантні звернення скіл-групи; потрібен `query` |

Напрями пам’яті клієнта треба передати явно; типовий набір їх не додає сам.

## Параметри читання

| Поле | Призначення | Типове | Максимум |
|---|---|---:|---:|
| `topK` | Скільки звернень у кожній вибірці | 8 | 20 |
| `candidateLimit` | Скільки кандидатів перевіряти перед видачею | 80 | 200 |
| `maxSnippetsPerAppeal` | Уривків повідомлень на звернення | 3 | 5 |
| `maxResponseBytes` | Розмір відповіді, байти | 65 536 | 262 144 |
| `tokenBudget` | Бюджет тексту для моделі | 8 000 | 8 000 |
| `timeoutMs` | Час очікування пошукової частини, мс | 2 000 | 5 000 |
| `query` | Текст релевантного пошуку | — | 512 символів |
| `from`, `to` | Необов’язковий діапазон дат для останніх звернень | — | — |
| `actions.limit` | Скільки дій у розділі `actions` | 20 | 100 |

`actions.actorTypes` — масив з `client`, `operator`, `integration`, `system`. Можна передати одне `actions.actorType`. Обидва поля разом заборонені.

Якщо пакет не вміщається в бюджет, API прибирає найменш пріоритетні уривки й ставить `coverage.partial=true` з причиною `pack_budget`.

## Що містить відповідь

Відповідь має `sections`: поточний стан, дії, властивості й матеріали залежно від запиту. Старе поле `facts` не повертається.

| Поле | Зміст |
|---|---|
| `sections.state` | Що відбувається зараз: робочі факти продукту і стан, записаний інтеграцією |
| `sections.actions` | Зареєстровані дії з виконавцем і часом |
| `sections.properties` | Відомі властивості, зокрема дозволені додаткові поля клієнта |
| `sections.evidence` | Відібрані звернення й уривки |
| `citations` | Посилання кожного факту або уривка на джерело |
| `coverage` | Чи повна відповідь і чому вона часткова |
| `budget` | Фактичний розмір пакета |

Приклад успішної відповіді:

```json
{
  "status": "success",
  "data": {
    "scope": { "entity": "client", "id": 10004 },
    "sections": {
      "state": { "status": "ready", "operational": [], "recorded": [] },
      "properties": { "status": "ready", "items": [] }
    },
    "citations": [],
    "coverage": { "partial": false, "reasons": [] },
    "budget": { "maxBytes": 65536, "maxTokens": 8000 }
  }
}
```

### Поля клієнта і тематики

Клієнт: `name`, `email`, `phone`, `organization_ids`. Додаткові поля — лише ті, що дозволені в картці клієнта, з ключем `custom.<field-key>`. Некоректне або заборонене поле пропускається; решта відповіді лишається.

Тематика: `name`, `alias`, `parent_id` якщо є, `confidential`. Видалена тематика фактів не повертає.

### Повнота відповіді

Неготовність пошуку для всього інстансу і неповнота однієї відповіді — різні речі. Одне звернення, яке не потрапило в пошук, не вимикає Context API. Відповідь, якої воно стосується, має `coverage.partial=true` і причину.

| Обсяг звернення | Що відбувається |
|---|---|
| До 1 000 повідомлень | Звичайний підтримуваний обсяг |
| 1 001–5 000 повідомлень | Список звернень може попередити про сповільнення; те саме бачить Панель оператора (OperatorLine) |
| Понад 5 000 повідомлень | Пошукове покриття Context API для цього звернення неповне. Повний текст доступний посторінково з джерела |

Типові причини в `coverage.reasons`: `pack_budget`, `appeal_quarantined`, `citation_revoked`, `recent_partial`, `relevant_partial`. `citation_text_refreshed` означає, що текст цитати оновлено з джерела; відповідь коректна, `partial` через це не ставиться.

## Запис дій і стану

Запис є лише для клієнта. Він не змінює поля CRM, статуси звернень, права чи маршрутизацію. Щоб закрити звернення або оновити картку, викликайте відповідний бізнес-API.

| Метод | Маршрут | Результат |
|---|---|---|
| `POST` | `/kw/clients/:client_id/context/actions` | Реєстрація дії. Новий запис — HTTP 201 |
| `PUT` | `/kw/clients/:client_id/context/state/:namespace` | Заміна стану в просторі імен. Потрібне `expectedVersion` |

Обидва запити потребують заголовка `Idempotency-Key`. Повтор тієї самої команди повертає перший результат із `replayed: true`. Інше тіло з тим самим ключем відхиляється. Поле `externalEventId` додатково захищає дію від дубля з боку зовнішньої системи.

`PUT` перевіряє `expectedVersion`: якщо стан уже змінив інший запис, команда не проходить. Простори імен на кшталт `commerce` або `onboarding` належать різним інтеграціям і не перезаписують одні одних випадково. Зарезервовані: `operational`, `system`.

Повідомлення клієнта «я оплатив» лишається уривком у `evidence`. Підтвердженою дією платежу воно не стає, поки інтеграція не зареєструє подію окремо.

## Дії в сценарії

Той самий запис і те саме підвантаження доступні з ноди **Action**. У наявні сценарії вони самі не додаються.

| Дія | Навіщо | Гілки |
|---|---|---|
| [register_client_context](/uk/actionjail/reference/actions/register_client_context.md) | Зареєструвати подію клієнта і за потреби замінити стан у просторі імен | `success`, `replayed`, `conflict`, `error` |
| [load_external_context](/uk/actionjail/reference/actions/load_external_context.md) | Підтягнути знімок з дозволеної зовнішньої системи в контекст клієнта | `applied`, `no_change`, `pending_import`, `conflict`, `invalid_response`, `unavailable` |

`send_request` зовнішній HTTP виконує, у сховище контексту відповідь не кладе. Параметри й приклади — на сторінках дій.

## Сесії та імпорт

Маршрути для зовнішньої історії й робочого контексту розмови:

| Метод | Маршрут |
|---|---|
| `POST` | `/kw/context/sessions` |
| `POST` | `/kw/context/sessions/:session_id/messages` |
| `GET` | `/kw/context/sessions/:session_id/messages` |
| `POST` | `/kw/context/sessions/:session_id/close` |
| `PUT` | `/kw/context/sessions/:session_id/working-context` |
| `POST` | `/kw/context/import-batches` |
| `GET` | `/kw/context/import-batches/:batch_id` |

API фіксує клієнта під час відкриття сесії. Наступне тіло повідомлення не може підмінити його.

| Обмеження | Значення |
|---|---|
| Записів на сторінку повідомлень | 100 |
| Розмір одного повідомлення | 1 MiB |
| `workingContext` | 8 KiB; списки цілей, задач, сутностей, тверджень і джерел обмежені |
| Елементів імпорту | 1–100 |
| Розмір імпорту | 1 MiB |

Імпорт зберігає точку відновлення і продовжується з тим самим `Idempotency-Key`. Тіла запитів дивіться в Swagger: меню допомоги → **API документація**.

## MCP-інструменти

Ті самі права й той самий маршрут читання. Операцій запису в MCP немає.

| Інструмент | Контекст |
|---|---|
| `get_client_context` | Клієнт |
| `get_subject_context` | Тематика |
| `get_operator_context` | Оператор |
| `get_skill_group_context` | Скіл-група |

Імена параметрів — `snake_case`: `client_id`, `subject_id`, `operator_id`, `skill_group_id`, `sections`, `actions`, `top_k`, `candidate_limit`, `max_snippets_per_appeal`, `max_response_bytes`, `token_budget`, `timeout_ms`.

## Помилки

| HTTP | Код | Значення |
|---:|---|---|
| 400 | `INVALID_REQUEST` | Некоректний scope, ID, target, sections або немає обов’язкового `query` |
| 400 | `QUERY_BUDGET_EXCEEDED` | Перевищено бюджет запиту чи відповіді |
| 401 | — | Сесія не авторизована |
| 403 | `ACCESS_DENIED` | Немає доступу або він змінився під час запиту |
| 429 | — | Перевищено дозволену паралельність або частоту |
| 503 | `SEARCH_UNAVAILABLE` | Можливість вимкнена або пошук не готовий |

Відповідь містить персональні дані клієнта. Не пишіть її в звичайні логи застосунку.

Якщо запити стабільно повертають 503, зверніться до адміністратора інстансу.

## Пов’язані матеріали

- [Про те, як Context API збирає контекст](/uk/integrations/explanation/what-is-context-api.md)
- [Дія register_client_context](/uk/actionjail/reference/actions/register_client_context.md)
- [Дія load_external_context](/uk/actionjail/reference/actions/load_external_context.md)
- [Як використовувати API](/uk/integrations/how-to/use-api.md)
- [API довідник](/uk/integrations/reference/api-reference.md)
- [Хаб інтеграцій](/uk/integrations/integrator-hub.md)