workspace tools

​

workspace_create

Tier: write · Tags: workspace, write Create a new top-level container for studies, asks, and people. On a saturated account this returns [usage_limit_reached]; inspect existing workspaces and reuse one instead - see docs_get("guides/cold-start"). name: human-readable workspace name (required). description: optional description. base_url: optional default URL studies in this workspace target. Returns Workspace; on failure raises ToolError with error_kind ∈ {auth_failed, forbidden, validation_error, usage_limit_reached, server_error, network_error, http_error}.

​

Parameters

​

workspace_delete

Tier: destructive · Tags: delete, workspace Permanently delete a workspace. DESTRUCTIVE - cascades to every study, ask, person, audience source, reference, and chatbot endpoint inside it, and is irreversible (no soft-archive). Confirm with the user first. workspace_id: UUID or short alias (e.g. w-6ec) to delete. Returns {"deleted": True, "workspace_id": <id>}; on failure raises ToolError with error_kind ∈ {auth_failed, forbidden, not_found, server_error, network_error, http_error}.

​

Parameters

​

workspace_get

Tier: read-only · Tags: read, workspace Read workspaces. Polymorphic on workspace_id.

• No workspace_id → list every accessible workspace, ordered most-recently-active first (idle ones last, then alphabetical). Each item carries has_headroom (a cheap affordability hint - whether the workspace can still create a study under its tier cap); pass an id for the full quota counters and credit pool.
• With workspace_id → that workspace’s details plus plan-limit usage counters (studies/people used + cap, tier) and the simulation-credit pool drawn on dispatch. A None cap means “unlimited”; treat None and 0 differently. When credits.unlimited is True, skip the headroom check - balances are untracked (None), not empty. See docs_get("concepts/workspace").

Use the list form to discover workspace IDs, or an id to branch on plan caps before a create that would return [usage_limit_reached] (see docs_get("guides/cold-start")) or to check credits before dispatch. References are separate; use reference_get(workspace_id). workspace_id: UUID or short alias (e.g. w-6ec). Omit to list. name: list-mode only - case-insensitive substring filter on the workspace name, applied after the fetch. Use it to find a workspace by name without the “list all then scan” round-trip (e.g. workspace_get(name="Test")). Ignored when workspace_id is set. Returns PaginatedList[Workspace] (iterate .items) when no id, else WorkspaceInfo; on failure raises ToolError with error_kind ∈ {auth_failed, forbidden, not_found, server_error, network_error, http_error}.

​

Parameters

​

workspace_list

Tier: read-only · Tags: read, workspace List every workspace you can access as a lean id / alias / name array. The cheap enumeration primitive for cross-workspace work. To review research across all your workspaces: workspace_list → study_list (per workspace, or study_list() with no args to fan out over every workspace) → study_get(study_id, view="insights") to read a study’s AI summary and key findings. Only top-level workspaces are returned: reference/child products (benchmark comparison targets) are excluded by design, matching the app and CLI. For one workspace’s plan-limit counters and simulation-credit pool call workspace_get(workspace_id) instead; this tool deliberately drops those to stay lean. For account-wide plan + credits, call account_usage(). name: optional case-insensitive substring filter on the workspace name, applied after the fetch (e.g. workspace_list(name="Acme")). Returns a list of WorkspaceListItem (id / alias / name), ordered case-insensitively by name. On failure raises ToolError with error_kind in {auth_failed, forbidden, server_error, network_error, http_error}.

​

Parameters