Enable work item types

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

Turn the work item types feature on for a project. This is the first call in the project-mode lifecycle. Until it succeeds, the project has no types, so there is nothing to create properties against and nothing for a work item's type_id to point at.

Enabling also provisions a default type, normally named Task, and returns it. New work items get the type with the returned id when no type_id is supplied, and you can attach properties to it right away.

The request has no body. The path carries everything the call needs.

This write requires project mode

If the workspace manages types at the workspace level, this returns 409 work_item_types_managed_at_workspace. In that mode there is nothing to enable per project. The workspace already owns the types, and you import them into the project 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.

project_id:requiredstring (uuid)

The project to turn work item types on for.

Body parameters

None. Send the request without a body.

Response shaping

fields:optionalstring

Comma-separated list of fields to return. Fields you don't request are left out of the response instead of coming back as null, so a missing key means you didn't ask for it and null means the value is null. id is always included, whether or not you name it.

Pass all to get every requestable field. An unknown field name returns 400 with the list of valid names and the closest match, so a typo is caught instead of being silently ignored.

Requestable here: created_at, description, external_id, external_source, governance_mode, id, is_active, is_active_in_project, is_default, is_default_in_project, is_epic, level, logo_props, name, project_ids, rollout, updated_at, updated_by_id.

See Sparse fields.

Scopes

projects.work_item_types:write

Errors

Status	Code	Cause
400	invalid_request	The request could not be processed as sent.
401	unauthorized	Missing or invalid credentials.
402	payment_required	The feature this endpoint belongs to isn't enabled on your plan, or is switched off.
403	forbidden	Your role or token scope can't configure this project's work item types.
404	not_found	No such workspace or project, or it's outside your tenant.
406	not_acceptable	The Accept header asks for a representation the API can't produce.
409	work_item_types_managed_at_workspace	The workspace manages types at the workspace level. Import instead of enabling.
413	payload_too_large	The request body is over the size limit.
415	unsupported_media_type	The Content-Type isn't one this endpoint accepts.
429	rate_limited	Throttled. Honor the Retry-After header before retrying.

Enable work item types

curl -X POST \
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/enable/" \
  -H "X-Api-Key: $PLANE_API_KEY"

import requests

response = requests.post(
    "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/enable/",
    headers={"X-Api-Key": "your-api-key"},
)
default_type = response.json()
print(default_type["id"], default_type["name"])

const response = await fetch(
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/enable/",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "your-api-key",
    },
  },
);
const defaultType = await response.json();

Response200

{
  "id": "9c2f8e51-4a63-47d8-b1e0-5f7a2c40d693",
  "name": "Task",
  "description": "Default work item type with the option to add new properties",
  "logo_props": {
    "in_use": "icon",
    "icon": {
      "name": "Check",
      "background_color": "#1FA191"
    }
  },
  "is_epic": false,
  "is_default": true,
  "is_active": true,
  "is_active_in_project": true,
  "is_default_in_project": true,
  "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
}

Response409

{
  "type": "conflict",
  "code": "work_item_types_managed_at_workspace",
  "detail": "Work item types are managed at the workspace level for this workspace."
}

Calling it twice is safe

A project that already has a default type gets that type back instead of a second one. You can put this call at the start of a provisioning script without a guard: it returns 200 either way, with the id you need in the body.

What comes next

Once the feature is on and you have the default type, finish the setup in this order:

1. Create your own types, such as Bug or Spike.
2. Create the properties they should carry.
3. Attach each property to a type, deciding there whether it is required.
4. Read the schema to confirm what a work item of that type now accepts.

The full sequence is laid out in the work item types overview.