Create a workspace work item type

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

Define a work item type for the whole workspace. The type becomes available to projects working from the workspace list, so one call gives every team the same Bug or Incident rather than each project inventing its own.

Workspace mode required

This write only succeeds while the workspace manages work item types at the workspace level. In project mode it returns 409 with code work_item_types_managed_at_project — create the type on the project endpoint instead. 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.

Body Parameters

name:requiredstring

Display name for the type, for example Incident. Maximum 255 characters. Reusing a name that already exists in the workspace returns 409.

description:optionalstring

What this type is for. It is shown next to the type wherever someone picks it, so write it for the person choosing.

is_active:optionalboolean

Whether the type can be selected. Send false to create a type that exists but stays out of pickers until you are ready to roll it out.

external_id:optionalstring

Your system's identifier for this type, for sync and import correlation. Maximum 255 characters, and accepts null. Write-only — it is not returned on read, so keep your own mapping to the Plane id.

external_source:optionalstring

The system external_id came from, for example jira. Maximum 255 characters, and accepts null. Write-only, like external_id — an external_id is only unique within its source, so record both.

is_default, is_epic, level, and logo_props are read-only. A type created here is a standard work item type; promote it to the workspace default with Mark a type as default.

Scopes

workspaces.work_item_types:write

Errors

Status	Code	Cause
400	validation_error	name is missing, empty, or longer than 255 characters. See errors[].
401	unauthorized	Missing or invalid credentials.
403	forbidden	Your role or token scope can't write workspace types.
404	resource_not_found	No such workspace, or it's outside your tenant.
409	work_item_types_managed_at_project	The workspace manages types at the project level. Use the project endpoint.
409	conflict	The type can't be created as requested — most often a name already in use. Read detail.
429	rate_limited	Throttled. Honor the Retry-After header before retrying.

Create a workspace work item type

curl -X POST \
  "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/" \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Incident",
  "description": "Customer-facing outage that needs a response now",
  "is_active": true,
  "external_id": "10004",
  "external_source": "jira"
}'

import requests

response = requests.post(
    "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/",
    headers={"X-Api-Key": "your-api-key"},
    json={
        "name": "Incident",
        "description": "Customer-facing outage that needs a response now",
        "is_active": True,
        "external_id": "10004",
        "external_source": "jira",
    },
)
print(response.json())

const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/work-item-types/", {
  method: "POST",
  headers: {
    "X-Api-Key": "your-api-key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Incident",
    description: "Customer-facing outage that needs a response now",
    is_active: true,
    external_id: "10004",
    external_source: "jira",
  }),
});
const data = await response.json();

Response201

{
  "id": "a3f52d07-8e19-4c6b-92d4-0b7e15c8f326",
  "name": "Incident",
  "description": "Customer-facing outage that needs a response now",
  "is_active": true,
  "is_default": false,
  "is_epic": false,
  "level": 0,
  "logo_props": {},
  "created_at": "2026-01-14T09:22:41.478363Z"
}

Response409

{
  "type": "https://api.plane.so/errors/work-item-types-managed-at-project",
  "title": "Conflict",
  "status": 409,
  "code": "work_item_types_managed_at_project",
  "detail": "This workspace manages work item types at the project level. Create the type on the project's work item types endpoint."
}

Next steps

A new type starts with no custom properties. Attach the properties it should collect, then bring it into the projects that need it with Import work item types, passing the id returned above.