--- title: "Create workspace build" method: POST path: "/api/v2/workspaces/{workspace}/builds" tags: ["Builds"] --- # Create workspace build `POST /api/v2/workspaces/{workspace}/builds` ## Path parameters - `workspace` string, uuid, required ## Request body - CodersdkCreateWorkspaceBuildRequest - `dry_run` boolean - `log_level` 'debug' - `on_success` CodersdkCreateWorkspaceBuildOnSuccessRequest - `rich_parameter_values` CodersdkWorkspaceBuildParameter[] — RichParameterValues are applied to the child build. Parameters not listed here fall back to their values from the previous build, matching normal build behavior. - `name` string - `value` string - `template_version_id` string, uuid — TemplateVersionID pins the child build to a specific template version. Pinning requires permission to update the template, since the active version may change before the child build runs. When empty, the child build uses the template's active version at the time it runs. - `template_version_preset_id` string, uuid — TemplateVersionPresetID selects a preset for the child build. It requires TemplateVersionID to also be set. - `transition` 'start' | 'stop' | 'delete', required - `orphan` boolean — Orphan may be set for the Destroy transition. - `reason` 'dashboard' | 'cli' | 'ssh_connection' | 'vscode_connection' | 'jetbrains_connection' | 'task_manual_pause' | 'task_resume' - `rich_parameter_values` CodersdkWorkspaceBuildParameter[] — ParameterValues are optional. It will write params to the 'workspace' scope. This will overwrite any existing parameters with the same name. This will not delete old params not included in this list. - `name` string - `value` string - `state` integer[] - `template_version_id` string, uuid - `template_version_preset_id` string, uuid — TemplateVersionPresetID is the ID of the template version preset to use for the build. - `transition` 'start' | 'stop' | 'delete', required ## Response `201` Created - CodersdkWorkspaceBuild - `build_number` integer - `created_at` string, date-time - `daily_cost` integer - `deadline` string, date-time - `has_ai_task` boolean — Deprecated: This field has been deprecated in favor of Task WorkspaceID. - `has_external_agent` boolean - `id` string, uuid - `initiator_id` string, uuid - `initiator_name` string - `job` CodersdkProvisionerJob - `available_workers` string[] - `canceled_at` string, date-time - `completed_at` string, date-time - `created_at` string, date-time - `error` string - `error_code` 'REQUIRED_TEMPLATE_VARIABLES' | 'INSUFFICIENT_QUOTA' - `file_id` string, uuid - `id` string, uuid - `initiator_id` string, uuid - `input` CodersdkProvisionerJobInput - `error` string - `template_version_id` string, uuid - `workspace_build_id` string, uuid - `logs_overflowed` boolean - `metadata` CodersdkProvisionerJobMetadata - `template_display_name` string - `template_icon` string - `template_id` string, uuid - `template_name` string - `template_version_name` string - `workspace_build_transition` 'start' | 'stop' | 'delete' - `workspace_id` string, uuid - `workspace_name` string - `organization_id` string, uuid - `queue_position` integer - `queue_size` integer - `started_at` string, date-time - `status` 'pending' | 'running' | 'succeeded' | 'canceling' | 'canceled' | 'failed' | 'unknown' - `tags` object - `type` 'template_version_import' | 'workspace_build' | 'template_version_dry_run' - `worker_id` string, uuid - `worker_name` string - `matched_provisioners` CodersdkMatchedProvisioners - `available` integer — Available is the number of provisioner daemons that are available to take jobs. This may be less than the count if some provisioners are busy or have been stopped. - `count` integer — Count is the number of provisioner daemons that matched the given tags. If the count is 0, it means no provisioner daemons matched the requested tags. - `most_recently_seen` string, date-time — MostRecentlySeen is the most recently seen time of the set of matched provisioners. If no provisioners matched, this field will be null. - `max_deadline` string, date-time - `reason` 'initiator' | 'autostart' | 'autostop' | 'dormancy' | 'dashboard' | 'cli' | 'ssh_connection' | 'vscode_connection' | 'jetbrains_connection' | 'task_auto_pause' | 'task_manual_pause' | 'task_resume' - `resources` CodersdkWorkspaceResource[] - `agents` CodersdkWorkspaceAgent[] - `api_version` string - `apps` CodersdkWorkspaceApp[] - `command` string - `display_name` string — DisplayName is a friendly name for the app. - `external` boolean — External specifies whether the URL should be opened externally on the client or not. - `group` string - `health` 'disabled' | 'initializing' | 'healthy' | 'unhealthy' - `healthcheck` CodersdkHealthcheck - `interval` integer — Interval specifies the seconds between each health check. - `threshold` integer — Threshold specifies the number of consecutive failed health checks before returning "unhealthy". - `url` string — URL specifies the endpoint to check for the app health. - `hidden` boolean - `icon` string — Icon is a relative path or external URL that specifies an icon to be displayed in the dashboard. - `id` string, uuid - `open_in` 'slim-window' | 'tab' - `sharing_level` 'owner' | 'authenticated' | 'organization' | 'public' - `slug` string — Slug is a unique identifier within the agent. - `statuses` CodersdkWorkspaceAppStatus[] — Statuses is a list of statuses for the app. - `agent_id` string, uuid - `app_id` string, uuid - `created_at` string, date-time - `icon` string — Deprecated: This field is unused and will be removed in a future version. Icon is an external URL to an icon that will be rendered in the UI. - `id` string, uuid - `message` string - `needs_user_attention` boolean — Deprecated: This field is unused and will be removed in a future version. NeedsUserAttention specifies whether the status needs user attention. - `state` 'working' | 'idle' | 'complete' | 'failure' - `uri` string — URI is the URI of the resource that the status is for. e.g. https://github.com/org/repo/pull/123 e.g. file:///path/to/file - `workspace_id` string, uuid - `subdomain` boolean — Subdomain denotes whether the app should be accessed via a path on the `coder server` or via a hostname-based dev URL. If this is set to true and there is no app wildcard configured on the server, the app will not be accessible in the UI. - `subdomain_name` string — SubdomainName is the application domain exposed on the `coder server`. - `tooltip` string — Tooltip is an optional markdown supported field that is displayed when hovering over workspace apps in the UI. - `url` string — URL is the address being proxied to inside the workspace. If external is specified, this will be opened on the client. - `architecture` string - `connection_timeout_seconds` integer - `created_at` string, date-time - `directory` string - `disconnected_at` string, date-time - `display_apps` CodersdkDisplayApp[] - `environment_variables` object - `expanded_directory` string - `first_connected_at` string, date-time - `health` CodersdkWorkspaceAgentHealth - `healthy` boolean — Healthy is true if the agent is healthy. - `reason` string — Reason is a human-readable explanation of the agent's health. It is empty if Healthy is true. - `id` string, uuid - `instance_id` string - `last_connected_at` string, date-time - `latency` object — DERPLatency is mapped by region name (e.g. "New York City", "Seattle"). - `lifecycle_state` 'created' | 'starting' | 'start_timeout' | 'start_error' | 'ready' | 'shutting_down' | 'shutdown_timeout' | 'shutdown_error' | 'off' - `log_sources` CodersdkWorkspaceAgentLogSource[] - `created_at` string, date-time - `display_name` string - `icon` string - `id` string, uuid - `workspace_agent_id` string, uuid - `logs_length` integer - `logs_overflowed` boolean - `name` string - `operating_system` string - `parent_id` UuidNullUUID - `uuid` string - `valid` boolean — Valid is true if UUID is not NULL - `ready_at` string, date-time - `resource_id` string, uuid - `scripts` CodersdkWorkspaceAgentScript[] - `cron` string - `display_name` string - `exit_code` integer - `id` string, uuid - `log_path` string - `log_source_id` string, uuid - `run_on_start` boolean - `run_on_stop` boolean - `script` string - `start_blocks_login` boolean - `status` 'ok' | 'exit_failure' | 'timed_out' | 'pipes_left_open' - `timeout` integer - `started_at` string, date-time - `startup_script_behavior` 'blocking' | 'non-blocking' - `status` 'connecting' | 'connected' | 'disconnected' | 'timeout' - `subsystems` CodersdkAgentSubsystem[] - `troubleshooting_url` string - `updated_at` string, date-time - `version` string - `created_at` string, date-time - `daily_cost` integer - `hide` boolean - `icon` string - `id` string, uuid - `job_id` string, uuid - `metadata` CodersdkWorkspaceResourceMetadata[] - `key` string - `sensitive` boolean - `value` string - `name` string - `type` string - `workspace_transition` 'start' | 'stop' | 'delete' - `status` 'pending' | 'starting' | 'running' | 'stopping' | 'stopped' | 'failed' | 'canceling' | 'canceled' | 'deleting' | 'deleted' - `template_version_id` string, uuid - `template_version_name` string - `template_version_preset_id` string, uuid - `transition` 'start' | 'stop' | 'delete' - `updated_at` string, date-time - `workspace_id` string, uuid - `workspace_name` string - `workspace_owner_avatar_url` string - `workspace_owner_id` string, uuid - `workspace_owner_name` string — WorkspaceOwnerName is the username of the owner of the workspace. --- [API](https://skmtc.net/coder/apis/coder-api.md) · [All operations](https://skmtc.net/coder/apis/coder-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/coder/coder-api/versions/56b6e9f08540/schema)