Fork the workspace at a point in its task history

POST

/workspaces/{id}/fork

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

• Hosted tenant

Permissions: workspace:read or workspace:read:own (creator-match on :own) — reading the parent is sufficient; the fork creates a new workspace owned by the forker.

Creates a new workspace whose snapshot is a copy of the parent’s at the boundary after fork_point_task_count completed tasks. Useful for branching conversations / experiments without losing the parent line.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string

Request Body ^required

Media type application/json

object

fork_point_task_count

required

Snapshot the parent at the boundary right after this many completed tasks. 0 means “fork from workspace creation, before any tasks ran”.

integer

Example ^generated

{
  "fork_point_task_count": 1
}

Responses

202

Fork initiated

Media type application/json

object

workspace_id

required

Child workspace id.

string

parent_workspace_id

required

string

fork_point_task_count

required

integer

fork_source_snapshot_ref

string

status

required

string

Example

{
  "status": "provisioning"
}

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"
  }
}

404

Resource not found in the caller’s org

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

invalid_state — parent isn’t in a forkable state (busy parents return this), or role_archived / provider_archived — the role or provider is archived; unarchive before forking.

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

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"
  }
}