Submit a build

OpenAPI contract

Method

POST

Path

/api/v1/builds

Security

jwtBearer (bearer) OR automationKey (bearer)

Response status

202 400 401 402 403 404 409 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": {
    "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"
        }
      }
    }
  }
}

Upload one .jar or .zip to create and queue a build. Use a JWT or an nfy_ key with build:write. Supplying projectId requires effective build:write capability on that project and an active workspace; an automation key also needs project:write. Whenever processorId is supplied, an automation key needs processor:read, and the preset remains caller-owned. Without a project, the build uses the caller's personal workspace and exact-owner fallback. This is a non-idempotent POST: retrying it can create another task and reserve credits again. Use the returned task URL to observe the original request instead of replaying it.

The request accepts target platforms, feature names, skipIrOpt, optional project/preset IDs, and an optional hostingPath. Empty platforms resolve in this order: request, project default, service fallback. Empty features resolve as request, selected processor preset, project default, then service fallback.

Every build receives a private hosted path. Without a custom value it is artifacts/{taskId}/native.jar; hostingPath changes the route address, not its authorization. The task response contains hostingPath, so construct the route under /api/v1/hosted/ yourself. Retrieval accepts a dashboard JWT or an nfy_ key carrying artifact:read, then requires effective artifact:output:read for a project task or exact ownership of a legacy/ad-hoc task. Upload validation, invalid options, unknown features, resource-authorization failures, queue limits, credit reservation, or dispatch capacity can prevent acceptance.

http

Authorization: Bearer <token>
Content-Type: multipart/form-data
[email protected]
features=flattening