Create Build

Create a new build or return a cached build for your uploaded context

POST /builds

Create a build

cURL

curl --request POST \
  --url https://api.pipecat.daily.co/v1/builds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "uploadId": "550e8400-e29b-41d4-a716-446655440000",
  "region": "us-west",
  "dockerfilePath": "Dockerfile"
}
'

200

{
  "build": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "organizationId": "org_abc123",
    "status": "building",
    "region": "us-west",
    "contextHash": "a1b2c3d4e5f6a7b8",
    "dockerfilePath": "Dockerfile",
    "imageUri": "123456789.dkr.ecr.us-west-2.amazonaws.com/pipecat-cloud/org_abc123:a1b2c3d4e5f6a7b8",
    "logsUrl": "https://console.aws.amazon.com/codebuild/...",
    "errorMessage": "Docker build failed: COPY failed - file not found",
    "contextSizeBytes": 10485760,
    "imageSizeBytes": 524288000,
    "buildDurationSeconds": 120,
    "startedAt": "2026-02-20T12:00:00.000Z",
    "completedAt": "2026-02-20T12:02:00.000Z",
    "createdAt": "2026-02-20T12:00:00.000Z",
    "updatedAt": "2026-02-20T12:02:00.000Z"
  },
  "contextHash": "a1b2c3d4e5f6a7b8",
  "cached": false
}

Build Caching

Pipecat Cloud automatically caches successful builds based on three factors:

1. Context hash - A hash of your uploaded context archive
2. Region - The target deployment region
3. Dockerfile path - The path to your Dockerfile

If a successful build already exists with the same combination, you’ll receive the cached build with cached: true. This makes repeated deployments much faster.

Build Flow

Example: Complete Build Flow

# 1. Get upload URL
UPLOAD_RESPONSE=$(curl -s -X POST "https://api.pipecat.daily.co/v1/builds/upload-url" \
  -H "Authorization: Bearer $PIPECAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"region": "us-west"}')

UPLOAD_ID=$(echo $UPLOAD_RESPONSE | jq -r '.uploadId')

# 2. Upload context (see upload-url endpoint for details)

# 3. Create the build
BUILD_RESPONSE=$(curl -s -X POST "https://api.pipecat.daily.co/v1/builds" \
  -H "Authorization: Bearer $PIPECAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"uploadId\": \"$UPLOAD_ID\",
    \"region\": \"us-west\",
    \"dockerfilePath\": \"Dockerfile\"
  }")

BUILD_ID=$(echo $BUILD_RESPONSE | jq -r '.build.id')
CACHED=$(echo $BUILD_RESPONSE | jq -r '.cached')

if [ "$CACHED" = "true" ]; then
  echo "Using cached build!"
  IMAGE_URI=$(echo $BUILD_RESPONSE | jq -r '.build.imageUri')
else
  echo "Build started: $BUILD_ID"
  echo "Poll GET /builds/$BUILD_ID for status"
fi

Build Statuses

Status	Description
pending	Build created, waiting to start
building	Build is in progress
success	Build completed successfully, imageUri is available
failed	Build failed, check errorMessage for details
timeout	Build exceeded the time limit

Authorizations

Authorization · string · header · required

Authentication using a Pipecat Cloud API token.

Body

application/json

uploadId · string<uuid> · required

The upload ID returned from the upload-url endpoint.

Example:

"550e8400-e29b-41d4-a716-446655440000"

region · string · required

Target region for the build. Must match the region used when getting the upload URL.

Example:

"us-west"

dockerfilePath · string · default: Dockerfile

Path to the Dockerfile within the context archive.

Example:

"Dockerfile"

Response

200

application/json

Cached build found - no new build triggered

build · object

Show child attributes

contextHash · string

Hash of the uploaded context. Used for build caching.

Example:

"a1b2c3d4e5f6a7b8"

cached · boolean

Whether this response uses a cached build (true) or triggered a new build (false).

Example:

false