Пули підключень провайдерів

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

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

Проєкт і організація

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

scope, що дорівнює project, створює пул у проєкті ключа. Без scope і project_id пул — пул організації, і ключ не може його створити: відповідь — 403 з кодом project_access_restricted.
Ключ читає пули свого проєкту й організації. Змінює він лише пули свого проєкту; запис у пул організації відповідає тим самим 403.
Пул іншого проєкту або неіснуючий відповідає 404 з кодом provider_pool_not_found.

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

Налаштування пулу

provider — провайдер, виклики якого пул обслуговує за замовчуванням. Його не можна змінити: створіть інший пул.
allow_cross_provider дозволяє пулу приймати підключення інших провайдерів. Без нього додавання такого підключення відповідає 422 з кодом connection_incompatible. Якщо вимкнути його пізніше, уже додані учасники лишаються.
max_attempts — від 1 до 5, 3, якщо не надіслано, — скільки підключень може спробувати один виклик.
on_rate_limit і on_provider_error кажуть, що йде за невдалою спробою. switch_connection — значення за замовчуванням в обох.
status, що дорівнює disabled, зупиняє пул. Він більше не маршрут за замовчуванням для свого провайдера, а вузол моделі, який його називає, відхиляється з provider_not_configured до звернення до будь-якого провайдера.

Учасники

Додавання підключення приймає його id і, якщо потрібно, умови участі.

Умова	Що вона робить	Якщо не надіслано
`priority`	Від 1 до 1000. Менше число пробується першим	`1`
`weight`	Від 0 до 100, його читає стратегія `weighted`. Учасник із `0` пробується лише після інших	`0`
`enabled`	`false` лишає учасника в пулі й виводить його з роботи	`true`
`cost_multiplier`	Десятковий рядок. Вартість спроби через цього учасника множиться на нього	`"1.0000"`

Підключення має бути доступне ключу: інше відповідає 404 з кодом provider_connection_not_found. Підключення організації може ввійти до пулу проєкту.
Підключення, яке вже учасник, відповідає 409 з кодом pool_connection_exists, а видалене підключення — 422 з connection_incompatible.
Зміна чи від’єднання підключення, яке не учасник, відповідає 404 з кодом pool_connection_not_found. Від’єднання зберігає підключення та його ключ.

Видалення пулу

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

Запас і аналітика

У запасі є рядок для кожного учасника: його ліміти, що він використав і що лишилося, і скільки викликів він виконує одночасно. model читає ліміти однієї моделі. Без нього рядки — ліміти всього підключення.
Аналітика пулу рахує його спроби, його операції, як часто виклик переходив на інше підключення і як трафік розподілився між учасниками. Вікно дотримується правил звіту: сім днів без from і to і не більше 31 дня.

Операції

Описи операцій і полів подано англійською.

Список пулів провайдерів

GET /v1/provider-pools

Дозвіл: management:read

Each pool's connections holds the members in the caller's reach, as on GET /v1/provider-pools/{id}.

Параметри

Параметр	Опис
`limit` необовʼязково query`integer`	Page size (default 30). Мінімум: `1` Максимум: `100`
`cursor` необовʼязково query`string`	The `meta.next_cursor` of the previous page.
`provider` необовʼязково query`ProviderCode`	Одне з: `openai`, `anthropic`, `google`
`status` необовʼязково query`PoolStatus`	Одне з: `active`, `disabled`
`project` необовʼязково query`string`	`current` narrows the list to the active project — an API key's own, a person's as switched on `POST /api/auth/me/project` — plus the organization's rows where the resource has them. A literal, never an id: anything else is 422. Without it the list is everything within the caller's reach. Одне з: `current`

Відповіді

200

One cursor page of pools

application/json

{
  "data": [
    {
      "provider_pool_id": "74438200973594624",
      "organization_id": "74438200973594624",
      "project_id": "74438200973594624",
      "name": "string",
      "provider": "openai",
      "allow_cross_provider": true,
      "strategy": "priority",
      "max_attempts": 1,
      "on_rate_limit": "switch_connection",
      "on_provider_error": "switch_connection",
      "status": "active",
      "connections": [
        {
          "connection_id": "74438200973594624",
          "name": "string",
          "provider": "openai",
          "environment": "production",
          "secret_last_four": "string",
          "status": "active",
          "health_status": "string",
          "priority": 1,
          "weight": 1,
          "enabled": true,
          "cost_multiplier": "string"
        }
      ],
      "created_at": "2026-10-02T09:30:00Z",
      "updated_at": "2026-10-02T09:30:00Z"
    }
  ],
  "meta": {
    "limit": 1,
    "next_cursor": "string"
  }
}

