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-агенти».

Не знайшли відповіді? Напишіть нам