> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Build

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

## 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

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant API
    participant Storage
    participant CodeBuild

    Client->>API: POST /builds/upload-url
    API-->>Client: uploadUrl, uploadId
    Client->>Storage: Upload context.tar.gz
    Client->>API: POST /builds
    API->>Storage: Get context hash
    API->>API: Check for cached build
    alt Cached build exists
        API-->>Client: 200 OK (cached: true)
    else No cached build
        API->>CodeBuild: Trigger build
        API-->>Client: 201 Created (cached: false)
    end
```

## Example: Complete Build Flow

```bash theme={null}
# 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                         |


## OpenAPI

````yaml POST /builds
openapi: 3.0.0
info:
  title: Pipecat Cloud
  version: 1.0.0
  description: Public API for Pipecat Cloud services
servers:
  - url: https://api.pipecat.daily.co/v1
    description: API server
security:
  - BearerAuth: []
paths:
  /builds:
    post:
      summary: Create a build
      description: >-
        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.
      operationId: createBuild
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBuildRequest'
      responses:
        '200':
          description: Cached build found - no new build triggered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateBuildResponse'
        '201':
          description: New build created and triggered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateBuildResponse'
        '400':
          description: Invalid request (e.g., upload not found, cloud build not enabled)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    CreateBuildRequest:
      type: object
      required:
        - uploadId
        - region
      properties:
        uploadId:
          type: string
          format: uuid
          description: The upload ID returned from the upload-url endpoint.
          example: 550e8400-e29b-41d4-a716-446655440000
        region:
          type: string
          description: >-
            Target region for the build. Must match the region used when getting
            the upload URL.
          example: us-west
        dockerfilePath:
          type: string
          default: Dockerfile
          description: Path to the Dockerfile within the context archive.
          example: Dockerfile
    CreateBuildResponse:
      type: object
      properties:
        build:
          $ref: '#/components/schemas/Build'
        contextHash:
          type: string
          description: Hash of the uploaded context. Used for build caching.
          example: a1b2c3d4e5f6a7b8
        cached:
          type: boolean
          description: >-
            Whether this response uses a cached build (true) or triggered a new
            build (false).
          example: false
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
    Build:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the build.
          example: 123e4567-e89b-12d3-a456-426614174000
        organizationId:
          type: string
          description: Organization that owns this build.
          example: org_abc123
        status:
          type: string
          enum:
            - pending
            - building
            - success
            - failed
            - timeout
          description: Current status of the build.
          example: building
        region:
          type: string
          description: Region where the build is running.
          example: us-west
        contextHash:
          type: string
          description: Hash of the build context.
          example: a1b2c3d4e5f6a7b8
        dockerfilePath:
          type: string
          description: Path to the Dockerfile used for this build.
          example: Dockerfile
        imageUri:
          type: string
          description: URI of the built image (only present when status is 'success').
          example: >-
            123456789.dkr.ecr.us-west-2.amazonaws.com/pipecat-cloud/org_abc123:a1b2c3d4e5f6a7b8
        logsUrl:
          type: string
          format: uri
          description: URL to view build logs.
          example: https://console.aws.amazon.com/codebuild/...
        errorMessage:
          type: string
          description: Error message if the build failed.
          example: 'Docker build failed: COPY failed - file not found'
        contextSizeBytes:
          type: integer
          description: Size of the uploaded context in bytes.
          example: 10485760
        imageSizeBytes:
          type: integer
          description: >-
            Size of the built Docker image in bytes. Only present for successful
            builds.
          example: 524288000
        buildDurationSeconds:
          type: integer
          description: Build duration in seconds (only present when build is complete).
          example: 120
        startedAt:
          type: string
          format: date-time
          description: When the build started.
          example: '2026-02-20T12:00:00.000Z'
        completedAt:
          type: string
          format: date-time
          description: When the build completed.
          example: '2026-02-20T12:02:00.000Z'
        createdAt:
          type: string
          format: date-time
          description: When the build record was created.
          example: '2026-02-20T12:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: When the build record was last updated.
          example: '2026-02-20T12:02:00.000Z'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Authentication using a Pipecat Cloud API token.

````