Помилки

Статус	Коди	Коли
401		No credential, or one that is not valid
403		Authenticated, but not allowed: scope (`insufficient_scope`), policy or tenant (`not_a_member`); a blocked end customer (`customer_blocked`); an act only a signed-in person may take (`session_required`); the role rule on members and invitations (`member_forbidden`, `invite_forbidden`); a write to the organization's own rows, or a read of the audit journal, by a caller that does not reach every project (`project_access_restricted`)
422		Validation failure or a semantically impossible request. Field-level validation from the framework answers `{"message", "errors"}`; domain refusals answer the standard error envelope. An `Idempotency-Key` longer than 190 characters is `invalid_request` in that envelope.

Заголовки

X-Request-Id

Тіло кожної помилки — конверт помилки.

Створити пул

POST /v1/provider-pools

Дозвіл: management:write

scope: project is the active project, organization (the default without scope and project_id) is no project and needs a caller that reaches every project (403 project_access_restricted); scope together with project_id is 422. A project_id that is not a project of the caller's organization in its reach is 404 project_not_found and nothing is stored (L3).

Тіло запиту

application/json

{
  "name": "string",
  "provider": "openai",
  "strategy": "priority",
  "max_attempts": 1,
  "on_rate_limit": "switch_connection",
  "on_provider_error": "switch_connection",
  "allow_cross_provider": true,
  "project_id": "74438200973594624",
  "scope": "organization"
}

Відповіді

201

The created pool

application/json

{
  "data": {
    "provider_pool_id": "74438200973594624",
    "organization_id": "74438200973594624",
    "project_id": "74438200973594624",
    "name": "string",
    "provider": "openai",
    "allow_cross_provider": true,
    "strategy": "priority",
    "max_attempts": 1,
    "on_rate_limit": "switch_connection",
    "on_provider_error": "switch_connection",
    "status": "active",
    "connections": [
      {
        "connection_id": "74438200973594624",
        "name": "string",
        "provider": "openai",
        "environment": "production",
        "secret_last_four": "string",
        "status": "active",
        "health_status": "string",
        "priority": 1,
        "weight": 1,
        "enabled": true,
        "cost_multiplier": "string"
      }
    ],
    "created_at": "2026-10-02T09:30:00Z",
    "updated_at": "2026-10-02T09:30:00Z"
  }
}

Помилки

Статус	Коди	Коли
401		No credential, or one that is not valid
403	`project_access_restricted`	Authenticated, but not allowed: scope (`insufficient_scope`), policy or tenant (`not_a_member`); a blocked end customer (`customer_blocked`); an act only a signed-in person may take (`session_required`); the role rule on members and invitations (`member_forbidden`, `invite_forbidden`); a write to the organization's own rows, or a read of the audit journal, by a caller that does not reach every project (`project_access_restricted`)
404	`project_not_found`	No such resource for this tenant. Somebody else's resource — and a resource of a project the caller does not reach — answers the same way on purpose: the two must not be distinguishable.
422		Validation failure or a semantically impossible request. Field-level validation from the framework answers `{"message", "errors"}`; domain refusals answer the standard error envelope. An `Idempotency-Key` longer than 190 characters is `invalid_request` in that envelope.

Заголовки

X-Request-Id

Тіло кожної помилки — конверт помилки.

Пул з його підключеннями

GET /v1/provider-pools/{id}

Дозвіл: management:read

connections holds the members in the caller's reach: a connection of a project out of reach is left out.

Параметри

Параметр	Опис
`id` обовʼязково path`Id`	Snowflake identifier, as a string. Шаблон: `^\d+$` Приклад: `74438200973594624`

Відповіді

200

The pool

application/json

