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

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

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

Проект и организация

Пул принадлежит одному проекту или всей организации. У пула организации 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