Import work item types

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

Make a set of workspace-level work item types available inside one project. Import does not create anything: the types already exist on the workspace, and this call adds them to a project's roster so work items there can use them.

This is the workspace-mode way to answer "which types does this project use". Reach for it when a workspace defines Bug, Task, and Incident centrally and a new project should offer Bug and Task but not Incident. List the candidates with List workspace work item types, then send the ids you want.

After a successful import, the imported types show up in List work item types for the project and each one's schema resolves against this project's states, labels, and members.

This is the one write here that requires workspace mode

Every other write in this group requires project mode. Import is the opposite: the types it moves are workspace-owned, so it only makes sense when the workspace manages types at the workspace level.

Calling it while the workspace runs in project mode returns 409 work_item_types_managed_at_project — in that mode a project authors its own types with Create a work item type and there is nothing to import. 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 import the types into.

Body Parameters

work_item_types:requiredarray of string (uuid)

The ids of the workspace work item types to make available in this project. Send them in one request rather than looping — the import is applied as a batch.

Plane skips ids that aren't work item types in this workspace, and they don't appear in the response.

Scopes

projects.work_item_types:write

Errors

Status	Code	Cause
400	invalid_request	An entry in work_item_types that isn't a UUID.
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_project	The workspace manages types per project. Create the type in the project instead.
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.

Import work item types

curl -X POST \
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/import/" \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "work_item_types": [
    "9c2f8e51-4a63-47d8-b1e0-5f7a2c40d693",
    "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240"
  ]
}'

import requests

response = requests.post(
    "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/import/",
    headers={"X-Api-Key": "your-api-key"},
    json={
        "work_item_types": [
            "9c2f8e51-4a63-47d8-b1e0-5f7a2c40d693",
            "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
        ]
    },
)
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/import/",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      work_item_types: [
        "9c2f8e51-4a63-47d8-b1e0-5f7a2c40d693",
        "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
      ],
    }),
  },
);
const data = 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": false,
    "level": 0,
    "governance_mode": "any",
    "rollout": "seed",
    "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
  },
  {
    "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": "constrained",
    "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:24:03.117482Z",
    "updated_at": "2026-01-14T09:24:03.117482Z",
    "updated_by_id": null
  }
]

Response409

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

The response lists the imported types

A successful import returns 200 with a JSON array of the imported types, in the order you sent their ids. Each entry has the same shape as Get a work item type. The response is a plain array, not the paginated data envelope. An empty work_item_types array returns [].

Imports in a governed workspace

In a workspace with workspace governance turned on, importing a type also gives the project a workflow for it, unless the project already has one. The workflow is the mandated one when the type is in required mode. Otherwise, it is the workflow the workspace pinned for this project. Without a pin, it is the workspace default workflow. Under constrained mode, when the default workflow isn't on the allowlist, it is the oldest allowlist entry instead. See Work item type governance.

Re-importing is safe

Sending an id the project already has is not an error and does not duplicate anything. If the project turned that type off, importing it again turns it back on. That makes the call safe to run on every provisioning pass: send the full desired set each time rather than diffing first.

Import only adds types. A type you leave out of the list stays in the project. To take workspace types out of a project, send the same work_item_types body to DELETE /api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/import/. That removal is all-or-nothing: if any type in the list can't be removed, for example because work items still use it or it is the project's default type, Plane removes none of them.

When to import versus create

Situation	Use
The workspace owns types and this project should offer some of them	Import
The project owns its own types	Create a work item type
You need a new type that does not exist at the workspace level yet	Create it on the workspace, then import it