{
  "data": {
    "provider_pool_id": "74438200973594624",
    "organization_id": "74438200973594624",
    "project_id": "74438200973594624",
    "name": "string",
    "provider": "openai",
    "allow_cross_provider": true,
    "strategy": "priority",
    "max_attempts": 1,
    "on_rate_limit": "switch_connection",
    "on_provider_error": "switch_connection",
    "status": "active",
    "connections": [
      {
        "connection_id": "74438200973594624",
        "name": "string",
        "provider": "openai",
        "environment": "production",
        "secret_last_four": "string",
        "status": "active",
        "health_status": "string",
        "priority": 1,
        "weight": 1,
        "enabled": true,
        "cost_multiplier": "string"
      }
    ],
    "created_at": "2026-10-02T09:30:00Z",
    "updated_at": "2026-10-02T09:30:00Z"
  }
}

Помилки

Статус	Коди	Коли
401		No credential, or one that is not valid
403		Authenticated, but not allowed: scope (`insufficient_scope`), policy or tenant (`not_a_member`); a blocked end customer (`customer_blocked`); an act only a signed-in person may take (`session_required`); the role rule on members and invitations (`member_forbidden`, `invite_forbidden`); a write to the organization's own rows, or a read of the audit journal, by a caller that does not reach every project (`project_access_restricted`)
404		No such resource for this tenant. Somebody else's resource — and a resource of a project the caller does not reach — answers the same way on purpose: the two must not be distinguishable.

Заголовки

X-Request-Id

Тіло кожної помилки — конверт помилки.

Змінити стратегію або перемикання в разі збою

PATCH /v1/provider-pools/{id}

Дозвіл: management:write

provider cannot change — it would orphan every attached connection.

