Вендори та провайдери

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

Каталог — це дворівневе дерево: вендор (компанія — openai, amazon, deepl) володіє одним чи кількома провайдерами (конкретний API-продукт — openai_api, amazon_translate, deepl_api). Деякі вендори цілком легітимно мають кілька провайдерів: один ключ акаунта — кілька моделей; або MT-продукт і LLM-продукт із різними credentials. Коди — стабільні ідентифікатори (^[a-z][a-z0-9_]{1,99}$) — зберігайте й логуйте саме їх, а не display-імена.

Читання каталогу

• GET /v1/vendors — вендори без провайдерів.
• GET /v1/vendors/{vendor_code} — один вендор плюс стислі картки провайдерів.
• GET /v1/providers — плаский список провайдерів; фільтри: category (mt/ai/custom_mt/hybrid), capability, vendor_code, status, пагінація.
• GET /v1/providers/{provider_code} — усе про один провайдер: схеми (Provider Schemas), можливості (capabilities), політика резолюції, технічні нотатки.
• GET /v1/providers/{provider_code}/technical-info — лише технічні нотатки.
• GET /v1/catalog — усе видиме дерево одним запитом (Full Catalog).

Кожна відповідь несе catalog_version (напр. 2026.08.24) — версію завантаженого YAML-знімка. Вона змінюється лише з деплойментом.

Статуси життєвого циклу та видимість

Вендори й провайдери рухаються шляхом active → deprecated → disabled → removed, і кожен неактивний статус несе метадані lifecycle (причина, відколи, опційний провайдер-заміна). Що ви бачите — залежить від вашої ролі:

include_removed=true від звичайної ролі — це 403. Сутність у статусі removed, яку запитала звичайна роль, невідрізнима від неіснуючої (404).

Що статуси означають для збережених credentials: deprecated-провайдери не приймають нових credentials (409 PROVIDER_DEPRECATED_FOR_NEW_CREDENTIALS), але наявні продовжують працювати й резолвитися — мігруйте у власному темпі в бік lifecycle.replacement_provider_code. disabled/removed-провайдери відмовляють і в нових credentials, і в resolve (409 PROVIDER_DISABLED).

Політика резолюції

Картка кожного провайдера несе credential_resolution: які рівні власності дозволені (user_credentials_allowed, organization_credentials_allowed, platform_credentials_allowed) і в якому порядку priority іде resolve. Провайдер, що вимагає ключів у власності клієнта, просто має вимкнений platform-рівень. Деталі: Resolve Chain.

Технічні нотатки

technical_info — це описова документація, яку курують мейнтейнери каталогу, а не живі метрики: одиниця запиту (characters, tokens, segments), задокументована пропускна здатність із URL її джерела, підтримувані формати входу та операційні нотатки — форма auth-заголовків, дивацтва вендора, пастки. last_verified_at каже, коли людина востаннє звіряла документацію вендора. Довіряйте цьому як документації з датою, а не як телеметрії.