---
title: "Retrieve or search workspace groups"
method: POST
path: "/api/workspaces/groups/search"
tags: ["CRUD", "WorkspaceGroups"]
---

# Retrieve or search workspace groups

`POST /api/workspaces/groups/search`

## Request

- Base URL: `https://app.airfocus.com`
- URL: `https://app.airfocus.com/api/workspaces/groups/search`
- Auth: HTTP bearer

Returns all workspace groups or searches workspace groups by query. Always returns only workspace groups which are accessible by the current user.<br/>Requirements:<br/>- auth-client scopes: "workspace:read"<br/>- user permission: "read" or higher

## Query parameters

- `actAsAdmin` boolean
- `offset` integer
- `limit` integer
- `from` integer
- `to` integer

## Request body

- WorkspaceGroupSearchQuery

## Response `200`

- WorkspaceGroupWithWorkspaceGroupSearchEmbedPage
  - `items` WorkspaceGroupWithWorkspaceGroupSearchEmbed[], required
    - `_embedded` WorkspaceGroupSearchEmbed, required: An object embedded into each workspace-group when searching workspaces.
      - `currentPermission` 'comment' | 'full' | 'read' | 'write'
      - `permissions` object, required: All explicitly defined permissions for all users for this workspace-group.
      - `userGroupPermissions` object, required: All explicitly defined permissions for all user groups for this workspace-group.
      - `workspaceIds` string[], required: List of workspace-ids which belongs to this workspace-group.
      - `workspaces` Workspace[], required: Deprecated and will be removed. Use 'workspaceIds' instead, and a followup workspace-search request.
        - `alias` string: A custom code of this workspace (e.g. PROD, DEV, etc), which is used to create aliases for items (e.g. DEV-123). Alias should consist of 1-10 uppercase letters, and should be unique within the team.
        - `assigneeSettings` WorkspaceAssigneeSettings
          - `required` boolean, required: Whether the assignees field is required when creating or updating items.
        - `createdAt` string, date-time, required: Timestamp of when this workspace was created.
        - `defaultPermission` 'comment' | 'full' | 'read' | 'write'
        - `description` RichText, required
          - `blocks` RichTextBlock[], required
            - union
              - …
        - `id` string, uuid, required: Unique identifier of this workspace.
        - `itemColor` 'amber' | 'azure' | 'black' | 'blue' | 'coco' | 'daulphine' | 'emerald' | 'fanta' | 'granite' | 'great' | 'leaf' | 'moss' | 'mutedAmber' | 'mutedAzure' | 'mutedBlack' | 'mutedBlue' | 'mutedCoco' | 'mutedDaulphine' | 'mutedEmerald' | 'mutedFanta' | 'mutedGranite' | 'mutedGreat' | 'mutedLeaf' | 'mutedMoss' | 'mutedOcean' | 'mutedOrange' | 'mutedPink' | 'mutedPurple' | 'mutedRed' | 'mutedSky' | 'mutedViolet' | 'mutedYellow' | 'ocean' | 'orange' | 'pink' | 'purple' | 'red' | 'sky' | 'violet' | 'yellow'
        - `itemType` 'bug' | 'epic' | 'experiment' | 'feature' | 'feedback' | 'idea' | 'initiative' | 'app:okr:objective' | 'opportunity' | 'product' | 'project' | 'story' | 'task'
        - `lastActivity` string, date-time, required: Timestamp of when any entities related to this workspace were last changed.
        - `lastUpdatedAt` string, date-time, required: Timestamp of when this workspace was last updated.
        - `metadata` WorkspaceWorkspaceMetadata
          - `duplicated` boolean, required: Whether this workspace was duplicated from another workspace.
          - `templateId` string: Id of the template used to create this workspace.
          - `templateWorkspaceRef` string: Which specific workspace-instruction in the template was used to create this workspace.
          - `version` string: Version of the server at the moment when this workspace was created.
        - `name` string, required: Name of this workspace.
        - `namespace` 'main' | 'app:okr' | 'app:portfolio', required
        - `order` integer, required: Order number of this workspace for sorting.
        - `progressMode` 'count' | 'none' | 'percentage', required
        - `statusPresetId` string, uuid: Optional reference to a shared status preset. When set, statuses are read from the preset instead of workspace-specific statuses.
        - `teamId` string, uuid, required: Id of the team this workspace belongs to.
    - `createdAt` string, date-time, required: Date-time when this group was created.
    - `defaultPermission` 'comment' | 'full' | 'read' | 'write'
    - `id` string, uuid, required: UUID of this group.
    - `lastUpdatedAt` string, date-time, required: Date-time when this group was last updated.
    - `name` string, required: Name of this group.
    - `order` integer, required: Order number of this group for sorting.
    - `parentId` string, uuid: UUID of the parent group (if applicable).
    - `teamId` string, uuid, required: UUID of the team which owns this group.
  - `totalItems` integer, required

## Other responses

- `400`: If payload is invalid.
- `401`: If missing authentication token.
- `403`: If user does not have the required permission, or authenticated client does not have the required access scopes.
- `default`: If any other error happens.

---

[API](https://skmtc.dev/airfocus/apis/airfocus-api.md) · [All operations](https://skmtc.dev/airfocus/apis/airfocus-api/llms.txt) · [OpenAPI document](https://skmtc.dev/airfocus/apis/airfocus-api/revisions/fc9ccaa2ec6d?raw)