---
title: "Create builder"
method: POST
path: "/builders"
---

# Create builder

`POST /builders`

## Request

- Base URL: `http://localhost:4973`
- URL: `http://localhost:4973/builders`
- Auth: HTTP bearer

Creates a builder and its cache disk. One build at a time runs per builder.

## Request body

- CreateBuilderRequest
  - `id` string: Optional caller-supplied identifier, auto-generated if not provided
  - `name` string: Optional non-unique display name
  - `disk_size_gb` integer: Cache disk size in gigabytes. Omit to use the server default.
  - `tags` Tags: User-defined key-value tags.

## Response `201`

Builder created

- Builder
  - `id` string, required: Builder identifier
  - `name` string: Optional non-unique display name
  - `disk_size_gb` integer, required: Persistent builder cache disk size in gigabytes. Cannot be changed after creation.
  - `status` 'ready' | 'pruning' | 'deleting' | 'error', required: Builder lifecycle status
  - `tags` Tags: User-defined key-value tags.
  - `created_at` string, date-time, required: Creation timestamp (RFC3339)
  - `last_used_at` string, date-time, nullable: When a build last ran on this builder
  - `max_concurrency` integer, required: Maximum concurrent builds on this builder. Currently fixed at 1.
  - `active_build_id` string, nullable: Point-in-time ID of the build currently running on this builder
  - `queued_builds` string[], required: Point-in-time IDs of queued builds waiting for this builder, oldest first

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `409`: Conflict - builder with this ID already exists or quota exceeded
- `500`: Internal server error

## Changes

- **2026-08-21** `b00eacfe26b2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/kernel/apis/hypeman-api/changes/builders/post.md)

---

[API](https://skmtc.dev/kernel/apis/hypeman-api.md) - [All operations](https://skmtc.dev/kernel/apis/hypeman-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kernel/apis/hypeman-api/revisions/befe3f654ef6?raw)