Регистрация
ГлавнаяРазработчикам
Разработчикам

Ваш код.
Рабочий API PIARIM.

Подключайте AI Агента и базу знаний к собственному сайту: публикуйте знания, выдавайте подтверждённый контекст авторизованного клиента и разрешайте помощнику запрашивать только нужные данные вашего сервера.

Базовый адрес и авторизация

HTTP API работает сервер-к-серверу. Ключ привязан к одному рабочему пространству, имеет явно заданные права доступа и хранится в PIARIM только в виде хэша. Полное значение показывается один раз при создании в разделе «API и ключи».

BASEhttps://piarim.biz/api/v1/platform
curl https://piarim.biz/api/v1/platform/workspace \
  -H "Authorization: Bearer piarim_pk_..." \
  -H "Accept: application/json"

Не помещайте API-ключ в HTML или JavaScript сайта. Для HTTP API нужен тариф с функцией API; сам виджет и подписанный контекст клиента могут использоваться независимо в пределах доступного тарифа.

Доступные методы API

МетодАдрес методаПраво доступа
GET/workspaceworkspace.read
GET/taskstasks.read
GET/agentsagents.read
GET/agents/{id}agents.read
POST/brain/documentsbrain.write
POST/agents/{id}/brain/documentsbrain.write
POST/widgets/{uuid}/customer-contextwidget.context.write
POST/visibility/auditsvisibility.write

Обучение конкретного агента

API-источник можно сразу опубликовать именно выбранному AI Агенту. Документ сохраняется в базе знаний текущего рабочего пространства, индексируется локально и добавляется в список разрешённых источников его виджета. Другие агенты не получают его автоматически.

curl -X POST https://piarim.biz/api/v1/platform/agents/12/brain/documents \
  -H "Authorization: Bearer piarim_pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title":"Доставка и возврат",
    "content":"Доставка по городу занимает 1–2 рабочих дня...",
    "publish_to_widget":true
  }'

Обычный /brain/documents добавляет источник в пространство без автоматической публикации конкретному виджету.

Авторизованный клиент сайта

Сервер вашего сайта может получить короткоживущий токен подтверждённого клиента и передать его загрузчику виджета. PIARIM фильтрует поля по списку разрешений, заданному владельцем агента.

curl -X POST https://piarim.biz/api/v1/platform/widgets/WIDGET_UUID/customer-context \
  -H "Authorization: Bearer piarim_pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "site":"https://shop.example.com",
    "customer":{
      "customer_id":"42",
      "name":"Алексей",
      "email":"alex@example.com",
      "plan":"business"
    }
  }'
<script
  src="https://piarim.biz/platform/widget-loader.js"
  data-piarim-widget="WIDGET_UUID"
  data-piarim-customer-context="TOKEN_FROM_YOUR_BACKEND"
  defer></script>

Токен живёт не более 15 минут и привязан к виджету и сайту. Не выдавайте его для другого домена.

Запрос актуальных данных клиента

Для вопросов, где нужен самый свежий статус — например «где мой заказ?» или «на какое время я записан?» — виджет может обратиться к вашему серверу во время ответа. Адрес запроса и разрешённые поля задаются в настройках конкретного виджета.

PIARIM не отправляет вашему обработчику полный текст сообщения. Он определяет требуемый тип данных и отправляет только идентификатор подтверждённого клиента и список разрешённых полей.

POST /your-api/piarim/customer
X-Piarim-Widget: WIDGET_UUID
X-Piarim-Timestamp: 1790350000
X-Piarim-Signature: sha256=...

{
  "v":1,
  "event":"customer.lookup",
  "request_id":"...",
  "widget":"WIDGET_UUID",
  "customer_id":"42",
  "fields":["last_order","order_status"],
  "iat":1790350000
}

Подпись: HMAC-SHA256(timestamp + "." + raw_body, lookup_secret). На своей стороне проверяйте подпись, отметку времени и идентификатор виджета до чтения данных.

{
  "customer":{
    "last_order":"#A-1042",
    "order_status":"Передан в доставку"
  }
}

Ответ ограничен разрешёнными полями и размером. PIARIM не следует перенаправлениям, не использует прокси и запрашивает актуальные данные клиента только по HTTPS.

Что получает AI Агент

Ответ формируется из четырёх независимых слоёв: публичные знания выбранного агента, короткая история текущего диалога, подтверждённый контекст клиента и — только при подходящем вопросе — актуальные данные из разрешённого запроса. Произвольного доступа модели к API клиента нет. Если разрешённых данных недостаточно, агент не должен придумывать статус и может передать диалог человеку.

Ошибки и идемпотентность

API возвращает структурированный error_code, HTTP-статус и trace_id для инфраструктурных ошибок. Изоляция рабочих пространств, права ключа, тарифные лимиты, домен виджета и права издателя проверяются сервером. Повтор одного и того же знания определяется по контрольной сумме, а изменение списка разрешённых источников отзывает прежние сессии посетителей.

Исходящие уведомления (webhooks)

Уведомления настраиваются в «API и webhooks». PIARIM сначала сохраняет событие, затем отдельный обработчик доставляет его на публичный HTTPS-адрес. Доступны события conversation.escalated, conversation.closed, knowledge.updated и agent.updated.

X-Piarim-Event: conversation.escalated
X-Piarim-Delivery: EVENT_UUID
X-Piarim-Timestamp: 1790350000
X-Piarim-Signature: sha256=...

{
  "id":"EVENT_UUID",
  "type":"conversation.escalated",
  "created_at":"...",
  "workspace_id":42,
  "data":{
    "conversation_id":104,
    "agent_id":12,
    "channel":"widget",
    "status":"handoff",
    "customer_id":"customer-42"
  }
}

Подпись считается как HMAC-SHA256(timestamp + "." + raw_body, webhook_secret). Проверяйте отметку времени и подпись до обработки. Один и тот же id может прийти повторно после временной ошибки, поэтому обработчик должен быть идемпотентным.

Перенаправления, прокси, локальные и частные IP-адреса, HTTP без TLS не используются. Неуспешные доставки повторяются с увеличивающейся задержкой, после исчерпания попыток остаются в журнале и могут быть запущены повторно вручную.

Открыть API-настройки Настроить AI Агента