---
title: "Create a new workspace"
method: POST
path: "/runners/workspaces"
tags: ["Runners Workspaces"]
---

# Create a new workspace

`POST /runners/workspaces`

Creates a new workspace with the provided configuration

## Request body

- CreateWorkspaceRequest
  - `runnerType` string, required — Type of runner (e.g., firefly_runners)
  - `iacType` string, required — Infrastructure as Code type
  - `workspaceName` string, required — Unique workspace name
  - `description` string — Workspace description
  - `labels` string[] — Labels assigned to the workspace
  - `vcsId` string, required — VCS integration ID
  - `repo` string, required — Repository name
  - `defaultBranch` string, required — Default branch
  - `vcsType` string, required — VCS type (github, gitlab, etc.)
  - `workDir` string, required — Working directory path
  - `variables` Variable[], required — Array of workspace variables
    - `key` string
    - `value` string
    - `sensitivity` 'string' | 'secret'
    - `destination` 'env' | 'iac'
  - `consumedVariableSets` string[] — Array of variable set IDs that this workspace consumes
  - `execution` object, required
    - `triggers` string[], required — When to trigger runs
    - `applyRule` string, required — Apply rule (manual/auto)
    - `terraformVersion` string, required — Terraform version
  - `project` string, nullable — Project ID or null for global access
  - `terraformVariables` object — Cleaned by deleteMockArrays
  - `terraformSensitiveVariables` object — Cleaned by deleteMockArrays
  - `providersCredentials` object — Cleaned by deleteMockArrays
  - `runnerEnvironment` object — Cleaned by deleteMockArrays
  - `iacProvisioner` IacProvisioner — Infrastructure as Code provisioner configuration
    - `type` 'terraform' | 'opentofu', required — Type of IaC provisioner
    - `version` string, required — Version of the provisioner
  - `multiEnvProvisioner` MultiEnvProvisioner — Multi-environment provisioner configuration
    - `type` 'terragrunt', required — Type of multi-environment provisioner
    - `version` string, required — Version of the multi-environment provisioner. Should be a valid semver when provided.
    - `applyAll` boolean — Whether to apply all environments or not
    - `stopOnError` boolean — Whether to stop on error during multi-environment provisioning
  - `poolId` string — ID of the runner pool associated with the workspace
  - `oidcAuthentication` boolean, nullable — OIDC authentication setting. If null, inherits from parent project.
  - `isRemote` boolean — Whether this workspace uses the internal remote backend for state management

## Response `201`

Workspace created successfully

- RunnersWorkspace
  - `id` string — Unique identifier for the workspace
  - `name` string, required — Name of the workspace
  - `description` string — Description of the workspace
  - `accountId` string — ID of the account the workspace belongs to
  - `repository` string, required — Repository URL for the workspace
  - `workingDirectory` string — Working directory within the repository
  - `vcsIntegrationId` string, required — ID of the VCS integration
  - `vcs` string, required — VCS type (e.g., github, gitlab)
  - `defaultBranch` string, required — Default branch for the workspace
  - `cronExecutionPattern` string — Cron pattern for scheduled executions
  - `iacProvisioner` IacProvisioner, required — Infrastructure as Code provisioner configuration
    - `type` 'terraform' | 'opentofu', required — Type of IaC provisioner
    - `version` string, required — Version of the provisioner
  - `multiEnvProvisioner` MultiEnvProvisioner — Multi-environment provisioner configuration
    - `type` 'terragrunt', required — Type of multi-environment provisioner
    - `version` string, required — Version of the multi-environment provisioner. Should be a valid semver when provided.
    - `applyAll` boolean — Whether to apply all environments or not
    - `stopOnError` boolean — Whether to stop on error during multi-environment provisioning
  - `labels` string[] — Labels assigned to the workspace
  - `poolId` string — ID of the runner pool associated with the workspace
  - `triggerConfig` WorkspaceTriggerConfig
    - `runOnPullRequest` boolean
    - `runOnPush` boolean
    - `autoApply` boolean
  - `oidcAuthentication` boolean, nullable — OIDC authentication setting. If null, inherits from parent project.
  - `isRemote` boolean — Whether this workspace uses the internal remote backend for state management

## Other responses

- `400` — Bad Request Error
- `401` — Unauthorized Error
- `403` — Insufficient permissions
- `500` — Internal Server Error

---

[API](https://skmtc.net/firefly/apis/api-gateway.md) · [All operations](https://skmtc.net/firefly/apis/api-gateway/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/firefly/api-gateway/revisions/eea119b4113f/schema)