REST API для AI-агентов и вашего сервера

Обновлено 2 ноября 2026 г.

Операции, которые AI-агент видит через MCP, доступны и через REST API. Это подходит для вашего сервера, скриптов и AI-приложений без MCP.

Аутентификация

Создайте AI-агента и его личный ключ в разделе «Настройки», «AI-агенты». Ключ (hrc_live_...) показывается один раз. Отправляйте каждый вызов с заголовком:

text

Authorization: Bearer hrc_live_...

Ключ действует от имени участника, создавшего AI-агента, и только с разрешениями AI-агента.

Вызовы

Каждый вызов это POST https://api.hrc.lt/private/<объект>/<действие> с JSON. В каждый вызов, у которого есть companyId, вписывайте ID своей компании: его возвращает /private/ai-agent-self/get.

curl -s https://api.hrc.lt/private/ai-agent-self/get \
  -H "Authorization: Bearer $HRC_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
# {"error":null,"data":{"companyId":"...","companyName":"...",
#   "areas":{...},"tools":[...]}}

Ответы и ошибки

Каждый ответ это { error, data }: одна сторона всегда null.

json

{
  "error": {
    "code": "AI_AGENT_NOT_ALLOWED",
    "message": "This AI agent is not allowed to do this. ...",
    "details": { "area": "kb", "needed": "write" }
  },
  "data": null
}

Код	Статус	Значение
`NOT_AUTHENTICATED`	401	Нет ключа, ключ отозван или истёк.
`AI_AGENTS_OFF`	403	Доступ AI-агентов в компании выключен.
`AI_AGENT_PAUSED`	403	AI-агент или ключ приостановлен.
`AI_AGENT_NOT_ALLOWED`	403	Недостаточно разрешений области (`details.area`, `details.needed`).
`AI_AGENT_SEND_NOT_ALLOWED`	403	Нет разрешения отправлять клиентам.
`OWNER_ROLE_REQUIRED`	403	Действие только для владельцев.
`COMPANY_NOT_FOUND`	404	Не ваша компания, или участник её покинул.
`TOO_MANY_REQUESTS`	429	Больше 120 вызовов в минуту (`details.retryAfterSec`).
`VALIDATION_ERROR`	400	Неверные входные данные (`details.issues`).
`CONFLICT`	409	Кто-то изменил объект раньше вас: прочитайте его снова и повторите.

Заголовок x-language: lt или en меняет язык сообщений об ошибках.

Файл OpenAPI

Все операции с входными данными и ответами: https://api.hrc.lt/agent-api/openapi.json. Его можно загрузить в Postman, Insomnia или генератор кода.

Node.js

// Node.js 18 или новее
const API = 'https://api.hrc.lt';

async function hrc(path, body) {
  const response = await fetch(API + path, {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.HRC_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  });
  const { error, data } = await response.json();
  if (error) throw new Error(error.code + ': ' + error.message);
  return data;
}

const me = await hrc('/private/ai-agent-self/get', {});
// Списки: all, new, open, pending, closed, unassigned, mine, snoozed, spam.
// open означает только статус «Активный»; all означает все статусы.
const list = await hrc('/private/conversation/list', {
  companyId: me.companyId,
  view: 'all',
  limit: 20,
});
for (const item of list.items) {
  console.log(item.ref, item.subject, item.contact.name);
}

Python

python

# Python 3 с requests
import os
import uuid

import requests

API = "https://api.hrc.lt"
HEADERS = {"Authorization": "Bearer " + os.environ["HRC_KEY"]}


def hrc(path, body):
    response = requests.post(
        API + path, json=body, headers=HEADERS, timeout=30
    )
    answer = response.json()
    if answer["error"]:
        error = answer["error"]
        raise RuntimeError(error["code"] + ": " + error["message"])
    return answer["data"]


me = hrc("/private/ai-agent-self/get", {})
company_id = me["companyId"]

# Подготовленный ответ: участник проверяет его и отправляет
hrc("/private/prepared-reply/replace", {
    "companyId": company_id,
    "conversationId": "CONVERSATION_ID",
    "bodyMd": "Hello, the payment works again. Thank you for waiting.",
})

# Задача, связанная с диалогом
hrc("/private/task/create", {
    "companyId": company_id,
    "requestId": str(uuid.uuid4()),
    "title": "Payment fails after the bank check",
    "conversationIds": ["CONVERSATION_ID"],
})

Надёжные поля профиля с вашего сервера

Значения, от которых что-то зависит (тариф, баланс, права), отправляйте с сервера. Их источник команда, поэтому ни ваш сайт, ни браузер не могут их изменить. Нужна область «Диалоги и сообщения» с правом изменения.

// С вашего сервера: эти значения надёжные (источник "team");
// сайт и браузер не могут их изменить.
// Использует hrc() из примера Node.js.
await hrc('/private/contact/set-profile', {
  companyId: me.companyId,
  contactId: 'CONTACT_ID',
  company: { name: 'Acme', plan: 'Enterprise' },
  set: [
    { key: 'plan', type: 'string', value: 'enterprise' },
    { key: 'seats', type: 'number', value: 40 },
    { key: 'renews_at', type: 'date', value: '2027-01-31' },
  ],
  unset: ['trial_ends_at'],
  addTags: ['key-account'],
});

Ограничения и повторы

120 вызовов в минуту на ключ. Получив 429, подождите details.retryAfterSec секунд. При создании объектов отправляйте requestId (UUID): повтор того же вызова не создаст дубликат.

Каждый вызов записывается в журнал «Что делали AI-агенты».

Не нашли ответа? Напишите нам