Перейти до вмісту
Sursa Developers

Швидкий старт

Цей посібник за п’ять хвилин проведе вас від нуля до робочої інтеграції: ви створите ключ API, перевірите його, додасте документ до бази знань, знайдете його й поставите запитання про нього. Кожен крок — один запит HTTP. Виберіть мову в будь-якому прикладі один раз, і всі приклади на сторінці перемкнуться разом із ним.

Приклади з перемикачем мов використовують адресу API цього порталу: https://api.sursa.com у хмарі Sursa або адресу API вашої власної інсталяції. Там, де приклад показує https://api.example.com, підставте свою адресу API. Якщо ви не впевнені, яка адреса у вас, див. Адреса API та середовища.

1. Створіть ключ API

Адміністратор організації створює ключі в Sursa в розділі Administration → API keys (адміністрування → ключі API). Дайте ключу назву, з якої видно, де його використовують (наприклад, «CRM sync»), виберіть його роль і, якщо хочете звузити його ще більше, області доступу. Ключ може робити те, що може користувач із цією роллю, і не більше, ніж дозволяють його області доступу. Для цього посібника досить ролі editor.

Ключ показують один раз. Збережіть його в сховищі секретів своєї системи й передавайте у свій код через змінну середовища:

export SURSA_API_KEY="kb_…"

Кожен запит надсилає ключ у заголовку Authorization як токен типу bearer. Посібник Ключі API та області доступу пояснює ролі, області доступу, строк дії та ротацію.

2. Налаштуйте клієнт

Бібліотека не потрібна: API — це звичайні HTTPS і JSON. Приклади цього посібника використовують невелику допоміжну функцію для кожної мови. Скопіюйте її для своєї мови; наступні посібники використовують ту саму функцію. Офіційні клієнтські бібліотеки наведено в розділі SDK.

# cURL needs no setup: each example below is a complete command.
export SURSA_API="https://api.sursa.com"

3. Перевірте ключ

GET /v1/me описує того, хто викликає: організацію, ключ, його роль та області доступу, а також ліміт частоти, що до нього застосовується. Ця операція працює з будь-яким дійсним ключем, тож це найкращий перший запит будь-якої інтеграції.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"
{
  "principal": "api_key",
  "org": {"id": 1, "slug": "acme", "name": "Acme"},
  "key": {"id": 42, "name": "CRM sync", "prefix": "kb_3f9c", "role": "editor"},
  "user": null,
  "role": "editor",
  "scopes": ["cards:read", "cards:write", "search", "ask"],
  "data_profile": null,
  "expires_at": null,
  "rate_limit": {"class": "standard", "requests_per_second": 20, "burst": 100}
}

401 з кодом auth.not_authenticated означає, що ключа немає, його відкликано або в ньому помилка; api_keys.expired означає, що строк дії ключа минув.

4. Знайдіть колекцію

Картки зберігаються в колекціях. GET /v1/collections повертає список колекцій, які бачить ваш ключ:

curl https://api.sursa.com/v1/collections \
  -H "Authorization: Bearer $SURSA_API_KEY"

Запишіть id і name колекції, з якою хочете працювати. Приклади нижче використовують колекцію 3 з назвою support.

5. Додайте документ

PUT /v1/cards-by-external-id/{external_id} створює картку з вашим власним ідентифікатором або замінює її, якщо картка вже існує. Виконати запит двічі безпечно: другого разу вміст не змінився, і відповідь — skipped із причиною unchanged. Як external_id використовуйте ідентифікатор запису у вашій системі.

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/policy-refunds \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": 3,
    "title": "Refund policy",
    "content_type": "markdown",
    "body": "# Refund policy\n\nRefunds are processed within 14 days of the request."
  }'

Запит повертається, коли картку вже можна знайти: 201 з "status": "ready" для нової картки, 200 — для заміненої. HTML і звичайний текст працюють так само з "content_type": "html" або "text". Файли (PDF, Word, Excel та інші) надсилаються через ту саму операцію як multipart/form-data; посібник Імпортуйте документи описує файли, папки, метадані й імпорт багатьох документів.

POST /v1/search знаходить уривки карток, що відповідають запиту, найкращий збіг першим:

curl -X POST https://api.sursa.com/v1/search \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "refund policy", "collection": "support"}'

collection приймає назву колекції. Без нього пошук охоплює колекцію з назвою default.

7. Поставте запитання

POST /v1/ask відповідає на запитання звичайною мовою й повертає джерела відповіді. Асистент знаходить потрібні знання й відповідає лише за картками, які ключу дозволено читати.

curl -X POST https://api.sursa.com/v1/ask \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "How long does a refund take?", "collection": "support"}'

Коли нічого доречного не знайдено, відповідь однаково має статус 200, з "empty": "no_hits" і коротким поясненням в answer. Що показати користувачеві в такому разі, вирішує ваш код.

Наступні кроки