Work item types overview

A work item type gives work items a shape. Bug, Task, and Spike are not just labels — each type carries its own set of custom properties, so a Bug can require a severity and a reproduction URL while a Task requires neither. Every work item in a type-enabled project points at exactly one type through type_id.

The pages in this group cover the project-level work item type endpoints: types owned by a single project and configured under /projects/{project_id}/work-item-types/.

A workspace runs in exactly one mode

Work item types are managed either per project or per workspace — never both. The endpoints on this page are the project surface, and their writes require project mode. Calling one while the workspace runs in workspace mode returns 409 work_item_types_managed_at_workspace, not a 404 or 403: the capability exists, it just lives on the other surface.

Reads are unaffected by mode. A project still lists and reads its types in either mode, so GET and the schema endpoint always work.

See Work item type modes for how to detect which mode a workspace is in, and the workspace type endpoints for the other surface.

The work item type object

Attributes

• id string (uuid)

  Unique identifier for the type. This is the value you send as type_id when creating a work item, and the {type_id} in the type-properties paths.

• name string

  Display name, for example Bug. Maximum 255 characters.

• description string

  Free-form explanation of when this type should be used. Worth filling in — an integration or agent reading the schema endpoint sees this text as type_description and uses it to choose between types.

• is_active boolean

  Whether the type can be assigned to new work items. Deactivating a type hides it from pickers without deleting it or touching the work items that already use it.

• is_default boolean

  Whether new work items land on this type when no type_id is supplied. Exactly one type per project holds the flag. It is not writable through create or update — move it with Mark a work item type as default.

• is_epic boolean

  Whether this is the project's epic type. Read-only — epics are provisioned by Plane, not authored through this endpoint.

• level number

  Hierarchy level for the type. Read-only, and the value to sort on when you want the order the project itself uses — see List work item types.

• logo_props any

  The icon and background color rendered next to the type. Generated by Plane when the type is created, so it is read-only here.

• created_at string (date-time)

  When the type was created.

external_id is write-only

external_id and external_source are accepted on create and update as correlation fields for sync and import, but they are not returned in the read shape. Neither is updated_at. To find a type you previously synced, keep your own mapping from external_id to the returned id.

Response200

{
  "id": "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
  "name": "Bug",
  "description": "Something is broken and needs a fix",
  "is_active": true,
  "is_default": false,
  "is_epic": false,
  "level": 0,
  "logo_props": {
    "in_use": "icon",
    "icon": {
      "name": "AlertCircle",
      "background_color": "#EF5974"
    }
  },
  "created_at": "2026-01-14T09:22:41.478363Z"
}

The project-mode lifecycle

Types and their properties are set up in a fixed order. Each step depends on the id returned by the one before it.

1. Enable the feature — POST .../work-item-types/enable/

   Turns work item types on for the project. This is the first call: until it succeeds, the project has no types to create properties against. It returns the default type Plane provisions, normally named Task. See Enable work item types.

2. Create your types — POST .../work-item-types/

   Add Bug, Spike, or whatever your team actually tracks. Keep the id from the response — every later step needs it. See Create a work item type.

3. Create the properties — POST .../work-item-properties/

   Properties are defined at the project level and are independent of any type. A Severity option property is created once. See Create a work item property.

4. Attach properties to a type — POST .../work-item-types/{type_id}/properties/

   This is the step that makes a property apply to a type, and where you decide whether it is required for that type. The same property can be attached to several types with different settings. See Attach a property to a type.

5. Read the schema — GET .../work-item-types/{pk}/schema/

   Ask the API what a work item of this type accepts: the standard fields with their valid options, plus every custom property attached in step 4. This is the call a client makes right before it constructs a work item. See Get a work item type schema.

After that, create work items with type_id set to the type and custom_fields filled in from the schema.

Endpoints

Method	Path	Description
POST	/api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/enable/	Enable work item types for a project
GET	/api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/	List work item types
POST	/api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/	Create a work item type
GET	/api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{pk}/	Get a work item type
PATCH	/api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{pk}/	Update a work item type
DELETE	/api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{pk}/	Delete a work item type
GET	/api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{pk}/schema/	Get a work item type schema
POST	/api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{pk}/mark-default/	Mark a type as the project default
POST	/api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/import/	Import workspace types into a project

What you can and cannot write

The writable surface is deliberately small: name, description, is_active, external_id, and external_source.

• is_default moves through mark-default, not the request body.
• is_epic and level are read-only. Epic types are a separate surface and do not appear in these lists.
• logo_props is generated when the type is created.

The default type

Exactly one type per project is the default. Marking a new one clears the flag on the previous holder, so promoting a type is a single request rather than a demote-then-promote pair.

The default type is protected. It cannot be deleted, and it cannot be deactivated with "is_active": false — promote a different type first.

Importing instead of creating

POST .../work-item-types/import/ copies workspace-level types into a project rather than creating new ones. It is the workspace-mode counterpart to create, so it is the one endpoint in this group whose write requires workspace mode. See Import work item types.