---
title: "Retrieve multiple workspaces by their IDs"
method: POST
path: "/api/workspaces/list"
tags: ["CRUD", "Workspaces"]
---

# Retrieve multiple workspaces by their IDs

`POST /api/workspaces/list`

## Request

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

Returns a list of workspaces resolved for the provided IDs.<br/>
Guarantees that the array-size and order of the returned workspaces matches the order of requested IDs.<br/>
Does not fail if any of the requested workspaces is not found or not accessible - instead it returns null as an array-element of the corresponding workspace which could not be accessed.<br/>Requirements:<br/>- auth-client scopes: "workspace:read"<br/>- user permission: "read" or higher

## Query parameters

- `actAsAdmin` boolean

## Request body

- string[]

## Response `200`

- WorkspaceWithWorkspaceEmbed[]
  - `_embedded` WorkspaceEmbed, required
    - `apps` object, required
    - `children` WorkspaceEmbedRelation[], required
      - `relationId` string, uuid, required
      - `workspace` Workspace
        - `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.
      - `workspaceId` string, uuid, required
    - `currentPermission` 'comment' | 'full' | 'read' | 'write'
    - `fields` object, required
    - `integrations` object, required
    - `itemCount` integer, required
    - `itemStatusCount` object, required
    - `itemStatusCountArchived` object, required
    - `parents` WorkspaceEmbedRelation[], required
      - `relationId` string, uuid, required
      - `workspace` Workspace
        - `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.
      - `workspaceId` string, uuid, required
    - `permissions` object, required
    - `statuses` object, required
    - `userGroupPermissions` object, required
    - `views` object, required
    - `workspaceGroup` WorkspaceEmbedWorkspaceGroup
      - `id` string, uuid, required
      - `name` string, required
      - `order` integer, required
      - `parentId` string, uuid
  - `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
            - union
              - …
          - `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
            - union
              - …
          - `level` integer, required
          - `meta` object
          - `type` 'headline', required
        - RichTextBlockIndentation
          - `content` RichTextBlock[], required
          - `type` 'indentation', required
        - RichTextBlockList
          - `bulletListMarker` string
          - `items` RichTextListItem[], required
            - `content` RichTextBlock[], 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
            - union
              - …
          - `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.

## 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)