Create a build draft

OpenAPI contract

Method

POST

Path

/api/v1/builds/draft

Security

jwtBearer (bearer) OR automationKey (bearer)

Response status

201 400 401 402 403 404 413 429 500

Request and response schemas

JSON

{
  "requestBody": {
    "multipart/form-data": {
      "properties": {
        "file": {
          "description": "Input JAR or ZIP archive",
          "format": "binary",
          "type": "string"
        }
      },
      "required": [
        "file"
      ],
      "type": "object"
    }
  },
  "responses": {
    "201": {
      "description": "Draft created",
      "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"
        }
      }
    },
    "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"
        }
      }
    }
  }
}

Upload a .jar or .zip now and configure it later. A JWT or an nfy_ key with build:write is required; an automation key also needs project:write when projectId is supplied. Creating a draft stores and inspects the input but does not reserve credits or dispatch compilation. It is a non-idempotent POST; retrying the upload creates another draft.

Only the file, optional project, and optional hostingPath are set at this stage. Supplying a project requires effective build:write capability on it, and an archived workspace rejects the draft. Without a project, the draft uses the caller's personal workspace and later relies on the exact-owner fallback. The draft starts pending and keeps its generated default private path unless a custom path is supplied. A custom path is never an access-control switch: once the build succeeds, hosted retrieval still requires a dashboard JWT or an nfy_ key carrying artifact:read, plus effective artifact:output:read for a project task or exact ownership of a legacy/ad-hoc task.

Use the returned task identifier with Start a build draft. Invalid archive input, unsupported filename, invalid or conflicting path, and a project outside the caller's writable collaboration boundary are rejected.