---
title: "Creates or replaces a node pool's configuration. Omitted fields take their defaults. Nodes pick up the new configuration on their next connection."
method: PUT
path: "/pools/{pool}"
tags: ["pools"]
---

# Creates or replaces a node pool's configuration. Omitted fields take their defaults. Nodes pick up the new configuration on their next connection.

`PUT /pools/{pool}`

## Request

- Base URL: `https://api.rivet.dev`
- URL: `https://api.rivet.dev/pools/{pool}`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-rivet-token`

## Path parameters

- `pool` string, required

## Query parameters

- `namespace` string

## Request body

- PoolUpsertRequest: Every field is optional. Unknown fields are rejected.
  - `drain_on_version_upgrade` boolean: Drain nodes running an older version when a newer version connects.
  - `actor_eviction_delay` integer: Seconds to wait before evicting actors from a draining node.
  - `actor_eviction_period` integer: Seconds over which actors are evicted from a draining node.
  - `actor_eviction_rate` number, double: Rate at which actors are evicted from a draining node. Must be finite and greater than 0.
  - `metadata` unknown

## Response `200`

The stored node pool.

- PoolResponse
  - `pool` Pool, required
    - `name` string, required: Name of the node pool.
    - `drain_on_version_upgrade` boolean, required: Drain nodes running an older version when a newer version connects.
    - `actor_eviction_delay` integer, required: Seconds to wait before evicting actors from a draining node.
    - `actor_eviction_period` integer, required: Seconds over which actors are evicted from a draining node.
    - `actor_eviction_rate` number, double, required: Rate at which actors are evicted from a draining node. Must be finite and greater than 0.
    - `metadata` unknown, required

## Other responses

- `400`: `pool.invalid`: the body has an unknown field or a value out of range. `pool.serverless_unsupported`: the body sets `serverless` or `kind: "serverless"`. `envoy.invalid_pool_name`: the pool name is not valid. `envoy.invalid_namespace_name`: the `namespace` value is not a DNS label of 1 to 63 lowercase letters, digits and hyphens. A body that is not valid JSON is rejected with a plain-text 400.
- `401`: `auth.invalid_token`: the request carries no token, or the token is not valid. `auth.token_expired`: the token has expired.
- `403`: `auth.insufficient_permissions`: the token's grants do not cover this request.
- `404`: `namespace.not_found`: the namespace does not exist.
- `415`: The request is missing the `Content-Type: application/json` header. Returned as plain text.
- `500`: `core.internal_error`: an unexpected failure. Details are only logged on the server.
- `503`: `auth.verification_unavailable`: token verification keys are temporarily unavailable. Retry the request.

## Changes

- **2026-10-31** `aa8d1a8a5d14`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/rivet-dev/apis/rivet-api-public/changes/pools/:pool/put.md)

---

[API](https://skmtc.dev/rivet-dev/apis/rivet-api-public.md) - [All operations](https://skmtc.dev/rivet-dev/apis/rivet-api-public/llms.txt) - [OpenAPI document](https://skmtc.dev/rivet-dev/apis/rivet-api-public/revisions/531e21275aec?raw)