---
title: "Create a new item"
method: POST
path: "/api/workspaces/{workspaceId}/items"
tags: ["CRUD", "Items"]
---

# Create a new item

`POST /api/workspaces/{workspaceId}/items`

## Request

- Base URL: `https://app.airfocus.com`
- URL: `https://app.airfocus.com/api/workspaces/{workspaceId}/items`
- Auth: HTTP bearer

Returns newly created item with its sanitised data.<br/>Requirements:<br/>- auth-client scopes: "workspace"<br/>- user permission: "write" or higher

## Path parameters

- `workspaceId` string, uuid, required

## Query parameters

- `actAsAdmin` boolean

## Request body

- CreateItemRequest
  - `archived` boolean: Whether this item is archived.
  - `assigneeUserGroupIds` string[]: Ids of user groups that are assigned to this item.
  - `assigneeUserIds` string[]: Ids of users who are assigned to this item.
  - `color` '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'
  - `description` RichText
    - `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
  - `fields` object: Values of custom fields, where each key is a custom-field ID and each value is a JSON-formatted value of the corresponding field.
  - `name` string, required: Name (title) of this item.
  - `order` integer: Order number of this item for sorting. If omitted, the item is appended at the end.
  - `statusId` string, uuid: Id of the status of this item. If omitted, the server picks a default for the workspace.

## Response `200`

- ItemWithItemEmbed
  - `_embedded` ItemEmbed, required
    - `alias` string
    - `apps` object, required
    - `attachmentCount` integer, required
    - `children` RelativeItemInfo[], required
      - `alias` string
      - `childOrder` integer, required
      - `item` Item
        - `archived` boolean, required: Whether this item is archived.
        - `assigneeUserGroupIds` string[], required: Ids of user groups that are assigned to this item.
        - `assigneeUserIds` string[], required: Ids of users who are assigned to this item.
        - `color` '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', required
        - `createdAt` string, date-time, required: Timestamp of when this item was created.
        - `creator` union
          - ActorAiActor
            - `actorType` union
              - …
            - `id` string, uuid, required
            - `onBehalfOf` Actor, required (recursive)
            - `type` 'aiActor', required
          - ActorApp
            - `id` string, uuid, required
            - `onBehalfOf` Actor (recursive)
            - `type` 'app', required
            - `typeId` string
          - ActorIntegration
            - `id` string, uuid, required
            - `onBehalfOf` Actor (recursive)
            - `type` 'integration', required
            - `typeId` string
          - ActorShareLink
            - `type` 'shareLink', required
          - ActorSystem
            - `type` 'system', required
          - ActorUser
            - `id` string, uuid, required
            - `type` 'user', required
        - `description` RichText, required
          - `blocks` RichTextBlock[], required
            - union
              - …
        - `fields` object, required: Values of custom fields, where each key is a custom-field ID and each value is a JSON-formatted value of the corresponding field.
        - `id` string, uuid, required: Unique identifier of this item.
        - `lastUpdatedAt` string, date-time, required: Timestamp of when this item was last updated.
        - `name` string, required: Name (title) of this item.
        - `number` integer: A numeric id of this item, which is used to create an alias to this item like DEV-123. The number is unique within the workspace, and defined by server on item creation.
        - `order` integer, required: A order number of this item for sorting.
        - `statusCategoryUpdatedAt` string, date-time: Timestamp of when the status of this item was last time switched from one category to another.
        - `statusId` string, uuid, required: Id of the status of this item.
        - `statusUpdatedAt` string, date-time: Timestamp of when the status of this item was last updated.
        - `workspaceId` string, uuid, required: Id of the workspace this workspace belongs to.
      - `itemId` string, uuid, required
      - `itemType` 'bug' | 'epic' | 'experiment' | 'feature' | 'feedback' | 'idea' | 'initiative' | 'app:okr:objective' | 'opportunity' | 'product' | 'project' | 'story' | 'task'
      - `parentOrder` integer, required
      - `relationId` string, uuid, required
      - `workspaceId` string, uuid, required
    - `commentCount` integer, required
    - `constraints` ItemConstraint[], required
      - union
        - ItemConstraintIntegrationPushForbidden
          - `extensionId` string, uuid, required
          - `type` 'integrationPushForbidden', required
        - ItemConstraintIntegrationToInternal
          - `extensionId` string, uuid, required
          - `property` union, required
            - 'archived' | 'assignees' | 'color' | 'createdAt' | 'creator' | 'description' | 'id' | 'lastUpdatedAt' | 'name' | 'number' | 'order' | 'status' | 'statusCategoryUpdatedAt' | 'statusUpdatedAt' | 'workspace'
            - string: A combination of 'fieldid:' prefix and a UUID field-id.
          - `type` 'integrationToInternal', required
        - ItemConstraintPropertyReadOnly
          - `extensionId` string, uuid, required
          - `property` union, required
            - 'archived' | 'assignees' | 'color' | 'createdAt' | 'creator' | 'description' | 'id' | 'lastUpdatedAt' | 'name' | 'number' | 'order' | 'status' | 'statusCategoryUpdatedAt' | 'statusUpdatedAt' | 'workspace'
            - string: A combination of 'fieldid:' prefix and a UUID field-id.
          - `type` 'propertyReadOnly', required
        - ItemConstraintUndeletable
          - `extensionId` string, uuid, required
          - `type` 'undeletable', required
    - `fieldEditMetadata` object: Who last edited each field of this item, and when. Absent when not retrieved.
    - `integration` ItemEmbedIntegration
      - `data` unknown, required
      - `id` string, uuid, required
      - `typeId` string, required
    - `linkCount` integer, required
    - `parents` RelativeItemInfo[], required
      - `alias` string
      - `childOrder` integer, required
      - `item` Item
        - `archived` boolean, required: Whether this item is archived.
        - `assigneeUserGroupIds` string[], required: Ids of user groups that are assigned to this item.
        - `assigneeUserIds` string[], required: Ids of users who are assigned to this item.
        - `color` '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', required
        - `createdAt` string, date-time, required: Timestamp of when this item was created.
        - `creator` union
          - ActorAiActor
            - `actorType` union
              - …
            - `id` string, uuid, required
            - `onBehalfOf` Actor, required (recursive)
            - `type` 'aiActor', required
          - ActorApp
            - `id` string, uuid, required
            - `onBehalfOf` Actor (recursive)
            - `type` 'app', required
            - `typeId` string
          - ActorIntegration
            - `id` string, uuid, required
            - `onBehalfOf` Actor (recursive)
            - `type` 'integration', required
            - `typeId` string
          - ActorShareLink
            - `type` 'shareLink', required
          - ActorSystem
            - `type` 'system', required
          - ActorUser
            - `id` string, uuid, required
            - `type` 'user', required
        - `description` RichText, required
          - `blocks` RichTextBlock[], required
            - union
              - …
        - `fields` object, required: Values of custom fields, where each key is a custom-field ID and each value is a JSON-formatted value of the corresponding field.
        - `id` string, uuid, required: Unique identifier of this item.
        - `lastUpdatedAt` string, date-time, required: Timestamp of when this item was last updated.
        - `name` string, required: Name (title) of this item.
        - `number` integer: A numeric id of this item, which is used to create an alias to this item like DEV-123. The number is unique within the workspace, and defined by server on item creation.
        - `order` integer, required: A order number of this item for sorting.
        - `statusCategoryUpdatedAt` string, date-time: Timestamp of when the status of this item was last time switched from one category to another.
        - `statusId` string, uuid, required: Id of the status of this item.
        - `statusUpdatedAt` string, date-time: Timestamp of when the status of this item was last updated.
        - `workspaceId` string, uuid, required: Id of the workspace this workspace belongs to.
      - `itemId` string, uuid, required
      - `itemType` 'bug' | 'epic' | 'experiment' | 'feature' | 'feedback' | 'idea' | 'initiative' | 'app:okr:objective' | 'opportunity' | 'product' | 'project' | 'story' | 'task'
      - `parentOrder` integer, required
      - `relationId` string, uuid, required
      - `workspaceId` string, uuid, required
    - `progress` ItemEmbedProgress, required
      - `closed` integer, required
      - `total` integer, required
    - `watched` boolean, required
    - `workspaceItemType` 'bug' | 'epic' | 'experiment' | 'feature' | 'feedback' | 'idea' | 'initiative' | 'app:okr:objective' | 'opportunity' | 'product' | 'project' | 'story' | 'task'
  - `archived` boolean, required: Whether this item is archived.
  - `assigneeUserGroupIds` string[], required: Ids of user groups that are assigned to this item.
  - `assigneeUserIds` string[], required: Ids of users who are assigned to this item.
  - `color` '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', required
  - `createdAt` string, date-time, required: Timestamp of when this item was created.
  - `creator` union
    - ActorAiActor
      - `actorType` union
        - 'assistant' | 'mcpServer'
        - string: An 'agent:' prefix followed by the specific agent type, e.g., 'agent:default:insights:create'
      - `id` string, uuid, required
      - `onBehalfOf` Actor, required (recursive)
      - `type` 'aiActor', required
    - ActorApp
      - `id` string, uuid, required
      - `onBehalfOf` Actor (recursive)
      - `type` 'app', required
      - `typeId` string
    - ActorIntegration
      - `id` string, uuid, required
      - `onBehalfOf` Actor (recursive)
      - `type` 'integration', required
      - `typeId` string
    - ActorShareLink
      - `type` 'shareLink', required
    - ActorSystem
      - `type` 'system', required
    - ActorUser
      - `id` string, uuid, required
      - `type` 'user', required
  - `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
  - `fields` object, required: Values of custom fields, where each key is a custom-field ID and each value is a JSON-formatted value of the corresponding field.
  - `id` string, uuid, required: Unique identifier of this item.
  - `lastUpdatedAt` string, date-time, required: Timestamp of when this item was last updated.
  - `name` string, required: Name (title) of this item.
  - `number` integer: A numeric id of this item, which is used to create an alias to this item like DEV-123. The number is unique within the workspace, and defined by server on item creation.
  - `order` integer, required: A order number of this item for sorting.
  - `statusCategoryUpdatedAt` string, date-time: Timestamp of when the status of this item was last time switched from one category to another.
  - `statusId` string, uuid, required: Id of the status of this item.
  - `statusUpdatedAt` string, date-time: Timestamp of when the status of this item was last updated.
  - `workspaceId` string, uuid, required: Id of the workspace 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)