{
  "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"
    }
  ],
  "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",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "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"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authentication using a Pipecat Cloud API token."
      }
    },
    "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
          }
        }
      },
      "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"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message"
          },
          "code": {
            "type": "string",
            "description": "Error code"
          }
        }
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ]
}