Быстрый старт

Пять запросов: от «есть ключ» до картинки, которую можно послать клиенту. Подставьте свой адрес сервиса и свой ключ.

BASE=https://teril.example.ru
KEY=pk_ваш_ключ
AUTH="Authorization: Bearer $KEY"
JSON="Content-Type: application/json"

1. Связь и остаток

curl -s "$BASE/v1/health"
# {"ok":true,"version":1,"model":"deepseek/deepseek-v4-pro-0813"}

curl -s -H "$AUTH" "$BASE/v1/usage"
# {"ok":true,"usage":{"coins_left":940,"coins_included":1000,"period_end":"…"}}

/v1/health отвечает без ключа — его и ставьте в мониторинг.

2. Завести разговор

external_id — ваш id лида. По нему разговор и находится потом: наш id хранить не обязательно.

curl -s -X POST -H "$AUTH" -H "$JSON" "$BASE/v1/conversations" -d '{
  "external_id": "lead-7781",
  "webhook_url": "https://ваш-сервис/hooks/teril"
}'

{ "ok": true, "conversation": {
  "id": "3f2b…", "external_id": "lead-7781", "order_id": "lead-lead-7781",
  "turn": 0, "running_turn": null, "has_project": false,
  "expires_at": "2026-10-18T…" } }

Тот же external_id второй раз вернёт 200 и тот же разговор — это не ошибка, а вернувшийся лид. Заводить разговор при каждом сообщении клиента безопасно.

3. Отправить просьбу клиента

CONV=3f2b…
curl -s -X POST -H "$AUTH" -H "$JSON" \
  -H "Idempotency-Key: msg-991" \
  "$BASE/v1/conversations/$CONV/turns" -d '{
    "text": "Кухня вдоль одной стены 3 метра. Мойка, посудомойка 60, варочная, духовка. Сверху навесные шкафы."
  }'

{ "ok": true, "turn": { "id": "b41c…", "state": "queued" } }

202, а не 200. Ход идёт минуты. Idempotency-Key — id сообщения у вас: повтор запроса с тем же ключом вернёт тот же ход и не потратит денег второй раз.

4. Дождаться исхода

Правильный путь — вебхук (см. webhooks.md). Запасной — опрос:

TURN=b41c…
curl -s -H "$AUTH" "$BASE/v1/turns/$TURN"

{ "ok": true, "turn": { "id": "b41c…", "state": "done", "status": "built",
  "result": {
    "status": "built",
    "note": "Собрал кухню 3 метра: тумба под мойку 800, посудомойка 600, ящики, духовка в пенале. Сверху четыре навесных шкафа.",
    "applied": 9, "turn": 1, "order_id": "lead-lead-7781",
    "usage": { "model": "…", "attempts": 1, "cost_usd": 0.0231, "ms": 41200, "coins": 1 }
  } } }

Клиенту показывайте note. Всё остальное — вам.

Если status — question, ассистент чего-то не знает про комнату и спросил: в note лежит вопрос, его и перешлите клиенту. Полная таблица статусов — в turns.md.

5. Показать картинку

curl -s -H "$AUTH" "$BASE/v1/conversations/$CONV/render?format=html&link=1"
# {"ok":true,"url":"https://teril.example.ru/r/eyJ…","expires_at":"…"}

Эту ссылку можно слать клиенту прямо в чат: она живёт сутки и ключа не требует. Страница самодостаточна — чертёж крутится, наружу не ходит ничего.

Просить её можно после ЛЮБОГО хода, а не только после built: вид принадлежит разговору, и question его не отменяет — картинка после вопроса та же, что была. Условие «если статус built» в вашем коде означает, что клиент, ответивший на вопрос ассистента, остался без картинки вовсе.

Нужна картинка внутрь своей вёрстки — возьмите format=svg без link:

curl -s -H "$AUTH" "$BASE/v1/conversations/$CONV/render?format=svg" > kitchen.svg

# Сплошными панелями: корпус и фасад красятся порознь (`clear` — как было).
curl -s -H "$AUTH" "$BASE/v1/conversations/$CONV/render?carcass=oak&facade=white" > kitchen.svg

6. Отдать в производство

curl -s -X POST -H "$AUTH" -H "$JSON" \
  "$BASE/v1/conversations/$CONV/handoff" -d '{"seat": "Цех на Ленина"}'
# {"ok":true,"handoff":{"seat_id":5,"seat_title":"Цех на Ленина","order_id":"lead-lead-7781","turn":3}}

Заказ появится карточкой в кабинете рабочего места. Что именно это значит и чего НЕ значит — handoff.md.

Дальше

• весь набор ручек — reference.md;
• готовый клиент на Node — examples/client.mjs;
• проверка подписи вебхука — examples/verify.mjs.