Create a work item type

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

Add a work item type to a project — Bug, Spike, Chore, whatever your team actually tracks. The new type is immediately selectable on work items, and becomes the target you attach custom properties to.

Call Enable work item types first. Creating a type in a project where the feature has never been turned on leaves you with a type nobody can pick.

Keep the id from the response. Every later step — attaching properties, reading the schema, creating a work item of this type — is keyed on it.

This write requires project mode

If the workspace manages types at the workspace level, this returns 409 work_item_types_managed_at_workspace. Create the type on the workspace surface instead, then import it into the project. See Work item type modes.

Path Parameters

slug:requiredstring

The workspace slug. It appears in your Plane URLs — in https://app.plane.so/my-team/projects/, the slug is my-team.

project_id:requiredstring (uuid)

The project to add the type to.

Body Parameters

name:requiredstring

Display name for the type, for example Bug. Maximum 255 characters.

description:optionalstring

What this type is for. This is not decoration: it is returned as type_description by the schema endpoint, which is how an integration or agent decides between Bug and Task without a human in the loop.

is_active:optionalboolean

Whether the type can be assigned to new work items. Create it inactive if you are staging a configuration and want to attach its properties before anyone can select it.

external_id:optionalstring

Your system's identifier for this type, for sync and import correlation. Maximum 255 characters, nullable.

external_source:optionalstring

The system external_id came from, for example github or jira. Maximum 255 characters, nullable.

is_default, is_epic, level and logo_props are not accepted here

is_default moves through mark-default. is_epic and level are read-only. logo_props is generated by Plane when the type is created — the response tells you what it picked.

Scopes

projects.work_item_types:write

Errors

Status	Code	Cause
400	validation_error	Missing name, or a field over its 255-character limit.
401	unauthorized	Missing or invalid credentials.
403	forbidden	Your role or token scope can't create work item types.
404	resource_not_found	No such workspace or project, or it's outside your tenant.
409	work_item_types_managed_at_workspace	The workspace manages types at the workspace level. Use the workspace surface.
409	conflict	A type in this project already uses this external_id and external_source pair.
429	rate_limited	Throttled. Honor the Retry-After header before retrying.

Create a work item type

curl -X POST \
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/" \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Bug",
  "description": "Something is broken and needs a fix",
  "is_active": true
}'

import requests

response = requests.post(
    "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/",
    headers={"X-Api-Key": "your-api-key"},
    json={
        "name": "Bug",
        "description": "Something is broken and needs a fix",
        "is_active": True,
    },
)
print(response.json())

const response = await fetch(
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Bug",
      description: "Something is broken and needs a fix",
      is_active: true,
    }),
  }
);
const data = await response.json();

Response201

{
  "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:24:03.117482Z"
}

Response409

{
  "type": "https://api.plane.so/errors/work_item_types_managed_at_workspace",
  "title": "Work Item Types Managed At Workspace",
  "status": 409,
  "code": "work_item_types_managed_at_workspace",
  "detail": "Work item types are managed at the workspace level for this workspace."
}

Reuse external_id to stay idempotent

external_id alone is not unique — the pair (external_id, external_source) is, within a project. Send both when you are syncing from another system so a repeated import surfaces as a clean 409 conflict instead of a duplicate type.