REST API dla agentów AI i twojego serwera

Zaktualizowano 2 listopada 2026

Operacje, które agent AI widzi przez MCP, są dostępne też przez REST API. Nadaje się ono dla twojego serwera, skryptów i aplikacji AI bez MCP.

Uwierzytelnianie

Utwórz agenta AI i jego klucz osobisty w „Ustawieniach”, w sekcji „Agenci AI”. Klucz (hrc_live_...) jest pokazywany raz. Wysyłaj każde wywołanie z nagłówkiem:

text

Authorization: Bearer hrc_live_...

Klucz działa w imieniu członka zespołu, który utworzył agenta AI, i tylko z uprawnieniami agenta AI.

Wywołania

Każde wywołanie to POST https://api.hrc.lt/private/<obiekt>/<akcja> z JSON. W każdym wywołaniu, którego dane mają companyId, wpisz ID swojej firmy: zwraca je /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":[...]}}

Odpowiedzi i błędy

Każda odpowiedź to { error, data }: jedna strona jest zawsze 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
}

Kod	Status	Znaczenie
`NOT_AUTHENTICATED`	401	Brak klucza albo klucz cofnięty lub wygasły.
`AI_AGENTS_OFF`	403	Dostęp agentów AI w firmie jest wyłączony.
`AI_AGENT_PAUSED`	403	Agent AI lub klucz jest wstrzymany.
`AI_AGENT_NOT_ALLOWED`	403	Za niskie uprawnienie obszaru (`details.area`, `details.needed`).
`AI_AGENT_SEND_NOT_ALLOWED`	403	Brak uprawnienia do wysyłania klientom.
`OWNER_ROLE_REQUIRED`	403	Działanie tylko dla właścicieli.
`COMPANY_NOT_FOUND`	404	Nie twoja firma albo członek zespołu z niej odszedł.
`TOO_MANY_REQUESTS`	429	Ponad 120 wywołań na minutę (`details.retryAfterSec`).
`VALIDATION_ERROR`	400	Złe dane wejściowe (`details.issues`).
`CONFLICT`	409	Ktoś zmienił obiekt przed tobą: odczytaj go ponownie i spróbuj jeszcze raz.

Nagłówek x-language: lt lub en zmienia język komunikatów o błędach.

Plik OpenAPI

Wszystkie operacje z danymi wejściowymi i odpowiedziami: https://api.hrc.lt/agent-api/openapi.json. Możesz go wczytać do Postman, Insomnia lub generatora kodu.

Node.js

// Node.js 18 lub nowszy
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', {});
// Widoki: all, new, open, pending, closed, unassigned, mine, snoozed, spam.
// open to tylko status „Aktywna”; all to wszystkie statusy.
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 z 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"]

# Przygotowana odpowiedź: członek zespołu ją sprawdza i wysyła
hrc("/private/prepared-reply/replace", {
    "companyId": company_id,
    "conversationId": "CONVERSATION_ID",
    "bodyMd": "Hello, the payment works again. Thank you for waiting.",
})

# Zadanie powiązane z rozmową
hrc("/private/task/create", {
    "companyId": company_id,
    "requestId": str(uuid.uuid4()),
    "title": "Payment fails after the bank check",
    "conversationIds": ["CONVERSATION_ID"],
})

Zaufane pola profilu z twojego serwera

Wartości, od których coś zależy (plan, saldo, uprawnienia), wysyłaj z serwera. Ich źródłem jest zespół, więc ani twoja strona, ani przeglądarka nie mogą ich zmienić. Potrzebny jest obszar „Rozmowy i wiadomości” z prawem do zmian.

// Z twojego serwera: te wartości są zaufane (źródło "team");
// strona i przeglądarka nie mogą ich zmienić.
// Używa hrc() z przykładu 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'],
});

Limity i ponowienia

120 wywołań na minutę na klucz. Po 429 odczekaj details.retryAfterSec sekund. Tworząc obiekty, wysyłaj requestId (UUID): powtórzenie tego samego wywołania nie utworzy duplikatu.

Każde wywołanie trafia do dziennika „Co robili agenci AI”.

Nie ma tu odpowiedzi? Napisz do nas