v1

latestOpenAPI 3.0.02026-07-26242779.3 KB

Create a build

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.

post/builds

Request body

uploadIdstring uuid required

The upload ID returned from the upload-url endpoint.

regionstring required

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

dockerfilePathstring

Path to the Dockerfile within the context archive.

Example request

{
  "uploadId": "550e8400-e29b-41d4-a716-446655440000",
  "region": "us-west",
  "dockerfilePath": "Dockerfile"
}

Response

Cached build found - no new build triggered

contextHashstring

Hash of the uploaded context. Used for build caching.

cachedboolean

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

Example response

{
  "build": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "organizationId": "org_abc123",
    "status": "success",
    "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: requirements.txt",
    "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"
}