---
title: "POST /v1/pools"
method: POST
path: "/v1/pools"
tags: ["pools"]
---

# POST /v1/pools

`POST /v1/pools`

## Request body

- union
  - object
    - `gpus` object, required
    - `bundle` string, nullable
    - `gpu_caps` object
    - `minimum_worker_count` integer — Per-pool warm floor (minimum machines kept warm via KEDA). Default 0 keeps scale-from-zero. See `PoolSpec::minimum_worker_count`.
    - `name` string, required — Pool name used in gpu="pool/machine_profile" routing. Names are stored and routed in lowercase. Only ASCII letters, digits, '_' and '-' are allowed; '_default' is reserved.
    - `pinned_models` string[] — Per-pool pinned-model set. Each id is validated against the models the gateway already tracks and stored canonicalized; ids may be profile-qualified (`model-name:profile_name`). Default empty leaves lazy-loading unchanged. See `PoolSpec::pinned_models`.
    - `queue_pool` string, nullable — Physical Helm/NATS queue namespace to draw workers from. Omit for normal dynamic logical pools; they use `default`. Set only to an operator-provisioned Helm queue pool declared under `queueRouting.staticQueuePools` for dedicated capacity.
    - `ttl_seconds` integer, nullable
  - object
    - `gpu_caps` object, required
    - `bundle` string, nullable
    - `gpus` object
    - `minimum_worker_count` integer — Per-pool warm floor (minimum machines kept warm via KEDA). Default 0 keeps scale-from-zero. See `PoolSpec::minimum_worker_count`.
    - `name` string, required — Pool name used in gpu="pool/machine_profile" routing. Names are stored and routed in lowercase. Only ASCII letters, digits, '_' and '-' are allowed; '_default' is reserved.
    - `pinned_models` string[] — Per-pool pinned-model set. Each id is validated against the models the gateway already tracks and stored canonicalized; ids may be profile-qualified (`model-name:profile_name`). Default empty leaves lazy-loading unchanged. See `PoolSpec::pinned_models`.
    - `queue_pool` string, nullable — Physical Helm/NATS queue namespace to draw workers from. Omit for normal dynamic logical pools; they use `default`. Set only to an operator-provisioned Helm queue pool declared under `queueRouting.staticQueuePools` for dedicated capacity.
    - `ttl_seconds` integer, nullable

## Response `201`

Pool created, renewed, or updated

- Pool
  - `spec` PoolSpec, required
    - `bundle` string, nullable
    - `gpu_caps` object
    - `gpus` object
    - `minimum_worker_count` integer — Per-pool warm floor: the minimum number of machines the gateway keeps warm (via KEDA) so the first request to the pool never hits a cold VM. The gateway publishes it as `sie.gateway.pool.warm_floor`; the collector translates it for KEDA's Prometheus query. Default 0 leaves scale-from-zero unchanged.
    - `name` string, required
    - `pinned_models` string[] — Per-pool pinned-model set: models the gateway keeps loaded so the first request to them pays no cold model-load. Chosen from the models the gateway already tracks (see `GET /v1/configs/models`); ids may be profile-qualified (`model-name:profile_name`). Default empty leaves lazy-loading unchanged.
    - `queue_pool` string — Physical Helm/NATS queue namespace backing this logical API pool. API-created pools default to the Helm `default` queue pool. Pool `name` is user/dynamic; a non-default `queue_pool` is infra/admin and must match a Helm worker queue declared under `queueRouting.staticQueuePools`.
    - `ttl_seconds` integer, nullable
  - `status` PoolStatus, required
    - `assigned_workers` AssignedWorker[]
      - `bundle` string
      - `gpu` string, required
      - `name` string, required
      - `url` string, required
    - `created_at` number, double
    - `last_renewed` number, double
    - `state` 'pending' | 'active' | 'expired', required

## Other responses

- `400` — Invalid pool request
- `401` — Missing or invalid bearer token (inference token)
- `403` — Valid bearer token but admin token required for this mutation (or admin token not configured)
- `500` — Gateway auth enabled but no tokens configured

---

[API](https://skmtc.net/superlinked/apis/sie-gateway.md) · [All operations](https://skmtc.net/superlinked/apis/sie-gateway/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/superlinked/sie-gateway/versions/06a326e2c3e9/schema)