Start a build draft

OpenAPI contract

Method

POST

Path

/api/v1/builds/{taskId}/start

Security

jwtBearer (bearer) OR automationKey (bearer)

Response status

202 400 401 402 403 404 409 413 429 500

Request and response schemas

JSON

{
  "requestBody": {},
  "responses": {
    "202": {
      "description": "Build accepted",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/CompileTaskResponse"
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/RequestError"
        }
      }
    },
    "401": {
      "description": "Authentication required or invalid",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/SecurityError"
        }
      }
    },
    "402": {
      "description": "Insufficient NCU balance",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    },
    "403": {
      "description": "Authenticated but not permitted",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/SecurityError"
        }
      }
    },
    "404": {
      "description": "Requested build was not found",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    },
    "409": {
      "description": "Request conflicts with current build state",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    },
    "413": {
      "description": "Upload or expanded archive exceeds a configured limit",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    },
    "429": {
      "description": "HTTP rate limit or API-key NCU usage limit exceeded",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/RateLimitError"
        }
      }
    },
    "500": {
      "description": "Unexpected server error",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}

Start one pending, unstarted draft with a JWT or an nfy_ key carrying build:write. Access to the draft itself requires effective build:write on its project or, for a legacy/ad-hoc draft, exact ownership. The resolved project also requires effective build:write and must belong to an active workspace. An automation key additionally needs project:write when projectId is supplied or the omitted parameter inherits a project already stored on the draft, and it needs processor:read whenever processorId is supplied. This is a non-idempotent POST: after it starts, repeat calls are not a safe retry. Poll the task URL returned by the original operation instead.

The service re-inspects the saved input and applies configuration field by field. projectId in this request wins over the draft project; if absent, the draft project remains. For platforms, request value wins, then the resolved project default, then the service fallback. For features, request value wins; otherwise a supplied processor preset wins; otherwise the resolved project default applies, then the service fallback. The request processorId replaces the draft processor value. skipIrOpt comes from this start request. A supplied hostingPath replaces the draft path; an omitted one preserves it.

The draft must still be pending and unstarted. Input loss, invalid configuration, missing project capability, an archived workspace, concurrency limits, insufficient credits, or capacity can stop the transition.