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.

An id that does not resolve to a work item type on this workspace is rejected with 400 validation_error.

Scopes

projects.work_item_types:write

Errors

Status	Code	Cause
400	validation_error	work_item_types missing, or an entry that isn't a UUID.
401	unauthorized	Missing or invalid credentials.
403	forbidden	Your role or token scope can't configure this project's work item types.
404	resource_not_found	No such workspace or project, or it's outside your tenant.
409	work_item_types_managed_at_project	The workspace manages types per project. Create the type in the project instead.
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.status_code)  # 200

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"],
    }),
  }
);
console.log(response.status); // 200

Response200

(empty body)

Response409

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

The response tells you nothing — read the list instead

A successful import returns 200 with an empty body, not the types it imported. To confirm the result, follow it with List work item types for the project.

Re-importing is safe

Sending an id the project already has is not an error and does not duplicate anything. That makes the call safe to run on every provisioning pass: send the full desired set each time rather than diffing first.

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