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

# Retrieve or search workspaces

`POST /api/workspaces/search`

## Request

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

Returns all workspaces or searches workspaces by query. Always returns only workspaces 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

- WorkspaceSearchQuery
  - `archived` boolean
  - `filter` union
    - WorkspaceSearchQueryFilterAnd
      - `inner` WorkspaceSearchQueryFilter[], required
      - `type` 'and', required
    - WorkspaceSearchQueryFilterAppTypeContainAny
      - `type` 'appType:containAny', required
      - `values` string[], required
    - WorkspaceSearchQueryFilterFieldContainAny
      - `type` 'field:containAny', required
      - `values` string[], required
    - WorkspaceSearchQueryFilterItemTypeContainAny
      - `type` 'itemType:containAny', required
      - `values` ItemType[], required
    - WorkspaceSearchQueryFilterMembersContainAny
      - `ids` string[], required
      - `type` 'members:containAny', required
    - WorkspaceSearchQueryFilterNameContain
      - `caseSensitive` boolean, required
      - `text` string, required
      - `type` 'name:contain', required
    - WorkspaceSearchQueryFilterNameEqual
      - `caseSensitive` boolean, required
      - `text` string, required
      - `type` 'name:equal', required
    - WorkspaceSearchQueryFilterNamespaceContainAny
      - `type` 'namespace:containAny', required
      - `values` WorkspaceNamespace[], required
    - WorkspaceSearchQueryFilterNot
      - `inner` WorkspaceSearchQueryFilter, required (recursive)
      - `type` 'not', required
    - WorkspaceSearchQueryFilterOr
      - `inner` WorkspaceSearchQueryFilter[], required
      - `type` 'or', required
  - `sort` union
    - WorkspaceSearchQuerySortCreatedAt
      - `direction` 'asc' | 'desc', required
      - `type` 'createdAt', required
    - WorkspaceSearchQuerySortLastActivity
      - `direction` 'asc' | 'desc', required
      - `type` 'lastActivity', required
    - WorkspaceSearchQuerySortLastUpdatedAt
      - `direction` 'asc' | 'desc', required
      - `type` 'lastUpdatedAt', required
    - WorkspaceSearchQuerySortName
      - `direction` 'asc' | 'desc', required
      - `type` 'name', required

## Response `200`

- WorkspaceWithWorkspaceSearchEmbedPage
  - `items` WorkspaceWithWorkspaceSearchEmbed[], required
    - `_embedded` WorkspaceSearchEmbed, required
      - `currentPermission` 'comment' | 'full' | 'read' | 'write'
      - `itemCount` integer, required
      - `permissions` object, required
      - `statuses` object, required
      - `userGroupPermissions` object, required
    - `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
          - RichTextBlockAttachment
            - `attachmentId` string, uuid, required
            - `caption` string
            - `contentType` string, required
            - `meta` object
            - `type` 'attachment', required
            - `width` integer
          - RichTextBlockBlockquote
            - `content` RichTextInline[], required
              - …
            - `meta` object
            - `type` 'blockquote', required
          - RichTextBlockCode
            - `content` string, required
            - `language` string
            - `meta` object
            - `type` 'code', required
          - RichTextBlockCustom
            - `id` string, required
            - `meta` object
            - `raw` string, required
            - `type` 'custom', required
          - RichTextBlockEmbed
            - `caption` string
            - `height` integer
            - `meta` object
            - `type` 'embed', required
            - `url` string, required
          - RichTextBlockHeadline
            - `content` RichTextInline[], required
              - …
            - `level` integer, required
            - `meta` object
            - `type` 'headline', required
          - RichTextBlockIndentation
            - `content` RichTextBlock[], required
            - `type` 'indentation', required
          - RichTextBlockList
            - `bulletListMarker` string
            - `items` RichTextListItem[], required
              - …
            - `meta` object
            - `ordered` boolean, required
            - `orderedListDelimiter` string
            - `orderedListStartsAt` integer
            - `type` 'list', required
          - RichTextBlockPanel
            - `colorHex` string
            - `content` RichTextBlock[], required
            - `title` string
            - `type` 'panel', required
          - RichTextBlockParagraph
            - `content` RichTextInline[], required
              - …
            - `meta` object
            - `type` 'paragraph', required
    - `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.
  - `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)