---
title: "Workspaces hooks"
description: "Hand-written shim. Generated CRUD via ./workspaces.gen. The hooks below
cover (a) the org-scoped handle lookup that composes two requests
(`useGetWorkspaceByHandle`) and (b) the email-settings sub-resource
(`useGetWorkspaceEmail`, `useUpdateWorkspaceEmail`) which the manifest
pipeline doesn't model yet."
section: "Libraries"
group: "React hooks"
order: 476
---

## Hooks

### `useCreateWorkspace` `mutation`

Create a workspace.

```ts
useCreateWorkspace(options?: MutationOpts<Workspace, CreateWorkspaceParams>)
```

**Types:** [Workspace](/types/workspace) · [CreateWorkspaceParams](/types/create-workspace-params)

### `useDeleteWorkspace` `mutation`

Soft-delete a workspace.

```ts
useDeleteWorkspace(options?: MutationOpts<SuccessResponse, string>)
```

**Types:** [SuccessResponse](/types/success-response)

### `useGetWorkspaceByHandle` `query`

Resolve a workspace by its (org-scoped) handle. Used by path-based URL
routing (`/<orghandle>/<wshandle>/…`).

Composes two requests: org by handle → workspace by org-id+handle. Both
underlying queries are gated on (a) the matching handle being non-empty
and (b) the caller's `enabled` option, so consumers like the global
header can call this from non-workspace routes without firing 404s.

```ts
useGetWorkspaceByHandle(orgHandle: string, wsHandle: string, options?: QueryOpts<Workspace>)
```

**Types:** [Workspace](/types/workspace)

### `useGetWorkspaceEmail` `query`

Fetch workspace email settings (address, enabled, config).

```ts
useGetWorkspaceEmail(workspaceId: string, options?: QueryOpts<WorkspaceEmailSettings>)
```

**Types:** [WorkspaceEmailSettings](/types/workspace-email-settings)

```ts
const { data: email } = useGetWorkspaceEmail("wsp_abc123");
```

### `useListWorkspaces` `query`

List workspaces.

```ts
useListWorkspaces(params?: Omit<ListWorkspacesParams, | > & { filter?: WorkspaceFilter; orderBy?: WorkspaceOrderBy[]; } & WorkspaceShorthands, options?: QueryOpts<Page<Workspace>>)
```

**Types:** [ListWorkspacesParams](/types/list-workspaces-params) · [WorkspaceFilter](/types/workspace-filter) · [WorkspaceOrderBy](/types/workspace-order-by) · [WorkspaceShorthands](/types/workspace-shorthands) · [Page](/types/page) · [Workspace](/types/workspace)

### `usePurgeWorkspace` `composite`

Permanently delete a soft-deleted workspace.

```ts
usePurgeWorkspace(options?: MutationOpts<SuccessResponse, PurgeWorkspaceParams>)
```

**Types:** [SuccessResponse](/types/success-response) · [PurgeWorkspaceParams](/types/purge-workspace-params)

### `useRestoreWorkspace` `composite`

Restore a soft-deleted workspace.

```ts
useRestoreWorkspace(options?: MutationOpts<Workspace, string>)
```

**Types:** [Workspace](/types/workspace)

### `useRetrieveWorkspace` `query`

Get a workspace by ID.

```ts
useRetrieveWorkspace(id: string, options?: QueryOpts<Workspace>)
```

**Types:** [Workspace](/types/workspace)

### `useUpdateWorkspace` `mutation`

Update a workspace.

```ts
useUpdateWorkspace(options?: MutationOpts<Workspace, UpdateWorkspaceParams>)
```

**Types:** [Workspace](/types/workspace) · [UpdateWorkspaceParams](/types/update-workspace-params)

### `useUpdateWorkspaceEmail` `mutation`

Update workspace email settings. Auto-invalidates email cache on success.

```ts
useUpdateWorkspaceEmail(options?: MutationOpts<WorkspaceEmailSettings, UpdateWorkspaceEmailSettingsParams>)
```

**Types:** [WorkspaceEmailSettings](/types/workspace-email-settings) · [UpdateWorkspaceEmailSettingsParams](/types/update-workspace-email-settings-params)

```ts
const update = useUpdateWorkspaceEmail();
update.mutate({ workspaceId: "wsp_abc123", enabled: true });
```