---
title: "Create a build"
method: POST
path: "/builds"
---

# Create a build

`POST /builds`

Create a new build from an uploaded context. If a successful build already exists with the same context hash, region, and Dockerfile path, the cached build is returned instead of triggering a new build.

## Request body

- CreateBuildRequest
  - `uploadId` string, uuid, required — The upload ID returned from the upload-url endpoint.
  - `region` string, required — Target region for the build. Must match the region used when getting the upload URL.
  - `dockerfilePath` string — Path to the Dockerfile within the context archive.

## Response `200`

Cached build found - no new build triggered

- CreateBuildResponse
  - `build` Build
    - `id` string, uuid — Unique identifier for the build.
    - `organizationId` string — Organization that owns this build.
    - `status` 'pending' | 'building' | 'success' | 'failed' | 'timeout' — Current status of the build.
    - `region` string — Region where the build ran.
    - `contextHash` string — Hash of the build context.
    - `dockerfilePath` string — Path to the Dockerfile used for this build.
    - `imageUri` string — URI of the built image. Use this value when deploying an agent. Only present when status is 'success'.
    - `logsUrl` string, uri — URL to view build logs in the cloud console.
    - `errorMessage` string — Detailed error message if the build failed. Includes information from the build phases to help diagnose issues.
    - `contextSizeBytes` integer — Size of the uploaded context in bytes.
    - `imageSizeBytes` integer — Size of the built Docker image in bytes. Only present for successful builds.
    - `buildDurationSeconds` integer — Total build duration in seconds. Only present when build is complete.
    - `startedAt` string, date-time — When the build started executing.
    - `completedAt` string, date-time — When the build completed (success, failed, or timeout).
    - `createdAt` string, date-time — When the build record was created.
    - `updatedAt` string, date-time — When the build record was last updated.
  - `contextHash` string — Hash of the uploaded context. Used for build caching.
  - `cached` boolean — Whether this response uses a cached build (true) or triggered a new build (false).

## Other responses

- `201` — New build created and triggered
- `400` — Invalid request (e.g., upload not found, cloud build not enabled)

---

[API](https://skmtc.dev/pipecat/apis/pipecat-cloud.md) · [All operations](https://skmtc.dev/pipecat/apis/pipecat-cloud/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pipecat/pipecat-cloud/revisions/acd0f7dfe734/schema)