Workspace work item types overview

A work item type classifies work — Bug, Task, Feature, Incident — and carries the set of custom properties that work items of that type collect.

When a workspace manages types at the workspace level, a type is defined once for the whole workspace and made available to projects, instead of being recreated project by project. One Bug definition, one set of properties, every project reading from the same list.

These endpoints hang off the workspace and have no project segment:

/api/v2/workspaces/{slug}/work-item-types/

Writes require workspace mode

A workspace manages work item types in exactly one mode: project-level or workspace-level. Creating, updating, deleting, or marking a default here works only while the workspace is in workspace mode. In project mode the same calls return 409 with code work_item_types_managed_at_project — the capability exists, it just lives on the project endpoints. Reads are unaffected by mode. See Work item type modes.

The work item type object

Attributes

• id string (uuid)

  Unique identifier for the type. This is the id you send as type_id on a work item, and the id you pass when importing types into a project.

• name string

  Display name, for example Bug. Maximum 255 characters.

• description string

  What this type is for. Shown next to the type wherever it is picked in Plane, so it is worth writing for the people choosing, not for your integration.

• logo_props any

  Free-form icon metadata Plane uses to render the type's badge. Plane manages it in the app. It is read-only over the API.

• is_epic boolean

  Whether the type is an epic type. Read-only, and there is no body parameter for it: every type you create through this API is a standard work item type.

• is_default boolean

  Whether this is the workspace's default type. Read-only on create and update — change it with Mark a type as default.

• is_active boolean

  Whether the type can currently be selected. Deactivating a type retires it from pickers without deleting it or touching the work items already using it.

• level number

  The type's level in the work item hierarchy. Read-only, and one of the values you can sort by with order_by.

• 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. 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. A type you just created has none.

• external_id string or null

  Your system's identifier for this type, set on create or update so an import can correlate it with a record in your own system.

• external_source string or null

  The system external_id came from, for example jira. In the workspace, 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.

No per-project flags here

The project-scoped reads under /projects/{project_id}/work-item-types/ add is_active_in_project and is_default_in_project. These workspace routes don't return them. See Work item types (project).

Response200

{
  "id": "c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63",
  "name": "Bug",
  "description": "Something is broken and needs a fix",
  "logo_props": {},
  "is_epic": false,
  "is_default": false,
  "is_active": true,
  "level": 0,
  "governance_mode": "any",
  "rollout": "none",
  "project_ids": ["4af68566-94a4-4eb3-94aa-50dc9427067b", "7c19e5b3-2d84-4f6a-b0e7-93a1c5d8f246"],
  "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
}

Endpoints

Method	Path	Description
GET	/api/v2/workspaces/{slug}/work-item-types/	List workspace work item types
GET	/api/v2/workspaces/{slug}/work-item-types/{pk}/	Get a workspace work item type
POST	/api/v2/workspaces/{slug}/work-item-types/	Create a workspace work item type
PATCH	/api/v2/workspaces/{slug}/work-item-types/{pk}/	Update a workspace work item type
DELETE	/api/v2/workspaces/{slug}/work-item-types/{pk}/	Delete a workspace work item type
POST	/api/v2/workspaces/{slug}/work-item-types/{pk}/mark-default/	Mark a workspace work item type as default

There is no enable and no import action at the workspace level. Both are project-level operations — see Work item types (project).

Workspace mode versus project mode

	Project mode	Workspace mode
Where a type is defined	Once per project, on /projects/{project_id}/work-item-types/	Once per workspace, on /work-item-types/
Same type in ten projects	Ten separate records to create and keep in step	One record the projects share
Renaming or editing a type	Repeat the edit in every project	Edit once
Cross-project reporting	Group by name and hope the names match	Group by the type id
Per-project variation	A project can shape its own types freely	Projects work from the workspace list

Choose workspace mode when the same taxonomy should hold across many projects — a support org where Incident must mean the same thing everywhere, or a company that reports on bug counts across every team. Choose project mode when teams are genuinely different and each one should be free to invent its own categories.

The trade-off is consistency against autonomy, and it is a workspace-wide decision: both surfaces exist, but only one of them accepts writes at a time.

How a project gets workspace types

Defining a type here makes it available to the workspace; a project surfaces it once the project is working from the workspace list. To bring a specific set of workspace types into a project, send their ids to the project-level import endpoint:

POST /api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/import/

Collect the ids from List workspace work item types, then see Import work item types for the request shape.

Defaults

Exactly one type is the workspace default — the one a work item gets when no type is supplied. is_default is read-only on create and update, so promoting a different type is its own call:

POST /api/v2/workspaces/{slug}/work-item-types/{pk}/mark-default/

Marking a type as default clears the flag on the type that held it.

Retiring a type

Deactivating (is_active: false) and deleting are different moves:

• Deactivate when the type should stop appearing in pickers but existing work items keep their classification. Reversible — send is_active: true to bring it back.
• Delete when the type should be gone. DELETE returns 204 with an empty body. A type that can't be removed in its current state returns 409; read the detail for the reason.