A pool of no project (the organization's) is written only by a caller that reaches every project (403 project_access_restricted).

Параметри

Параметр	Опис
`id` обовʼязково path`Id`	Snowflake identifier, as a string. Шаблон: `^\d+$` Приклад: `74438200973594624`

Тіло запиту

application/json

{
  "name": "string",
  "strategy": "priority",
  "max_attempts": 1,
  "on_rate_limit": "switch_connection",
  "on_provider_error": "switch_connection",
  "status": "active",
  "allow_cross_provider": true
}

Відповіді

200

The updated pool

application/json

{
  "data": {
    "provider_pool_id": "74438200973594624",
    "organization_id": "74438200973594624",
    "project_id": "74438200973594624",
    "name": "string",
    "provider": "openai",
    "allow_cross_provider": true,
    "strategy": "priority",
    "max_attempts": 1,
    "on_rate_limit": "switch_connection",
    "on_provider_error": "switch_connection",
    "status": "active",
    "connections": [
      {
        "connection_id": "74438200973594624",
        "name": "string",
        "provider": "openai",
        "environment": "production",
        "secret_last_four": "string",
        "status": "active",
        "health_status": "string",
        "priority": 1,
        "weight": 1,
        "enabled": true,
        "cost_multiplier": "string"
      }
    ],
    "created_at": "2026-10-02T09:30:00Z",
    "updated_at": "2026-10-02T09:30:00Z"
  }
}

Помилки

Статус	Коди	Коли
401		No credential, or one that is not valid
403	`project_access_restricted`	Authenticated, but not allowed: scope (`insufficient_scope`), policy or tenant (`not_a_member`); a blocked end customer (`customer_blocked`); an act only a signed-in person may take (`session_required`); the role rule on members and invitations (`member_forbidden`, `invite_forbidden`); a write to the organization's own rows, or a read of the audit journal, by a caller that does not reach every project (`project_access_restricted`)
404		No such resource for this tenant. Somebody else's resource — and a resource of a project the caller does not reach — answers the same way on purpose: the two must not be distinguishable.
422		Validation failure or a semantically impossible request. Field-level validation from the framework answers `{"message", "errors"}`; domain refusals answer the standard error envelope. An `Idempotency-Key` longer than 190 characters is `invalid_request` in that envelope.

Заголовки

X-Request-Id

Тіло кожної помилки — конверт помилки.

Видалити пул

DELETE /v1/provider-pools/{id}

Дозвіл: management:write

A pool of no project (the organization's) is written only by a caller that reaches every project (403 project_access_restricted).

409 pool_in_use — the pool is named by the live version of a flow (an archived flow's live version counts), or by a version an unfinished execution (running, queued, waiting) is pinned to. A version that was replaced does not hold the pool; a rollback to such a version after the pool is gone is 422 flow_invalid with an unknown_pool issue.

Параметри

Параметр	Опис
`id` обовʼязково path`Id`	Snowflake identifier, as a string. Шаблон: `^\d+$` Приклад: `74438200973594624`

Відповіді

204

Deleted

Без тіла

Помилки

Статус	Коди	Коли
401		No credential, or one that is not valid
403	`project_access_restricted`	Authenticated, but not allowed: scope (`insufficient_scope`), policy or tenant (`not_a_member`); a blocked end customer (`customer_blocked`); an act only a signed-in person may take (`session_required`); the role rule on members and invitations (`member_forbidden`, `invite_forbidden`); a write to the organization's own rows, or a read of the audit journal, by a caller that does not reach every project (`project_access_restricted`)
404		No such resource for this tenant. Somebody else's resource — and a resource of a project the caller does not reach — answers the same way on purpose: the two must not be distinguishable.
409	`pool_in_use`	State conflict: idempotency clash, stale draft, illegal transition; the last owner of an organization (`last_owner`); the owned-organization limit (`organization_limit_reached`); an end customer with credit history that cannot be deleted (`customer_has_history`)

Заголовки

X-Request-Id

Тіло кожної помилки — конверт помилки.

Додати підключення до пулу

POST /v1/provider-pools/{id}/connections

Дозвіл: management:write

connection_id must be a connection the caller reaches (404 provider_connection_not_found otherwise): another project's credentials never join the caller's pool. Attaching an organization connection to one's own pool is not a write to that connection and is allowed.

A pool of no project (the organization's) is written only by a caller that reaches every project (403 project_access_restricted).

Параметри

Параметр	Опис
`id` обовʼязково path`Id`	Snowflake identifier, as a string. Шаблон: `^\d+$` Приклад: `74438200973594624`

Тіло запиту

application/json

{
  "connection_id": "74438200973594624",
  "priority": 1,
  "weight": 1,
  "enabled": true,
  "cost_multiplier": "100.0000"
}

Відповіді

201

The pool with the new member

application/json

{
  "data": {
    "provider_pool_id": "74438200973594624",
    "organization_id": "74438200973594624",
    "project_id": "74438200973594624",
    "name": "string",
    "provider": "openai",
    "allow_cross_provider": true,
    "strategy": "priority",
    "max_attempts": 1,
    "on_rate_limit": "switch_connection",
    "on_provider_error": "switch_connection",
    "status": "active",
    "connections": [
      {
        "connection_id": "74438200973594624",
        "name": "string",
        "provider": "openai",
        "environment": "production",
        "secret_last_four": "string",
        "status": "active",
        "health_status": "string",
        "priority": 1,
        "weight": 1,
        "enabled": true,
        "cost_multiplier": "string"
      }
    ],
    "created_at": "2026-10-02T09:30:00Z",
    "updated_at": "2026-10-02T09:30:00Z"
  }
}

Помилки

Статус	Коди	Коли
401		No credential, or one that is not valid
403	`project_access_restricted`	Authenticated, but not allowed: scope (`insufficient_scope`), policy or tenant (`not_a_member`); a blocked end customer (`customer_blocked`); an act only a signed-in person may take (`session_required`); the role rule on members and invitations (`member_forbidden`, `invite_forbidden`); a write to the organization's own rows, or a read of the audit journal, by a caller that does not reach every project (`project_access_restricted`)
404	`provider_connection_not_found`	No such resource for this tenant. Somebody else's resource — and a resource of a project the caller does not reach — answers the same way on purpose: the two must not be distinguishable.
409		State conflict: idempotency clash, stale draft, illegal transition; the last owner of an organization (`last_owner`); the owned-organization limit (`organization_limit_reached`); an end customer with credit history that cannot be deleted (`customer_has_history`)
422		Validation failure or a semantically impossible request. Field-level validation from the framework answers `{"message", "errors"}`; domain refusals answer the standard error envelope. An `Idempotency-Key` longer than 190 characters is `invalid_request` in that envelope.

Заголовки

X-Request-Id

Тіло кожної помилки — конверт помилки.

Змінити пріоритет, вагу або множник вартості підключення

PATCH /v1/provider-pools/{id}/connections/{connectionId}

Дозвіл: management:write

A pool of no project (the organization's) is written only by a caller that reaches every project (403 project_access_restricted).

Параметри

Параметр	Опис
`id` обовʼязково path`Id`	Snowflake identifier, as a string. Шаблон: `^\d+$` Приклад: `74438200973594624`
`connectionId` обовʼязково path`Id`	Provider connection id. Шаблон: `^\d+$` Приклад: `74438200973594624`

Тіло запиту

application/json

{
  "priority": 1,
  "weight": 1,
  "enabled": true,
  "cost_multiplier": "100.0000"
}

Відповіді

200

The pool with the updated member

application/json

{
  "data": {
    "provider_pool_id": "74438200973594624",
    "organization_id": "74438200973594624",
    "project_id": "74438200973594624",
    "name": "string",
    "provider": "openai",
    "allow_cross_provider": true,
    "strategy": "priority",
    "max_attempts": 1,
    "on_rate_limit": "switch_connection",
    "on_provider_error": "switch_connection",
    "status": "active",
    "connections": [
      {
        "connection_id": "74438200973594624",
        "name": "string",
        "provider": "openai",
        "environment": "production",
        "secret_last_four": "string",
        "status": "active",
        "health_status": "string",
        "priority": 1,
        "weight": 1,
        "enabled": true,
        "cost_multiplier": "string"
      }
    ],
    "created_at": "2026-10-02T09:30:00Z",
    "updated_at": "2026-10-02T09:30:00Z"
  }
}

Помилки

Статус	Коди	Коли
401		No credential, or one that is not valid
403	`project_access_restricted`	Authenticated, but not allowed: scope (`insufficient_scope`), policy or tenant (`not_a_member`); a blocked end customer (`customer_blocked`); an act only a signed-in person may take (`session_required`); the role rule on members and invitations (`member_forbidden`, `invite_forbidden`); a write to the organization's own rows, or a read of the audit journal, by a caller that does not reach every project (`project_access_restricted`)
404		No such resource for this tenant. Somebody else's resource — and a resource of a project the caller does not reach — answers the same way on purpose: the two must not be distinguishable.
422		Validation failure or a semantically impossible request. Field-level validation from the framework answers `{"message", "errors"}`; domain refusals answer the standard error envelope. An `Idempotency-Key` longer than 190 characters is `invalid_request` in that envelope.

Заголовки

X-Request-Id

Тіло кожної помилки — конверт помилки.

Прибрати підключення з пулу

DELETE /v1/provider-pools/{id}/connections/{connectionId}

Дозвіл: management:write

A pool of no project (the organization's) is written only by a caller that reaches every project (403 project_access_restricted).

Параметри

Параметр	Опис
`id` обовʼязково path`Id`	Snowflake identifier, as a string. Шаблон: `^\d+$` Приклад: `74438200973594624`
`connectionId` обовʼязково path`Id`	Provider connection id. Шаблон: `^\d+$` Приклад: `74438200973594624`

Відповіді

204

Detached

Без тіла

Помилки

Статус	Коди	Коли
401		No credential, or one that is not valid
403	`project_access_restricted`	Authenticated, but not allowed: scope (`insufficient_scope`), policy or tenant (`not_a_member`); a blocked end customer (`customer_blocked`); an act only a signed-in person may take (`session_required`); the role rule on members and invitations (`member_forbidden`, `invite_forbidden`); a write to the organization's own rows, or a read of the audit journal, by a caller that does not reach every project (`project_access_restricted`)
404		No such resource for this tenant. Somebody else's resource — and a resource of a project the caller does not reach — answers the same way on purpose: the two must not be distinguishable.

Заголовки

X-Request-Id

Тіло кожної помилки — конверт помилки.

Поточний запас кожного підключення

GET /v1/provider-pools/{id}/capacity

Дозвіл: management:read

Omitting model reads the connection-wide default limits. One row per member in the caller's reach.

Параметри

Параметр	Опис
`id` обовʼязково path`Id`	Snowflake identifier, as a string. Шаблон: `^\d+$` Приклад: `74438200973594624`
`model` необовʼязково query`string`	Максимальна довжина: `64`

Відповіді

200

One row per member connection

application/json

{
  "data": [
    {
      "connection_id": "74438200973594624",
      "model": "gpt-4o-mini",
      "limits": {
        "rpm": 1,
        "tpm": 1,
        "input_tpm": 1,
        "output_tpm": 1,
        "max_concurrency": 1,
        "daily_quota": 1
      },
      "used": {
        "requests": 1,
        "tokens": 1
      },
      "remaining": {
        "requests": 1,
        "tokens": 1
      },
      "active_concurrency": 1,
      "reset_at": "2026-10-02T09:30:00Z"
    }
  ]
}

Помилки

Статус	Коди	Коли
401		No credential, or one that is not valid
403		Authenticated, but not allowed: scope (`insufficient_scope`), policy or tenant (`not_a_member`); a blocked end customer (`customer_blocked`); an act only a signed-in person may take (`session_required`); the role rule on members and invitations (`member_forbidden`, `invite_forbidden`); a write to the organization's own rows, or a read of the audit journal, by a caller that does not reach every project (`project_access_restricted`)
404		No such resource for this tenant. Somebody else's resource — and a resource of a project the caller does not reach — answers the same way on purpose: the two must not be distinguishable.
422		Validation failure or a semantically impossible request. Field-level validation from the framework answers `{"message", "errors"}`; domain refusals answer the standard error envelope. An `Idempotency-Key` longer than 190 characters is `invalid_request` in that envelope.

Заголовки

X-Request-Id

Тіло кожної помилки — конверт помилки.

Перемикання, доступність і розподіл трафіку пулу

GET /v1/provider-pools/{id}/analytics

Дозвіл: read

traffic_distribution names the connections in the caller's reach only; the pool's totals are the pool's own.

Параметри

Параметр	Опис
`id` обовʼязково path`Id`	Snowflake identifier, as a string. Шаблон: `^\d+$` Приклад: `74438200973594624`
`from` необовʼязково query`string`	Start of the window an analytics answer covers — a date the server can parse, ISO-8601 recommended (a value without an offset is read as UTC). Unlike the lists, each end is optional on its own and the window is never refused, only fitted (`AnalyticsWindowResolver`): Формат: `date-time`
`to` необовʼязково query`string`	End of the window an analytics answer covers; now when absent. See `from` (`WindowFrom`) for how the window is fitted rather than refused. Формат: `date-time`

Відповіді

200

Pool analytics for the window

application/json

{
  "data": {
    "pool_id": "74438200973594624",
    "window": {
      "from": "2026-10-02T09:30:00Z",
      "to": "2026-10-02T09:30:00Z"
    },
    "total_attempts": 1,
    "operations": 1,
    "failover_count": 1,
    "requests_saved_from_rejection": 1,
    "total_cost": "0.02700000",
    "availability": "string",
    "traffic_distribution": [
      {
        "connection_id": "74438200973594624",
        "attempts": 1,
        "succeeded": 1,
        "share": "string",
        "cost": "0.02700000"
      }
    ]
  }
}

Помилки

Статус	Коди	Коли
401		No credential, or one that is not valid
403		Authenticated, but not allowed: scope (`insufficient_scope`), policy or tenant (`not_a_member`); a blocked end customer (`customer_blocked`); an act only a signed-in person may take (`session_required`); the role rule on members and invitations (`member_forbidden`, `invite_forbidden`); a write to the organization's own rows, or a read of the audit journal, by a caller that does not reach every project (`project_access_restricted`)
404		No such resource for this tenant. Somebody else's resource — and a resource of a project the caller does not reach — answers the same way on purpose: the two must not be distinguishable.
422		Validation failure or a semantically impossible request. Field-level validation from the framework answers `{"message", "errors"}`; domain refusals answer the standard error envelope. An `Idempotency-Key` longer than 190 characters is `invalid_request` in that envelope.

Заголовки

X-Request-Id

Тіло кожної помилки — конверт помилки.

Приклади

Отримати список пулів

У списку пули, доступні ключу: пули його проєкту й організації.

Terminal

curl https://api.slen.ai/api/v1/provider-pools \
  -H "Authorization: Bearer $SLEN_API_KEY"

200 OK

{
  "data": [
    {
      "provider_pool_id": "74438955400675328",
      "organization_id": "74438200973594112",
      "project_id": "74438200973594624",
      "name": "OpenAI",
      "provider": "openai",
      "allow_cross_provider": false,
      "strategy": "priority",
      "max_attempts": 3,
      "on_rate_limit": "switch_connection",
      "on_provider_error": "switch_connection",
      "status": "active",
      "connections": [
        {
          "connection_id": "74438912450035712",
          "name": "OpenAI production",
          "provider": "openai",
          "environment": "production",
          "secret_last_four": "c81d",
          "status": "active",
          "health_status": "healthy",
          "priority": 1,
          "weight": 0,
          "enabled": true,
          "cost_multiplier": "1.0000"
        }
      ],
      "created_at": "2026-10-02T08:14:02+00:00",
      "updated_at": "2026-10-02T08:14:02+00:00"
    }
  ],
  "meta": {
    "limit": 30,
    "next_cursor": null
  }
}

Створити пул

Пул проєкту з порядком за пріоритетом. Учасників у пулу поки немає.

Terminal

curl https://api.slen.ai/api/v1/provider-pools \
  -H "Authorization: Bearer $SLEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "project",
    "name": "OpenAI failover",
    "provider": "openai",
    "strategy": "priority",
    "max_attempts": 3
  }'

201 Created

{
  "data": {
    "provider_pool_id": "74443250117779456",
    "organization_id": "74438200973594112",
    "project_id": "74438200973594624",
    "name": "OpenAI failover",
    "provider": "openai",
    "allow_cross_provider": false,
    "strategy": "priority",
    "max_attempts": 3,
    "on_rate_limit": "switch_connection",
    "on_provider_error": "switch_connection",
    "status": "active",
    "connections": [],
    "created_at": "2026-10-02T10:02:17+00:00",
    "updated_at": "2026-10-02T10:02:17+00:00"
  }
}

Прочитати пул

Відповідь — пул у тій самій формі, що відповідь вище, з його учасниками.

Terminal

curl https://api.slen.ai/api/v1/provider-pools/74438955400675328 \
  -H "Authorization: Bearer $SLEN_API_KEY"

200 OK

{
  "data": {
    "provider_pool_id": "74438955400675328",
    "organization_id": "74438200973594112",
    "project_id": "74438200973594624",
    "name": "OpenAI",
    "provider": "openai",
    "allow_cross_provider": false,
    "strategy": "priority",
    "max_attempts": 3,
    "on_rate_limit": "switch_connection",
    "on_provider_error": "switch_connection",
    "status": "active",
    "connections": [
      {
        "connection_id": "74438912450035712",
        "name": "OpenAI production",
        "provider": "openai",
        "environment": "production",
        "secret_last_four": "c81d",
        "status": "active",
        "health_status": "healthy",
        "priority": 1,
        "weight": 0,
        "enabled": true,
        "cost_multiplier": "1.0000"
      }
    ],
    "created_at": "2026-10-02T08:14:02+00:00",
    "updated_at": "2026-10-02T08:14:02+00:00"
  }
}

Змінити налаштування

Пул переходить на стратегію weighted. Його провайдер і учасники лишаються.

Terminal

curl -X PATCH https://api.slen.ai/api/v1/provider-pools/74438955400675328 \
  -H "Authorization: Bearer $SLEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "strategy": "weighted"
  }'

200 OK

{
  "data": {
    "provider_pool_id": "74438955400675328",
    "organization_id": "74438200973594112",
    "project_id": "74438200973594624",
    "name": "OpenAI",
    "provider": "openai",
    "allow_cross_provider": false,
    "strategy": "weighted",
    "max_attempts": 3,
    "on_rate_limit": "switch_connection",
    "on_provider_error": "switch_connection",
    "status": "active",
    "connections": [
      {
        "connection_id": "74438912450035712",
        "name": "OpenAI production",
        "provider": "openai",
        "environment": "production",
        "secret_last_four": "c81d",
        "status": "active",
        "health_status": "healthy",
        "priority": 1,
        "weight": 0,
        "enabled": true,
        "cost_multiplier": "1.0000"
      }
    ],
    "created_at": "2026-10-02T08:14:02+00:00",
    "updated_at": "2026-10-02T10:05:40+00:00"
  }
}

Видалити пул

У відповіді немає тіла.

Terminal

curl -X DELETE https://api.slen.ai/api/v1/provider-pools/74443250117779456 \
  -H "Authorization: Bearer $SLEN_API_KEY"

204 No Content

Додати підключення

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

Terminal

curl https://api.slen.ai/api/v1/provider-pools/74443250117779456/connections \
  -H "Authorization: Bearer $SLEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "74438912450035712",
    "priority": 1
  }'

201 Created

{
  "data": {
    "provider_pool_id": "74443250117779456",
    "organization_id": "74438200973594112",
    "project_id": "74438200973594624",
    "name": "OpenAI failover",
    "provider": "openai",
    "allow_cross_provider": false,
    "strategy": "priority",
    "max_attempts": 3,
    "on_rate_limit": "switch_connection",
    "on_provider_error": "switch_connection",
    "status": "active",
    "connections": [
      {
        "connection_id": "74438912450035712",
        "name": "OpenAI production",
        "provider": "openai",
        "environment": "production",
        "secret_last_four": "c81d",
        "status": "active",
        "health_status": "healthy",
        "priority": 1,
        "weight": 0,
        "enabled": true,
        "cost_multiplier": "1.0000"
      }
    ],
    "created_at": "2026-10-02T10:02:17+00:00",
    "updated_at": "2026-10-02T10:03:05+00:00"
  }
}

Змінити учасника

Учасник отримує вагу для стратегії weighted.

Terminal

curl -X PATCH https://api.slen.ai/api/v1/provider-pools/74438955400675328/connections/74438912450035712 \
  -H "Authorization: Bearer $SLEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "weight": 70
  }'

200 OK

{
  "data": {
    "provider_pool_id": "74438955400675328",
    "organization_id": "74438200973594112",
    "project_id": "74438200973594624",
    "name": "OpenAI",
    "provider": "openai",
    "allow_cross_provider": false,
    "strategy": "weighted",
    "max_attempts": 3,
    "on_rate_limit": "switch_connection",
    "on_provider_error": "switch_connection",
    "status": "active",
    "connections": [
      {
        "connection_id": "74438912450035712",
        "name": "OpenAI production",
        "provider": "openai",
        "environment": "production",
        "secret_last_four": "c81d",
        "status": "active",
        "health_status": "healthy",
        "priority": 1,
        "weight": 70,
        "enabled": true,
        "cost_multiplier": "1.0000"
      }
    ],
    "created_at": "2026-10-02T08:14:02+00:00",
    "updated_at": "2026-10-02T10:05:40+00:00"
  }
}

Від’єднати підключення

У відповіді немає тіла. Підключення лишається таким, як було.

Terminal

curl -X DELETE https://api.slen.ai/api/v1/provider-pools/74443250117779456/connections/74438912450035712 \
  -H "Authorization: Bearer $SLEN_API_KEY"

204 No Content

Прочитати запас

Учасник використав 112 із 500 запитів на хвилину, які дозволяють його ліміти.

Terminal

curl "https://api.slen.ai/api/v1/provider-pools/74438955400675328/capacity?model=gpt-4o-mini" \
  -H "Authorization: Bearer $SLEN_API_KEY"

200 OK

{
  "data": [
    {
      "connection_id": "74438912450035712",
      "model": "gpt-4o-mini",
      "limits": {
        "rpm": 500,
        "tpm": 200000,
        "input_tpm": null,
        "output_tpm": null,
        "max_concurrency": 20,
        "daily_quota": null
      },
      "used": {
        "requests": 112,
        "tokens": 41250
      },
      "remaining": {
        "requests": 388,
        "tokens": 158750
      },
      "active_concurrency": 3,
      "reset_at": "2026-10-02T10:06:00+00:00"
    }
  ]
}

Прочитати, як пул обслуговував виклики

Вікно — останні сім днів.

Terminal

curl https://api.slen.ai/api/v1/provider-pools/74438955400675328/analytics \
  -H "Authorization: Bearer $SLEN_API_KEY"

Що читати далі

Пули провайдерів — ті самі пули в консолі, стратегії й вибір у разі збоїв.
Підключення провайдерів — підключення, які об’єднує пул.
Аналітика — як звіт читає своє вікно.
Коди помилок — що означає кожен код цієї сторінки і що з ним робити.

Зібрано з openapi b070e1f, sdk contract 5cc7055, php ae4a53b, node 84bc62d