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.

Two writes work in either mode: mark a type as default, and an update whose body has only is_active.

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.
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.
is_epic boolean
Whether this is the project's epic type. Read-only. Plane creates epic types; you can't create one through this endpoint.
is_default boolean
The type's own default flag. For a type the project owns, it marks the project's default. For a type shared from the workspace, it is the workspace default, and marking the type as this project's default sets is_default_in_project instead. It is not writable through create or update. Move it with Mark a work item type as default.
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_active_in_project boolean
Whether the type is turned on in this project. is_active is the type's own flag, so for a type shared from the workspace, the two can differ. The type is usable in the project only when both are true.
is_default_in_project boolean
Whether this project marked the type as its own default. New work items land on this type when no type_id is supplied. If no type in the project has this flag, they land on the type whose is_default is true. For a type shared from the workspace, this can be true while is_default, the workspace default flag, is false.
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.
governance_mode string
How a workspace with governance turned on decides which workflow this type uses: any, constrained, or required. Defaults to any. Read-only here. Change it with Update work item type governance.
rollout string
How the workspace spreads the type to projects. none leaves it to each project. seed adds it to every new project in a governed workspace. mandatory makes it active in every project, where it can't be turned off or removed. You set it in Plane. It is read-only over the API.
project_ids array of string (uuid)
Every project the type is added to, including other projects for a type shared from the workspace. The list holds ids only, so the response doesn't reveal the names of projects you aren't a member of. A deleted project, or one the type was removed from, drops out.
external_id string or null
Your system's identifier for this type, set on create or update for sync and import correlation.
external_source string or null
The system external_id came from, for example jira. Within a project, the pair of external_id and external_source identifies one type.
created_at string (date-time)
When the type was created.
updated_at string (date-time)
When the type was last updated.
updated_by_id string (uuid) or null
The user who last updated the type. null until someone updates it.

Response200

json

{
  "id": "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
  "name": "Bug",
  "description": "Something is broken and needs a fix",
  "logo_props": {
    "in_use": "icon",
    "icon": {
      "name": "AlertCircle",
      "background_color": "#EF5974"
    }
  },
  "is_epic": false,
  "is_default": false,
  "is_active": true,
  "is_active_in_project": true,
  "is_default_in_project": false,
  "level": 0,
  "governance_mode": "any",
  "rollout": "none",
  "project_ids": ["4af68566-94a4-4eb3-94aa-50dc9427067b"],
  "external_id": null,
  "external_source": null,
  "created_at": "2026-01-14T09:22:41.478363Z",
  "updated_at": "2026-01-14T09:22:41.478363Z",
  "updated_by_id": null
}

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.

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.
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.
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.
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.
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
`GET`	`/api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/`	List work item types
`GET`	`/api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{pk}/schema/`	Get a work item type schema
`GET`	`/api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{pk}/`	Get a work item type
`POST`	`/api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/`	Create 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
`POST`	`/api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/enable/`	Enable work item types
`POST`	`/api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/import/`	Import work item types
`POST`	`/api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{pk}/mark-default/`	Mark a work item type as default

What you can and cannot write

The writable surface is deliberately small: name, description, is_active, external_id, and external_source. governance_mode, rollout, and project_ids are read-only, and the API ignores them in a request body.

is_default moves through mark-default, not the request body.
is_epic and level are read-only. Epic types are listed like any other type, but you can only turn them on or off.
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.

Work item types overview ​

The work item type object ​

Attributes ​

The project-mode lifecycle ​

Endpoints ​

What you can and cannot write ​

The default type ​

Importing instead of creating ​