Skip to content
Evershell Docs

Create a workspace (empty, no initial task)

POST
/workspaces
 
curl --request POST \
  --url https://your-org.evershell.ai/v1/workspaces \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "role_id": "example", "role_name": "example", "environment": "example" }'

Permissions: workspace:write or workspace:write:own.

The workspace lands in idle after provisioning. Use POST /tasks to atomically create-workspace-and-submit-task in one call.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type application/json
object
role_id

One of role_id or role_name

string
role_name
required
string
environment
string
Example generated
{
  "role_id": "example",
  "role_name": "example",
  "environment": "example"
}

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Created

Media type application/json
object
id
required
string
org_id
required
string
role_id
required
string
environment
string
status
required

Archived workspaces keep their status (typically stopped) and carry a non-null archived_at; archive is not a status value.

string
Allowed values: provisioning idle busy stopping stopped failed
created_by_user_id
string
snapshot_ref
string
last_snapshot_error

Populated when Stop ran against a pod that no longer existed and the snapshot save failed — paired with an empty snapshot_ref. Cleared on the next successful snapshot.

string
parent_workspace_id

Set on forked workspaces; references the parent.

string
fork_source_snapshot_ref

Set on forked workspaces; references the snapshot the fork was created from.

string
fork_point_task_count

Set on forked workspaces; how many parent tasks were included before the fork boundary.

integer
pack_status

Whether the workspace’s running pod reflects the role’s current pack set. Computed at fetch time, not persisted.

string
Allowed values: current stale unknown
created_at
string format: date-time
updated_at
string format: date-time
archived_at

Set when the workspace has been archived; null otherwise.

string format: date-time
Example 
{
  "id": "ws_01HZ",
  "status": "provisioning",
  "pack_status": "current"
}

400

Section titled “400 ”

Validation failure

Media type application/json
object
error
required
object
code
required

Closed-enum slug (e.g. permission_denied, validation_error, workspace_not_found)

string
message
required

Human-readable summary

string
request_id
required

Server-generated request id for correlating logs

string
details

Optional structured context. Validation errors land at details.fields as a per-field map.

object
key
additional properties
any
Example 
{
  "error": {
    "code": "permission_denied",
    "message": "caller lacks required scope",
    "request_id": "7f3a9c2e"
  }
}

409

Section titled “409 ”

role_archived or provider_archived — the role (or its provider) is archived; unarchive before creating workspaces against it.

Media type application/json
object
error
required
object
code
required

Closed-enum slug (e.g. permission_denied, validation_error, workspace_not_found)

string
message
required

Human-readable summary

string
request_id
required

Server-generated request id for correlating logs

string
details

Optional structured context. Validation errors land at details.fields as a per-field map.

object
key
additional properties
any
Example 
{
  "error": {
    "code": "permission_denied",
    "message": "caller lacks required scope",
    "request_id": "7f3a9c2e"
  }
}

422

Section titled “422 ”

invalid_capabilities — the role’s caps.yaml failed to compile. Edit the role to fix it, then retry.

Media type application/json
object
error
required
object
code
required

Closed-enum slug (e.g. permission_denied, validation_error, workspace_not_found)

string
message
required

Human-readable summary

string
request_id
required

Server-generated request id for correlating logs

string
details

Optional structured context. Validation errors land at details.fields as a per-field map.

object
key
additional properties
any
Example 
{
  "error": {
    "code": "permission_denied",
    "message": "caller lacks required scope",
    "request_id": "7f3a9c2e"
  }
}

423

Section titled “423 ”

Tenant is past_due, decommissioning, or trial-expired

Media type application/json
object
error
required
object
code
required

Closed-enum slug (e.g. permission_denied, validation_error, workspace_not_found)

string
message
required

Human-readable summary

string
request_id
required

Server-generated request id for correlating logs

string
details

Optional structured context. Validation errors land at details.fields as a per-field map.

object
key
additional properties
any
Example 
{
  "error": {
    "code": "permission_denied",
    "message": "caller lacks required scope",
    "request_id": "7f3a9c2e"
  }
}