Skip to main content
POST
Create workspace
Create a workspace from a configuration or saved template. Returns 201 when created, 200 for an identical retry with the same ID, or 409 if that ID has a different configuration. Set explain=true to check policies without creating anything.
See error examples and recovery steps. The complete OpenAPI contract includes every response schema.

Authorizations

Authorization
string
header
required

The server's token (MIRAGE_AUTH_TOKEN) or a JWT. A daemon in the default local mode with no token accepts requests without one.

Query Parameters

explain
boolean
default:false

Return what the call would do without running it.

Body

application/json

Workspace configuration or saved template to create from. Supply exactly one of config and template.

config
WorkspaceConfig · object | null

Workspace configuration. Supply config or template, never both.

template
string | null

Name of a saved template. Supply template or config, never both.

id
string | null

Workspace identifier. Use the same identifier to retry an identical configuration.

Response

Existing workspace for an identical retry, or policy evaluation when explain=true.

id
string
required
status
enum<string>
required

running while the server holds the workspace in memory; stopped while it keeps only its config and state, until a start.

Available options:
running,
stopped
created_at
string<date-time>
required

When the workspace was created. A stopped workspace that kept no creation time reports 1970-01-01T00:00:00.000Z.

Example:

"2026-11-07T00:00:00.000Z"

system_time
string | null
sessions
SessionSummary · object[]
mounts
MountSummary · object[]
internals
WorkspaceInternals · object | null