Adjoint Docs Product ↗
Menu

Pools

Pre-warmed clone pools — the mechanic behind adj clone sometimes resolving in seconds instead of minutes. See Clone pools for the full "why" and the claim semantics from POST /v1/instances's perspective. All routes on this page are admin-gated.

POST /v1/pools — create a pool

Auth: admin.

Request body

Field Type Required Notes
golden string yes The golden lineage to pre-warm. The pool pins whatever version is latest and ready at creation time — it does not auto-follow later versions.
target_warm integer yes Must be >= 1. How many warm clones to keep ready.
max_warming integer no Caps concurrent in-flight provisions (defaults applied server-side if omitted/zero — FSx volume creation is rate-limited, so pools fill gradually). 
$ curl -s https://api.stagdb.com/v1/pools -X POST -H "Authorization: Bearer $TOKEN" \
    -H 'Content-Type: application/json' \
    -d '{"golden":"prod-pg16","target_warm":5,"max_warming":2}'

Response 202 Accepted — the pool fills asynchronously in the data plane.

{
  "id": "8f4b2c1a-3d5e-4a7b-9c0d-1e2f3a4b5c6d",
  "golden": "prod-pg16",
  "version": 3,
  "substrate": "postgres",
  "target_warm": 5,
  "max_warming": 2,
  "phase": "Filling",
  "warm": 0,
  "warming": 2,
  "created_at": "2026-07-19T21:03:12Z"
}
Status When
400 golden empty; target_warm < 1; or the golden has no ready version to pin. Wire body is the generic {"error": "invalid input"} in all three cases.
403 Caller is not an admin.
409 A pool for this exact golden+version already exists on this cluster — wire body is the generic {"error": "conflict"}; or the org has no registered cluster — the one 409 that IS distinguishable from the body: {"error": "org has no registered cluster"}.

GET /v1/pools — list pools

Auth: admin.

$ curl -s https://api.stagdb.com/v1/pools -H "Authorization: Bearer $TOKEN"

Response 200 OK

{"pools": [ /* pool objects, same shape as the POST response above */ ]}
Status When
403 Caller is not an admin.

GET /v1/pools/{id} — get one pool

Auth: admin.

$ curl -s https://api.stagdb.com/v1/pools/8f4b2c1a-3d5e-4a7b-9c0d-1e2f3a4b5c6d -H "Authorization: Bearer $TOKEN"

Response 200 OK — a single pool object. Once fully filled, phase reads "Ready" and warm equals target_warm.

Status When
400 {id} not a valid UUID.
403 Caller is not an admin.
404 No such pool in this org.

DELETE /v1/pools/{id} — remove a pool

Auth: admin.

$ curl -s https://api.stagdb.com/v1/pools/8f4b2c1a-3d5e-4a7b-9c0d-1e2f3a4b5c6d -X DELETE \
    -H "Authorization: Bearer $TOKEN" -o /dev/null -w '%{http_code}\n'
204

Tombstones the pool and drains its warm, unclaimed clones in the data plane (they're destroyed). Instances a developer already fast-claimed out of the pool are untouched — they're regular instances now, following the normal lifecycle (reset/refresh/destroy via Instances).

Response: 204 No Content.

Status When
400 {id} not a valid UUID.
403 Caller is not an admin.
404 No such pool in this org.

Refreshing a pool onto a new version

There's no update endpoint — a pool pins one version for its whole lifetime. To move to a newer golden version, remove and recreate:

$ curl -s https://api.stagdb.com/v1/pools/8f4b2c1a-3d5e-4a7b-9c0d-1e2f3a4b5c6d -X DELETE -H "Authorization: Bearer $TOKEN"
$ curl -s https://api.stagdb.com/v1/pools -X POST -H "Authorization: Bearer $TOKEN" \
    -H 'Content-Type: application/json' -d '{"golden":"prod-pg16","target_warm":5}'

The new pool picks up whatever is latest-and-ready at the moment it's created.

Next