Skip to content
ShareOutShareOut Docs

Workspaces

import { Aside } from ‘@astrojs/starlight/components’;

A workspace is a shared container for artifacts, members, folders, and connectors. Each workspace has its own role hierarchy, membership policy, and optional subdomain.

Create a workspace

Section titled “Create a workspace”
POST /v1/workspaces
Authorization: Bearer {token}
Content-Type: application/json


{ "name": "Acme Analytics", "slug": "acme" }

Get a workspace

Section titled “Get a workspace”
GET /v1/workspaces/{workspaceId}
GET /v1/workspaces/by-slug/{slug}

Update or delete

Section titled “Update or delete”
PATCH /v1/workspaces/{workspaceId}
DELETE /v1/workspaces/{workspaceId}

Delete requires owner role and cascades to memberships.

Members and roles

Section titled “Members and roles”
Role Capabilities
owner Full workspace control, including delete and ownership transfer. Can edit any workspace artifact in Live Studio and Edit-Lite.
admin Manage members, policy, subdomain, connectors, schedules, automations. Can edit any workspace artifact in Live Studio and Edit-Lite.
member Create/edit own artifacts; view workspace-visible artifacts. Editing another member’s artifact requires an explicit editor collaborator invite.
Method Endpoint Notes
GET /v1/workspaces/{id}/members List members.
POST /v1/workspaces/{id}/members Add a member; policy-gated.
DELETE /v1/workspaces/{id}/members/{userId} Remove a member.
POST /v1/workspaces/{id}/members/invite Bulk invite by email.
GET /v1/workspaces/{id}/members/metrics Member activity metrics. Admin+.
GET /v1/workspaces/{id}/people People picker list for UI.
POST /v1/workspaces/{id}/transfer-ownership Transfer to another member. Owner only.

Re-inviting an existing member with POST /members updates their role (member or admin). Owners cannot be demoted via this path.

Section titled “Workspace logo”

Upload a logo from Admin → Branding in Home or via API:

POST /v1/workspaces/{workspaceId}/logo
Content-Type: multipart/form-data


DELETE /v1/workspaces/{workspaceId}/logo

Served at /wl/{workspaceId}.{ext} for the Home rail and subdomain branding. Admin+ only.

Membership policy

Section titled “Membership policy”

Controls who may join — separate from per-artifact access_policy.

GET /v1/workspaces/{workspaceId}/access-policy
Authorization: Bearer {token}
{
  "allowed_domains": ["example.com"],
  "allowed_emails": ["contractor@example.net"]
}

Set policy (admin or owner):

PUT /v1/workspaces/{workspaceId}/access-policy
Authorization: Bearer {token}
Content-Type: application/json


{
  "allowed_domains": ["example.com"],
  "allowed_emails": ["contractor@example.net"]
}

Rules:

  • allowed_domains — users with matching email domains join automatically as member on login.
  • allowed_emails — individual allowlist for emails outside the allowed domains.
  • Send [] to clear a list. Omit a field to leave it unchanged.
  • Inviting outside policy: 403 DOMAIN_NOT_ALLOWED.

Workspace visibility

Section titled “Workspace visibility”

Publish an artifact with visibility: "workspace" so every workspace member can see it:

{
  "workspace_id": "wsp_abc123",
  "visibility": "workspace"
}

workspace visibility requires workspace_id to be set.

Workspace context files

Section titled “Workspace context files”

Optional markdown files that teach agents your team’s house style. Members read them; admins manage them.

GET /v1/workspaces/{workspaceId}/context
GET /v1/workspaces/{workspaceId}/context/{name}
PUT /v1/workspaces/{workspaceId}/context/{name}
DELETE /v1/workspaces/{workspaceId}/context/{name}
PUT /v1/workspaces/{workspaceId}/context          ← set entry file: { "entry": "index.md" }

Writes require admin or owner. Files must be lowercase .md, ≤ 64 KB.

Recommended files:

File Contents
index.md Short entry point, golden rules, links to topic files.
style.md Colors, fonts, layout, logo, chart conventions.
voice.md Tone, terminology, words to use/avoid.
conventions.md Report and dashboard structure.
data.md Connector names, metric definitions, key tables.

Agents can fetch the workspace-scoped skill (context included) via:

GET /v1/skill?workspace={workspaceSlugOrId}
Authorization: Bearer {token}

Branding

Section titled “Branding”

Upload a workspace logo and set brand colors:

POST /v1/workspaces/{workspaceId}/logo
PUT /v1/workspaces/{workspaceId}/branding
GET /v1/workspaces/{workspaceId}/branding
DELETE /v1/workspaces/{workspaceId}/logo

Personal vs workspace model

Section titled “Personal vs workspace model”

Artifacts without a workspace_id belong to the Personal space (the publishing owner). Setting workspace_id at publish time moves the artifact into a workspace — it appears in the Team Space alongside folders and workspace-visible content.

On the home screen, use the avatar switcher to move between Personal and each team workspace you belong to. Personal and Team Space each have their own folder chips in one unified top bar.

The redesigned workspace Home adds tabbed artifacts, the Inspector (Details, Comments, Automate), quick Edit mode, and the Activity feed (Needs You + Pulse).