Get one workspace

GET

/workspaces/{id}

const url = 'https://your-org.evershell.ai/v1/workspaces/example';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://your-org.evershell.ai/v1/workspaces/example \
  --header 'Authorization: Bearer <token>'

Permissions: workspace:read (org-wide) or workspace:read:own (caller must be the workspace’s creator — 403 workspace_not_visible otherwise).

Authorizations

bearerAuth

Parameters

Path Parameters

required

string

Responses

200

application/json

object

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

403

Caller lacks the required scope, or cross-org access attempted

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

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