Workspace shell
Workspace shell & routes
The workspace home, canonical file URLs, responsive shell behavior, and the APIs that power shell cards.
The workspace host has product routes of its own. A virtual-file-system path and a browser URL are therefore related, but they are no longer the same string.
Canonical routes
| Browser route | Purpose |
|---|---|
/ | Workspace home: recents, launchable apps, Daily Brief, runs, automations and activity. |
/files | Root of the workspace VFS. |
/files/<encoded-path> | A file or folder surface. Each path segment is URL-encoded. |
/apps/<resource-registration-id> | A file-independent app enabled by spec.launch. |
The file route accepts ?mode=source or ?mode=browse when a caller needs to bypass the default
surface resolver. Without a mode, the workspace chooses the best registered app, execution engine or
browser surface for the node.
SDK file methods continue to accept VFS paths such as /reports/q1.json. Likewise,
client.bridge.navigate('/reports/q1.json') accepts a VFS path; the host converts it to the canonical
browser route /files/reports/q1.json. Passing an already-canonical /files/... target is also
supported.
Legacy root-path links are not redirected
The former catch-all file URLs (/reports/q1.json, for example) were removed when / became the
workspace home. The host intentionally does not redirect those browser URLs. Update bookmarks,
notifications and copied links to /files/**; keep raw VFS paths only in SDK/API arguments.
Responsive shell behavior
On large screens the shell shows a persistent, collapsible sidebar beside a sticky top bar. Below the large breakpoint, navigation moves into a left drawer and route changes close it automatically. Notifications, the context inspector and the assistant use overlay panels so the current file or app surface remains mounted.
Hosted apps must treat the iframe as a resizable container:
- use fluid widths and avoid assuming the browser viewport is the app viewport;
- allow layouts to collapse cleanly when workspace chrome reduces the available width;
- use
client.bridge?.resize(height)only when an intrinsic-height surface needs to report a new height; full-height app shells should normally fill their container; - test both file launches and
spec.launchworkspace launches on narrow and wide screens.
Shell data APIs
The home and global shell load each resource independently. A missing scope can hide one card without blocking navigation or the rest of the workspace.
| Shell data | Request | Required scope | Contract notes |
|---|---|---|---|
| Daily Brief policy | GET /v1/settings?scopeKind=Workspace&parentId=<workspaceId>&includeSecretValues=false | fabric.setting.read-all | Reads brief.daily-enabled and general.timezone before loading a dated brief. |
| Daily Brief | GET /v1/ai/briefs/workspace?workspaceId=<id>&briefDate=YYYY-MM-DD&timeZone=<iana-zone> | ai.brief.read | Returns the persisted brief or no content. |
| Generate Daily Brief | POST /v1/ai/briefs/workspace/generate | ai.brief.generate | Body: workspaceId, briefDate, timeZone; returns the persisted WorkspaceBriefDto. |
| Notifications | GET /v1/notifications?pageNo=1&pageSize=20&includeDismissed=false | fabric.notification.read | Workspace and user come from token claims; the response includes items and unreadCount. |
| Notification state | PUT /v1/notifications/{id}/read, /v1/notifications/read-all, or /v1/notifications/{id}/dismiss | fabric.notification.update | Dismissal also marks the notification read. |
| Storage | GET /v1/workspaces/current/storage | node.storage.read | Returns plan, quota, used/reserved bytes, percentage and capture/version metadata for the token workspace. |
| Automations | GET /v1/automations?workspaceId=<id>&branch=main | execution.execution.read | Returns projected schedules and file-change triggers; this read scope does not allow starting or cancelling runs. |
All of these calls use a workspace-bound access token. Endpoints named current or notification
endpoints derive workspace/user identity from claims; do not try to override them with query
parameters.
Response shapes used by the shell
WorkspaceBriefDtoincludesbriefDate,timeZone,content, generation/staleness metadata,links[],sourceSignalsJson, and creation/update timestamps.NotificationPageDtoincludesitems, paging totals andunreadCount. Each item carries source, type, severity, read/dismiss timestamps, and a typed navigation target for a workspace, file, resource or execution.WorkspaceStorageUsageDtoincludesplanCode,quotaBytes,usedBytes,reservedBytes,percentage,assignmentVersionandcapturedAt.AutomationDtoidentifies ascheduleortriggerand includes its source path, branch, enabled state, optional file/engine/tool metadata, next/last run timestamps and run-as service principal.
Next
Handle file and workspace launch contexts from an iframe app.