# Shvydko

> Typed decisions over your context: Choice, Score and Noul. Operated by Codebridge Technology, Inc.

## API and integration

- [OpenAPI 3.1 contract](https://shvydko.ai/openapi.json): Public bearer-key endpoints only; no SDK installation required.

- [Full documentation](https://shvydko.ai/llms-full.txt): All current documentation as Markdown.

- [Runtime configuration](https://shvydko.ai/api/config): Current mode, published price and request limits. Preview requests cost zero; do not infer paid billing from the published future price.

## Documentation

- [Перший запит](https://shvydko.ai/docs-markdown/quickstart.md): Від прикладу в Playground до типізованого рішення у вашому застосунку.

- [Контекст і питання](https://shvydko.ai/docs-markdown/concepts/context.md): Відокремте факти від правила рішення. Один контекст може відповідати на кілька незалежних питань.

- [Choice](https://shvydko.ai/docs-markdown/primitives/choice.md): Одна іменована категорія з ваших варіантів: команда, намір, маршрут або клас документа.

- [Score](https://shvydko.ai/docs-markdown/primitives/score.md): Числова оцінка на шкалі, рівні якої ви пояснюєте словами.

- [Noul](https://shvydko.ai/docs-markdown/primitives/noul.md): Оцінка твердження від 0 до 1: перевірка наявності факту, відповідності правилу або виконання умови.

- [POST /v1/systemone](https://shvydko.ai/docs-markdown/api/systemone.md): Контракт запиту та відповіді для Choice, Score і Noul через один HTTP endpoint.

- [GET /v1/models](https://shvydko.ai/docs-markdown/api/models.md): Дізнайтеся ім’я доступної моделі та обмеження її контексту перед інтеграцією.

- [Ключі та автентифікація](https://shvydko.ai/docs-markdown/api/authentication.md): Організаційні API-ключі для сервера, одноразовий показ секрету й відкликання доступу.

- [Помилки та повтори](https://shvydko.ai/docs-markdown/api/errors.md): Розрізняйте валідацію, ліміт, нестачу резерву й недоступність моделі.

- [Ліміти та контекст](https://shvydko.ai/docs-markdown/api/limits.md): Три різні межі: розмір JSON, токени моделі та частота запитів організації.

- [Модель Shvydko](https://shvydko.ai/docs-markdown/models.md): Типізовані рішення через один API. Можливості, поточна картка та межі застосування.

- [Вартість та облік](https://shvydko.ai/docs-markdown/pricing.md): Тариф за вхідні токени, разові поповнення через Stripe, резервування й фактичне списання.

- [Упевненість у рішенні](https://shvydko.ai/docs-markdown/confidence.md): Як читати probabilities, confidence і Noul та вибирати пороги для власного процесу.

- [Як оцінити модель](https://shvydko.ai/docs-markdown/evaluation.md): Від робочого прикладу до відтворюваної перевірки якості, вартості й затримки.

- [Python через HTTP](https://shvydko.ai/docs-markdown/integrations/python.md): Повний приклад на стандартній бібліотеці Python без окремого SDK.

- [JavaScript через HTTP](https://shvydko.ai/docs-markdown/integrations/javascript.md): Серверний fetch із перевіркою статусу, тайм-аутом і без передавання API-ключа в браузер.

- [Shvydko для AI-агентів](https://shvydko.ai/docs-markdown/integrations/coding-agents.md): Дайте агенту актуальний контракт, перевірте запит локально й підключіть типізоване рішення до свого серверного коду.

- [Маршрутизація звернень](https://shvydko.ai/docs-markdown/patterns/routing.md): Практичний процес: класифікувати звернення, перевірити впевненість і залишити ручний маршрут.

## Other resources

- [Examples](https://shvydko.ai/examples): Runnable decision inputs, not customer outcome claims.

- [Comparison and limitations](https://shvydko.ai/compare): Versions, methodology and limitations beside the diagnostic result.

- [Terms](https://shvydko.ai/terms): Operator, credit and refund terms.

- [Privacy](https://shvydko.ai/privacy): Data processing and account information.


---

# Перший запит

Від прикладу в Playground до типізованого рішення у вашому застосунку.

Source: https://shvydko.ai/docs/quickstart

## 01. Спробуйте в кабінеті

Створіть обліковий запис і відкрийте Playground. Додайте контекст, сформулюйте питання та виберіть Choice, Score або Noul. Перед запуском перевірте активну організацію: її ключі, ліміти й історія запитів спільні для учасників.

Відкрийте сценарій «Куди спрямувати звернення?». Це той самий вигаданий збій оплати, який показано на головній сторінці. Нижче наведено його повний запит: у Playground можна змінити одну деталь і перевірити нову відповідь.

- [Відкрити цей приклад у Playground](https://shvydko.ai/console/playground?example=support-routing)
- [Покроковий урок Choice](https://shvydko.ai/console/playground?lesson=choice)
- [Покроковий урок Score](https://shvydko.ai/console/playground?lesson=score)
- [Покроковий урок Noul](https://shvydko.ai/console/playground?lesson=noul)

## 02. Підготуйте ключ і середовище

Власник або адміністратор організації створює ключ у розділі API Keys. Повне значення показується лише під час створення. Збережіть його у сховищі секретів або змінній середовища на сервері.

SHVYDKO_BASE_URL — адреса Shvydko без завершального слеша. SHVYDKO_API_KEY — ваш секретний ключ. Не додавайте ключ до браузерного JavaScript, репозиторію чи посилання на приклад.

### Адреса API · shell

```bash
export SHVYDKO_BASE_URL='https://shvydko.ai'
# Передайте SHVYDKO_API_KEY через менеджер секретів вашого середовища.
```

- [Створити API-ключ](https://shvydko.ai/console/keys)

## 03. Збережіть request.json

Один state містить факти для всіх питань. team обирає команду, impact оцінює вплив збою, human_review перевіряє правило термінового розгляду. Відповіді повернуться за цими ж ідентифікаторами у answers.

### request.json · вигаданий приклад

```json
{
  "state": "Звернення клієнта інтернет-магазину: «Вже 15 хвилин жоден покупець не може оплатити замовлення карткою. Сторінка показує payment unavailable. Оплата при отриманні працює. Ми перевірили з трьох різних пристроїв. Гроші з карток не списуються». Правило маршрутизації: збої роботи сайту — технічній команді; питання про списання та рахунки — фінансовій; терміни доставки — логістичній. Масовий збій способу оплати потребує термінової перевірки людиною.",
  "questions": {
    "team": {
      "type": "choice",
      "instructions": "Яка команда має розглянути це звернення? Оберіть за головною причиною проблеми.",
      "criteria": {
        "engineering": "Технічна команда: збій сайту або інтеграції",
        "finance": "Фінансова команда: рахунки, повернення списаних коштів",
        "logistics": "Логістична команда: відправлення та доставка"
      }
    },
    "impact": {
      "type": "score",
      "instructions": "Оцініть вплив описаної проблеми на оформлення замовлень.",
      "criteria": [
        "Не перешкоджає оформленню",
        "Ускладнює оформлення одному клієнту",
        "Блокує один спосіб оплати для багатьох клієнтів",
        "Блокує всі способи оформлення для всіх клієнтів"
      ]
    },
    "human_review": {
      "type": "noul",
      "instructions": "За наведеним правилом це звернення потребує термінової перевірки людиною."
    }
  }
}
```

## 04. Надішліть запит

Перевірте HTTP-статус перед читанням answers. У відповіді знайдіть request_id, usage.input_tokens і usage.cost_usd. Потім звірте запит з історією Usage у кабінеті.

У preview діють обмежені безкоштовні запуски. Опублікований тариф сам по собі не означає, що списання вже ввімкнено: фактичний режим є у service_mode.

### Термінал

```bash
curl --fail-with-body "$SHVYDKO_BASE_URL/v1/systemone" \
  -H "Authorization: Bearer $SHVYDKO_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json
```

- [Переглянути використання](https://shvydko.ai/console/usage)

## 05. Порівняйте з записаною відповіддю

Цю відповідь отримано від публічного API 2026-10-17T00:40:25Z на запит вище. Це один збережений запуск на вигаданому зверненні, а не результат вашого браузера чи оцінка якості на всіх задачах. Ваш повторний запит може дати інші значення.

API повернув команду engineering, оцінку впливу 1.9977 на шкалі 0–3 та Noul 0.9956 для правила термінового розгляду. Значення впевненості не є виміряною часткою правильних відповідей.

У цьому запуску модель повідомила 181 мс обробки; запит від сервера кабінету до моделі тривав 306.03 мс; повний HTTPS-запит із клієнта, який зберіг запис, — 497.87 мс. Це різні межі вимірювання одного запуску, а не гарантія швидкості. У режимі preview списання становило $0.

### Відповідь API · запис 2026-10-17

```json
{
  "answers": {
    "team": {
      "type": "choice",
      "choice": "engineering",
      "probabilities": {
        "engineering": 0.9997,
        "finance": 0.0002,
        "logistics": 0
      },
      "confidence": 0.9996
    },
    "impact": {
      "type": "score",
      "score": 1.9977,
      "probabilities": {
        "0": 0.0012,
        "1": 0,
        "2": 0.9985,
        "3": 0.0002
      },
      "confidence": 0.9973,
      "legend": {
        "0": "Не перешкоджає оформленню",
        "1": "Ускладнює оформлення одному клієнту",
        "2": "Блокує один спосіб оплати для багатьох клієнтів",
        "3": "Блокує всі способи оформлення для всіх клієнтів"
      }
    },
    "human_review": {
      "type": "noul",
      "noul": 0.9956
    }
  },
  "usage": {
    "input_tokens": 342,
    "output_tokens": 885,
    "cost_microusd": 0,
    "cost_usd": "0.000000",
    "price_per_million_input_usd": null
  },
  "latency_ms": 181,
  "model": "shvydko-latest",
  "request_id": "req_W9EZpyJrh3BXT9URozC6IFu4",
  "service_mode": "preview",
  "gateway_latency_ms": 306.03
}
```

- [Повний запис запиту та відповіді JSON](https://shvydko.ai/research/support-routing-recorded-2026-10-17.json)

## 06. Передайте рішення у свій код

Ключ engineering означає технічну чергу, finance — розгляд платежів, logistics — підтримку доставки. Невідомий або відсутній ключ залишаємо для ручного розбору. Функція нижче формує наступний крок; підключення до вашої системи звернень виконує інтеграція.

Перед автоматичним розподілом перевірте рішення на власних прикладах і визначте правило ручного розгляду. Одного успішного запуску недостатньо, щоб оцінити якість на всіх ваших зверненнях.

### JavaScript · наступна черга

```javascript
function nextSupportStep(result) {
  const queues = new Map([
    ["engineering", "technical_support"],
    ["finance", "billing_review"],
    ["logistics", "delivery_support"],
  ]);
  const answer = result?.answers?.team;
  const queue = answer?.type === "choice" && queues.has(answer.choice)
    ? queues.get(answer.choice)
    : "manual_review";

  return { queue, request_id: result?.request_id ?? null };
}

// Returns a proposed queue; your integration performs the next action.
const nextStep = nextSupportStep(result);
console.log(nextStep);
```

- [Запустити через Python](https://shvydko.ai/docs/integrations/python)
- [Запустити через JavaScript](https://shvydko.ai/docs/integrations/javascript)
- [Перевірити на своїх даних](https://shvydko.ai/docs/evaluation)

## Related documentation

- [Контекст і питання](https://shvydko.ai/docs-markdown/concepts/context.md)
- [POST /v1/systemone](https://shvydko.ai/docs-markdown/api/systemone.md)
- [Python через HTTP](https://shvydko.ai/docs-markdown/integrations/python.md)

---

# Контекст і питання

Відокремте факти від правила рішення. Один контекст може відповідати на кілька незалежних питань.

Source: https://shvydko.ai/docs/concepts/context

## State: факти задачі

state приймає JSON: рядок, об’єкт, масив або інше JSON-значення. Для листа підійде текст, для заявки — об’єкт із полями. Передавайте саме дані, які потрібні для рішення: текст звернення, стан замовлення, правила або уривок документа.

URL у тексті не завантажує сторінку автоматично. Витягніть її зміст у власному застосунку й передайте потрібний фрагмент. Файли, зображення, аудіо та відео не є окремими підтримуваними входами цього API.

### Структурований state

```json
{
  "state": {
    "message": "Хочу змінити адресу доставки",
    "shipment_status": "not_dispatched",
    "policy": "Адресу можна змінити до відправлення"
  },
  "questions": {
    "change_allowed": {
      "type": "noul",
      "instructions": "Чи дозволяє наведене правило змінити адресу цього замовлення?"
    }
  }
}
```

## Questions: правило рішення

questions — об’єкт, у якому кожне питання має власний ідентифікатор, type, необов’язкові instructions і criteria відповідної форми. Формулюйте одну зрозумілу задачу на питання та пояснюйте відмінності між критеріями.

Питання в одному запиті читають спільний контекст. Не просіть одне питання використати відповідь іншого. Для залежного рішення виконайте другий запит у своєму коді після отримання першого.

- Choice: іменовані категорії, між якими треба обрати одну.
- Score: впорядковані рівні шкали від першого до останнього.
- Noul: твердження або запитання з відповіддю «так / ні».

## Невідоме теж має бути передбачене

Додайте категорію «недостатньо даних», якщо задача допускає невизначеність. Якщо факт відсутній, модель не отримує його з вашої бази чи інших запитів автоматично.

Вхідний текст може містити інструкції сторонньої людини. Визначайте задачу у власних instructions, відокремлюйте цитати від правил і перевіряйте випадки з конфліктними вказівками на своєму наборі тестів. Сам формат JSON не гарантує захист від помилкового рішення.

## Зберігання і поширення

Історія Usage зберігає метадані запиту, токени, час, статус і вартість. Збережений приклад у Shares окремо містить state та questions, тому перевіряйте його вміст перед поширенням.

Новий приклад за замовчуванням доступний організації. Публічний доступ потрібно вибрати явно; він також залежить від дозволу організації. Приберіть персональні дані, секрети та реальні клієнтські документи з демонстрацій.

- [Політика приватності](https://shvydko.ai/privacy)
- [Збережені приклади](https://shvydko.ai/console/shares)

## Related documentation

- [Choice](https://shvydko.ai/docs-markdown/primitives/choice.md)
- [Score](https://shvydko.ai/docs-markdown/primitives/score.md)
- [Noul](https://shvydko.ai/docs-markdown/primitives/noul.md)
- [Ліміти та контекст](https://shvydko.ai/docs-markdown/api/limits.md)

---

# Choice

Одна іменована категорія з ваших варіантів: команда, намір, маршрут або клас документа.

Source: https://shvydko.ai/docs/primitives/choice

## Опишіть категорії

criteria — об’єкт із 1–255 варіантів. Ключі — стабільні ідентифікатори для вашого коду, значення пояснюють зміст категорій. Назви мають бути унікальними в JSON-об’єкті.

Choice повертає рівно одну категорію. Для кількох незалежних ознак створіть кілька питань Noul; для впорядкованої шкали використайте Score.

### Choice у повному запиті

```json
{
  "state": "Оплата карткою не працює. Оплата при отриманні доступна. Клієнт просить допомогти оформити замовлення.",
  "questions": {
    "team": {
      "type": "choice",
      "instructions": "Якій команді передати звернення?",
      "criteria": {
        "engineering": "Збої сайту та платіжних інтеграцій",
        "logistics": "Доставка й отримання замовлень",
        "other": "Питання поза цими категоріями або недостатньо даних"
      }
    }
  }
}
```

## Прочитайте choice і probabilities

answers.team.choice — ключ обраної категорії. probabilities містить числові оцінки для всіх ваших ключів; confidence — окремий показник упевненості від 0 до 1.

Для бізнес-дії використовуйте дозволений перелік ключів. Низька впевненість або категорія other можуть вести до ручного розгляду. Поріг підбирайте на власних розмічених даних.

### Ілюстрація answers.team; не результат запуску

```json
{
  "type": "choice",
  "choice": "engineering",
  "probabilities": {
    "engineering": 0.88,
    "logistics": 0.04,
    "other": 0.08
  },
  "confidence": 0.82
}
```

> Значення probabilities та confidence не є гарантією правильності рішення.

## Як зробити критерії корисними

- Пишіть, що входить у кожну категорію, а не лише коротку назву.
- Приберіть категорії з однаковим змістом або поясніть правило вибору між ними.
- Додайте приклади на межі категорій до оцінювання, а не лише очевидні позитивні випадки.
- Не змінюйте значення ідентифікаторів без оновлення коду, який обробляє відповідь.

## Related documentation

- [Упевненість у рішенні](https://shvydko.ai/docs-markdown/confidence.md)
- [Маршрутизація звернень](https://shvydko.ai/docs-markdown/patterns/routing.md)
- [Score](https://shvydko.ai/docs-markdown/primitives/score.md)

---

# Score

Числова оцінка на шкалі, рівні якої ви пояснюєте словами.

Source: https://shvydko.ai/docs/primitives/score

## Задайте впорядковану шкалу

criteria — масив із 1–255 описів у порядку від першого рівня до останнього. Індекси починаються з 0. Для трьох критеріїв результат лежить у межах 0–2.

Опишіть спостережувану різницю між рівнями. Для терміновості це може бути вплив на роботу та наявність обхідного способу; для релевантності — відповідність конкретному запиту.

### Score у повному запиті

```json
{
  "state": "Оплата карткою не працює. Оплата при отриманні доступна. Клієнт просить допомогти оформити замовлення.",
  "questions": {
    "urgency": {
      "type": "score",
      "instructions": "Оціни терміновість звернення за наведеними рівнями.",
      "criteria": [
        "Інформаційне питання; нічого не заблоковано",
        "Є незручність, але доступний інший спосіб завершити дію",
        "Дію повністю заблоковано; потрібна оперативна допомога"
      ]
    }
  }
}
```

## Score може бути дробовим

score — оцінка позиції на шкалі, а не текстова назва рівня. probabilities використовує строкові ключі індексів: «0», «1», «2». confidence повертається окремо. Сервіс також повертає legend — описи рівнів за їхніми індексами.

Вирішіть у своєму коді, чи потрібен безперервний бал, округлений рівень або порогове рішення. Не перетворюйте score на відсоток імовірності: шкала визначається вашими критеріями.

### Ілюстрація answers.urgency; не результат запуску

```json
{
  "type": "score",
  "score": 1.1,
  "probabilities": {
    "0": 0.05,
    "1": 0.8,
    "2": 0.15
  },
  "legend": {
    "0": "Інформаційне питання; нічого не заблоковано",
    "1": "Є незручність, але доступний інший спосіб завершити дію",
    "2": "Дію повністю заблоковано; потрібна оперативна допомога"
  },
  "confidence": 0.7
}
```

## Порівнюйте на однаковій шкалі

Для ранжування кількох записів застосовуйте ті самі instructions і criteria. Якщо ви зміните кількість або зміст рівнів, попередні й нові оцінки більше не будуть прямо порівнюваними.

Перевіряйте не лише середню помилку, а й випадки, де помилка на один рівень має різні наслідки. Для критичних порогів потрібна окрема перевірка помилкових пропусків та спрацьовувань.

## Related documentation

- [Choice](https://shvydko.ai/docs-markdown/primitives/choice.md)
- [Упевненість у рішенні](https://shvydko.ai/docs-markdown/confidence.md)
- [Як оцінити модель](https://shvydko.ai/docs-markdown/evaluation.md)

---

# Noul

Оцінка твердження від 0 до 1: перевірка наявності факту, відповідності правилу або виконання умови.

Source: https://shvydko.ai/docs/primitives/noul

## Сформулюйте одну умову

type: «noul» підходить для питання з двома сторонами: так і ні. criteria можна не передавати або задати описи з ключами true та false. Якщо у питанні кілька незалежних умов, краще розділити їх.

Уточнюйте, чи перевіряєте ви факт у контексті, чи робите висновок за правилом. «Чи згадано повернення?» і «Чи дозволено повернення?» — різні задачі.

### Noul у повному запиті

```json
{
  "state": "Оплата карткою не працює. Оплата при отриманні доступна. Клієнт просить допомогти оформити замовлення.",
  "questions": {
    "alternative": {
      "type": "noul",
      "instructions": "Чи вказано в контексті інший доступний спосіб оплати?",
      "criteria": {
        "true": "Доступний інший спосіб оплати",
        "false": "Альтернативу не вказано або вона недоступна"
      }
    }
  }
}
```

## Прочитайте noul

answers.alternative.noul — число від 0 до 1. Більше значення означає сильнішу підтримку сторони true. Окремі поля confidence і probabilities для Noul не є частиною цього контракту.

0.5 можна використати як початкову межу для експерименту, але робочий поріг залежить від наслідків помилки. Між порогами прийняття й відхилення можна залишити зону ручної перевірки.

### Ілюстрація answers.alternative; не результат запуску

```json
{
  "type": "noul",
  "noul": 0.94
}
```

> 0.94 у прикладі показує формат числа. Це не виміряна ймовірність успіху вашого процесу.

## Перевірте заперечення і брак даних

- Додайте тексти зі словами «не», «раніше», «поки що» та умовними формулюваннями.
- Розрізняйте відсутність згадки й явне заперечення факту, якщо це важливо для задачі.
- Перевірте цитати, переслані повідомлення та суперечливі дані.
- Для важливої дії збережіть можливість людського перегляду.

## Related documentation

- [Упевненість у рішенні](https://shvydko.ai/docs-markdown/confidence.md)
- [Контекст і питання](https://shvydko.ai/docs-markdown/concepts/context.md)
- [Як оцінити модель](https://shvydko.ai/docs-markdown/evaluation.md)

---

# POST /v1/systemone

Контракт запиту та відповіді для Choice, Score і Noul через один HTTP endpoint.

Source: https://shvydko.ai/docs/api/systemone

## HTTP і заголовки

Передавайте Bearer API-ключ організації та JSON у UTF-8. Відповідь успішного запиту має HTTP 200. Endpoint повертає повну JSON-відповідь; потокова генерація тексту не підтримується.

### POST · application/json

```bash
curl --fail-with-body "$SHVYDKO_BASE_URL/v1/systemone" \
  -H "Authorization: Bearer $SHVYDKO_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json
```

## Поля запиту

| Поле | Тип | Правило |
| --- | --- | --- |
| state | JSON | Обов’язковий спільний контекст |
| questions | object | Від 1 до 32 питань; ID має 1–100 символів |
| questions[id].type | string | choice, score або noul |
| questions[id].instructions | JSON, необов’язково | Рекомендовано ясне текстове формулювання задачі |
| questions[id].criteria | object / array | Форма залежить від типу питання |
| model | string, необов’язково | Ім’я з GET /v1/models; без поля обирається налаштована модель |

> Додаткові поля верхнього рівня та невідомі поля всередині питання відхиляються. Параметри temperature, messages, stream і tools не входять до цього контракту.

## Поля відповіді

| Поле | Значення |
| --- | --- |
| answers | Об’єкт із тими самими ID, що у questions |
| model | Публічне ім’я налаштованої моделі |
| request_id | ID запиту для зіставлення з Usage |
| service_mode | preview або paid |
| usage.input_tokens / output_tokens | Фактичний облік токенів від сервісу моделі |
| usage.cost_microusd | Вартість у цілих мікродоларах; 1 USD = 1 000 000 microUSD |
| usage.cost_usd | Та сама вартість десятковим рядком у USD |
| usage.price_per_million_input_usd | Застосований тариф; null у безкоштовному preview |
| gateway_latency_ms | Час обробки запиту шлюзом у мілісекундах |

### Ілюстрація структури preview-відповіді; не вимірювання

```json
{
  "answers": {
    "team": {
      "type": "choice",
      "choice": "engineering",
      "probabilities": {
        "engineering": 0.88,
        "logistics": 0.04,
        "other": 0.08
      },
      "confidence": 0.82
    },
    "urgency": {
      "type": "score",
      "score": 1.1,
      "probabilities": {
        "0": 0.05,
        "1": 0.8,
        "2": 0.15
      },
      "legend": {
        "0": "Інформаційне питання; нічого не заблоковано",
        "1": "Є незручність, але доступний інший спосіб завершити дію",
        "2": "Дію повністю заблоковано; потрібна оперативна допомога"
      },
      "confidence": 0.7
    },
    "alternative": {
      "type": "noul",
      "noul": 0.94
    }
  },
  "model": "shvydko-latest",
  "request_id": "req_example",
  "service_mode": "preview",
  "usage": {
    "input_tokens": 120,
    "output_tokens": 20,
    "cost_microusd": 0,
    "cost_usd": "0.000000",
    "price_per_million_input_usd": null
  },
  "gateway_latency_ms": 245
}
```

## Зіставлення та повторні запити

Успішна відповідь містить заголовок x-shvydko-request-id. Він відповідає request_id у JSON. Зберігайте ID разом із власним ID задачі, щоб знайти запис у Usage.

API не надає контракту ідемпотентності для inference. Повторний POST — новий запит. Якщо зв’язок обірвався після обробки, сліпе повторення може створити друге списання у paid-режимі. Обмежуйте повтори і перевіряйте історію перед повторною бізнес-дією.

## Related documentation

- [Ключі та автентифікація](https://shvydko.ai/docs-markdown/api/authentication.md)
- [Помилки та повтори](https://shvydko.ai/docs-markdown/api/errors.md)
- [Ліміти та контекст](https://shvydko.ai/docs-markdown/api/limits.md)
- [Вартість та облік](https://shvydko.ai/docs-markdown/pricing.md)

---

# GET /v1/models

Дізнайтеся ім’я доступної моделі та обмеження її контексту перед інтеграцією.

Source: https://shvydko.ai/docs/api/models

## Отримайте поточну картку

Endpoint потребує дійсного API-ключа. Він повертає публічне ім’я та поточні ліміти Shvydko без запуску оцінювання. Для авторизованого кабінету той самий зміст доступний через GET /api/models.

Передавайте models[0].name у полі model або пропустіть model у запиті, щоб використати поточну версію сервісу.

### GET · Bearer API key

```bash
curl --fail-with-body "$SHVYDKO_BASE_URL/v1/models" \
  -H "Authorization: Bearer $SHVYDKO_API_KEY"
```

## Що означають поля

Поля контексту можуть бути відсутні. Не підставляйте вигадані значення. Якщо context містить max_state і max_branch, перше обмежує спільний state, друге — state разом з окремою гілкою питання.

strict: true у картці контексту означає суворий контроль меж сервісом. Навіть коли запит вкладається у JSON-ліміт шлюзу, токенний контекст моделі може виявитися завеликим.

| Поле моделі | Значення |
| --- | --- |
| name | Публічне ім’я для POST /v1/systemone |
| context | Поточні обмеження контексту, якщо сервіс їх надає |

## Доступність і версія

HTTP 502 означає, що картку підключеної моделі зараз не вдалося отримати; 503 — що сервіс моделі не налаштований. Успішний GET перевіряє доступність метаданих, але не вимірює якість чи швидкість inference.

shvydko-latest позначає поточну версію сервісу. Вона може оновлюватися. Якщо ваш процес вимагає незмінної версії, узгодьте це до запуску; публічний API наразі не має окремого параметра для її фіксації.

## Related documentation

- [Модель Shvydko](https://shvydko.ai/docs-markdown/models.md)
- [Ключі та автентифікація](https://shvydko.ai/docs-markdown/api/authentication.md)
- [Ліміти та контекст](https://shvydko.ai/docs-markdown/api/limits.md)

---

# Ключі та автентифікація

Організаційні API-ключі для сервера, одноразовий показ секрету й відкликання доступу.

Source: https://shvydko.ai/docs/api/authentication

## Створення ключа

Власник або адміністратор відкриває API Keys у потрібній організації та задає зрозумілу назву: наприклад, support-staging. Секрет показується один раз. У списку залишаються назва й префікс для розпізнавання.

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

- [Керувати ключами](https://shvydko.ai/console/keys)

## Передавання ключа

Викликайте API з довіреного сервера. Не використовуйте публічні змінні NEXT_PUBLIC_ для секрету й не зберігайте його в localStorage. Для браузерного застосунку створіть власний серверний endpoint із перевіркою користувача.

Зовнішні /v1 endpoints використовують Bearer-ключ. Cookie-сесія кабінету та його заголовок активної організації не потрібні для інтеграції через /v1.

### HTTP-заголовок

```http
Authorization: Bearer <SHVYDKO_API_KEY>
```

## Ротація та відкликання

Відкликаний, невідомий або відсутній ключ повертає HTTP 401. Не записуйте Authorization у логи й не додавайте його до звернення щодо помилки.

- Створіть новий ключ і оновіть секрет у своєму серверному середовищі.
- Перевірте запит до GET /v1/models із новим ключем.
- Відкличте старий ключ у кабінеті.
- У разі витоку відкличте ключ одразу; повторне читання його повного значення неможливе.

## Related documentation

- [Перший запит](https://shvydko.ai/docs-markdown/quickstart.md)
- [Помилки та повтори](https://shvydko.ai/docs-markdown/api/errors.md)
- [Маршрутизація звернень](https://shvydko.ai/docs-markdown/patterns/routing.md)

---

# Помилки та повтори

Розрізняйте валідацію, ліміт, нестачу резерву й недоступність моделі.

Source: https://shvydko.ai/docs/api/errors

## Прочитайте HTTP-статус і detail

Помилка повертається з неуспішним HTTP-статусом і полем detail. При валідації також може бути errors — список полів і повідомлень. Не очікуйте answers у такій відповіді.

### Приклад форми помилки валідації

```json
{
  "detail": "Request validation failed",
  "errors": [
    {
      "field": "body.questions",
      "message": "Questions must use supported types"
    }
  ]
}
```

> Текст прикладу ілюстративний. Обробляйте статус і структуру, а не точне формулювання detail.

## Статуси

| HTTP | Причина | Що зробити |
| --- | --- | --- |
| 401 | Ключ відсутній, невідомий або відкликаний | Перевірити серверний секрет; не повторювати з тим самим ключем |
| 402 | Не вистачає доступного балансу на резерв у paid-режимі | Перевірити баланс і активні резерви |
| 403 | Організацію призупинено для перевірки білінгу | Перевірити стан організації; не обходити новими ключами |
| 409 | Резерв запиту вже завершено або прострочено | Перевірити Usage; автоматично не повторювати дію |
| 413 | JSON перевищує ліміт байтів | Скоротити контекст або розбити задачу |
| 422 | Невірна структура, ім’я моделі або відхилений контекст | Виправити запит чи зменшити контекст |
| 429 | Хвилинний ліміт або добова preview-квота | Врахувати Retry-After, якщо є; для добової квоти — 00:00 UTC |
| 502 | Модель недоступна, відповідь некоректна або сплив час | Обмежений повтор із затримкою; перевірка Usage при втраті зв’язку |
| 503 | Сервіс моделі не підключений | Перевірити стан сервісу пізніше |

## Повтори мають бути обмеженими

Для хвилинного 429 використайте Retry-After та невеликий випадковий зсув між клієнтами. Добова квота preview може повернути 429 без цього заголовка: повідомлення вкаже на скидання о 00:00 UTC.

Не повторюйте 401, 402, 403, 413 або 422 без зміни причини. Для мережевих збоїв та 502 задайте невеликий ліміт спроб і загальний часовий бюджет. У POST /v1/systemone немає гарантії ідемпотентності.

Шлюз не списує кредити за запит, який він завершив помилкою моделі. Втрата відповіді на стороні вашого клієнта — інша ситуація: сервер міг уже успішно завершити роботу.

## Related documentation

- [Ліміти та контекст](https://shvydko.ai/docs-markdown/api/limits.md)
- [Вартість та облік](https://shvydko.ai/docs-markdown/pricing.md)
- [Python через HTTP](https://shvydko.ai/docs-markdown/integrations/python.md)
- [JavaScript через HTTP](https://shvydko.ai/docs-markdown/integrations/javascript.md)

---

# Ліміти та контекст

Три різні межі: розмір JSON, токени моделі та частота запитів організації.

Source: https://shvydko.ai/docs/api/limits

## Current configuration

Runtime values are not frozen in this document. Read GET https://shvydko.ai/api/config for the current service mode, pricing and gateway limits. Read authenticated GET /v1/models for model context limits. Configuration alone does not prove inference availability.

## Перевіряйте актуальну конфігурацію

Параметри в блоці поточної конфігурації отримуються з GET /api/config. Вони можуть змінюватися між розгортаннями. Число ключів організації не збільшує її квоту.

Розмір тіла вимірюється в байтах UTF-8, а контекст моделі — у токенах. Український текст, JSON-розмітка й описи критеріїв також займають місце. Кількість символів не є точним підрахунком токенів.

| Межа | Що обмежує |
| --- | --- |
| max_request_bytes | Повний JSON-запит у байтах |
| max_questions | Кількість питань одного запиту |
| requests_per_minute | Спільну частоту API і Playground організації |
| preview_request_limit | Добову кількість запитів організації у preview |
| preview_global_request_limit | Добову preview-місткість усього сервісу |
| reserve_tokens / max_input_tokens | Верхню межу обліку та фінансового резерву шлюзу; це не розмір контексту моделі |

## Контекст визначає сервіс моделі

Діючі межі state і гілки питання читайте в GET /v1/models → models[].context. Значення max_input_tokens з /api/config не означає, що state такого розміру поміститься в модель.

Великий запит може пройти перевірку байтів і все одно бути відхилений через контекст моделі. Відбирайте релевантні фрагменти, скорочуйте повтори й розділяйте незалежні документи на окремі запити. Якість на довгому контексті перевіряйте окремо.

## Preview і відновлення квоти

Preview має окремі добові межі організації та всього сервісу; скидання відбувається о 00:00 UTC. Запити, які вже прийняті до обробки й потім завершилися помилкою, теж витрачають добову квоту. HTTP-помилки до прийняття запиту не створюють запису inference.

Одна організація використовує спільну хвилинну квоту через API та Playground. Для паралельної обробки обмежуйте кількість одночасних запитів у своєму застосунку.

## Related documentation

- [GET /v1/models](https://shvydko.ai/docs-markdown/api/models.md)
- [Вартість та облік](https://shvydko.ai/docs-markdown/pricing.md)
- [Помилки та повтори](https://shvydko.ai/docs-markdown/api/errors.md)

---

# Модель Shvydko

Типізовані рішення через один API. Можливості, поточна картка та межі застосування.

Source: https://shvydko.ai/docs/models

## Current configuration

Runtime values are not frozen in this document. Read GET https://shvydko.ai/api/config for the current service mode, pricing and gateway limits. Read authenticated GET /v1/models for model context limits. Configuration alone does not prove inference availability.

## Для яких задач

Shvydko приймає контекст і питання та повертає Choice, Score або Noul. Типові задачі — маршрутизація звернень, класифікація документів, оцінювання релевантності й перевірка умов.

API працює з текстом і JSON-контекстом. Він не надає чат із генерацією довільної відповіді, вебпошук, інструменти агента, зображення чи Box. Для складеного процесу ваш застосунок поєднує кілька рішень із власними даними й діями.

- [Приклади задач](https://shvydko.ai/examples)

## Картка доступної моделі

GET /v1/models повертає фактичну картку підключеного сервісу, зокрема context, якщо він доступний. Назва в блоці поточної конфігурації показує налаштований псевдонім; сама наявність конфігурації не доводить, що inference зараз працює.

Публічне ім’я може залишатися тим самим після оновлення сервісу. Окремий вибір незмінної версії через цей API наразі не підтримується.

### Отримати поточні метадані

```bash
curl --fail-with-body "$SHVYDKO_BASE_URL/v1/models" \
  -H "Authorization: Bearer $SHVYDKO_API_KEY"
```

## Якість залежить від задачі

Коректна JSON-структура не означає правильне рішення. Перевіряйте українську та інші потрібні мови, неоднозначні формулювання, нові категорії й контекст вашого домену на власній розміченій вибірці.

Демонстраційні запуски показують роботу інтеграції та формату. Вони не доводять загальної точності, калібрування ймовірностей або переваги над іншою моделлю. Окремі дослідницькі порівняння мають власні набори та межі висновків.

- [Порівняння й межі вимірювань](https://shvydko.ai/compare)

## Перед застосуванням у процесі

- Зафіксуйте версію своїх критеріїв, тестову вибірку та правило переходу до ручного перегляду.
- Перевірте поточні ліміти контексту і поведінку на перевищенні.
- Виміряйте затримку та частку помилок на своєму навантаженні.
- Не використовуйте модель як єдину підставу для важливого незворотного рішення.

## Related documentation

- [GET /v1/models](https://shvydko.ai/docs-markdown/api/models.md)
- [Упевненість у рішенні](https://shvydko.ai/docs-markdown/confidence.md)
- [Як оцінити модель](https://shvydko.ai/docs-markdown/evaluation.md)
- [Вартість та облік](https://shvydko.ai/docs-markdown/pricing.md)

---

# Вартість та облік

Тариф за вхідні токени, разові поповнення через Stripe, резервування й фактичне списання.

Source: https://shvydko.ai/docs/pricing

## Current configuration

Runtime values are not frozen in this document. Read GET https://shvydko.ai/api/config for the current service mode, pricing and gateway limits. Read authenticated GET /v1/models for model context limits. Configuration alone does not prove inference availability.

## Тариф і режим — окремі речі

Опублікований тариф Shvydko — $0.042 за мільйон вхідних токенів; вихідні токени не оплачуються. Поточний режим сервісу показано в блоці поточної конфігурації. У preview запити безкоштовні в межах квоти, навіть якщо тариф уже опублікований.

service_mode у відповіді визначає режим запиту. usage.price_per_million_input_usd — застосований тариф; у preview він null, а cost_microusd дорівнює 0. Доступність поповнення окремо позначається billing_enabled.

> Перевіряйте режим перед запуском навантаження. Наявність грошей на балансі не вмикає платний режим сама по собі.

## Розрахунок paid-запиту

Фактична вартість обчислюється з usage.input_tokens, які повернув сервіс моделі. Шлюз зберігає гроші цілими microUSD та округлює кожен успішний платний запит угору до одного microUSD.

За тарифу 0.042 запит на 1 000 вхідних токенів коштує 42 microUSD, тобто $0.000042. Запит на 49 токенів — 3 microUSD після округлення. Це арифметичні приклади, не оцінка середнього розміру ваших запитів.

### Формула · paid mode

```text
cost_microusd = ceil(input_tokens × price_per_million_input_usd)
cost_usd = cost_microusd / 1_000_000

preview: cost_microusd = 0
```

## Резерв перед виконанням

Перед платним запитом шлюз резервує максимальну суму за своєю межею reserve_tokens. Якщо balance мінус активні резерви недостатній, повертається 402 і модель не викликається.

Після успіху списується фактична сума, а решта резерву звільняється. За помилки моделі резерв звільняється без списання. Для одночасних запитів доступний баланс враховує всі активні резерви.

Через резерв навіть короткому запиту може знадобитися більше доступних коштів, ніж його остаточна ціна. Порівнюйте available balance і reserve, а не лише підсумковий баланс.

## Перевірте використання за період

У розділі «Використання» виберіть готовий період або власні дати в UTC: обидві дати включені, не більш ніж 90 днів. Окремо можна переглянути API, Playground або всі запити. Графік має погодинний і поденний масштаб та показує також інтервали без запитів.

Історія показує по 100 запитів на сторінку. Поки ви гортаєте сторінки, зріз залишається стабільним; натисніть оновлення, щоб додати нові запити. CSV містить усі записи вибраного періоду й джерела, а не лише поточну сторінку. Вартість береться з фактично записаного обліку запиту — зміна опублікованого тарифу не перераховує старі записи.

Експорт використання містить метадані й облік, а не початковий текст вашого контексту. Для звіряння окремого запуску використовуйте request_id з відповіді API або звіту оцінювання.

- [Переглянути використання та CSV](https://shvydko.ai/console/usage)

## Баланс, платежі й документи

Коли поповнення увімкнено, власник або адміністратор простору може вибрати разове поповнення від $5 до $1 000 та оплатити його на захищеній сторінці Stripe. Після повернення кабінет перевіряє конкретний платіж і оновлює баланс. Кредити нараховуються лише після підтвердження оплати сервером. Простий перехід за посиланням успіху не змінює баланс.

У Billing показані доступний баланс, резерви, історія операцій і незавершені поповнення. Якщо сторінка оплати ще дійсна, її можна продовжити зі списку. Якщо кошти списано, але підтвердження затримується, перевірте статус пізніше або зверніться до підтримки; повторно оплачувати не потрібно.

Для підтвердженого платежу доступна квитанція, коли Stripe готовий її видати. Платіжними даними можна керувати у Stripe; email для оплати й назва організації змінюються в налаштуваннях простору. Повернення коштів відображається в історії та змінює кредитний баланс; якщо кредити вже витрачені, баланс може стати від’ємним.

Оплату за API-кредити Shvydko приймає Codebridge Technology, Inc. через Stripe у доларах США. Невикористані придбані кредити можна повернути за зверненням, зокрема під час закриття облікового запису; суму звіряємо з поповненнями та фактичним використанням. Напишіть на business@codebridge.tech та вкажіть платіж з історії. Порядок повернення й розгляду помилок наведено на сторінці умов сервісу.

Промокод активується в Billing один раз на робочий простір і додає окремі безкоштовні кредити. Вони витрачаються першими та не повертаються грошима. Код може мати строк активації та ліміт загальної кількості використань.

Автопоповнення доступне лише після ввімкнення відповідної функції в платному режимі. Адміністратор окремо погоджує поріг балансу, суму й місячний ліміт UTC та зберігає картку через Stripe. У preview списання не запускаються. Помилка або невідомий результат ставлять автопоповнення на паузу; повторного автоматичного списання немає. Вимкнення не скасовує вже відправлений платіж. Створення власних інвойсів не підтримується.

- [Відкрити Billing](https://shvydko.ai/console/billing)
- [Умови сервісу](https://shvydko.ai/terms)

## Related documentation

- [Ліміти та контекст](https://shvydko.ai/docs-markdown/api/limits.md)
- [POST /v1/systemone](https://shvydko.ai/docs-markdown/api/systemone.md)
- [Помилки та повтори](https://shvydko.ai/docs-markdown/api/errors.md)

---

# Упевненість у рішенні

Як читати probabilities, confidence і Noul та вибирати пороги для власного процесу.

Source: https://shvydko.ai/docs/confidence

## Три різні сигнали

Не підміняйте confidence найбільшою probabilities і не інтерпретуйте Score як імовірність. Зберігайте поля окремо, якщо аналізуєте якість.

Висока впевненість не виключає помилки. Значення 0.9 не є обіцянкою 90% правильних рішень на вашому потоці: це потрібно перевіряти на розмічених даних.

| Сигнал | Як читати |
| --- | --- |
| Choice probabilities | Розподіл оцінок між вашими іменованими категоріями |
| Score probabilities | Розподіл оцінок між індексами впорядкованої шкали |
| Choice / Score confidence | Окремий показник упевненості від 0 до 1 |
| Noul noul | Оцінка сторони true від 0 до 1; окремого confidence немає |

## Поріг залежить від ціни помилки

Спершу визначте, що гірше для процесу: пропустити потрібний випадок чи помилково спрацювати. Виберіть поріг на окремій калібрувальній вибірці та перевірте його на даних, які не використовували для вибору.

Порівнюйте точність прийнятих рішень із coverage — часткою випадків, які система бере на себе. Підвищення порога зазвичай змінює і coverage, і склад помилок; оцінюйте обидва показники.

## Залиште маршрут для сумніву

- Визначте ручний перегляд або інший обробник для невпевненого рішення.
- Для Noul можна мати дві межі: прийняти true, прийняти false і перевірити середину.
- Для Choice додайте категорію, що покриває невідомі або сторонні запити.
- Повторюйте перевірку після зміни критеріїв, домену даних або сервісу моделі.

> Порогові числа з навчального прикладу не замінюють перевірку на ваших даних.

## Related documentation

- [Як оцінити модель](https://shvydko.ai/docs-markdown/evaluation.md)
- [Маршрутизація звернень](https://shvydko.ai/docs-markdown/patterns/routing.md)
- [Noul](https://shvydko.ai/docs-markdown/primitives/noul.md)

---

# Як оцінити модель

Від робочого прикладу до відтворюваної перевірки якості, вартості й затримки.

Source: https://shvydko.ai/docs/evaluation

## Почніть із задачі та даних

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

Розділіть дані для розробки формулювань, вибору порога та фінальної перевірки. Приклади одного документа, клієнта чи шаблону тримайте в одній частині, щоб близькі дублікати не створювали хибне враження якості.

- Позитивні та негативні приклади, включно з рідкісними категоріями.
- Українська й інші потрібні мови з окремими результатами.
- Заперечення, суперечливі факти, брак інформації та сторонні інструкції в контексті.
- Довгі тексти й випадки на межі допустимого контексту.

## Оберіть метрики під рішення

Рахуйте показники на всіх запланованих записах. Тайм-аути й помилки формату не можна мовчки прибирати з результату. Для порівняння моделей використовуйте однакові записи, критерії та правила підрахунку.

| Задача | Що вимірювати |
| --- | --- |
| Choice | Точність, помилки між категоріями, результати кожної категорії |
| Score | Помилку щодо еталонної шкали й помилки біля бізнес-порога |
| Noul | Хибні спрацьовування та пропуски за обраного порога |
| Ручний перегляд | Coverage і частку помилок серед автоматично прийнятих |
| Операційна робота | p50/p95 затримки, частку HTTP-помилок, вхідні токени й вартість |

## Збережіть умови перевірки

- Версію й контрольну суму набору даних та розділення на частини.
- Точний state, instructions і criteria або їхню контрольовану версію.
- Дату, endpoint, публічне ім’я та поточні ліміти сервісу; ім’я shvydko-latest може залишатися тим самим після оновлення.
- request_id, відповідь, токени, режим оплати, вартість і затримку.
- Правило порога та перелік виключень, визначені до фінального підрахунку.

> Не публікуйте API-ключі, персональні дані чи закриті документи разом зі звітом.

## Запустіть свій набір у кабінеті

Відкрийте «Оцінювання» й завантажте JSONL-файл: один об’єкт на рядок, до 100 прикладів. Кожен запис містить id, state, questions і expected. Для Choice expected містить ключ правильної категорії; для Noul — true або false; для Score — об’єкт із min і max допустимого результату.

Кабінет перевіряє файл перед запуском і послідовно надсилає запити від вашої активної організації. Правило для Noul у цьому інструменті — поріг 0.5. Результати, помилки та використання зберігаються у звіті, який можна завантажити й відкрити повторно без нових викликів моделі.

Набір і звіт залишаються у вашому браузері, доки ви їх не експортуєте; серверного сховища eval-наборів немає. Під час запуску контекст передається сервісу так само, як у Playground. Синтетичний приклад перевіряє процес запуску й не є доказом якості на ваших даних.

### Один рядок evaluation.jsonl · вигаданий приклад

```json
{"id":"support-001","state":"Оплата карткою не працює, але готівкою при отриманні оплатити можна.","questions":{"team":{"type":"choice","instructions":"Яка команда має перевірити збій?","criteria":{"engineering":"Технічний збій платежу","logistics":"Проблема доставки"}}},"expected":{"team":"engineering"}}
```

- [Відкрити оцінювання](https://shvydko.ai/console/evaluations)
- [Завантажити приклад набору](https://shvydko.ai/examples/workflows.jsonl)

## Демо, дослідження й ваша перевірка

Готові приклади демонструють формат і сценарій. Дослідницький звіт описує конкретний набір та умови. Ваша перевірка відповідає на питання, чи підходить сервіс для конкретного продукту.

На сторінці порівняння Shvydko наведено наявні дослідницькі результати та їхні обмеження. Оцінювання в кабінеті допомагає перевірити власний набір; воно не замінює незалежний holdout, аналіз зсуву даних і перевірку калібрування.

- [Прочитати дослідницьке порівняння](https://shvydko.ai/compare)
- [Перевірити приклади](https://shvydko.ai/examples)

## Related documentation

- [Упевненість у рішенні](https://shvydko.ai/docs-markdown/confidence.md)
- [Модель Shvydko](https://shvydko.ai/docs-markdown/models.md)
- [Маршрутизація звернень](https://shvydko.ai/docs-markdown/patterns/routing.md)

---

# Python через HTTP

Повний приклад на стандартній бібліотеці Python без окремого SDK.

Source: https://shvydko.ai/docs/integrations/python

## Підготуйте вхідні дані

Збережіть request.json зі сторінки першого запиту. Передайте SHVYDKO_BASE_URL і SHVYDKO_API_KEY через середовище серверного процесу. Приклад використовує json, os та urllib.request зі стандартної бібліотеки.

- [Скопіювати request.json](https://shvydko.ai/docs/quickstart#request)

## Запит, статус і відповідь

Приклад навмисно не повторює POST автоматично. Додайте власний обмежений механізм повторів після аналізу HTTP-статусу та ризику повторної обробки.

### request.py · Python 3

```python
import json
import os
import urllib.error
import urllib.request

base_url = os.environ["SHVYDKO_BASE_URL"].rstrip("/")
api_key = os.environ["SHVYDKO_API_KEY"]
with open("request.json", encoding="utf-8") as source:
    payload = json.load(source)

request = urllib.request.Request(
    base_url + "/v1/systemone",
    data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + api_key,
        "Content-Type": "application/json",
        "User-Agent": "ShvydkoClient/1.0",
    },
    method="POST",
)

try:
    with urllib.request.urlopen(request, timeout=150) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    # Do not log the API key or the original customer context.
    try:
        detail = json.loads(error.read()).get("detail", "Request failed")
    except (ValueError, AttributeError):
        detail = "Non-JSON error response"
    retry_after = error.headers.get("Retry-After")
    raise SystemExit(
        f"Shvydko HTTP {error.code}: {detail}; Retry-After={retry_after}"
    )
except (urllib.error.URLError, TimeoutError) as error:
    raise SystemExit(
        "Network failure; check Usage before repeating a paid request"
    ) from error

print("request_id:", result["request_id"])
print("team:", result["answers"]["team"]["choice"])
print("input_tokens:", result["usage"]["input_tokens"])
print("cost_usd:", result["usage"]["cost_usd"])
```

## Підключення до застосунку

- Зберігайте секрет у серверному середовищі, окремо для різних середовищ розробки.
- Передавайте до бізнес-логіки лише перевірені поля й дозволені категорії.
- Обмежуйте паралельність відповідно до квоти організації.
- Зіставляйте request_id зі своїм ID задачі без запису секретів у журнал.

> Це прямий HTTP-клієнт Shvydko. Окремий офіційний Python SDK або сумісність усіх сторонніх SDK тут не заявляються.

## Related documentation

- [Перший запит](https://shvydko.ai/docs-markdown/quickstart.md)
- [POST /v1/systemone](https://shvydko.ai/docs-markdown/api/systemone.md)
- [Помилки та повтори](https://shvydko.ai/docs-markdown/api/errors.md)

---

# JavaScript через HTTP

Серверний fetch із перевіркою статусу, тайм-аутом і без передавання API-ключа в браузер.

Source: https://shvydko.ai/docs/integrations/javascript

## Запускайте на сервері

Приклад використовує Node.js із вбудованими fetch та AbortSignal.timeout. Збережіть файл як request.mjs, а request.json візьміть із quickstart. Змінні SHVYDKO_BASE_URL і SHVYDKO_API_KEY мають бути доступні серверному процесу.

У вебзастосунку викликайте Shvydko зі свого захищеного серверного endpoint. Не вставляйте секрет у клієнтський React-компонент, HTML чи публічний bundle.

- [Скопіювати request.json](https://shvydko.ai/docs/quickstart#request)

## Запит через fetch

### request.mjs · server-side JavaScript

```javascript
import { readFile } from "node:fs/promises";

const baseUrl = process.env.SHVYDKO_BASE_URL?.replace(/\/$/, "");
const apiKey = process.env.SHVYDKO_API_KEY;
if (!baseUrl || !apiKey) throw new Error("Missing server configuration");
const payload = JSON.parse(await readFile("request.json", "utf8"));

let response;
try {
  response = await fetch(baseUrl + "/v1/systemone", {
    method: "POST",
    headers: {
      Authorization: "Bearer " + apiKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
    signal: AbortSignal.timeout(150_000),
  });
} catch {
  throw new Error("Network failure; check Usage before retrying a paid request");
}

const body = await response.json().catch(() => null);
if (!response.ok) {
  const detail = typeof body?.detail === "string" ? body.detail : "Request failed";
  const retryAfter = response.headers.get("Retry-After");
  throw new Error(
    "Shvydko HTTP " + response.status + ": " + detail + "; Retry-After=" + retryAfter
  );
}
if (!body?.answers || !body?.usage || !body?.request_id) {
  throw new Error("Unexpected response shape");
}

console.log({
  requestId: body.request_id,
  team: body.answers.team.choice,
  inputTokens: body.usage.input_tokens,
  costUsd: body.usage.cost_usd,
});
```

## Вбудуйте в контрольований процес

Перевіряйте статус до читання answers. Для бізнес-дії звіряйте choice з дозволеним переліком, а числові значення — з очікуваними межами. Мережевий тайм-аут вашого клієнта не доводить, що сервер не встиг виконати запит.

Приклад не потребує SDK і не припускає підтримки OpenAI chat/completions. Використовуйте саме контракт /v1/systemone.

## Related documentation

- [Перший запит](https://shvydko.ai/docs-markdown/quickstart.md)
- [Ключі та автентифікація](https://shvydko.ai/docs-markdown/api/authentication.md)
- [Помилки та повтори](https://shvydko.ai/docs-markdown/api/errors.md)

---

# Shvydko для AI-агентів

Дайте агенту актуальний контракт, перевірте запит локально й підключіть типізоване рішення до свого серверного коду.

Source: https://shvydko.ai/docs/integrations/coding-agents

## Документація, яку агент може прочитати

llms.txt містить індекс тем і посилання на Markdown. llms-full.txt містить повний текст тих самих сторінок. OpenAPI описує тільки публічні GET /v1/models і POST /v1/systemone, які працюють з API-ключем. Ці файли доступні без входу; самі запити до моделі потребують ключа.

Режим, тариф і квоти можуть змінюватися. Читайте /api/config, а контекст моделі — через GET /v1/models. Опублікований тариф не означає, що платний режим увімкнений: у preview вартість запиту дорівнює нулю.

- [Індекс для агентів](https://shvydko.ai/llms.txt)
- [Повний текст документації](https://shvydko.ai/llms-full.txt)
- [OpenAPI 3.1 JSON](https://shvydko.ai/openapi.json)

## Завдання для вашого coding-агента

### Скопіюйте завдання в робочий простір агента

```text
Підключи Shvydko до мого серверного застосунку.

1. Прочитай https://shvydko.ai/llms.txt і https://shvydko.ai/openapi.json.
2. Використай HTTP API /v1/systemone. Не встановлюй вигаданий SDK
   і не використовуй chat/completions.
3. Ключ SHVYDKO_API_KEY бери лише із серверного середовища.
   Не показуй його в коді, логах, URL, браузері чи повідомленнях.
4. Підготуй запит: state — факти задачі, questions — Choice, Score
   або Noul із чіткими критеріями й ручним маршрутом для невизначеності.
5. Перевір HTTP-статус, структуру відповіді, request_id та usage.
   Оброби 401, 402, 403, 409, 413, 422, 429, 502 і 503.
   Не повторюй POST автоматично після мережевого тайм-ауту.
6. Додай локальні перевірки для коректної відповіді, помилки
   і невідомої категорії. Модель лише пропонує рішення; зовнішню
   дію виконує мій застосунок після власної перевірки.
7. Перед реальним викликом покажи payload без секретів.
   За моїм запитом виконай один контрольний виклик і звір usage.
```

> Це інструкція для вашого coding-агента, а не окремий MCP-сервер чи опублікований SDK. Доступ до документації не надає доступу до вашого кабінету.

## Перетворіть рішення на інструмент

У реєстрі інструментів вашого агента створіть серверну функцію evaluate_decision з параметрами state і questions за схемою DecisionRequest з OpenAPI. Ім’я моделі можна не передавати: сервіс вибере поточну публічну модель.

Функція має повернути перевірені answers, request_id і usage. Не дозволяйте відповіді моделі самостійно обирати адресу HTTP-запиту, отримувача платежу чи іншу зовнішню дію. Якщо один крок залежить від попереднього, спершу перевірте першу відповідь, а потім побудуйте наступний запит у коді.

- [Серверна функція через fetch](https://shvydko.ai/docs/integrations/javascript#code)
- [HTTP-клієнт на Python](https://shvydko.ai/docs/integrations/python#code)
- [Рішення з ручним маршрутом](https://shvydko.ai/docs/patterns/routing#decision)

## Що перевірити перед запуском

- Форма request відповідає OpenAPI, питання має стабільний ID, а критерії охоплюють ваші допустимі результати.
- Невірний ключ, ліміт запитів і недоступність сервісу не запускають зовнішню дію.
- Мок-відповідь перевіряє тільки ваш код; якість рішення оцінюйте на власних розмічених прикладах.
- Після дозволеного реального запуску request_id, токени й cost_usd узгоджуються з Usage у кабінеті.

## Related documentation

- [Перший запит](https://shvydko.ai/docs-markdown/quickstart.md)
- [POST /v1/systemone](https://shvydko.ai/docs-markdown/api/systemone.md)
- [Помилки та повтори](https://shvydko.ai/docs-markdown/api/errors.md)
- [JavaScript через HTTP](https://shvydko.ai/docs-markdown/integrations/javascript.md)

---

# Маршрутизація звернень

Практичний процес: класифікувати звернення, перевірити впевненість і залишити ручний маршрут.

Source: https://shvydko.ai/docs/patterns/routing

## Рішення перед дією

Уявімо сервіс підтримки, де технічні збої йдуть до engineering, платежі — до finance, а доставка — до logistics. Shvydko повертає категорію; ваш застосунок вирішує, чи достатньо даних для автоматичного маршруту.

Використайте питання team з quickstart. Додайте приклади, у яких згадуються і оплата, і доставка, щоб перевірити правило основної причини звернення.

- [Контекст і критерії прикладу](https://shvydko.ai/docs/quickstart#request)

## Визначте безпечний результат функції

reviewed_threshold — ваш перевірений поріг, а не універсальна константа. Спершу збирайте запропоновані маршрути й порівнюйте їх із рішеннями операторів. Автоматичне виконання ввімкніть лише після оцінювання.

### Python · без зовнішніх дій

```python
def decide_route(result, reviewed_threshold):
    answer = result["answers"]["team"]
    choice = answer.get("choice")
    confidence = answer.get("confidence")
    allowed = {"engineering", "finance", "logistics"}

    if (
        choice not in allowed
        or not isinstance(confidence, (int, float))
        or confidence < reviewed_threshold
    ):
        return {"route": "manual_review", "request_id": result["request_id"]}

    return {"route": choice, "request_id": result["request_id"]}

# Pass a threshold selected on your own labelled calibration data.
# This function chooses a route; it does not create a ticket or send a message.
```

## Коли додавати друге питання

Незалежну оцінку терміновості можна додати як Score у той самий запит. Перевірку наявності потрібного факту — як Noul. Якщо друге рішення залежить від обраної категорії, сформуйте окремий запит після першої відповіді.

Зберігайте власний ID звернення й request_id. Перед зовнішньою дією перевіряйте, чи вже виконували її для цього звернення: ідемпотентність бізнес-операції має забезпечувати ваш застосунок.

## Що перевіряти після запуску

- Частку ручного перегляду та помилки в кожній категорії.
- Нові теми звернень, для яких немає відповідної категорії.
- Затримку, HTTP-помилки й витрати за кількістю запитів.
- Зміни результатів після редагування критеріїв або оновлення моделі.

- [Перевірити Usage](https://shvydko.ai/console/usage)
- [План оцінювання](https://shvydko.ai/docs/evaluation)

## Related documentation

- [Choice](https://shvydko.ai/docs-markdown/primitives/choice.md)
- [Упевненість у рішенні](https://shvydko.ai/docs-markdown/confidence.md)
- [Як оцінити модель](https://shvydko.ai/docs-markdown/evaluation.md)
- [Python через HTTP](https://shvydko.ai/docs-markdown/integrations/python.md)