# Start build (v2) (/docs/api-reference/templates/start-build-v2)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 1825 · updated: 2026-07-30 -->
Related: [Create template (v3)](/docs/api-reference/templates/create-template-v3.md), [List templates (v2)](/docs/api-reference/templates/list-templates-v2.md), [Create template (v2)](/docs/api-reference/templates/create-template-v2.md), [Get build upload link](/docs/api-reference/templates/get-build-upload-link.md), [List templates](/docs/api-reference/templates/list-templates.md), [Create template](/docs/api-reference/templates/create-template.md)

# Start build (v2)

`POST /v2/templates/{templateID}/builds/{buildID}`

Start the build

## OpenAPI

```json
{
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "parameters": [
    {
      "name": "templateID",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "buildID",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "fromImage": {
              "type": "string",
              "description": "Image to use as a base for the template build"
            },
            "fromTemplate": {
              "type": "string",
              "description": "Template to use as a base for the template build"
            },
            "fromImageRegistry": {
              "oneOf": [
                {
                  "type": "object",
                  "required": [
                    "type",
                    "awsAccessKeyId",
                    "awsSecretAccessKey",
                    "awsRegion"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "aws"
                      ],
                      "description": "Type of registry authentication"
                    },
                    "awsAccessKeyId": {
                      "type": "string",
                      "description": "AWS Access Key ID for ECR authentication"
                    },
                    "awsSecretAccessKey": {
                      "type": "string",
                      "description": "AWS Secret Access Key for ECR authentication"
                    },
                    "awsRegion": {
                      "type": "string",
                      "description": "AWS Region where the ECR registry is located"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "type",
                    "serviceAccountJson"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "gcp"
                      ],
                      "description": "Type of registry authentication"
                    },
                    "serviceAccountJson": {
                      "type": "string",
                      "description": "Service Account JSON for GCP authentication"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "type",
                    "username",
                    "password"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "registry"
                      ],
                      "description": "Type of registry authentication"
                    },
                    "username": {
                      "type": "string",
                      "description": "Username to use for the registry"
                    },
                    "password": {
                      "type": "string",
                      "description": "Password to use for the registry"
                    }
                  }
                }
              ],
              "discriminator": {
                "propertyName": "type",
                "mapping": {
                  "aws": "#/components/schemas/AWSRegistry",
                  "gcp": "#/components/schemas/GCPRegistry",
                  "registry": "#/components/schemas/GeneralRegistry"
                }
              }
            },
            "force": {
              "default": false,
              "type": "boolean",
              "description": "Whether the whole build should be forced to run regardless of the cache"
            },
            "steps": {
              "default": [],
              "description": "List of steps to execute in the template build",
              "type": "array",
              "items": {
                "description": "Step in the template build process",
                "required": [
                  "type"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "description": "Type of the step"
                  },
                  "args": {
                    "default": [],
                    "type": "array",
                    "description": "Arguments for the step",
                    "items": {
                      "type": "string"
                    }
                  },
                  "filesHash": {
                    "type": "string",
                    "description": "Hash of the files used in the step"
                  },
                  "force": {
                    "default": false,
                    "type": "boolean",
                    "description": "Whether the step should be forced to run regardless of the cache"
                  }
                },
                "type": "object"
              }
            },
            "startCmd": {
              "description": "Start command to execute in the template after the build",
              "type": "string"
            },
            "readyCmd": {
              "description": "Ready check command to execute in the template after the build",
              "type": "string"
            }
          }
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "The build has started",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "description": "Empty response"
          }
        }
      }
    },
    "401": {
      "description": "Authentication error",
      "content": {
        "application/json": {
          "schema": {
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "integer",
                "format": "int32",
                "description": "Error code"
              },
              "message": {
                "type": "string",
                "description": "Error"
              }
            },
            "type": "object"
          }
        }
      }
    },
    "500": {
      "description": "Server error",
      "content": {
        "application/json": {
          "schema": {
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "integer",
                "format": "int32",
                "description": "Error code"
              },
              "message": {
                "type": "string",
                "description": "Error"
              }
            },
            "type": "object"
          }
        }
      }
    }
  }
}
```