---
title: "Start queued warm pool build"
method: POST
path: "/v1/environments/{environment_id}/warm-pools/build-now"
tags: ["Warm pools"]
---

# Start queued warm pool build

`POST /v1/environments/{environment_id}/warm-pools/build-now`

## Request

- Base URL: `https://api.replicas.dev`
- URL: `https://api.replicas.dev/v1/environments/{environment_id}/warm-pools/build-now`
- Auth: HTTP bearer

Edits queue a warm pool build that starts after 45 seconds without further edits, at most 3 minutes after the first. This starts the queued build right away, or retries the current build if it failed.

## Path parameters

- `environment_id` string, required

## Headers

- `X-Replicas-Api-Version` '2026-10-07'

## Response `200`

Build started

- BuildWarmPoolNowResponse
  - `build` WarmPoolBuildRecord, required: One warm pool generation that was asked to build.
    - `id` string, uuid, required
    - `generation` integer, required
    - `status` 'queued' | 'building' | 'succeeded' | 'failed' | 'superseded' | 'cancelled', required
    - `reasons` string[], required: Every change folded into this build while it was queued
    - `attempts` integer, required
    - `queued_at` string, date-time, required
    - `build_after` string, date-time, required: When a queued build starts unless more edits push it back
    - `started_at` string, date-time, nullable, required
    - `finished_at` string, date-time, nullable, required
    - `superseded_by` string, uuid, nullable, required
    - `error_message` string, nullable, required
    - `builder_warm_pool_workspace_id` string, uuid, nullable, required: Warm pool workspace that ran the build; stream its output from `/v1/warm-pool-workspaces/{id}/stream`
    - `changes` EnvironmentChange[], required: Edits this build applies, including those of earlier builds that never went live
      - `kind` 'repositories' | 'warm_hook' | 'variable' | 'file' | 'skill' | 'skills_registry' | 'default_skills' | 'agent_auth' | 'workspace_size' | 'agent_setup' | 'restore' | 'system', required
      - `key` string, nullable, required: The edited row: variable key, file path, skill slug, registry, or provider
      - `op` 'created' | 'updated' | 'deleted', required
      - `user_id` string, uuid, nullable, required: Who made the edit
    - `failure_kind` 'hook' | 'infra' | 'null', nullable, required
    - `restorable` boolean, required: The setup this build made live is stored and can be restored with `POST /v1/environments/{environment_id}/restore`

## Other responses

- `401`: Unauthorized - Invalid or missing API key
- `404`: Resource not found
- `409`: Conflict - Resource already exists or operation conflicts with current state
- `500`: Internal server error

---

[API](https://skmtc.dev/replicas/apis/replicas-api.md) - [All operations](https://skmtc.dev/replicas/apis/replicas-api/llms.txt) - [OpenAPI document](https://skmtc.dev/replicas/apis/replicas-api/revisions/2703ac1c9cb7?raw)