List workspaces

GET

/workspaces

const url = 'https://your-org.evershell.ai/v1/workspaces';
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 \
  --header 'Authorization: Bearer <token>'

Permissions: workspace:read or workspace:read:own — the unscoped variant returns every workspace in the org; :own filters to the caller’s own.

Optional role_name query param filters to workspaces under one agent role; the server resolves the name to a role id and 404s with role_not_found if no such role exists.

Authorizations

bearerAuth

Parameters

Query Parameters

include_archived

boolean

role_name

string

Filter to workspaces using the named agent role. Resolved server-side via the same name-lookup that POST /workspaces accepts in the body. Returns 404 role_not_found if the role doesn’t exist (silent empty would hide typos).

Responses

200

application/json

object

workspaces

Array<object>

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

{
  "workspaces": [
    {
      "id": "ws_01HZ",
      "status": "provisioning",
      "pack_status": "current"
    }
  ]
}